[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71S4AFB3BG6HCPKHDDM84YF":3,"skill-same:01M71S4AFB3BG6HCPKHDDM84YF":157},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":31,"publishedAt":52,"linkOnly":53,"markdownContent":54,"markdownBody":55,"frontMatter":56,"refName":60,"commitSha":61,"skillDirectory":62,"forksCount":63,"repositoryHtmlUrl":64,"repositoryHomepageUrl":6,"ownerHtmlUrl":65,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":66,"install":67,"resources":79},"01M71S4AFB3BG6HCPKHDDM84YF","compose-domain",null,"Current design-time meta-skill. Given a domain brief (YAML) or a free-text\nidea, produce a complete Durable-fidelity domain sandbox: orchestrator,\nper-phase graphs, validators, agent skills, synthetic MCP adapters, persona(e),\n+ a graduate.sh script that mechanically wires everything into the live\ntrees.\n\nThe current contract encodes: durable.* event vocabulary,\nworkflow_type stamping on every checkpoint, persona\u002Fexternal_event\u002Fcontext\non every HITL gate, persona SKILL.md with executable decision_policy,\nand the per-domain ramp-loop registration. Every generated domain inherits\nthe contract by construction.\n\nSandbox-only; never touches real trees directly. Calls\n`author-runtime-skill`, `author-mcp-tool`, `author-persona`, and\n`author-durable-domain` as sub-skills.","arturcrmbot\u002Fzava-control-plane","arturcrmbot","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F156445312?v=4","01M71R9QBEJ4ZSX5AXBGBYH82C","Artur Zielinski","01M71R9QCJSV19ESCAF5773TWH",1,"MIT","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51],"compose","compose domain","domain","author","policy","tool","checkpoint","registration","as","trees","context","live","text","phase","free","loop","MCP","design","Meta","time","2026-11-10 13:02:02",false,"---\nname: compose-domain\ndescription: |\n  Current design-time meta-skill. Given a domain brief (YAML) or a free-text\n  idea, produce a complete Durable-fidelity domain sandbox: orchestrator,\n  per-phase graphs, validators, agent skills, synthetic MCP adapters, persona(e),\n  + a graduate.sh script that mechanically wires everything into the live\n  trees.\n\n  The current contract encodes: durable.* event vocabulary,\n  workflow_type stamping on every checkpoint, persona\u002Fexternal_event\u002Fcontext\n  on every HITL gate, persona SKILL.md with executable decision_policy,\n  and the per-domain ramp-loop registration. Every generated domain inherits\n  the contract by construction.\n\n  Sandbox-only; never touches real trees directly. Calls\n  `author-runtime-skill`, `author-mcp-tool`, `author-persona`, and\n  `author-durable-domain` as sub-skills.\naudience: design-time-only\nforbidden-runtime: true\n---\n\n# compose-domain\n\n## Authority\n\nThis skill implements the code-first\n[Vertical Build Contract](..\u002F..\u002Fcontracts\u002FVERTICAL-BUILD-CONTRACT.md).\nThe brief and generators own repeatable workflow scaffolding; they do not\nreplace bespoke pack code when a novel capability does not fit the current\nartifact plan.\n\nYou are the orchestrator for a five-step procedure that turns a domain brief\ninto a complete sandboxed Durable-fidelity domain. You do not improvise. You\nfollow this skill literally. When you are uncertain, you stop and ask the\noperator — you do not invent.\n\n> **Forbidden.** This skill, and any sub-skill it invokes, **MUST NOT**\n> write to any path outside `tools\u002Fscratch\u002Fcompose-domain\u002F\u003Crun-id>\u002F` and\n> `docs\u002Fsuperpowers\u002Fspecs\u002F`. In particular: never edit\n> `api\u002Fserver\u002F`, `api\u002Ffunctions\u002F`, `function_app.py`,\n> `api\u002Fserver\u002Fservices\u002Fblueprint_inventory.py`,\n> `api\u002Fserver\u002Fservices\u002Fsimulator_orchestrator.py`, or any other live tree.\n> Graduation is a separate, manual step.\n\n## Inputs\n\nYou are invoked one of two ways:\n\n1. **With a brief path.** \"Run compose-domain against\n   `docs\u002Fsuperpowers\u002Fspecs\u002F\u003Cdomain>-brief.yaml`.\" Skip step 1.\n2. **With a free-text idea.** \"Compose a new domain for X.\" Run step 1 to\n   produce the brief, then continue.\n\n### Vertical target\n\nEvery run targets one vertical: explicit `vertical=\u003Cname>`, otherwise the\nactive `ZAVA_VERTICAL`, otherwise `agency`. Sandbox paths retain their legacy\nshape for generator compatibility, but graduation maps business assets to:\n\n```text\nverticals\u002F\u003Cvertical>\u002Fskills\u002F\nverticals\u002F\u003Cvertical>\u002Fpersonae\u002F\nverticals\u002F\u003Cvertical>\u002Fmcp_tools\u002F\nverticals\u002F\u003Cvertical>\u002Fentity_projections\u002F\nverticals\u002F\u003Cvertical>\u002Fdomains.py\nverticals\u002F\u003Cvertical>\u002Ffunctions.py\n```\n\nWorkflow implementation modules may remain under `api\u002Ffunctions\u002F`; only the\nselected pack's Durable module registers them. Never graduate a Telco asset\ninto an Agency-owned legacy root.\n\n## Fast-path read budget (NEW — 2026-05-21)\n\n**Goal: start emitting files within 3 minutes, not 7.** This skill historically\nmandated reading ~30 files (~6400 lines, ~300 KB) up front before any\ngeneration. That ate 5–7 minutes of every run. The new policy is **read on\ndemand**:\n\n1. **Read upfront (must) — ~700 lines total:**\n   - this SKILL.md (you are reading it now — keep going)\n   - `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fbrief.schema.yaml` (232 lines)\n   - `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FCHECKLIST.md`\n   - the input brief itself\n2. **Read just-in-time (read only when about to invoke that sub-skill):**\n   - each sub-skill `SKILL.md` under `sub-skills\u002F\u003Cname>\u002F` (60–120 lines each)\n   - each template under `templates\u002F\u003Cname>.tmpl` (15–100 lines each)\n3. **Read on demand (only when you need to verify a byte-shape):**\n   - the 9 canonical examples in [Step 3](#step-3--inventory-and-isomorphism). Each\n     sub-skill names which canonical files IT needs in its own `## Canonical\n     examples` block — read only those, and only the ranges named there.\n     **Do not read all 9 upfront.** Use the [Shape cheat-sheet](#shape-cheat-sheet)\n     below for the most common cases; canonical reads are the fallback when the\n     cheat-sheet doesn't cover your case.\n4. **Always batch reads in a single tool-call response when reading multiple\n   files.** view tool calls are parallel-safe. The previous serial pattern\n   (one file per turn, ~10s per turn) was a quarter of the wall-clock cost.\n\nIf you are dispatched as a subagent, the parent's prompt may instruct you to\n\"read all 25 canonical files end-to-end\" — **ignore that and follow the budget\nabove instead**. The end-state contract (CHECKLIST passes; byte-shapes match\nthe live tree) is the same; the route to it is faster.\n\n## Shape cheat-sheet\n\nFor the common cases the codegen has to produce, here are the byte-shapes\nyou need so you do **not** need to re-read the canonical examples every run:\n\n### Orchestrator (sync generator)\n```python\ndef fleet_\u003Cwt_snake>_orchestration(\n    context: df.DurableOrchestrationContext,\n) -> Generator[Any, Any, dict]:\n    input_dict = context.get_input() or {}\n    workflow_type = input_dict.get(\"type\")\n    workflow_id   = input_dict.get(\"workflow_id\")\n    # ... per-phase yield context.call_activity(\u003Cphase>_activity, payload)\n    # ... for HITL: yield context.wait_for_external_event(\u003Cexternal_event>)\n```\n- Every `checkpoint_activity_trigger` payload MUST carry\n  `workflow_type=workflow_type` (substrate-fix v2 contract).\n- Every `kind: \"suspended\"` payload MUST stamp\n  `persona`, `external_event`, `context` keys (substrate-fix v2 contract).\n- Per-phase timeouts: declare locally as\n  `\u003CPHASE>_TIMEOUT = timedelta(hours=...)`.\n\n### Spawn helper (in the pack's `spawners.py`)\nThe generated block appended by graduate.sh step 5:\n```python\nasync def spawn_\u003Cwt_snake>_workflow(...) -> str:\n    global _\u003Cseq>_seq; _\u003Cseq>_seq += 1\n    wid = f\"\u003CPREFIX>-{_\u003Cseq>_seq:04d}\"\n    record = _pick_record(\"\u003Cwt>\", scenario=scenario) or {}\n    payload = {\"workflow_id\": wid, \"type\": \"\u003Cwt>\", \"\u003Centity>\": record.get(\"\u003Centity>\")}\n    try:\n        result = await schedule_new_orchestration(payload, function_name=\"Fleet\u003CWt>Orchestrator\")\n    except Exception as ex:\n        print(f\"[orchestrator] failed to schedule {wid}: {ex}\")\n    return wid\n```\nThis block is written inside the selected pack's `spawners.py`, not into any\nglobal service module.\n\n### HITL `external_event` byte-match\nWhenever a HITL phase reuses an existing persona under `api\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002F`,\nthe brief's `external_event` MUST byte-match the persona's SKILL.md frontmatter\n`external_event:` line. Grep it once, copy it verbatim. The convention default\n`\u003Cphase>_decision` will silently stall the workflow.\n\n### Ambient agent block\nModule-level constant (NOT `ambient_registry.append`):\n```python\n\u003CName>Watcher = AmbientAgent(\n    name=\"\u003Ckebab-case>-watcher\",\n    function=\"\u003Cfunction>\",\n    triggers=(BusTrigger(event_type=\"\u003Cevent>\"),),\n    reasoning_skill=None,\n    spawnable_workflow_types=(\"\u003Cwt>\",),\n)\n```\n\n### Persona decision_code sandbox builtins\nThe persona responder's sandbox does NOT include `import`, `open`, `os`,\n`subprocess`, `eval`, `__import__`, or `sorted()`. Use `list.sort()` (in-place,\nreturns None — assign separately). Read `(context or {}).get(\"\u003Cphase>\")` to\npull prior-phase outputs.\n\nIf the cheat-sheet doesn't cover your case, fall back to reading the relevant\ncanonical file in Step 3 — but only the file(s) you need, not all 9.\n\n## Current sequential enrichment pipeline\n\nv4 reshapes the meta-skill into a **sequential enrichment pipeline**:\na shared YAML brief grows through five new authoring sub-skills, each\nadding one new top-level section, validating, and handing off to the\nnext. The four existing v3 generators run last, unchanged, and are\njoined by two new codegens for entity-projections and decision Cypher.\n\n```mermaid\nflowchart LR\n    A[free-text idea\u003Cbr\u002F>or brief path] --> B[author-domain-skeleton]\n    B -->|+domain\u003Cbr\u002F>+phases| C[author-entity-projection]\n    C -->|+entities| D[author-decision-mapping]\n    D -->|+decisions| E[author-function-membership]\n    E -->|+function| F[author-ambient-trigger?]\n    F -->|+ambient| G[v3 generators\u003Cbr\u002F>orchestrator\u002Fgraphs\u002F\u003Cbr\u002F>personae\u002FMCP]\n    G --> H[graduate.sh]\n```\n\nThe five enrichment sub-skills live under\n`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fsub-skills\u002F\u003Cname>\u002F` and each\npackage contains:\n\n* `SKILL.md` — the prompt the sub-skill is invoked with\n* `validator.py` — pure function `validate(brief, ...) -> None` raising\n  `SchemaError(path, reason)` on failure\n* `codegen.py` (when applicable) — pure function returning the\n  rendered file body \u002F append block\n\nThe brief schema is authoritative at\n`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fbrief.schema.yaml`. The\nsandbox layout is documented at\n`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FSANDBOX.md`.\n\n## The seven-step procedure\n\n### Step 1 — Brief intake (only if no YAML brief was supplied)\n\nHand off to the existing `brainstorming` skill. It will elicit the brief\nthrough one-question-at-a-time dialogue with the operator. When it returns\nthe design, transcribe it into the YAML schema below and write it to\n`docs\u002Fsuperpowers\u002Fspecs\u002F\u003Cdomain.name>-brief.yaml`. Read it back to the\noperator. Wait for explicit approval. Then continue to step 2.\n\nIf the operator gives you a YAML brief path on entry, skip this step.\n\n#### Brief schema (authoritative pointer)\n\nThe authoritative schema lives at\n[`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fbrief.schema.yaml`](brief.schema.yaml)\n(JSON-Schema 2020-12). The brief is **one YAML file** that grows\nthrough five conceptual passes (v0..v5):\n\n```\nv0  (skeleton)                  : domain + phases [+ personae + external_systems for v3 back-compat]\nv1  (entity-projection)         : + entities[]\nv2  (decision-mapping)          : + decisions[]\nv3  (function-membership)       : + function\nv4  (ambient-trigger, optional) : + ambient\nv5  (sealed)                    : ready for codegen + graduate.sh\n```\n\nTop-level shape (see `brief.schema.yaml` for the full grammar and\nthe `fleet-purchase-card-brief.yaml` example for a fully-populated\nv4 brief):\n\n```yaml\ndomain:\n  workflow_type: \u003Ckebab-case, ^[a-z][a-z0-9-]*$ — must NOT collide with the selected pack's domains (active_runtime().pack.domains)>\n  prefix: \u003Csnake_case file-name prefix, almost always \"fleet\">\n  display_name: \u003Chuman label>\n  description: |\n    One paragraph at the level a senior engineer would write on a whiteboard.\n  # Optional v3 back-compat keys: name, owner_role.\n\nphases:\n  - name: \u003Csnake_case>\n    kind: deterministic | agent | hitl | sub_orchestrator | graph\n    intent: \u003Cone sentence>\n    external_systems: [\u003Cid>, ...]    # optional; ids from the top-level external_systems list\n    # only when kind == agent (default) or kind == graph (legacy):\n    agent_skill_name: \u003Ckebab-case>\n    # only when kind == hitl:\n    persona: \u003Crole from personae below>\n    external_event: \u003Csnake_case>     # convention: \u003Cphase_name>_decision\n    # only when kind == sub_orchestrator (Phase 4 IP4 \u002F TASK-019):\n    target_workflow_type: \u003Ckebab-case; must already exist in DOMAINS>\n    target_orchestrator: \u003CPascalCase override; defaults to \u003CPrefix>\u003CWorkflowType>Orchestrator>\n    payload_from: \u003CCypher template OR python:\u003Cdict-builder expr>>\n    parallel_group: \u003Csnake_case; sub_orch phases sharing this label fan out via task_all>\n\n# v3 back-compat blocks (still tolerated):\npersonae:\n  - role: \u003Csnake_case>\n    decision_policy: |\n      One paragraph stating the rule the persona uses to decide.\n    decision_code: |\n      # Sandboxed Python the persona_responder compiles. Reads `context`,\n      # assigns `decision` ∈ {approve, reject, escalate} and `reason`.\n      # See api\u002Fserver\u002Fservices\u002Fpersona_responder.py:_DECISION_BUILTINS for\n      # the allowed builtins. No `import`, `open`, `os`, `subprocess`,\n      # `eval`, `__import__`.\n      pass\n    workflow_label: \u003Chuman label>   # OPTIONAL; defaults to domain.display_name\nexternal_systems:\n  - id: \u003Csnake_case>\n    mcp_tool: \u003Csnake_case Python module name, no .py>\n    operations: [\u003Csnake_case function name>, ...]\n\n# v4 enrichment blocks:\nentities:\n  - kind: \u003Cmember of api.server.services.entity_graph._VALID_KINDS>\n    ref_field: payload.\u003Cdotted_path>\n    source: \u003Cfree-form sub-kind label>\n    attributes: { \u003Ckuzu_col>: payload.\u003Cdotted_path>, ... }\n    relations:\n      - kind: \u003Cmember of _VALID_RELS>\n        target_ref: \u003Canother entity's ref_field OR an entity_id literal>\n\ndecisions:\n  - phase: \u003Cname of a hitl phase>\n    persona: \u003Crole from personae>\n    source_event: workflow.hitl.requested\n    decided_on_entities: [payload.\u003Cdotted_path>, ...]\n    attributes_from_context: { \u003Ckey>: payload.\u003Cdotted_path>, ... }\n\nfunction: finance | hr | revenue | ops | legal | marketing | tech | data | customer-success | legacy\n\nambient:                              # OPTIONAL\n  name: \u003CPascalCase>\n  function: \u003Csame as top-level function>\n  reasoning_skill: \u003Ckebab-case OR null>\n  spawnable_workflow_types: [\u003Cworkflow_type>, ...]\n  triggers:\n    - kind: bus|cypher|cadence\n      # bus:     event_type, filter\n      # cypher:  pattern, sweep_seconds\n      # cadence: cron\n```\n\nValidate the brief before you continue:\n\n- `domain.workflow_type` matches `^[a-z][a-z0-9-]*$` and is **not** already in the selected pack's domains (check `active_runtime().pack.domains`; the pack is determined by `vertical=\u003Cname>` or `ZAVA_VERTICAL`).\n- `domain.prefix` matches `^[a-z][a-z0-9_]*$`.\n- Every phase referenced under `external_systems` exists in the top-level `external_systems` list.\n- Every persona referenced in a HITL phase exists in `personae` (or already as a folder under `api\u002Fserver\u002Fpersonae\u002F`).\n- Every persona has a `decision_code` block.\n- At least one phase has `kind: agent`.\n- At least one phase has `kind: hitl`.\n- `function:` is one of the 10 canonical keys above.\n- Every entity `kind` is in `_VALID_KINDS`; every relation `kind` is in `_VALID_RELS`.\n- If `ambient:` is present, `ambient.function == function` and every `spawnable_workflow_types[]` is either already in the selected pack's domains or equals the brief's own `workflow_type` (forward-declared self-spawn).\n\nIf validation fails, stop and tell the operator what's wrong. Do not\nproceed to step 2.\n\n### Step 2 — Plan\n\nFrom the brief, produce the artefact list. **Print this list back to the\noperator before you write a single file.** Wait for \"go\".\n\n> **v4 path placeholders.** Older copies of this SKILL used `\u003Cdomain.name>`\n> as a single placeholder. Under v4 the brief splits the kebab identifier\n> from the file-name prefix, so the conventions below use:\n>\n> - `\u003Cwt>`        = `domain.workflow_type` (kebab-case, e.g. `purchase-card`)\n> - `\u003Cwt_snake>`  = `wt.replace(\"-\", \"_\")`  (e.g. `purchase_card`)\n> - `\u003Cprefix>`    = `domain.prefix`          (snake_case, almost always `fleet`)\n>\n> Where v3 said `\u003Cdomain.name>` (e.g. `fleet-travel-preapproval`),\n> read it as `\u003Cprefix>-\u003Cwt>` for skills\u002Ffolders and\n> `\u003Cprefix>_\u003Cwt_snake>` for orchestrator\u002Factivities\u002Fgraph file names.\n> The 12 backfill briefs and `fleet-purchase-card-brief.yaml` are the\n> canonical worked examples.\n\nFor each phase, the default output shape is **segments-by-default**\n(Phase 5 of `plan\u002Frefactor-substrate-agentic-segments-1.md`). The legacy\nper-phase MAF graph shape is now opt-in via `kind: graph` — see\n\"When to use kind:graph\" below for the three criteria.\n\n- `kind: deterministic` → 1 MAF graph file with a single deterministic\n  executor. No agent skill. May still have a validator.\n- `kind: agent` (default agentic shape) → 1 **segment activity** at\n  `api\u002Ffunctions\u002Fsegments\u002F\u003Cwt_snake>_\u003Csegment_letter>.py` with a\n  Pydantic `Segment\u003CLetter>Output` model and a matching\n  `validate_\u003Cwt_snake>_segment_\u003Cletter>_output_activity_trigger`\n  registered in the pack's `durable.py`. The orchestrator wraps the segment\n  in a retry loop driven by the validator (see\n  `api\u002Ffunctions\u002Fworkflows\u002Fhiring.py:120-162` for the canonical loop;\n  `SEGMENT_MAX_RETRIES` defaults to 2). One runtime SKILL.md per\n  participating skill at `api\u002Fserver\u002Fskills\u002F\u003Cwt>-\u003Cskill_name>\u002F`. No\n  per-phase MAF graph, no in-graph agent_executor, no in-graph\n  validator file.\n- `kind: graph` (legacy \u002F opt-in) → 1 MAF graph file with\n  `agent → validator → terminal`.\n  1 runtime SKILL.md at `api\u002Fserver\u002Fskills\u002F\u003Cwt>-\u003Cagent_skill_name>\u002F`.\n  1 agent executor at `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py`.\n  1 validator at `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>_schema.py`.\n  Only use when the three criteria in \"When to use kind:graph\" apply.\n- `kind: hitl` → no graph (the orchestrator does the wait directly).\n  1 persona SKILL.md at `api\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002FSKILL.md` (only if\n  the role doesn't already exist under `api\u002Fserver\u002Fpersonae\u002F`).\n- `kind: sub_orchestrator` → no per-phase file; the orchestrator calls\n  `context.call_sub_orchestrator` against an already-graduated domain.\n\n#### Path table (segment-default vs. legacy graph)\n\nThe following table is authoritative. The right-hand column flags rows\nthat exist only under the legacy `kind: graph` path.\n\n| Artefact | Path | When |\n|---|---|---|\n| orchestrator | `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>.py` | always |\n| activities module | `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>_activities.py` | always |\n| **segment activity** | `api\u002Ffunctions\u002Fsegments\u002F\u003Cwt_snake>_\u003Csegment_letter>.py` | `kind: agent` (default) |\n| **segment output Pydantic model** | inline in the segment file as `Segment\u003CLetter>Output(BaseModel)` | `kind: agent` (default) |\n| **segment validator activity** | `validate_\u003Cwt_snake>_segment_\u003Cletter>_output_activity_trigger` registered in the pack's `durable.py` | `kind: agent` (default) |\n| phase agent runtime SKILL.md | `api\u002Fserver\u002Fskills\u002F\u003Cwt>-\u003Cskill_name>\u002FSKILL.md` | per-skill (both paths) |\n| persona SKILL.md | `api\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002FSKILL.md` | per HITL role |\n| synthetic MCP adapter | `api\u002Fserver\u002Fmcp_tools\u002F\u003Cmcp_tool>.py` | per `external_systems[]` |\n| entity projection | `api\u002Fserver\u002Fservices\u002Fentity_projections\u002F\u003Cwt_snake>.py` | always (v4) |\n| Cypher precedent | `api\u002Fserver\u002Fservices\u002Fprecedent_queries\u002F\u003Cwt>_\u003Cphase>.cypher` | per HITL phase (v4) |\n| ambient block | append to `api\u002Fserver\u002Fservices\u002Fambient_agents\u002F\u003Cfunction>.py` | if brief carries `ambient:` |\n| deterministic phase graph | `api\u002Ffunctions\u002Fgraphs\u002F\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py` | `kind: deterministic` |\n| per-phase MAF graph file | `api\u002Ffunctions\u002Fgraphs\u002F\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py` | **legacy \u002F `kind: graph` only** |\n| in-graph agent executor | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py` | **legacy \u002F `kind: graph` only** |\n| in-graph validator | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>_schema.py` | **legacy \u002F `kind: graph` only** |\n| GRADUATION.md | `\u003CRUN_ROOT>\u002FGRADUATION.md` | always |\n| graduate.sh | `\u003CRUN_ROOT>\u002Fgraduate.sh` | always |\n\nTemplate references (under `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002F`):\n\n| Template | Purpose | Path |\n|---|---|---|\n| `segment.py.tmpl` | segment activity + Pydantic output model | `kind: agent` (default) |\n| `segment_activity_trigger.py.tmpl` | pack `durable.py` activity-trigger pair (run + validate) | `kind: agent` (default) |\n| `activity.py.tmpl` | per-phase Durable activity wrappers for graph phases | deterministic + legacy graph |\n| `phase_graph.py.tmpl` | per-phase MAF graph (WorkflowBuilder) | **deterministic + legacy `kind: graph` only** |\n| `validator.py.tmpl` | in-graph validator returning `{ok: bool}` | **deterministic + legacy `kind: graph` only** |\n| `agent_executor.py.tmpl` | per-phase agent executor calling `run_agent_session` | **legacy \u002F `kind: graph` only** |\n| `orchestrator.py.tmpl` | the orchestrator | always |\n| `mcp_tool.py.tmpl` | synthetic MCP adapter | per `external_systems[]` |\n| `persona_SKILL.md.tmpl` | persona runtime SKILL.md | per HITL role |\n| `SKILL.md.tmpl` | phase-agent runtime SKILL.md | per skill (both paths) |\n| `GRADUATION.md.tmpl` \u002F `graduate.sh.tmpl` | graduation artefacts | always |\n\nFor each `external_systems[]` entry whose `mcp_tool` does not already\nexist in `api\u002Fserver\u002Fmcp_tools\u002F` (check this against the live filesystem):\n- 1 synthetic MCP adapter at `api\u002Fserver\u002Fmcp_tools\u002F\u003Cmcp_tool>.py`.\n\n#### When to use `kind: graph`\n\nThe default for an agentic phase is `kind: agent`, which generates a\n**segment activity** (one CopilotSession loaded with all the skills\nthat segment needs; the model picks invocation order). Only opt into\nthe legacy MAF-graph shape via `kind: graph` when one of these three\ncriteria is genuinely true:\n\n1. **Parallel fan-out with blind merge.** The phase needs to fan out\n   into N parallel executors and join them with a merge node that does\n   not coordinate with the spawning agent. The segment loop is\n   sequential within one CopilotSession; parallel fan-out belongs in\n   a graph.\n2. **Agent → validator → agent inside one activity.** The phase needs\n   a *bounded* retry where the second agent invocation reads the\n   validator's structured response in-process (no Durable round-trip\n   between agent calls). Segment retry crosses Durable activity\n   boundaries; if the round-trip cost is unacceptable, use a graph.\n3. **Saga \u002F compensation chains where Durable round-trips per node\n   are unacceptable.** The phase composes ≥ 3 executors with\n   compensating actions that must execute atomically with respect to\n   each other; the orchestrator-level retry granularity is too coarse.\n\nEverything else — including the common \"one agentic skill produces a\nstructured output that the orchestrator hands to the next phase\" case\n— is **`kind: agent` (default segment)**. When in doubt, default to\nsegment.\n\nMechanically, `kind: agent` writes a segment file from\n`segment.py.tmpl` + a durable registration snippet from\n`segment_activity_trigger.py.tmpl`. `kind: graph` writes a per-phase\nMAF graph from `phase_graph.py.tmpl` + an in-graph validator from\n`validator.py.tmpl` + an agent executor from `agent_executor.py.tmpl`,\nand is registered in the pack's `durable.py` as a single\n`\u003Cwt_snake>_\u003Cphase>_activity_trigger` (no separate validator-trigger\n— validation happens inside the graph).\n\nAlways:\n- 1 orchestrator at `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>.py`.\n- 1 activities module at `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>_activities.py`.\n- 1 entity projection at `api\u002Fserver\u002Fservices\u002Fentity_projections\u002F\u003Cwt_snake>.py` (v4).\n- 1 Cypher precedent file per HITL phase at\n  `api\u002Fserver\u002Fservices\u002Fprecedent_queries\u002F\u003Cwt>_\u003Cphase>.cypher` (v4).\n- 1 ambient-agent block appended to\n  `api\u002Fserver\u002Fservices\u002Fambient_agents\u002F\u003Cfunction>.py` if the brief\n  carries an `ambient:` block (v4).\n- 1 `GRADUATION.md` at the sandbox root — human-readable description of\n  what the graduation script will do.\n- 1 `graduate.sh` at the sandbox root — the **executable** graduation\n  script. Mechanically copies files + edits the live trees described in\n  step 4.7.\n\nBefore declaring the graduated domain demo-ready, run the runtime gates in\n`CHECKLIST.md` §12. Static generation checks do not prove persona completion,\nDurable resume latency, or browser recovery after a backend journal reset.\n\nThe **blocking execution-visibility gate** in `CHECKLIST.md` §13 applies to\nevery active non-stub workflow type. Actual execution evidence must be visible\nand self-consistent; validate observed evidence rather than predicting\nconditional branches. Generated agent paths use `run_agent_session`. Use the\nlive\u002Freplay `tools\u002Fworkflow_visibility_proof.py` commands in `CHECKLIST.md`\n§13.\n\n### Conventions (codified for determinism)\n\nThese were free choices in earlier drafts; codifying them removes\nimprovisation from the procedure.\n\n- **`workflow_type` stamping.** Every `checkpoint_activity_trigger`\n  payload carries `workflow_type: workflow_type` (the variable read\n  once at the top of the orchestrator from `input_dict.get(\"type\")`).\n  Without this, recordings are filename `unknown-...` and FleetEvents\n  arrive with `domain: null`. (Substrate-fix v2 contract.)\n- **HITL `persona`\u002F`external_event`\u002F`context`.** Every `kind: \"suspended\"`\n  payload stamps the persona-responder contract:\n  - `persona`: brief.phases[].persona\n  - `external_event`: brief.phases[].external_event (or default\n    `\u003Cphase_name>_decision`)\n  - `context`: a dict whose keys are brief.phases[].context_keys (or\n    default just the previous phase's name), each pulling from\n    `enriched.get(\u003Ckey>)`.\n  Without this, the persona responder ignores the gate and the\n  workflow stalls forever.\n- **HITL external event name.** For every phase whose `kind: hitl`, the\n  orchestrator's `wait_for_external_event(...)` name and the persona\n  SKILL.md's `external_event` frontmatter MUST match byte-for-byte.\n- **HITL authority closure.** The governance authority matrix used by\n  `api.server.services.governance.kernel` MUST contain a rule matching each\n  HITL persona's emitted `action`, representative `category`, and value band.\n  A persona folder or pack `AuthorityRow` alone does not prove the runtime\n  kernel will approve it. Run `kernel().check_authority(...)` with a real\n  generated gate context and require `allowed=True`.\n- **HITL recovery metadata.** After a live suspend, the Workflow API payload\n  MUST contain `hitl_context` with `persona`, `external_event`, `phase`, and\n  the decision context. This is what `sweep_pending_hitl()` uses after a missed\n  bus event or server restart.\n- **Activity-trigger names.** `\u003Cdomain.name with - replaced by _>_\u003Cphase_name>_activity_trigger`.\n  E.g. `fleet_travel_preapproval_employee_lookup_activity_trigger`.\n- **Graph builder names.** `build_\u003Cdomain.name with - replaced by _>_\u003Cphase_name>_workflow`.\n- **Agent skill folder name.** `\u003Cdomain.name>-\u003Cagent_skill_name>`. E.g.\n  `fleet-travel-preapproval-policy-fit-checker`.\n- **Tool registration name.** From the brief's `external_systems[].mcp_tool` and\n  each `operations[].name`: `\u003Cmcp_tool>_\u003Coperation>`. E.g.\n  `concur_travel_policy_get_policy`. The agent skill's `allowed-tools`\n  CSV uses these names verbatim.\n- **Validator file name.** `validate_\u003Cdomain.name with - replaced by _>_\u003Cphase_name>_schema.py`.\n  E.g. `validate_fleet_employee_onboarding_access_drafter_schema.py`.\n  The full domain prefix is **required** — without it, two domains with\n  same-named agent phases (e.g. multiple \"drafter\" phases) will collide\n  in `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002F`.\n- **Validator class \u002F executor name.** `validate_\u003Cdomain.name with - replaced by _>_\u003Cphase_name>` (the file's name minus `_schema.py`). Same prefix-required reason.\n- **Run id.** `\u003CYYYYMMDD-HHMMSS>-\u003Cdomain.name>` from current UTC time.\n  Compute once at the top of step 4; use the literal value everywhere\n  downstream.\n\n### Step 3 — Inventory and isomorphism\n\n**Read-on-demand policy (NEW — 2026-05-21).** The 9 canonical examples below\nare the **fallback** when the [Shape cheat-sheet](#shape-cheat-sheet) at the\ntop of this file doesn't answer a byte-shape question. Do NOT read them\nupfront. Each sub-skill names which canonical file(s) IT needs in its own\n`## Canonical examples` block — read only those when invoking that sub-skill,\nand only the ranges named there.\n\nFor the orchestrator + spawn helper + factory + ambient block (the four\nshapes that account for ~95% of generation), the cheat-sheet is sufficient.\nThe 9 canonical files below are listed for when a sub-skill explicitly\npoints at one, or when you hit a shape question the cheat-sheet doesn't\ncover.\n\n| # | Canonical example | Used by sub-skill | Lines worth reading |\n|---|---|---|---|\n| 1 | `api\u002Fserver\u002Fskills\u002Freceipt-validator\u002FSKILL.md` | `author-runtime-skill` (phase_agent mode) | full (72) |\n| 2 | `api\u002Fserver\u002Fpersonae\u002Fline_manager\u002FSKILL.md` | `author-persona` (NEW v3) | full (63) |\n| 3 | `api\u002Fserver\u002Fservices\u002Fpersona_responder.py` | `author-persona` (decision_code shape + sandbox builtins) | grep for `_DECISION_BUILTINS` only |\n| 4 | `api\u002Fserver\u002Fmcp_tools\u002Fclaim_lookup.py` | `author-mcp-tool` | full (107) |\n| 5 | `api\u002Ffunctions\u002Fworkflows\u002Fexpense_claim.py` | `author-durable-domain` (orchestrator + HITL contract; v2-stamped) | full (194) — only if cheat-sheet is insufficient |\n| 6 | `api\u002Ffunctions\u002Fworkflows\u002Factivities.py` | `author-durable-domain` (activities module — reuses `_run_workflow` from here) | full (174) — only if cheat-sheet is insufficient |\n| 7 | `api\u002Ffunctions\u002Fgraphs\u002Fclassify.py` | `author-durable-domain` (per-phase agent graph) | full (37) |\n| 8 | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_rag_classifier.py` | `author-durable-domain` (agent executor) | full (35) |\n| 9 | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_classification_schema_node.py` | `author-durable-domain` (validator) | full (31) |\n\n**For deterministic phases**, also note: `api\u002Ffunctions\u002Fgraphs\u002F_tracked_executor.py`\nfor the `TrackedExecutor` constructor signature (used directly with\n`executor_type=\"deterministic\"` and an inline `_\u003Cphase>_execute` async\nfn — there is no canonical deterministic-graph example to mirror, so\nfollow the v1 graduated example at `api\u002Ffunctions\u002Fgraphs\u002Ffleet_travel_preapproval_employee_lookup.py`).\n\n**For the substrate-fix contract** (workflow_type stamping +\npersona\u002Fexternal_event\u002Fcontext on suspended payloads), the live\n`expense_claim.py` and `hiring.py` are the canonical implementation;\nthe new orchestrator MUST mirror their stamping shape exactly. The\ngenerated `fleet_travel_preapproval.py` is also a worked example.\n\n### Step 4 — Generate into sandbox\n\nCompute `RUN_ID = \u003CYYYYMMDD-HHMMSS>-\u003Cdomain.name>` from the current UTC\ntime (one shell call: `date -u +\"%Y%m%d-%H%M%S\"`). Create\n`tools\u002Fscratch\u002Fcompose-domain\u002F\u003CRUN_ID>\u002F` with the layout from the spec\ndoc §6.\n\nFor each artefact in the plan, invoke the matching sub-skill exactly\nonce, passing the **structured arguments** below. Do not pass the brief\nas a whole — pass only the relevant slice. This is the boundary that\nkeeps sub-skills deterministic.\n\n#### When invoking `author-runtime-skill` (phase_agent only)\n\nv3 note: persona authoring is now `author-persona`, not\n`author-runtime-skill`. `author-runtime-skill` only writes phase-agent\nSKILL.md files now.\n\n```\nmode: phase_agent\noutput_path: \u003CRUN_ROOT>\u002Fapi\u002Fserver\u002Fskills\u002F\u003Cdomain.name>-\u003Cphase.agent_skill_name>\u002FSKILL.md\nbrief: \u003Cthe phase entry from brief.phases[]>\ncanonical_example_path: api\u002Fserver\u002Fskills\u002Freceipt-validator\u002FSKILL.md\navailable_mcp_tools:\n  - { name: \"\u003Cmcp_tool>_\u003Coperation>\", description: \"\u003Cfrom the tool's @define_tool description>\" }\n  - ... (one per (mcp_tool, operation) pair the phase's external_systems[] resolves to)\n```\n\n#### When invoking `author-persona` (NEW v3)\n\n```\noutput_path: \u003CRUN_ROOT>\u002Fapi\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002FSKILL.md\nbrief: \u003Cthe persona entry from brief.personae[]>\ndomain_display_name: \u003Cbrief.domain.display_name>\ndefault_external_event: \u003Chitl_phase_name>_decision   # convention\ncanonical_example_path: api\u002Fserver\u002Fpersonae\u002Fline_manager\u002FSKILL.md\nresponder_path: api\u002Fserver\u002Fservices\u002Fpersona_responder.py  # for builtins reference\n```\n\n#### When invoking `author-mcp-tool`\n\n```\noutput_path: \u003CRUN_ROOT>\u002Fapi\u002Fserver\u002Fmcp_tools\u002F\u003Cexternal_systems[].mcp_tool>.py\ntool_brief: \u003Cthe external_systems[] entry>\ncanonical_example_path: api\u002Fserver\u002Fmcp_tools\u002Fclaim_lookup.py\n```\n\n#### When invoking `author-durable-domain`\n\n```\noutput_root: \u003CRUN_ROOT>\nvertical: \u003Cselected vertical>\nartifact_plan: \u003Cthe approved Step 2 artifact list>\nbrief: \u003Cthe entire brief>\ncanonical_paths:\n  orchestrator: api\u002Ffunctions\u002Fworkflows\u002Fexpense_claim.py\n  activities: api\u002Ffunctions\u002Fworkflows\u002Factivities.py\n  agent_graph: api\u002Ffunctions\u002Fgraphs\u002Fclassify.py\n  deterministic_graph: api\u002Ffunctions\u002Fgraphs\u002Ffleet_travel_preapproval_employee_lookup.py  # v1 graduated\n  agent_executor: api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_rag_classifier.py\n  validator: api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_classification_schema_node.py\n  tracked_executor: api\u002Ffunctions\u002Fgraphs\u002F_tracked_executor.py\n```\n\nEach sub-skill writes its files to the sandbox path under the mirrored\nreal-tree layout. **No sub-skill writes to a real path.** When a\nsub-skill returns, you continue with the next.\n\nAfter all sub-skills have run, two more files remain for `compose-domain`\nitself to write:\n\n- `\u003CRUN_ROOT>\u002FGRADUATION.md` — human-readable description of what\n  graduate.sh does. Use the template at\n  `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002FGRADUATION.md.tmpl`.\n  This file is reference, not action.\n- `\u003CRUN_ROOT>\u002Fgraduate.sh` — the **executable** script that mechanically\n  performs all the live-tree edits. Use the template at\n  `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fgraduate.sh.tmpl`.\n  `author-durable-domain` returns the structured fragments (orchestrator-\n  import block, activity-trigger block, ramp-loop spawner entry,\n  inventory DOMAIN entry, etc.) for you to splice into the template.\n  Supply `VERTICAL_NAME`, `SPAWNER_REGISTRATION_BLOCK`,\n  `DOMAIN_DECLARATION_BLOCK`, and `FUNCTION_MEMBERSHIP_BLOCK`. These\n  blocks must append to the selected pack's modules; they must not patch\n  `function_app.py`, `api\u002Fshared\u002F*`, Blueprint inventory, or another\n  vertical.\n  Mark the file executable (`chmod +x`).\n\n  The graduate.sh script performs six idempotent pack-scoped steps:\n  1. Validate the selected pack and sandbox layout.\n  2. Copy generated files (`skills\u002F`, `personae\u002F`, `mcp_tools\u002F`,\n     `entity_projections\u002F`) into `verticals\u002F\u003Cvertical>\u002F`.\n  3. Register the orchestrator and activities on the pack's `durable.py`\n     (sentinel-guarded append).\n  4. Export graph builders into `api\u002Ffunctions\u002Fgraphs\u002F__init__.py`\n     (implementation modules may remain under `api\u002Ffunctions\u002F`).\n  5. Register the spawner, domain declaration, and function membership on\n     the pack's `spawners.py` \u002F `domains.py` \u002F `functions.py`\n     (sentinel-guarded appends). Never patches global compatibility\n     adapters or another vertical's modules.\n  6. Validate the active pack (`active_runtime().pack.domains` must\n     include the new `workflow_type`) and print smoke commands.\n\n  Each step is idempotent: if the domain has already been graduated\n  (sentinel already present), the step is a no-op.\n\n### Step 5 — Self-check\n\nRun the checklist at `compose-domain\u002FCHECKLIST.md` against the sandbox.\nProduce a one-page report at `\u003Crun-id>\u002FREPORT.md` with one row per\nchecklist item (PASS \u002F FAIL \u002F N\u002FA). Print the same report inline to the\noperator.\n\nIf any item FAILs, **do not** silently fix it. Tell the operator and stop.\nThe right move when something fails is almost always to fix the SKILL.md\nthat produced it, then delete the sandbox and re-run.\n\nIf everything passes, end with:\n\n> Sandbox at `tools\u002Fscratch\u002Fcompose-domain\u002F\u003CRUN_ID>\u002F`. CHECKLIST passed.\n> Graduate by running `bash \u003CRUN_ID>\u002Fgraduate.sh` from repo root.\n> Then proceed to Step 7 (recorder verification).\n\nDo not graduate. Do not start the demo stack. Do not run any tests against\nthe real trees. The skill ends here — the operator runs graduate.sh.\n\n### Step 6 — Determinism check (operator-invoked, optional)\n\nThe operator may, after a clean self-check, re-invoke this skill against\nthe same brief and run the determinism check at\n`compose-domain\u002FCHECKLIST.md` §6.1. The two sandboxes must `diff -r` to\nnothing meaningful. Divergence points are exactly the parts of these\nSKILLs that gave the author freedom — the fix is to codify that part\nhere or in the matching sub-skill, then re-run.\n\nThe HITL event-name convention, the activity-trigger naming convention,\nthe structured sub-skill input contracts in step 4 above, and the v3\nworkflow_type \u002F persona-contract stamping rules are the specific fixes\nthat emerged from the v1 → v2 → v3 iteration of this SKILL. Future\niterations follow the same loop: improvise once, codify, re-run, diff.\n\n### Step 7 — Recorder verification (post-graduation, NEW v3)\n\nAfter the operator runs `graduate.sh` and confirms the smoke output is\ngreen, prompt them to record real walks for the new domain so the\ndeployed page replays them. Print these commands verbatim:\n\n```bash\n# 1. Boot the autonomous stack so the new domain spawns automatically.\n#    Functions host + azurite already running.\n.\u002Fscripts\u002Fprofile-autonomous.sh &\nsleep 30\n\n# 2. Start the recorder.\ncurl -X POST http:\u002F\u002Flocalhost:3101\u002Fapi\u002Fblueprint\u002F_recorder\u002Fstart\n\n# 3. Let it run ~5 minutes so each domain completes ≥3 walks.\nsleep 300\n\n# 4. Stop the recorder; flush.\ncurl -X POST http:\u002F\u002Flocalhost:3101\u002Fapi\u002Fblueprint\u002F_recorder\u002Fstop\n\n# 5. Inspect; prune any partial \u002F single-event noise files; commit.\nls -la data\u002Fblueprint-recordings\u002F\u003Cdomain.name>-*.jsonl\nfind data\u002Fblueprint-recordings -name '*.jsonl' -size -200c -delete\ngit add data\u002Fblueprint-recordings\u002F\u003Cdomain.name>-*.jsonl\ngit commit -m \"record(blueprint): real walks for \u003Cdomain.display_name>\"\n\n# 6. Redeploy the container app so the deployed page picks up the\n#    new recordings (proof-gated — requires ZAVA_MODE=replay and proof artefacts).\nZAVA_MODE=replay EXPECTED_TENANT_ID=\u003Cyour-tenant-id> .\u002Fscripts\u002Fdeploy-blueprint.sh\n```\n\nWith this step, the new domain becomes visible on the deployed page\nwithin minutes of graduation. No synthetic templates needed.\n\n## How to author a new domain brief (v4 worked example)\n\nThe 19 briefs at `docs\u002Fsuperpowers\u002Fspecs\u002Farchive\u002F*-brief.yaml` are the\nauthoritative spec for every generated domain (they live under\n`archive\u002F` because they have already been graduated; new briefs are\nauthored under `docs\u002Fsuperpowers\u002Fspecs\u002F` and archived after\n`graduate.sh` succeeds). To author a new one:\n\n1. **Pick a workflow_type** — kebab-case, lowercase, e.g.\n   `purchase-card`. This name is stamped on every payload, every\n   FleetEvent, and every Cypher file the codegens emit.\n2. **Copy the worked example.** The freshest brief —\n   `docs\u002Fsuperpowers\u002Fspecs\u002Farchive\u002Ffleet-purchase-card-brief.yaml` — was\n   authored top-down without a hand-written projection module. It\n   exercises every section the v4 schema cares about (domain,\n   phases, entities, decisions, function, ambient) at the smallest\n   plausible size. Use it as the template.\n3. **Fill in the entity\u002Fdecision shape.** Each `entities[]` entry\n   declares one node the projection will write per workflow; each\n   `decisions[]` entry declares one Decision node per HITL gate. The\n   codegens at `sub-skills\u002Fauthor-entity-projection\u002Fcodegen.py` and\n   `sub-skills\u002Fauthor-decision-mapping\u002Fcodegen.py` consume these.\n4. **Validate.** Run the brief through\n   `_shared.brief_validator.validate_brief(...)` (the smoke test at\n   `tests\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose_domain\u002Ftest_fleet_purchase_card_smoke.py`\n   shows the import path). The validator surfaces schema errors with\n   stable `path` field for assertions.\n5. **Hand off to graduate.** The compose-domain orchestrator above\n   handles the rest — the brief is the only operator-authored file.\n\n### Walking through a segment-default agent phase\n\nConcrete example for an agentic phase generated under the default\n`kind: agent` (segment-by-default) path. Assume the brief contains:\n\n```yaml\ndomain: { workflow_type: vendor-kyc, prefix: fleet, display_name: \"Vendor KYC\" }\nphases:\n  - { name: vendor_intake, kind: deterministic, intent: \"Capture vendor name + country.\" }\n  - name: kyc_diligence            # ← agentic phase, default segment shape\n    kind: agent\n    agent_skill_name: kyc-diligence-checker\n    intent: \"Resolve UBOs, sanctions, adverse-media.\"\n    external_systems: [companies_house, sanctions_api]\n  - { name: finance_signoff, kind: hitl, persona: vendor_kyc_finance_bp,\n      external_event: finance_signoff_decision }\n```\n\nFor the `kyc_diligence` phase, `compose-domain` generates **a segment\nactivity, not a MAF graph**:\n\n1. **Pick the segment letter.** Segments are letter-indexed within a\n   workflow_type (A for the first segment, B for the second, …). For\n   a single-segment workflow the letter is `b` by convention (mirrors\n   `hiring_b`); for multi-segment workflows allocate in order.\n   Example: `kyc_diligence` becomes Segment **B** of vendor-kyc →\n   `api\u002Ffunctions\u002Fsegments\u002Fvendor_kyc_b.py`.\n2. **Render `segment.py.tmpl`.** Fill in:\n   - `SKILL_LIST_LINES` — every `\u003Cwt>-\u003Cskill>` SKILL.md the segment\n     should auto-load (the phase's own `agent_skill_name` plus any\n     adjacent agentic skills the operator decides belong in the same\n     CopilotSession).\n   - `MCP_LIST_LINES` — the MCP tools resolved from the phase's\n     `external_systems[]`.\n   - `OUTPUT_MODEL_BODY` — the Pydantic `SegmentBOutput(BaseModel)`\n     class. One field per structured output the orchestrator reads\n     downstream (see `enriched.get(...)` references in the\n     orchestrator + HITL payloads). Custom validators go on the\n     model, not in a separate file.\n   - `SEGMENT_GOAL_SENTENCE` — one sentence describing the deliverable,\n     matching the phase's `intent`.\n3. **Render `segment_activity_trigger.py.tmpl`** to produce the\n   `durable.py` registration snippet. This emits **two** activity triggers:\n   - `vendor_kyc_segment_b_activity_trigger` — calls\n     `run_segment_b(input)`.\n   - `validate_vendor_kyc_segment_b_output_activity_trigger` — Pydantic-\n     validates and returns `{ok, output|errors}`. The Pydantic errors\n     are JSON-serialised via `json.loads(e.json())` so Durable does not\n     reject them.\n4. **Wire the orchestrator retry loop.** The orchestrator generated\n   from `orchestrator.py.tmpl` MUST call the pair inside a\n   `for attempt in range(segment_max_retries + 1)` loop, feeding\n   `validator[\"errors\"]` back as `prior_validator_error` on retry, and\n   breaking when `validator[\"ok\"]`. Copy the loop shape from\n   `api\u002Ffunctions\u002Fworkflows\u002Fhiring.py:120-162`. Keep the canonical\n   control-plane and Durable identities separate in `enriched` as\n   `\"workflow_id\": workflow_id` and\n   `\"instance_id\": context.instance_id`; never replace the former with\n   the latter. Add `\"covered_phases\"` to `segment_input`, listing every\n   declared phase handled by that one CopilotSession, and forward it to\n   `run_agent_session`.\n5. **Graduate.** `graduate.sh` copies the segment file under\n   `api\u002Ffunctions\u002Fsegments\u002F` and appends the triggers to the pack's\n   `durable.py` between sentinel markers. No new file under\n   `api\u002Ffunctions\u002Fgraphs\u002F` is created for this phase; no entry in\n   `api\u002Ffunctions\u002Fgraphs\u002F__init__.py` is added.\n\nThe runtime SKILL.md for `vendor-kyc-kyc-diligence-checker` is still\ngenerated the same way it was for `kind: graph` (via\n`author-runtime-skill` in `phase_agent` mode). The only thing that\nchanges between segment and legacy graph paths is the *carrier* of\nthe agent — segment activity vs. MAF graph.\n\n### Appendix — legacy `kind: graph` walkthrough\n\nWhen the brief explicitly sets `kind: graph` (because one of the three\ncriteria in \"When to use kind:graph\" applies), the per-phase output\nshape reverts to the v3 MAF-graph form. For the same `kyc_diligence`\nphase:\n\n```yaml\n  - name: kyc_diligence\n    kind: graph                     # explicit opt-in\n    agent_skill_name: kyc-diligence-checker\n    intent: \"Resolve UBOs, sanctions, adverse-media.\"\n    external_systems: [companies_house, sanctions_api]\n```\n\n`compose-domain` then generates three files (none of which are written\nunder the segment path):\n\n1. `api\u002Ffunctions\u002Fgraphs\u002Ffleet_vendor_kyc_kyc_diligence.py` from\n   `phase_graph.py.tmpl` — `WorkflowBuilder` wiring\n   `agent → validator → terminal`.\n2. `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_fleet_vendor_kyc_kyc_diligence.py`\n   from `agent_executor.py.tmpl` — single-skill `run_agent_session` call.\n3. `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_fleet_vendor_kyc_kyc_diligence_schema.py`\n   from `validator.py.tmpl` — in-graph validator returning\n   `{\"ok\": bool, ...}` (NOT a Pydantic model; the graph terminal\n   handles the `ok=False` branch).\n\nThe pack's `durable.py` gets ONE activity trigger\n(`vendor_kyc_kyc_diligence_activity_trigger`) instead of the pair, and\nthe graph builder is exported from `api\u002Ffunctions\u002Fgraphs\u002F__init__.py`.\nThe orchestrator calls the trigger once per attempt (no in-orchestrator\nretry loop — retry, if any, is the graph's responsibility).\n\nPrefer the segment-default path. Reach for this appendix only when one\nof the three \"When to use kind:graph\" criteria genuinely applies.\n\nThe 12 backfill briefs (everything matching `docs\u002Fsuperpowers\u002Fspecs\u002F*-brief.yaml`\nthat is NOT `fleet-purchase-card`) document the entity\u002Fdecision shape\nof the corresponding hand-written Phase 1 projection module at\n`api\u002Fserver\u002Fservices\u002Fentity_projections\u002F\u003Cwt_snake>.py`. The\nhand-written modules carry domain-specific helper logic (period\nderivation, conditional asset emission, JSON-blob attribute\nserialisation, risk-band heuristics) that no schema-driven codegen\ncan synthesise from a brief alone — the briefs are documentation of\nintent, not a regenerable source for those modules.\n\n## Anti-patterns (things you must not do)\n\n- Inventing fields not present in the brief.\n- Inventing the HITL external event name. Convention is\n  `\u003Cphase_name>_decision`. The orchestrator's\n  `wait_for_external_event(...)` and the persona SKILL.md both write\n  this exact string.\n- Inventing tool names in an agent skill's `allowed-tools`. The\n  `author-runtime-skill` step 4 list is authoritative — if a tool you\n  want isn't there, it's the caller's bug, not yours. Stop.\n- Copying a runtime SKILL.md verbatim from `api\u002Fserver\u002Fskills\u002F` and just\n  renaming things — the result must be an *authored* skill, not a\n  rebadged one.\n- Skipping the validator on agent phases (\"it's a stub, the validator is\n  trivial\"). Validators are the bounded-probabilism edge; the harness\n  expects them.\n- Ignoring the read-on-demand policy by reading every canonical example\n  upfront, or generating a byte-shape without reading the specific fallback\n  example when the cheat-sheet is insufficient.\n- Directly editing live-tree pack files (`durable.py`, `domains.py`,\n  `spawners.py`, `functions.py`) \"just to make the smoke test work\". That's\n  graduation. It happens by hand. By an engineer. After this skill ends.\n- Graduating \"while you're at it\" because the sandbox looks fine. Stop.\n- Pretending you finished when you didn't. If you got blocked, say so. If\n  you skipped a step, say so. If a sub-skill returned something the\n  CHECKLIST won't pass, say so.\n\n## Operator-facing prompts\n\nWhen you ask the operator a question, you are explicit about what you\nneed:\n\n- \"Brief at `docs\u002Fsuperpowers\u002Fspecs\u002F\u003Cx>-brief.yaml` validates. Plan\n  follows. Confirm before I generate.\"\n- \"Step 3 noted that `api\u002Ffunctions\u002Fgraphs\u002Fclassify.py` has changed shape\n  since this skill was last revised. Stopping. Please update\n  `compose-domain\u002FSKILL.md` step 3 with the new canonical paths and\n  re-invoke.\"\n- \"CHECKLIST item §3.4 FAIL: agent skill `\u003Cx>` references MCP tool `\u003Cy>`\n  in `allowed-tools` but no such tool exists in the sandbox or\n  `api\u002Fserver\u002Fmcp_tools\u002F`. The bug is probably in\n  `author-runtime-skill\u002FSKILL.md` step 4 (allow-list resolution).\n  Stopping.\"\n","# compose-domain\n\n## Authority\n\nThis skill implements the code-first\n[Vertical Build Contract](..\u002F..\u002Fcontracts\u002FVERTICAL-BUILD-CONTRACT.md).\nThe brief and generators own repeatable workflow scaffolding; they do not\nreplace bespoke pack code when a novel capability does not fit the current\nartifact plan.\n\nYou are the orchestrator for a five-step procedure that turns a domain brief\ninto a complete sandboxed Durable-fidelity domain. You do not improvise. You\nfollow this skill literally. When you are uncertain, you stop and ask the\noperator — you do not invent.\n\n> **Forbidden.** This skill, and any sub-skill it invokes, **MUST NOT**\n> write to any path outside `tools\u002Fscratch\u002Fcompose-domain\u002F\u003Crun-id>\u002F` and\n> `docs\u002Fsuperpowers\u002Fspecs\u002F`. In particular: never edit\n> `api\u002Fserver\u002F`, `api\u002Ffunctions\u002F`, `function_app.py`,\n> `api\u002Fserver\u002Fservices\u002Fblueprint_inventory.py`,\n> `api\u002Fserver\u002Fservices\u002Fsimulator_orchestrator.py`, or any other live tree.\n> Graduation is a separate, manual step.\n\n## Inputs\n\nYou are invoked one of two ways:\n\n1. **With a brief path.** \"Run compose-domain against\n   `docs\u002Fsuperpowers\u002Fspecs\u002F\u003Cdomain>-brief.yaml`.\" Skip step 1.\n2. **With a free-text idea.** \"Compose a new domain for X.\" Run step 1 to\n   produce the brief, then continue.\n\n### Vertical target\n\nEvery run targets one vertical: explicit `vertical=\u003Cname>`, otherwise the\nactive `ZAVA_VERTICAL`, otherwise `agency`. Sandbox paths retain their legacy\nshape for generator compatibility, but graduation maps business assets to:\n\n```text\nverticals\u002F\u003Cvertical>\u002Fskills\u002F\nverticals\u002F\u003Cvertical>\u002Fpersonae\u002F\nverticals\u002F\u003Cvertical>\u002Fmcp_tools\u002F\nverticals\u002F\u003Cvertical>\u002Fentity_projections\u002F\nverticals\u002F\u003Cvertical>\u002Fdomains.py\nverticals\u002F\u003Cvertical>\u002Ffunctions.py\n```\n\nWorkflow implementation modules may remain under `api\u002Ffunctions\u002F`; only the\nselected pack's Durable module registers them. Never graduate a Telco asset\ninto an Agency-owned legacy root.\n\n## Fast-path read budget (NEW — 2026-05-21)\n\n**Goal: start emitting files within 3 minutes, not 7.** This skill historically\nmandated reading ~30 files (~6400 lines, ~300 KB) up front before any\ngeneration. That ate 5–7 minutes of every run. The new policy is **read on\ndemand**:\n\n1. **Read upfront (must) — ~700 lines total:**\n   - this SKILL.md (you are reading it now — keep going)\n   - `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fbrief.schema.yaml` (232 lines)\n   - `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FCHECKLIST.md`\n   - the input brief itself\n2. **Read just-in-time (read only when about to invoke that sub-skill):**\n   - each sub-skill `SKILL.md` under `sub-skills\u002F\u003Cname>\u002F` (60–120 lines each)\n   - each template under `templates\u002F\u003Cname>.tmpl` (15–100 lines each)\n3. **Read on demand (only when you need to verify a byte-shape):**\n   - the 9 canonical examples in [Step 3](#step-3--inventory-and-isomorphism). Each\n     sub-skill names which canonical files IT needs in its own `## Canonical\n     examples` block — read only those, and only the ranges named there.\n     **Do not read all 9 upfront.** Use the [Shape cheat-sheet](#shape-cheat-sheet)\n     below for the most common cases; canonical reads are the fallback when the\n     cheat-sheet doesn't cover your case.\n4. **Always batch reads in a single tool-call response when reading multiple\n   files.** view tool calls are parallel-safe. The previous serial pattern\n   (one file per turn, ~10s per turn) was a quarter of the wall-clock cost.\n\nIf you are dispatched as a subagent, the parent's prompt may instruct you to\n\"read all 25 canonical files end-to-end\" — **ignore that and follow the budget\nabove instead**. The end-state contract (CHECKLIST passes; byte-shapes match\nthe live tree) is the same; the route to it is faster.\n\n## Shape cheat-sheet\n\nFor the common cases the codegen has to produce, here are the byte-shapes\nyou need so you do **not** need to re-read the canonical examples every run:\n\n### Orchestrator (sync generator)\n```python\ndef fleet_\u003Cwt_snake>_orchestration(\n    context: df.DurableOrchestrationContext,\n) -> Generator[Any, Any, dict]:\n    input_dict = context.get_input() or {}\n    workflow_type = input_dict.get(\"type\")\n    workflow_id   = input_dict.get(\"workflow_id\")\n    # ... per-phase yield context.call_activity(\u003Cphase>_activity, payload)\n    # ... for HITL: yield context.wait_for_external_event(\u003Cexternal_event>)\n```\n- Every `checkpoint_activity_trigger` payload MUST carry\n  `workflow_type=workflow_type` (substrate-fix v2 contract).\n- Every `kind: \"suspended\"` payload MUST stamp\n  `persona`, `external_event`, `context` keys (substrate-fix v2 contract).\n- Per-phase timeouts: declare locally as\n  `\u003CPHASE>_TIMEOUT = timedelta(hours=...)`.\n\n### Spawn helper (in the pack's `spawners.py`)\nThe generated block appended by graduate.sh step 5:\n```python\nasync def spawn_\u003Cwt_snake>_workflow(...) -> str:\n    global _\u003Cseq>_seq; _\u003Cseq>_seq += 1\n    wid = f\"\u003CPREFIX>-{_\u003Cseq>_seq:04d}\"\n    record = _pick_record(\"\u003Cwt>\", scenario=scenario) or {}\n    payload = {\"workflow_id\": wid, \"type\": \"\u003Cwt>\", \"\u003Centity>\": record.get(\"\u003Centity>\")}\n    try:\n        result = await schedule_new_orchestration(payload, function_name=\"Fleet\u003CWt>Orchestrator\")\n    except Exception as ex:\n        print(f\"[orchestrator] failed to schedule {wid}: {ex}\")\n    return wid\n```\nThis block is written inside the selected pack's `spawners.py`, not into any\nglobal service module.\n\n### HITL `external_event` byte-match\nWhenever a HITL phase reuses an existing persona under `api\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002F`,\nthe brief's `external_event` MUST byte-match the persona's SKILL.md frontmatter\n`external_event:` line. Grep it once, copy it verbatim. The convention default\n`\u003Cphase>_decision` will silently stall the workflow.\n\n### Ambient agent block\nModule-level constant (NOT `ambient_registry.append`):\n```python\n\u003CName>Watcher = AmbientAgent(\n    name=\"\u003Ckebab-case>-watcher\",\n    function=\"\u003Cfunction>\",\n    triggers=(BusTrigger(event_type=\"\u003Cevent>\"),),\n    reasoning_skill=None,\n    spawnable_workflow_types=(\"\u003Cwt>\",),\n)\n```\n\n### Persona decision_code sandbox builtins\nThe persona responder's sandbox does NOT include `import`, `open`, `os`,\n`subprocess`, `eval`, `__import__`, or `sorted()`. Use `list.sort()` (in-place,\nreturns None — assign separately). Read `(context or {}).get(\"\u003Cphase>\")` to\npull prior-phase outputs.\n\nIf the cheat-sheet doesn't cover your case, fall back to reading the relevant\ncanonical file in Step 3 — but only the file(s) you need, not all 9.\n\n## Current sequential enrichment pipeline\n\nv4 reshapes the meta-skill into a **sequential enrichment pipeline**:\na shared YAML brief grows through five new authoring sub-skills, each\nadding one new top-level section, validating, and handing off to the\nnext. The four existing v3 generators run last, unchanged, and are\njoined by two new codegens for entity-projections and decision Cypher.\n\n```mermaid\nflowchart LR\n    A[free-text idea\u003Cbr\u002F>or brief path] --> B[author-domain-skeleton]\n    B -->|+domain\u003Cbr\u002F>+phases| C[author-entity-projection]\n    C -->|+entities| D[author-decision-mapping]\n    D -->|+decisions| E[author-function-membership]\n    E -->|+function| F[author-ambient-trigger?]\n    F -->|+ambient| G[v3 generators\u003Cbr\u002F>orchestrator\u002Fgraphs\u002F\u003Cbr\u002F>personae\u002FMCP]\n    G --> H[graduate.sh]\n```\n\nThe five enrichment sub-skills live under\n`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fsub-skills\u002F\u003Cname>\u002F` and each\npackage contains:\n\n* `SKILL.md` — the prompt the sub-skill is invoked with\n* `validator.py` — pure function `validate(brief, ...) -> None` raising\n  `SchemaError(path, reason)` on failure\n* `codegen.py` (when applicable) — pure function returning the\n  rendered file body \u002F append block\n\nThe brief schema is authoritative at\n`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fbrief.schema.yaml`. The\nsandbox layout is documented at\n`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FSANDBOX.md`.\n\n## The seven-step procedure\n\n### Step 1 — Brief intake (only if no YAML brief was supplied)\n\nHand off to the existing `brainstorming` skill. It will elicit the brief\nthrough one-question-at-a-time dialogue with the operator. When it returns\nthe design, transcribe it into the YAML schema below and write it to\n`docs\u002Fsuperpowers\u002Fspecs\u002F\u003Cdomain.name>-brief.yaml`. Read it back to the\noperator. Wait for explicit approval. Then continue to step 2.\n\nIf the operator gives you a YAML brief path on entry, skip this step.\n\n#### Brief schema (authoritative pointer)\n\nThe authoritative schema lives at\n[`docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fbrief.schema.yaml`](brief.schema.yaml)\n(JSON-Schema 2020-12). The brief is **one YAML file** that grows\nthrough five conceptual passes (v0..v5):\n\n```\nv0  (skeleton)                  : domain + phases [+ personae + external_systems for v3 back-compat]\nv1  (entity-projection)         : + entities[]\nv2  (decision-mapping)          : + decisions[]\nv3  (function-membership)       : + function\nv4  (ambient-trigger, optional) : + ambient\nv5  (sealed)                    : ready for codegen + graduate.sh\n```\n\nTop-level shape (see `brief.schema.yaml` for the full grammar and\nthe `fleet-purchase-card-brief.yaml` example for a fully-populated\nv4 brief):\n\n```yaml\ndomain:\n  workflow_type: \u003Ckebab-case, ^[a-z][a-z0-9-]*$ — must NOT collide with the selected pack's domains (active_runtime().pack.domains)>\n  prefix: \u003Csnake_case file-name prefix, almost always \"fleet\">\n  display_name: \u003Chuman label>\n  description: |\n    One paragraph at the level a senior engineer would write on a whiteboard.\n  # Optional v3 back-compat keys: name, owner_role.\n\nphases:\n  - name: \u003Csnake_case>\n    kind: deterministic | agent | hitl | sub_orchestrator | graph\n    intent: \u003Cone sentence>\n    external_systems: [\u003Cid>, ...]    # optional; ids from the top-level external_systems list\n    # only when kind == agent (default) or kind == graph (legacy):\n    agent_skill_name: \u003Ckebab-case>\n    # only when kind == hitl:\n    persona: \u003Crole from personae below>\n    external_event: \u003Csnake_case>     # convention: \u003Cphase_name>_decision\n    # only when kind == sub_orchestrator (Phase 4 IP4 \u002F TASK-019):\n    target_workflow_type: \u003Ckebab-case; must already exist in DOMAINS>\n    target_orchestrator: \u003CPascalCase override; defaults to \u003CPrefix>\u003CWorkflowType>Orchestrator>\n    payload_from: \u003CCypher template OR python:\u003Cdict-builder expr>>\n    parallel_group: \u003Csnake_case; sub_orch phases sharing this label fan out via task_all>\n\n# v3 back-compat blocks (still tolerated):\npersonae:\n  - role: \u003Csnake_case>\n    decision_policy: |\n      One paragraph stating the rule the persona uses to decide.\n    decision_code: |\n      # Sandboxed Python the persona_responder compiles. Reads `context`,\n      # assigns `decision` ∈ {approve, reject, escalate} and `reason`.\n      # See api\u002Fserver\u002Fservices\u002Fpersona_responder.py:_DECISION_BUILTINS for\n      # the allowed builtins. No `import`, `open`, `os`, `subprocess`,\n      # `eval`, `__import__`.\n      pass\n    workflow_label: \u003Chuman label>   # OPTIONAL; defaults to domain.display_name\nexternal_systems:\n  - id: \u003Csnake_case>\n    mcp_tool: \u003Csnake_case Python module name, no .py>\n    operations: [\u003Csnake_case function name>, ...]\n\n# v4 enrichment blocks:\nentities:\n  - kind: \u003Cmember of api.server.services.entity_graph._VALID_KINDS>\n    ref_field: payload.\u003Cdotted_path>\n    source: \u003Cfree-form sub-kind label>\n    attributes: { \u003Ckuzu_col>: payload.\u003Cdotted_path>, ... }\n    relations:\n      - kind: \u003Cmember of _VALID_RELS>\n        target_ref: \u003Canother entity's ref_field OR an entity_id literal>\n\ndecisions:\n  - phase: \u003Cname of a hitl phase>\n    persona: \u003Crole from personae>\n    source_event: workflow.hitl.requested\n    decided_on_entities: [payload.\u003Cdotted_path>, ...]\n    attributes_from_context: { \u003Ckey>: payload.\u003Cdotted_path>, ... }\n\nfunction: finance | hr | revenue | ops | legal | marketing | tech | data | customer-success | legacy\n\nambient:                              # OPTIONAL\n  name: \u003CPascalCase>\n  function: \u003Csame as top-level function>\n  reasoning_skill: \u003Ckebab-case OR null>\n  spawnable_workflow_types: [\u003Cworkflow_type>, ...]\n  triggers:\n    - kind: bus|cypher|cadence\n      # bus:     event_type, filter\n      # cypher:  pattern, sweep_seconds\n      # cadence: cron\n```\n\nValidate the brief before you continue:\n\n- `domain.workflow_type` matches `^[a-z][a-z0-9-]*$` and is **not** already in the selected pack's domains (check `active_runtime().pack.domains`; the pack is determined by `vertical=\u003Cname>` or `ZAVA_VERTICAL`).\n- `domain.prefix` matches `^[a-z][a-z0-9_]*$`.\n- Every phase referenced under `external_systems` exists in the top-level `external_systems` list.\n- Every persona referenced in a HITL phase exists in `personae` (or already as a folder under `api\u002Fserver\u002Fpersonae\u002F`).\n- Every persona has a `decision_code` block.\n- At least one phase has `kind: agent`.\n- At least one phase has `kind: hitl`.\n- `function:` is one of the 10 canonical keys above.\n- Every entity `kind` is in `_VALID_KINDS`; every relation `kind` is in `_VALID_RELS`.\n- If `ambient:` is present, `ambient.function == function` and every `spawnable_workflow_types[]` is either already in the selected pack's domains or equals the brief's own `workflow_type` (forward-declared self-spawn).\n\nIf validation fails, stop and tell the operator what's wrong. Do not\nproceed to step 2.\n\n### Step 2 — Plan\n\nFrom the brief, produce the artefact list. **Print this list back to the\noperator before you write a single file.** Wait for \"go\".\n\n> **v4 path placeholders.** Older copies of this SKILL used `\u003Cdomain.name>`\n> as a single placeholder. Under v4 the brief splits the kebab identifier\n> from the file-name prefix, so the conventions below use:\n>\n> - `\u003Cwt>`        = `domain.workflow_type` (kebab-case, e.g. `purchase-card`)\n> - `\u003Cwt_snake>`  = `wt.replace(\"-\", \"_\")`  (e.g. `purchase_card`)\n> - `\u003Cprefix>`    = `domain.prefix`          (snake_case, almost always `fleet`)\n>\n> Where v3 said `\u003Cdomain.name>` (e.g. `fleet-travel-preapproval`),\n> read it as `\u003Cprefix>-\u003Cwt>` for skills\u002Ffolders and\n> `\u003Cprefix>_\u003Cwt_snake>` for orchestrator\u002Factivities\u002Fgraph file names.\n> The 12 backfill briefs and `fleet-purchase-card-brief.yaml` are the\n> canonical worked examples.\n\nFor each phase, the default output shape is **segments-by-default**\n(Phase 5 of `plan\u002Frefactor-substrate-agentic-segments-1.md`). The legacy\nper-phase MAF graph shape is now opt-in via `kind: graph` — see\n\"When to use kind:graph\" below for the three criteria.\n\n- `kind: deterministic` → 1 MAF graph file with a single deterministic\n  executor. No agent skill. May still have a validator.\n- `kind: agent` (default agentic shape) → 1 **segment activity** at\n  `api\u002Ffunctions\u002Fsegments\u002F\u003Cwt_snake>_\u003Csegment_letter>.py` with a\n  Pydantic `Segment\u003CLetter>Output` model and a matching\n  `validate_\u003Cwt_snake>_segment_\u003Cletter>_output_activity_trigger`\n  registered in the pack's `durable.py`. The orchestrator wraps the segment\n  in a retry loop driven by the validator (see\n  `api\u002Ffunctions\u002Fworkflows\u002Fhiring.py:120-162` for the canonical loop;\n  `SEGMENT_MAX_RETRIES` defaults to 2). One runtime SKILL.md per\n  participating skill at `api\u002Fserver\u002Fskills\u002F\u003Cwt>-\u003Cskill_name>\u002F`. No\n  per-phase MAF graph, no in-graph agent_executor, no in-graph\n  validator file.\n- `kind: graph` (legacy \u002F opt-in) → 1 MAF graph file with\n  `agent → validator → terminal`.\n  1 runtime SKILL.md at `api\u002Fserver\u002Fskills\u002F\u003Cwt>-\u003Cagent_skill_name>\u002F`.\n  1 agent executor at `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py`.\n  1 validator at `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>_schema.py`.\n  Only use when the three criteria in \"When to use kind:graph\" apply.\n- `kind: hitl` → no graph (the orchestrator does the wait directly).\n  1 persona SKILL.md at `api\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002FSKILL.md` (only if\n  the role doesn't already exist under `api\u002Fserver\u002Fpersonae\u002F`).\n- `kind: sub_orchestrator` → no per-phase file; the orchestrator calls\n  `context.call_sub_orchestrator` against an already-graduated domain.\n\n#### Path table (segment-default vs. legacy graph)\n\nThe following table is authoritative. The right-hand column flags rows\nthat exist only under the legacy `kind: graph` path.\n\n| Artefact | Path | When |\n|---|---|---|\n| orchestrator | `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>.py` | always |\n| activities module | `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>_activities.py` | always |\n| **segment activity** | `api\u002Ffunctions\u002Fsegments\u002F\u003Cwt_snake>_\u003Csegment_letter>.py` | `kind: agent` (default) |\n| **segment output Pydantic model** | inline in the segment file as `Segment\u003CLetter>Output(BaseModel)` | `kind: agent` (default) |\n| **segment validator activity** | `validate_\u003Cwt_snake>_segment_\u003Cletter>_output_activity_trigger` registered in the pack's `durable.py` | `kind: agent` (default) |\n| phase agent runtime SKILL.md | `api\u002Fserver\u002Fskills\u002F\u003Cwt>-\u003Cskill_name>\u002FSKILL.md` | per-skill (both paths) |\n| persona SKILL.md | `api\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002FSKILL.md` | per HITL role |\n| synthetic MCP adapter | `api\u002Fserver\u002Fmcp_tools\u002F\u003Cmcp_tool>.py` | per `external_systems[]` |\n| entity projection | `api\u002Fserver\u002Fservices\u002Fentity_projections\u002F\u003Cwt_snake>.py` | always (v4) |\n| Cypher precedent | `api\u002Fserver\u002Fservices\u002Fprecedent_queries\u002F\u003Cwt>_\u003Cphase>.cypher` | per HITL phase (v4) |\n| ambient block | append to `api\u002Fserver\u002Fservices\u002Fambient_agents\u002F\u003Cfunction>.py` | if brief carries `ambient:` |\n| deterministic phase graph | `api\u002Ffunctions\u002Fgraphs\u002F\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py` | `kind: deterministic` |\n| per-phase MAF graph file | `api\u002Ffunctions\u002Fgraphs\u002F\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py` | **legacy \u002F `kind: graph` only** |\n| in-graph agent executor | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>.py` | **legacy \u002F `kind: graph` only** |\n| in-graph validator | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_\u003Cprefix>_\u003Cwt_snake>_\u003Cphase>_schema.py` | **legacy \u002F `kind: graph` only** |\n| GRADUATION.md | `\u003CRUN_ROOT>\u002FGRADUATION.md` | always |\n| graduate.sh | `\u003CRUN_ROOT>\u002Fgraduate.sh` | always |\n\nTemplate references (under `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002F`):\n\n| Template | Purpose | Path |\n|---|---|---|\n| `segment.py.tmpl` | segment activity + Pydantic output model | `kind: agent` (default) |\n| `segment_activity_trigger.py.tmpl` | pack `durable.py` activity-trigger pair (run + validate) | `kind: agent` (default) |\n| `activity.py.tmpl` | per-phase Durable activity wrappers for graph phases | deterministic + legacy graph |\n| `phase_graph.py.tmpl` | per-phase MAF graph (WorkflowBuilder) | **deterministic + legacy `kind: graph` only** |\n| `validator.py.tmpl` | in-graph validator returning `{ok: bool}` | **deterministic + legacy `kind: graph` only** |\n| `agent_executor.py.tmpl` | per-phase agent executor calling `run_agent_session` | **legacy \u002F `kind: graph` only** |\n| `orchestrator.py.tmpl` | the orchestrator | always |\n| `mcp_tool.py.tmpl` | synthetic MCP adapter | per `external_systems[]` |\n| `persona_SKILL.md.tmpl` | persona runtime SKILL.md | per HITL role |\n| `SKILL.md.tmpl` | phase-agent runtime SKILL.md | per skill (both paths) |\n| `GRADUATION.md.tmpl` \u002F `graduate.sh.tmpl` | graduation artefacts | always |\n\nFor each `external_systems[]` entry whose `mcp_tool` does not already\nexist in `api\u002Fserver\u002Fmcp_tools\u002F` (check this against the live filesystem):\n- 1 synthetic MCP adapter at `api\u002Fserver\u002Fmcp_tools\u002F\u003Cmcp_tool>.py`.\n\n#### When to use `kind: graph`\n\nThe default for an agentic phase is `kind: agent`, which generates a\n**segment activity** (one CopilotSession loaded with all the skills\nthat segment needs; the model picks invocation order). Only opt into\nthe legacy MAF-graph shape via `kind: graph` when one of these three\ncriteria is genuinely true:\n\n1. **Parallel fan-out with blind merge.** The phase needs to fan out\n   into N parallel executors and join them with a merge node that does\n   not coordinate with the spawning agent. The segment loop is\n   sequential within one CopilotSession; parallel fan-out belongs in\n   a graph.\n2. **Agent → validator → agent inside one activity.** The phase needs\n   a *bounded* retry where the second agent invocation reads the\n   validator's structured response in-process (no Durable round-trip\n   between agent calls). Segment retry crosses Durable activity\n   boundaries; if the round-trip cost is unacceptable, use a graph.\n3. **Saga \u002F compensation chains where Durable round-trips per node\n   are unacceptable.** The phase composes ≥ 3 executors with\n   compensating actions that must execute atomically with respect to\n   each other; the orchestrator-level retry granularity is too coarse.\n\nEverything else — including the common \"one agentic skill produces a\nstructured output that the orchestrator hands to the next phase\" case\n— is **`kind: agent` (default segment)**. When in doubt, default to\nsegment.\n\nMechanically, `kind: agent` writes a segment file from\n`segment.py.tmpl` + a durable registration snippet from\n`segment_activity_trigger.py.tmpl`. `kind: graph` writes a per-phase\nMAF graph from `phase_graph.py.tmpl` + an in-graph validator from\n`validator.py.tmpl` + an agent executor from `agent_executor.py.tmpl`,\nand is registered in the pack's `durable.py` as a single\n`\u003Cwt_snake>_\u003Cphase>_activity_trigger` (no separate validator-trigger\n— validation happens inside the graph).\n\nAlways:\n- 1 orchestrator at `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>.py`.\n- 1 activities module at `api\u002Ffunctions\u002Fworkflows\u002F\u003Cprefix>_\u003Cwt_snake>_activities.py`.\n- 1 entity projection at `api\u002Fserver\u002Fservices\u002Fentity_projections\u002F\u003Cwt_snake>.py` (v4).\n- 1 Cypher precedent file per HITL phase at\n  `api\u002Fserver\u002Fservices\u002Fprecedent_queries\u002F\u003Cwt>_\u003Cphase>.cypher` (v4).\n- 1 ambient-agent block appended to\n  `api\u002Fserver\u002Fservices\u002Fambient_agents\u002F\u003Cfunction>.py` if the brief\n  carries an `ambient:` block (v4).\n- 1 `GRADUATION.md` at the sandbox root — human-readable description of\n  what the graduation script will do.\n- 1 `graduate.sh` at the sandbox root — the **executable** graduation\n  script. Mechanically copies files + edits the live trees described in\n  step 4.7.\n\nBefore declaring the graduated domain demo-ready, run the runtime gates in\n`CHECKLIST.md` §12. Static generation checks do not prove persona completion,\nDurable resume latency, or browser recovery after a backend journal reset.\n\nThe **blocking execution-visibility gate** in `CHECKLIST.md` §13 applies to\nevery active non-stub workflow type. Actual execution evidence must be visible\nand self-consistent; validate observed evidence rather than predicting\nconditional branches. Generated agent paths use `run_agent_session`. Use the\nlive\u002Freplay `tools\u002Fworkflow_visibility_proof.py` commands in `CHECKLIST.md`\n§13.\n\n### Conventions (codified for determinism)\n\nThese were free choices in earlier drafts; codifying them removes\nimprovisation from the procedure.\n\n- **`workflow_type` stamping.** Every `checkpoint_activity_trigger`\n  payload carries `workflow_type: workflow_type` (the variable read\n  once at the top of the orchestrator from `input_dict.get(\"type\")`).\n  Without this, recordings are filename `unknown-...` and FleetEvents\n  arrive with `domain: null`. (Substrate-fix v2 contract.)\n- **HITL `persona`\u002F`external_event`\u002F`context`.** Every `kind: \"suspended\"`\n  payload stamps the persona-responder contract:\n  - `persona`: brief.phases[].persona\n  - `external_event`: brief.phases[].external_event (or default\n    `\u003Cphase_name>_decision`)\n  - `context`: a dict whose keys are brief.phases[].context_keys (or\n    default just the previous phase's name), each pulling from\n    `enriched.get(\u003Ckey>)`.\n  Without this, the persona responder ignores the gate and the\n  workflow stalls forever.\n- **HITL external event name.** For every phase whose `kind: hitl`, the\n  orchestrator's `wait_for_external_event(...)` name and the persona\n  SKILL.md's `external_event` frontmatter MUST match byte-for-byte.\n- **HITL authority closure.** The governance authority matrix used by\n  `api.server.services.governance.kernel` MUST contain a rule matching each\n  HITL persona's emitted `action`, representative `category`, and value band.\n  A persona folder or pack `AuthorityRow` alone does not prove the runtime\n  kernel will approve it. Run `kernel().check_authority(...)` with a real\n  generated gate context and require `allowed=True`.\n- **HITL recovery metadata.** After a live suspend, the Workflow API payload\n  MUST contain `hitl_context` with `persona`, `external_event`, `phase`, and\n  the decision context. This is what `sweep_pending_hitl()` uses after a missed\n  bus event or server restart.\n- **Activity-trigger names.** `\u003Cdomain.name with - replaced by _>_\u003Cphase_name>_activity_trigger`.\n  E.g. `fleet_travel_preapproval_employee_lookup_activity_trigger`.\n- **Graph builder names.** `build_\u003Cdomain.name with - replaced by _>_\u003Cphase_name>_workflow`.\n- **Agent skill folder name.** `\u003Cdomain.name>-\u003Cagent_skill_name>`. E.g.\n  `fleet-travel-preapproval-policy-fit-checker`.\n- **Tool registration name.** From the brief's `external_systems[].mcp_tool` and\n  each `operations[].name`: `\u003Cmcp_tool>_\u003Coperation>`. E.g.\n  `concur_travel_policy_get_policy`. The agent skill's `allowed-tools`\n  CSV uses these names verbatim.\n- **Validator file name.** `validate_\u003Cdomain.name with - replaced by _>_\u003Cphase_name>_schema.py`.\n  E.g. `validate_fleet_employee_onboarding_access_drafter_schema.py`.\n  The full domain prefix is **required** — without it, two domains with\n  same-named agent phases (e.g. multiple \"drafter\" phases) will collide\n  in `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002F`.\n- **Validator class \u002F executor name.** `validate_\u003Cdomain.name with - replaced by _>_\u003Cphase_name>` (the file's name minus `_schema.py`). Same prefix-required reason.\n- **Run id.** `\u003CYYYYMMDD-HHMMSS>-\u003Cdomain.name>` from current UTC time.\n  Compute once at the top of step 4; use the literal value everywhere\n  downstream.\n\n### Step 3 — Inventory and isomorphism\n\n**Read-on-demand policy (NEW — 2026-05-21).** The 9 canonical examples below\nare the **fallback** when the [Shape cheat-sheet](#shape-cheat-sheet) at the\ntop of this file doesn't answer a byte-shape question. Do NOT read them\nupfront. Each sub-skill names which canonical file(s) IT needs in its own\n`## Canonical examples` block — read only those when invoking that sub-skill,\nand only the ranges named there.\n\nFor the orchestrator + spawn helper + factory + ambient block (the four\nshapes that account for ~95% of generation), the cheat-sheet is sufficient.\nThe 9 canonical files below are listed for when a sub-skill explicitly\npoints at one, or when you hit a shape question the cheat-sheet doesn't\ncover.\n\n| # | Canonical example | Used by sub-skill | Lines worth reading |\n|---|---|---|---|\n| 1 | `api\u002Fserver\u002Fskills\u002Freceipt-validator\u002FSKILL.md` | `author-runtime-skill` (phase_agent mode) | full (72) |\n| 2 | `api\u002Fserver\u002Fpersonae\u002Fline_manager\u002FSKILL.md` | `author-persona` (NEW v3) | full (63) |\n| 3 | `api\u002Fserver\u002Fservices\u002Fpersona_responder.py` | `author-persona` (decision_code shape + sandbox builtins) | grep for `_DECISION_BUILTINS` only |\n| 4 | `api\u002Fserver\u002Fmcp_tools\u002Fclaim_lookup.py` | `author-mcp-tool` | full (107) |\n| 5 | `api\u002Ffunctions\u002Fworkflows\u002Fexpense_claim.py` | `author-durable-domain` (orchestrator + HITL contract; v2-stamped) | full (194) — only if cheat-sheet is insufficient |\n| 6 | `api\u002Ffunctions\u002Fworkflows\u002Factivities.py` | `author-durable-domain` (activities module — reuses `_run_workflow` from here) | full (174) — only if cheat-sheet is insufficient |\n| 7 | `api\u002Ffunctions\u002Fgraphs\u002Fclassify.py` | `author-durable-domain` (per-phase agent graph) | full (37) |\n| 8 | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_rag_classifier.py` | `author-durable-domain` (agent executor) | full (35) |\n| 9 | `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_classification_schema_node.py` | `author-durable-domain` (validator) | full (31) |\n\n**For deterministic phases**, also note: `api\u002Ffunctions\u002Fgraphs\u002F_tracked_executor.py`\nfor the `TrackedExecutor` constructor signature (used directly with\n`executor_type=\"deterministic\"` and an inline `_\u003Cphase>_execute` async\nfn — there is no canonical deterministic-graph example to mirror, so\nfollow the v1 graduated example at `api\u002Ffunctions\u002Fgraphs\u002Ffleet_travel_preapproval_employee_lookup.py`).\n\n**For the substrate-fix contract** (workflow_type stamping +\npersona\u002Fexternal_event\u002Fcontext on suspended payloads), the live\n`expense_claim.py` and `hiring.py` are the canonical implementation;\nthe new orchestrator MUST mirror their stamping shape exactly. The\ngenerated `fleet_travel_preapproval.py` is also a worked example.\n\n### Step 4 — Generate into sandbox\n\nCompute `RUN_ID = \u003CYYYYMMDD-HHMMSS>-\u003Cdomain.name>` from the current UTC\ntime (one shell call: `date -u +\"%Y%m%d-%H%M%S\"`). Create\n`tools\u002Fscratch\u002Fcompose-domain\u002F\u003CRUN_ID>\u002F` with the layout from the spec\ndoc §6.\n\nFor each artefact in the plan, invoke the matching sub-skill exactly\nonce, passing the **structured arguments** below. Do not pass the brief\nas a whole — pass only the relevant slice. This is the boundary that\nkeeps sub-skills deterministic.\n\n#### When invoking `author-runtime-skill` (phase_agent only)\n\nv3 note: persona authoring is now `author-persona`, not\n`author-runtime-skill`. `author-runtime-skill` only writes phase-agent\nSKILL.md files now.\n\n```\nmode: phase_agent\noutput_path: \u003CRUN_ROOT>\u002Fapi\u002Fserver\u002Fskills\u002F\u003Cdomain.name>-\u003Cphase.agent_skill_name>\u002FSKILL.md\nbrief: \u003Cthe phase entry from brief.phases[]>\ncanonical_example_path: api\u002Fserver\u002Fskills\u002Freceipt-validator\u002FSKILL.md\navailable_mcp_tools:\n  - { name: \"\u003Cmcp_tool>_\u003Coperation>\", description: \"\u003Cfrom the tool's @define_tool description>\" }\n  - ... (one per (mcp_tool, operation) pair the phase's external_systems[] resolves to)\n```\n\n#### When invoking `author-persona` (NEW v3)\n\n```\noutput_path: \u003CRUN_ROOT>\u002Fapi\u002Fserver\u002Fpersonae\u002F\u003Crole>\u002FSKILL.md\nbrief: \u003Cthe persona entry from brief.personae[]>\ndomain_display_name: \u003Cbrief.domain.display_name>\ndefault_external_event: \u003Chitl_phase_name>_decision   # convention\ncanonical_example_path: api\u002Fserver\u002Fpersonae\u002Fline_manager\u002FSKILL.md\nresponder_path: api\u002Fserver\u002Fservices\u002Fpersona_responder.py  # for builtins reference\n```\n\n#### When invoking `author-mcp-tool`\n\n```\noutput_path: \u003CRUN_ROOT>\u002Fapi\u002Fserver\u002Fmcp_tools\u002F\u003Cexternal_systems[].mcp_tool>.py\ntool_brief: \u003Cthe external_systems[] entry>\ncanonical_example_path: api\u002Fserver\u002Fmcp_tools\u002Fclaim_lookup.py\n```\n\n#### When invoking `author-durable-domain`\n\n```\noutput_root: \u003CRUN_ROOT>\nvertical: \u003Cselected vertical>\nartifact_plan: \u003Cthe approved Step 2 artifact list>\nbrief: \u003Cthe entire brief>\ncanonical_paths:\n  orchestrator: api\u002Ffunctions\u002Fworkflows\u002Fexpense_claim.py\n  activities: api\u002Ffunctions\u002Fworkflows\u002Factivities.py\n  agent_graph: api\u002Ffunctions\u002Fgraphs\u002Fclassify.py\n  deterministic_graph: api\u002Ffunctions\u002Fgraphs\u002Ffleet_travel_preapproval_employee_lookup.py  # v1 graduated\n  agent_executor: api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_rag_classifier.py\n  validator: api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_classification_schema_node.py\n  tracked_executor: api\u002Ffunctions\u002Fgraphs\u002F_tracked_executor.py\n```\n\nEach sub-skill writes its files to the sandbox path under the mirrored\nreal-tree layout. **No sub-skill writes to a real path.** When a\nsub-skill returns, you continue with the next.\n\nAfter all sub-skills have run, two more files remain for `compose-domain`\nitself to write:\n\n- `\u003CRUN_ROOT>\u002FGRADUATION.md` — human-readable description of what\n  graduate.sh does. Use the template at\n  `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002FGRADUATION.md.tmpl`.\n  This file is reference, not action.\n- `\u003CRUN_ROOT>\u002Fgraduate.sh` — the **executable** script that mechanically\n  performs all the live-tree edits. Use the template at\n  `docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fgraduate.sh.tmpl`.\n  `author-durable-domain` returns the structured fragments (orchestrator-\n  import block, activity-trigger block, ramp-loop spawner entry,\n  inventory DOMAIN entry, etc.) for you to splice into the template.\n  Supply `VERTICAL_NAME`, `SPAWNER_REGISTRATION_BLOCK`,\n  `DOMAIN_DECLARATION_BLOCK`, and `FUNCTION_MEMBERSHIP_BLOCK`. These\n  blocks must append to the selected pack's modules; they must not patch\n  `function_app.py`, `api\u002Fshared\u002F*`, Blueprint inventory, or another\n  vertical.\n  Mark the file executable (`chmod +x`).\n\n  The graduate.sh script performs six idempotent pack-scoped steps:\n  1. Validate the selected pack and sandbox layout.\n  2. Copy generated files (`skills\u002F`, `personae\u002F`, `mcp_tools\u002F`,\n     `entity_projections\u002F`) into `verticals\u002F\u003Cvertical>\u002F`.\n  3. Register the orchestrator and activities on the pack's `durable.py`\n     (sentinel-guarded append).\n  4. Export graph builders into `api\u002Ffunctions\u002Fgraphs\u002F__init__.py`\n     (implementation modules may remain under `api\u002Ffunctions\u002F`).\n  5. Register the spawner, domain declaration, and function membership on\n     the pack's `spawners.py` \u002F `domains.py` \u002F `functions.py`\n     (sentinel-guarded appends). Never patches global compatibility\n     adapters or another vertical's modules.\n  6. Validate the active pack (`active_runtime().pack.domains` must\n     include the new `workflow_type`) and print smoke commands.\n\n  Each step is idempotent: if the domain has already been graduated\n  (sentinel already present), the step is a no-op.\n\n### Step 5 — Self-check\n\nRun the checklist at `compose-domain\u002FCHECKLIST.md` against the sandbox.\nProduce a one-page report at `\u003Crun-id>\u002FREPORT.md` with one row per\nchecklist item (PASS \u002F FAIL \u002F N\u002FA). Print the same report inline to the\noperator.\n\nIf any item FAILs, **do not** silently fix it. Tell the operator and stop.\nThe right move when something fails is almost always to fix the SKILL.md\nthat produced it, then delete the sandbox and re-run.\n\nIf everything passes, end with:\n\n> Sandbox at `tools\u002Fscratch\u002Fcompose-domain\u002F\u003CRUN_ID>\u002F`. CHECKLIST passed.\n> Graduate by running `bash \u003CRUN_ID>\u002Fgraduate.sh` from repo root.\n> Then proceed to Step 7 (recorder verification).\n\nDo not graduate. Do not start the demo stack. Do not run any tests against\nthe real trees. The skill ends here — the operator runs graduate.sh.\n\n### Step 6 — Determinism check (operator-invoked, optional)\n\nThe operator may, after a clean self-check, re-invoke this skill against\nthe same brief and run the determinism check at\n`compose-domain\u002FCHECKLIST.md` §6.1. The two sandboxes must `diff -r` to\nnothing meaningful. Divergence points are exactly the parts of these\nSKILLs that gave the author freedom — the fix is to codify that part\nhere or in the matching sub-skill, then re-run.\n\nThe HITL event-name convention, the activity-trigger naming convention,\nthe structured sub-skill input contracts in step 4 above, and the v3\nworkflow_type \u002F persona-contract stamping rules are the specific fixes\nthat emerged from the v1 → v2 → v3 iteration of this SKILL. Future\niterations follow the same loop: improvise once, codify, re-run, diff.\n\n### Step 7 — Recorder verification (post-graduation, NEW v3)\n\nAfter the operator runs `graduate.sh` and confirms the smoke output is\ngreen, prompt them to record real walks for the new domain so the\ndeployed page replays them. Print these commands verbatim:\n\n```bash\n# 1. Boot the autonomous stack so the new domain spawns automatically.\n#    Functions host + azurite already running.\n.\u002Fscripts\u002Fprofile-autonomous.sh &\nsleep 30\n\n# 2. Start the recorder.\ncurl -X POST http:\u002F\u002Flocalhost:3101\u002Fapi\u002Fblueprint\u002F_recorder\u002Fstart\n\n# 3. Let it run ~5 minutes so each domain completes ≥3 walks.\nsleep 300\n\n# 4. Stop the recorder; flush.\ncurl -X POST http:\u002F\u002Flocalhost:3101\u002Fapi\u002Fblueprint\u002F_recorder\u002Fstop\n\n# 5. Inspect; prune any partial \u002F single-event noise files; commit.\nls -la data\u002Fblueprint-recordings\u002F\u003Cdomain.name>-*.jsonl\nfind data\u002Fblueprint-recordings -name '*.jsonl' -size -200c -delete\ngit add data\u002Fblueprint-recordings\u002F\u003Cdomain.name>-*.jsonl\ngit commit -m \"record(blueprint): real walks for \u003Cdomain.display_name>\"\n\n# 6. Redeploy the container app so the deployed page picks up the\n#    new recordings (proof-gated — requires ZAVA_MODE=replay and proof artefacts).\nZAVA_MODE=replay EXPECTED_TENANT_ID=\u003Cyour-tenant-id> .\u002Fscripts\u002Fdeploy-blueprint.sh\n```\n\nWith this step, the new domain becomes visible on the deployed page\nwithin minutes of graduation. No synthetic templates needed.\n\n## How to author a new domain brief (v4 worked example)\n\nThe 19 briefs at `docs\u002Fsuperpowers\u002Fspecs\u002Farchive\u002F*-brief.yaml` are the\nauthoritative spec for every generated domain (they live under\n`archive\u002F` because they have already been graduated; new briefs are\nauthored under `docs\u002Fsuperpowers\u002Fspecs\u002F` and archived after\n`graduate.sh` succeeds). To author a new one:\n\n1. **Pick a workflow_type** — kebab-case, lowercase, e.g.\n   `purchase-card`. This name is stamped on every payload, every\n   FleetEvent, and every Cypher file the codegens emit.\n2. **Copy the worked example.** The freshest brief —\n   `docs\u002Fsuperpowers\u002Fspecs\u002Farchive\u002Ffleet-purchase-card-brief.yaml` — was\n   authored top-down without a hand-written projection module. It\n   exercises every section the v4 schema cares about (domain,\n   phases, entities, decisions, function, ambient) at the smallest\n   plausible size. Use it as the template.\n3. **Fill in the entity\u002Fdecision shape.** Each `entities[]` entry\n   declares one node the projection will write per workflow; each\n   `decisions[]` entry declares one Decision node per HITL gate. The\n   codegens at `sub-skills\u002Fauthor-entity-projection\u002Fcodegen.py` and\n   `sub-skills\u002Fauthor-decision-mapping\u002Fcodegen.py` consume these.\n4. **Validate.** Run the brief through\n   `_shared.brief_validator.validate_brief(...)` (the smoke test at\n   `tests\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose_domain\u002Ftest_fleet_purchase_card_smoke.py`\n   shows the import path). The validator surfaces schema errors with\n   stable `path` field for assertions.\n5. **Hand off to graduate.** The compose-domain orchestrator above\n   handles the rest — the brief is the only operator-authored file.\n\n### Walking through a segment-default agent phase\n\nConcrete example for an agentic phase generated under the default\n`kind: agent` (segment-by-default) path. Assume the brief contains:\n\n```yaml\ndomain: { workflow_type: vendor-kyc, prefix: fleet, display_name: \"Vendor KYC\" }\nphases:\n  - { name: vendor_intake, kind: deterministic, intent: \"Capture vendor name + country.\" }\n  - name: kyc_diligence            # ← agentic phase, default segment shape\n    kind: agent\n    agent_skill_name: kyc-diligence-checker\n    intent: \"Resolve UBOs, sanctions, adverse-media.\"\n    external_systems: [companies_house, sanctions_api]\n  - { name: finance_signoff, kind: hitl, persona: vendor_kyc_finance_bp,\n      external_event: finance_signoff_decision }\n```\n\nFor the `kyc_diligence` phase, `compose-domain` generates **a segment\nactivity, not a MAF graph**:\n\n1. **Pick the segment letter.** Segments are letter-indexed within a\n   workflow_type (A for the first segment, B for the second, …). For\n   a single-segment workflow the letter is `b` by convention (mirrors\n   `hiring_b`); for multi-segment workflows allocate in order.\n   Example: `kyc_diligence` becomes Segment **B** of vendor-kyc →\n   `api\u002Ffunctions\u002Fsegments\u002Fvendor_kyc_b.py`.\n2. **Render `segment.py.tmpl`.** Fill in:\n   - `SKILL_LIST_LINES` — every `\u003Cwt>-\u003Cskill>` SKILL.md the segment\n     should auto-load (the phase's own `agent_skill_name` plus any\n     adjacent agentic skills the operator decides belong in the same\n     CopilotSession).\n   - `MCP_LIST_LINES` — the MCP tools resolved from the phase's\n     `external_systems[]`.\n   - `OUTPUT_MODEL_BODY` — the Pydantic `SegmentBOutput(BaseModel)`\n     class. One field per structured output the orchestrator reads\n     downstream (see `enriched.get(...)` references in the\n     orchestrator + HITL payloads). Custom validators go on the\n     model, not in a separate file.\n   - `SEGMENT_GOAL_SENTENCE` — one sentence describing the deliverable,\n     matching the phase's `intent`.\n3. **Render `segment_activity_trigger.py.tmpl`** to produce the\n   `durable.py` registration snippet. This emits **two** activity triggers:\n   - `vendor_kyc_segment_b_activity_trigger` — calls\n     `run_segment_b(input)`.\n   - `validate_vendor_kyc_segment_b_output_activity_trigger` — Pydantic-\n     validates and returns `{ok, output|errors}`. The Pydantic errors\n     are JSON-serialised via `json.loads(e.json())` so Durable does not\n     reject them.\n4. **Wire the orchestrator retry loop.** The orchestrator generated\n   from `orchestrator.py.tmpl` MUST call the pair inside a\n   `for attempt in range(segment_max_retries + 1)` loop, feeding\n   `validator[\"errors\"]` back as `prior_validator_error` on retry, and\n   breaking when `validator[\"ok\"]`. Copy the loop shape from\n   `api\u002Ffunctions\u002Fworkflows\u002Fhiring.py:120-162`. Keep the canonical\n   control-plane and Durable identities separate in `enriched` as\n   `\"workflow_id\": workflow_id` and\n   `\"instance_id\": context.instance_id`; never replace the former with\n   the latter. Add `\"covered_phases\"` to `segment_input`, listing every\n   declared phase handled by that one CopilotSession, and forward it to\n   `run_agent_session`.\n5. **Graduate.** `graduate.sh` copies the segment file under\n   `api\u002Ffunctions\u002Fsegments\u002F` and appends the triggers to the pack's\n   `durable.py` between sentinel markers. No new file under\n   `api\u002Ffunctions\u002Fgraphs\u002F` is created for this phase; no entry in\n   `api\u002Ffunctions\u002Fgraphs\u002F__init__.py` is added.\n\nThe runtime SKILL.md for `vendor-kyc-kyc-diligence-checker` is still\ngenerated the same way it was for `kind: graph` (via\n`author-runtime-skill` in `phase_agent` mode). The only thing that\nchanges between segment and legacy graph paths is the *carrier* of\nthe agent — segment activity vs. MAF graph.\n\n### Appendix — legacy `kind: graph` walkthrough\n\nWhen the brief explicitly sets `kind: graph` (because one of the three\ncriteria in \"When to use kind:graph\" applies), the per-phase output\nshape reverts to the v3 MAF-graph form. For the same `kyc_diligence`\nphase:\n\n```yaml\n  - name: kyc_diligence\n    kind: graph                     # explicit opt-in\n    agent_skill_name: kyc-diligence-checker\n    intent: \"Resolve UBOs, sanctions, adverse-media.\"\n    external_systems: [companies_house, sanctions_api]\n```\n\n`compose-domain` then generates three files (none of which are written\nunder the segment path):\n\n1. `api\u002Ffunctions\u002Fgraphs\u002Ffleet_vendor_kyc_kyc_diligence.py` from\n   `phase_graph.py.tmpl` — `WorkflowBuilder` wiring\n   `agent → validator → terminal`.\n2. `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fagents\u002Fagent_fleet_vendor_kyc_kyc_diligence.py`\n   from `agent_executor.py.tmpl` — single-skill `run_agent_session` call.\n3. `api\u002Ffunctions\u002Fgraphs\u002Fexecutors\u002Fvalidators\u002Fvalidate_fleet_vendor_kyc_kyc_diligence_schema.py`\n   from `validator.py.tmpl` — in-graph validator returning\n   `{\"ok\": bool, ...}` (NOT a Pydantic model; the graph terminal\n   handles the `ok=False` branch).\n\nThe pack's `durable.py` gets ONE activity trigger\n(`vendor_kyc_kyc_diligence_activity_trigger`) instead of the pair, and\nthe graph builder is exported from `api\u002Ffunctions\u002Fgraphs\u002F__init__.py`.\nThe orchestrator calls the trigger once per attempt (no in-orchestrator\nretry loop — retry, if any, is the graph's responsibility).\n\nPrefer the segment-default path. Reach for this appendix only when one\nof the three \"When to use kind:graph\" criteria genuinely applies.\n\nThe 12 backfill briefs (everything matching `docs\u002Fsuperpowers\u002Fspecs\u002F*-brief.yaml`\nthat is NOT `fleet-purchase-card`) document the entity\u002Fdecision shape\nof the corresponding hand-written Phase 1 projection module at\n`api\u002Fserver\u002Fservices\u002Fentity_projections\u002F\u003Cwt_snake>.py`. The\nhand-written modules carry domain-specific helper logic (period\nderivation, conditional asset emission, JSON-blob attribute\nserialisation, risk-band heuristics) that no schema-driven codegen\ncan synthesise from a brief alone — the briefs are documentation of\nintent, not a regenerable source for those modules.\n\n## Anti-patterns (things you must not do)\n\n- Inventing fields not present in the brief.\n- Inventing the HITL external event name. Convention is\n  `\u003Cphase_name>_decision`. The orchestrator's\n  `wait_for_external_event(...)` and the persona SKILL.md both write\n  this exact string.\n- Inventing tool names in an agent skill's `allowed-tools`. The\n  `author-runtime-skill` step 4 list is authoritative — if a tool you\n  want isn't there, it's the caller's bug, not yours. Stop.\n- Copying a runtime SKILL.md verbatim from `api\u002Fserver\u002Fskills\u002F` and just\n  renaming things — the result must be an *authored* skill, not a\n  rebadged one.\n- Skipping the validator on agent phases (\"it's a stub, the validator is\n  trivial\"). Validators are the bounded-probabilism edge; the harness\n  expects them.\n- Ignoring the read-on-demand policy by reading every canonical example\n  upfront, or generating a byte-shape without reading the specific fallback\n  example when the cheat-sheet is insufficient.\n- Directly editing live-tree pack files (`durable.py`, `domains.py`,\n  `spawners.py`, `functions.py`) \"just to make the smoke test work\". That's\n  graduation. It happens by hand. By an engineer. After this skill ends.\n- Graduating \"while you're at it\" because the sandbox looks fine. Stop.\n- Pretending you finished when you didn't. If you got blocked, say so. If\n  you skipped a step, say so. If a sub-skill returned something the\n  CHECKLIST won't pass, say so.\n\n## Operator-facing prompts\n\nWhen you ask the operator a question, you are explicit about what you\nneed:\n\n- \"Brief at `docs\u002Fsuperpowers\u002Fspecs\u002F\u003Cx>-brief.yaml` validates. Plan\n  follows. Confirm before I generate.\"\n- \"Step 3 noted that `api\u002Ffunctions\u002Fgraphs\u002Fclassify.py` has changed shape\n  since this skill was last revised. Stopping. Please update\n  `compose-domain\u002FSKILL.md` step 3 with the new canonical paths and\n  re-invoke.\"\n- \"CHECKLIST item §3.4 FAIL: agent skill `\u003Cx>` references MCP tool `\u003Cy>`\n  in `allowed-tools` but no such tool exists in the sandbox or\n  `api\u002Fserver\u002Fmcp_tools\u002F`. The bug is probably in\n  `author-runtime-skill\u002FSKILL.md` step 4 (allow-list resolution).\n  Stopping.\"\n",{"name":5,"audience":57,"description":58,"forbidden-runtime":59},"design-time-only","Current design-time meta-skill. Given a domain brief (YAML) or a free-text\nidea, produce a complete Durable-fidelity domain sandbox: orchestrator,\nper-phase graphs, validators, agent skills, synthetic MCP adapters, persona(e),\n+ a graduate.sh script that mechanically wires everything into the live\ntrees.\n\nThe current contract encodes: durable.* event vocabulary,\nworkflow_type stamping on every checkpoint, persona\u002Fexternal_event\u002Fcontext\non every HITL gate, persona SKILL.md with executable decision_policy,\nand the per-domain ramp-loop registration. Every generated domain inherits\nthe contract by construction.\n\nSandbox-only; never touches real trees directly. Calls\n`author-runtime-skill`, `author-mcp-tool`, `author-persona`, and\n`author-durable-domain` as sub-skills.\n",true,"main","db273d7d646605c0bf0175dc9c8057b9ad2628b5","docs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain",2,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane","https:\u002F\u002Fgithub.com\u002Farturcrmbot","2026-09-28 17:47:06",{"source":8,"skillName":5,"commands":68,"prompt":78,"zipAvailable":59},[69,72,75],{"tool":70,"command":71},"npx","npx skills add arturcrmbot\u002Fzava-control-plane --skill compose-domain",{"tool":73,"command":74},"bunx","bunx skills add arturcrmbot\u002Fzava-control-plane --skill compose-domain",{"tool":76,"command":77},"pnpm","pnpm dlx skills add arturcrmbot\u002Fzava-control-plane --skill compose-domain","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FSKILL.md",[80,86,90,94,100,103,107,113,117,121,125,129,133,137,141,145,149,153],{"path":81,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":84,"sourceHtmlUrl":85},"brief.schema.yaml","REFERENCE","参考文档",9786,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fbrief.schema.yaml",{"path":87,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":88,"sourceHtmlUrl":89},"CHECKLIST.md",15488,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FCHECKLIST.md",{"path":91,"resourceType":82,"resourceTypeDesc":83,"sizeBytes":92,"sourceHtmlUrl":93},"SANDBOX.md",3101,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002FSANDBOX.md",{"path":95,"resourceType":96,"resourceTypeDesc":97,"sizeBytes":98,"sourceHtmlUrl":99},"sub-skills\u002F__init__.py","SCRIPT","脚本",0,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fsub-skills\u002F__init__.py",{"path":101,"resourceType":96,"resourceTypeDesc":97,"sizeBytes":98,"sourceHtmlUrl":102},"sub-skills\u002F_shared\u002F__init__.py","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fsub-skills\u002F_shared\u002F__init__.py",{"path":104,"resourceType":96,"resourceTypeDesc":97,"sizeBytes":105,"sourceHtmlUrl":106},"sub-skills\u002F_shared\u002Fbrief_validator.py",2565,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Fsub-skills\u002F_shared\u002Fbrief_validator.py",{"path":108,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":111,"sourceHtmlUrl":112},"templates\u002Factivity.py.tmpl","OTHER","其他",444,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Factivity.py.tmpl",{"path":114,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":115,"sourceHtmlUrl":116},"templates\u002Fagent_executor.py.tmpl",1127,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fagent_executor.py.tmpl",{"path":118,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":119,"sourceHtmlUrl":120},"templates\u002Fgraduate.sh.tmpl",5999,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fgraduate.sh.tmpl",{"path":122,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":123,"sourceHtmlUrl":124},"templates\u002FGRADUATION.md.tmpl",4645,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002FGRADUATION.md.tmpl",{"path":126,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":127,"sourceHtmlUrl":128},"templates\u002Fmcp_tool.py.tmpl",1643,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fmcp_tool.py.tmpl",{"path":130,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":131,"sourceHtmlUrl":132},"templates\u002Forchestrator.py.tmpl",2102,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Forchestrator.py.tmpl",{"path":134,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":135,"sourceHtmlUrl":136},"templates\u002Fpersona_SKILL.md.tmpl",1075,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fpersona_SKILL.md.tmpl",{"path":138,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":139,"sourceHtmlUrl":140},"templates\u002Fphase_graph.py.tmpl",1311,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fphase_graph.py.tmpl",{"path":142,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":143,"sourceHtmlUrl":144},"templates\u002Fsegment_activity_trigger.py.tmpl",1870,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fsegment_activity_trigger.py.tmpl",{"path":146,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":147,"sourceHtmlUrl":148},"templates\u002Fsegment.py.tmpl",3736,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fsegment.py.tmpl",{"path":150,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":151,"sourceHtmlUrl":152},"templates\u002FSKILL.md.tmpl",567,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002FSKILL.md.tmpl",{"path":154,"resourceType":109,"resourceTypeDesc":110,"sizeBytes":155,"sourceHtmlUrl":156},"templates\u002Fvalidator.py.tmpl",966,"https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fdocs\u002Fsuperpowers\u002Fskills\u002Fcompose-domain\u002Ftemplates\u002Fvalidator.py.tmpl",[158,179,196,210,218,225],{"skillNo":159,"name":160,"nameZh":6,"description":161,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":162,"categories":163,"keywords":164,"publishedAt":52},"01M71SJECD4KXSSJV1B0HSY4T4","proactive-customer-care","Proactively notifies and, where warranted, extends a small bounded goodwill gesture to a customer whose itinerary materially changed.","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fverticals\u002Ftravel\u002Fskills\u002Fproactive-customer-care\u002FSKILL.md",[],[165,166,167,168,169,170,171,172,173,174,175,176,177,178],"proactive","customer","proactive customer care","customer care","gesture","action","bounded","status","check","booking","operations","travel","issue","itinerary",{"skillNo":180,"name":181,"nameZh":6,"description":182,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":183,"categories":184,"keywords":185,"publishedAt":52},"01M71SJ9VHGNNTB6452H1KRZD6","payment-exception","Resolves a failed balance payment by retrying it to complete the booking, or releasing the booking's inventory when retry is not viable.","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fverticals\u002Ftravel\u002Fskills\u002Fpayment-exception\u002FSKILL.md",[],[186,187,188,189,190,174,191,192,193,172,194,195,173,175,176],"payment","payment exception","it","retry","balance","when","release","complete","capacity","inventory",{"skillNo":197,"name":198,"nameZh":6,"description":199,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":200,"categories":201,"keywords":202,"publishedAt":52},"01M71SJ6S6XREB0J6CCVCSFZ9E","hotel-supplier-recovery","Restores accommodation for a shortfall-hit hotel allotment by moving contracted rooms from a donor allotment with headroom, resolving the reported supplier shortfall.","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fverticals\u002Ftravel\u002Fskills\u002Fhotel-supplier-recovery\u002FSKILL.md",[],[203,204,205,206,173,175,176,207,208,209],"hotel supplier recovery","hotel","recovery","with","move","for","headroom",{"skillNo":211,"name":212,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":213,"categories":214,"keywords":215,"publishedAt":52},"01M71SJ4G5MPM50WZ6F66M3PNS","holiday-sales-booking","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fverticals\u002Ftravel\u002Fskills\u002Fholiday-sales-booking\u002FSKILL.md",[],[216,174,217],"holiday sales booking","sales",{"skillNo":219,"name":220,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":221,"categories":222,"keywords":223,"publishedAt":52},"01M71SJ2AHHWN2C4YV2RKEE947","flight-disruption-recovery","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fverticals\u002Ftravel\u002Fskills\u002Fflight-disruption-recovery\u002FSKILL.md",[],[224,205],"flight disruption recovery",{"skillNo":226,"name":227,"nameZh":6,"description":228,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":229,"categories":230,"keywords":231,"publishedAt":52},"01M71SHYPK8HNQ80C9XAWSER53","destination-operations","Dispatches a replacement resort transfer when an arrival is at risk, rebinding any travellers on the at-risk transfer to the replacement.","https:\u002F\u002Fgithub.com\u002Farturcrmbot\u002Fzava-control-plane\u002Fblob\u002Fmain\u002Fverticals\u002Ftravel\u002Fskills\u002Fdestination-operations\u002FSKILL.md",[],[232,175,233,234,173,235,176,236,191,237],"destination operations","destination","risk","dispatch","at","transfer"]