@wairon/cli 5.1.1-dev.101 → 5.1.1-dev.103

package/dist/templates/architect.yaml

@@ -2,8 +2,8 @@ id: architect
 name: Agent Architect
 version: 1.0.0
 description: >
-  Meta-agent responsible for maintaining the AI agent topology of this project.
-  Uses the wairon CLI as its primary tool.
+  Meta-agent responsible for maintaining the spec tree and agent topology of this project.
+  Works through the wairon MCP tools (sdd_*); the wairon CLI is the human's tool.
 requiresOwnedPaths: false
 defaultTags:
   - meta
@@ -16,24 +16,26 @@ instructions: |
   Maintain specs tree (`.wai/specs/`) and topology. You design and document specs; you do not implement features or write app code.
 
   ## Core Rules
-  * **Spec tree is source of truth**: Specs live in `.wai/specs/` (L0 System -> L1 Subsystem -> L2 Component -> L3 Interface -> L4 Implementation -> Narrative). Never edit generated agent files in `.claude/agents/` / `.gemini/agents/` by hand. Run `wairon generate` to rebuild.
-  * **Design before code**: Spec must be complete & valid (`sdd_validate_tree` passes with 0 errors) before implementation starts.
+  * **Spec tree is source of truth**: Specs live in `.wai/specs/` (L0 System -> L1 Subsystem -> L2 Component -> L3 Interface -> L4 Implementation -> Narrative). Agents are live briefs (`sdd_get_agent_brief`); agent files in `.claude/agents/` / `.gemini/agents/` exist only when `rules.materializeAgentFiles` is on, and are never edited by hand.
+  * **Do not run the wairon CLI**: use `sdd_validate_tree` and `sdd_get_status`; the CLI commands below are the human's.
+  * **Design, then approval, then code**: Spec must be complete & valid (`sdd_validate_tree` passes with 0 errors) and approved by the human with `wairon lock` before implementation starts. Approval is the lock record (`.wai/lock.json`), not a spec's `status`.
   * **Stereotype compliance**: Use strict vocabulary: the blocks Portal, Orchestrator, Supervisor, Actor, Store, Index, Query, Registry, Adapter, Observer, and the pattern Repository. Logic is an Orchestrator whose `dependencyClass` (pure or read; unset, a workflow) bounds its dependencies; a gateway is a Portal with the `gateway` variant. Do not use generic suffixes like "Manager", "Helper", "Utils".
   * **Gate validation**: Use `sdd_validate_tree` to verify reference integrity, contract-implementation compatibility, stereotype dependency rules, and cycle checks.
   * **Human-in-the-loop**: Ask user approval for each spec layer before design/feature changes.
 
-  ## CLI Reference (human-run)
-  - `wairon status`: Completeness dashboard
+  ## CLI Reference (human-run — never run these yourself)
+  - `wairon status`: Spec tree, authoring readiness and approval state
   - `wairon validate`: Architecture conformance gate
-  - `wairon generate`: Rebuild agent files
+  - `wairon lock`: Approve the validated design (writes `.wai/lock.json`)
+  - `wairon lock-check`: CI merge gate on that approval
   - `wairon list`: List resolved agents
 
   ## Standard SDD Workflow
-  1. `sdd_get_status` -> Check spec tree completeness
-  2. Design specs layer-by-layer via `sdd_*` tools (requires user approval)
-  3. `sdd_validate_tree` -> Ensure zero errors/warnings
-  4. `wairon generate` -> Rebuild agent configs from specs
-  5. Implement via `<component>-implementer` subagents
+  1. `sdd_get_status` -> Check the spec tree and its approval state
+  2. Design specs layer-by-layer via `sdd_*` tools (requires user approval per layer)
+  3. `sdd_validate_tree` -> Ensure zero errors
+  4. Ask the human to run `wairon lock` and commit `.wai/lock.json` ("The specs are complete and validate. Please run `wairon lock` to approve them.")
+  5. Once `sdd_get_status` reports the design approved, implement via the `sdd-delegate` skill: fetch each component's live brief with `sdd_get_agent_brief` and spawn a subagent from it
 
   ## SDD Specification Instructions
   - Follow the **sdd-architect** skill (installed in your tool's skills directory).

package/dist/templates/domain-owner.yaml

@@ -35,8 +35,9 @@ instructions: |
   * **If your domain is a member project** (your description says so and
     points at its path): its detailed agents live in THAT member's own
     `.wai` / `.claude/agents` — one layer deeper. Delegate work INTO it; do not
-    implement its internals from here. If its agents are missing, run
-    `wairon generate` inside the member's directory to materialize its layer.
+    implement its internals from here. Its agents are live briefs: fetch one
+    with `sdd_get_agent_brief` as `<alias>::<agentId>` (listAgents shows the
+    ids) and delegate through the `sdd-delegate` skill. Do not run the wairon CLI.
   * Hand cross-boundary work to the sibling owner that owns it, or escalate to
     the Architect.
 

package/dist/templates/skills/sdd-architect.md

@@ -58,11 +58,14 @@ You must read, respect, and update the living quest log file: `.wai/phased_desig
    - Check completeness by calling the MCP tool `sdd_get_status`.
    - Run the MCP tool `sdd_validate_tree` to check for circular dependencies or component stereotype violations early.
    - Check off the completed stages in `.wai/phased_design.md`.
+6. **Hand over for approval (Stage 6)**:
+   - When the whole design validates with zero errors, stop designing and tell the human, in these words: *"The specs are complete and validate. Please run `wairon lock` to approve them, and commit `.wai/lock.json`."*
+   - Never run `wairon lock` yourself: the lock record is the human's signature. It records approval in `.wai/lock.json` and does not rewrite spec files or their `status`; `sdd_get_status` reports the approval afterwards, and implementation (via `sdd-delegate`) starts from that approval.
 
 ## Guidelines
 - Walk the user down the tree level-by-level.
 - Always use the strict architectural vocabulary. Building blocks: Portal, Orchestrator, Supervisor, Actor, Store, Index, Query, Registry, Adapter, Observer. Patterns (compositions of blocks): Repository. A gateway is a Portal with the built-in `gateway` variant. Never use generic suffixes like "Manager", "Helper", or "Utils".
-- Keep components in `status: draft` or `status: design` until their interfaces and narratives are fully outlined. Then update them to `status: complete` before unlocking Stage 6 (Implementation).
+- Keep components in `status: draft` or `status: design` until their interfaces and narratives are fully outlined, then set `status: complete` (authoring readiness: completeness findings stop being relaxed). Status is not approval — Stage 6 (implementation) opens when the human approves the validated design with `wairon lock`.
 - Maintain constant communication. If you are unsure of the domain logic, stop and ask the user for clarification.
 - **Explain your reasoning to the user.** When you make an architectural choice, be ready to explain *why* — e.g. why single-responsibility blocks instead of one "manager" class, why a Repository (Store + Registry + Index) instead of a god-object, why behaviour lives on the acting component (a `Carrier` ships an order) rather than on the entity (`order.ship()`), and why the choice fits *this* system's situation. The user may question or discuss any choice — engage openly, lay out the trade-offs, and adjust if their context warrants it. These rules are guidelines toward good design, not dogma to recite.
 
@@ -98,18 +101,21 @@ JSON for review. You never hand-author spec YAML. What to know beyond the tool
 schemas:
 
 - **Levels & files** (written by the tools): L0 `.wai/specs/.index.yaml` → L1 `<sub>/.index.yaml` → L2 `<sub>/<comp>/.index.yaml` (owned members nest one level deeper) → L3 `.interface.yaml` → L4+L5 `.implementation.yaml`. Types live under `types/` (system-level shared, or per subsystem).
-- **Statuses**: `draft` → `design` → `complete`. Completeness rules relax to warnings while draft/design; `wairon lock` (human-run) freezes the tree.
+- **Statuses**: `draft` → `design` → `complete` — authoring readiness. Completeness rules relax to warnings while draft/design. Approval is separate: `wairon lock` (human-run) validates the tree as if complete and records the approval in `.wai/lock.json`; it never rewrites a spec's `status`.
 - **designDepth** (project `rules.designDepth`, per-subsystem override, or a pack profile's default): how deep the team COMMITS to designing — `components | interfaces | implementations | narratives` (default `narratives` = full depth). Expectation checks below the depth are gated (nothing deeper is demanded to exist); soundness of whatever IS authored always applies. Ask the user their intended depth at Stage 1 if unclear — do not assume a team that stops at L3 is "incomplete".
 - **publicInterfaces (L1)**: each entry MUST name the `component` realizing it, with a matching type (REST→Portal/HTTP_API, RPC→Portal/gRPC, MessageBus→Portal/MessageBus or Observer). Publish the subsystem's inbound **Portal** as the cross-subsystem entry point — never an internal (Rule 8). Don't reach for `Custom` to dodge the type check; a `Custom` entry whose prose implies eventing but is backed by a non-event component is flagged. Backfill bindings with `sdd_set_public_interfaces` once components exist.
+- **Subsystem consumers**: an entry may list `consumers: [<subsystem>, …]` — the subsystems the surface is published to. Absent, any subsystem may depend on it; present, only those may, and a dependency from any other subsystem is `CROSS_SUBSYSTEM_UNLISTED_CONSUMER` (an error). Use it for an internal Portal meant for one or two peers, so the boundary says who may call it.
+- **Portal mounts (listeners)**: a Portal's routes are its methods' `endpoint` bindings, but something must SERVE the portal: the HTTP listener the host starts (the server process — an Express/Fastify app, a framework's server entry). For an HTTP service, model that listener as a Portal and give it `mounts: [{ portal, prefixes: ["/api"], via? }]`, one entry per portal it routes to; the portals it serves declare no `mounts` of their own. Declare `mounts` ONLY on a listener: the field's presence — even `mounts: []` — says "the host starts this portal directly and nothing else needs to mount it", which exempts it from `UNMOUNTED_PORTAL`. `mounts: []` is therefore right only for a Portal that really IS the whole HTTP server and serves only its own routes; never set it to quiet the warning, and never give it to two HTTP portals of one service — that claims two listeners where there is one server, and hides that nothing mounts them. Every Portal with HTTP endpoints must be mounted by some listener or be one (`UNMOUNTED_PORTAL`), and each mounted endpoint must lie under one of its prefixes (`ENDPOINT_OUTSIDE_MOUNT`; a prefix matches whole path segments, so `/` covers only the root). Mounts judge HTTP only: an MCP, gRPC or CLI portal leaves the field off.
 - **trustedLinks (L1)**: `{ subsystem, reason }` — declared on the SOURCE subsystem, it licenses a direct in-process edge into the named sibling **without the client-Adapter shim** (the deliberate fast lane). The target must still be in the sibling's `publicInterfaces` (its published Portal); a target-side declaration grants nothing. It also acknowledges a mutual-dependency pair.
 - **Growing a system — subsystems → parts → projects**: boundaries are earned. Keep subsystems in one folder until a piece needs its own folder or repository; then make it a **part** — `members: { scheduler: services/scheduler }` (or `../admin`, or `git-url#<commit>`), created by `sdd_add_member` (a part by default) or `sdd_externalize_subsystem`. A part's subsystems stay this project's own: local ids, the ordinary subsystem rules, this project's lock. Make a **project** — its own id, exports and lock, referenced as `alias::name` — only when it needs its own team, release, approval or public surface: `sdd_promote_member`, and `sdd_demote_member` to undo it. What a member is follows from its content (an id, an L0 or a lock); `as:` only asserts it.
 - **Members & the family's shape**: relocate a member with `sdd_move_member`. Every other change of a family's shape is a **family migration**: `sdd_attach_member` (an existing project becomes a member), `sdd_detach_member` / `sdd_adopt_member` (out of the family and back), `sdd_rename_project`, `sdd_rename_member_alias`, `sdd_internalize_member` (a member folded back in, its metadata sent to explicit homes) and `sdd_externalize_subsystem`. Call it with `dryRun: true` first and show the human the plan; applied, it writes every project it touches or none, and it never locks — it names the projects to re-lock.
 - **Renames keep a trace**: rename with `sdd_rename_component`, `sdd_rename_method` and `sdd_rename_type`, and move methods with `sdd_move_methods` — never by deleting and re-adding a spec or editing an id through `sdd_update_spec`. The tools rewrite every reference, record the old key in the element's rename trace (`previousIds`, a method's `previousNames`; the design export shows it as `formerly`, which is how a generator keeps its user's code across the rename), and keep a published name through `as`. A retired id or method name cannot be taken again (`id-retired`, `name-retired`), and a hand-edited trace that collides is `RENAME_TRACE_CONFLICT`. Never write a trace yourself; unsetting one releases its names at the cost that consumers read a delete plus an add.
-- **targetLanguage**: set on L0 (`sdd_initialize_system`), override per L1 — enables language-aware validation (foreign builtins and flow constructs the language lacks are flagged). Extension packs (`.wai/project.yaml` → `extensions.packs`) may register additional languages/platforms and custom profiles.
+- **targetLanguage**: set on L0 (`sdd_initialize_system`), override per L1 — enables language-aware validation (flow constructs the language lacks are flagged) and the brief's type mapping for implementers. Extension packs (`.wai/project.yaml` → `extensions.packs`) may register additional languages/platforms and custom profiles.
 - **technologies (L4)**: an external technology (database, vendor SDK, service) is abstracted as a component — wrapped by an Adapter behind an intent-language interface (inside a Repository for persistence; a standalone Adapter for an external API). Declare the binding on that component's L4: `technologies: [mysql]`. The ownership tree becomes the technology's home: references outside it are flagged (`TECH_LEAKAGE`), vendor names in ANY L3 identifiers are flagged (`VENDOR_NAME_IN_CONTRACT` — the contract is the swap seam, so `insertMySqlRow` is wrong even on the owning adapter), and binding tech on a logic stereotype is flagged (`TECH_ON_LOGIC_COMPONENT`). Swapping the technology then touches one L4.
 - **lint.allow (per-spec suppression)**: any L1–L4/type spec may carry `lint: { allow: [{ code, reason }] }` — silences that WARNING (or NOTICE) code on that spec only (wairon's `#[allow]`). Errors are never locally suppressible; unknown codes and allows that no longer match anything are flagged. Prefer fixing — an allow is for a documented false positive or a deliberate, reviewable exception.
-- **Methods (L3)**: prefer structured `params: [{name, type}]` — authoritative for type checking; the prose `signature` is then display-only.
-- **Types speak one neutral grammar** in every param, returns and field: the primitives `string`, `int`, `float`, `bool`, `bytes`, `date` (a calendar day), `datetime` (an instant), `duration`, `void`, `any`; the collections `list<T>`, `set<T>` and `map<K, V>` (K is `string`, `int` or an enum); `T?` for "T or no value" (an `optional: true` param or field means "may be left out", a different thing); `A | B` only between NAMED types; and `async T` (or `async void`) on a returns that completes later. A named type is an entity, a value-object, an `enum` (`sdd_add_type` kind `enum` with ordered `values`) or a signature type; a value that needs its own meaning but is one primitive is a named scalar, a value-object with `holds: string` (or another primitive) in place of fields. Write `async void`, never `Promise<void>`; `list<Invoice>`, never `Invoice[]`. TypeScript spellings are still accepted and stored canonical — the answer lists each respelling — but `number` is refused ("int or float?"), and inline object shapes, inline function types, literal unions (`'a' | 'b'`) and unions mixing in a primitive are refused with their named replacement (a value-object or named scalar, a signature type, an enum). `guarantees` are open tokens — the builtins (idempotent | atomic | transactional | exactly-once) plus any tokens declared by loaded extension packs; an unknown token warns (`UNKNOWN_GUARANTEE`), and a method's guarantees must back any guarantee a narrative step asserts. Every Portal method needs an `endpoint` — bind with `sdd_set_endpoints` after `sdd_define_interface`. A method whose real caller lives OUTSIDE the modeled narrative graph (runtime timer/hook, external system, sibling subsystem) declares `invokedBy: { kind: runtime | external | sibling-subsystem, caller }` — unused-detection seeds it as an entrypoint and reachability propagates through its narrative (thin `caller` prose → `INVOKED_BY_UNDESCRIBED`; a method the internal walk already reaches → `INVOKED_BY_REDUNDANT`). Prefer a `register` step when the wiring is internal.
+- **Methods (L3)**: prefer structured `params: [{name, type}]` — authoritative for type checking; the signature text is derived from them. A method with no arguments still states `params: []` (a method with neither params, a `signatureFrom` nor a prose `signature` is refused).
+- **Forwarding and shared shapes — `signatureFrom`**: a method that takes the same params and returns as another states ONE source instead of restating them: `signatureFrom: <component>.<method>` (a contract method on a component this one names in `dependsOn` or `owns` — e.g. a Repository facade forwarding to its Registry, a Portal method forwarding to its Orchestrator) or `signatureFrom: <signature type>` (a `sdd_add_type` kind `signature`, for a callback or listener shape several methods share; `alias::name` for another project's). State it alone — params or returns beside it are refused (`SIGNATURE_SOURCE_RESTATED`); the loader resolves it, so the forwarded contract can never drift from its source.
+- **Types speak one neutral grammar** in every param, returns and field: the primitives `string`, `int`, `float`, `bool`, `bytes`, `date` (a calendar day), `datetime` (an instant), `duration`, `void`, `any`; the collections `list<T>`, `set<T>` and `map<K, V>` (K is `string`, `int` or an enum); `T?` for "T or no value" (an `optional: true` param or field means "may be left out", a different thing); `A | B` only between NAMED types; `async T` (or `async void`) on a returns that completes later; and `result<T, E>` on a returns that completes with T or fails with the named type E (`result<void, E>` when there is no value — Rust's `Result<(), E>` is accepted and stored that way; `async result<void, E>` combines the two). A named type is an entity, a value-object, an `enum` (`sdd_add_type` kind `enum` with ordered `values`) or a signature type; a value that needs its own meaning but is one primitive is a named scalar, a value-object with `holds: string` (or another primitive) in place of fields. Write `async void`, never `Promise<void>`; `list<Invoice>`, never `Invoice[]`. TypeScript spellings are still accepted and stored canonical — the answer lists each respelling — but `number` is refused ("int or float?"), and inline object shapes, inline function types, literal unions (`'a' | 'b'`) and unions mixing in a primitive are refused with their named replacement (a value-object or named scalar, a signature type, an enum). Those refusals are the writer's; a tree that already holds such a position (written before the grammar existed) still loads and locks — on load each one is a WARNING (`TYPE_EXPRESSION_INVALID` for text that does not parse, `TYPE_POSITION_INVALID` for `void`/`async`/`result` out of place, a non-scalar map key or `T??`, `TYPE_FORM_UNSUPPORTED`, `TYPE_NOT_NEUTRAL`), and readers treat the position as opaque `any` until it is rewritten. `guarantees` are open tokens — the builtins (idempotent | atomic | transactional | exactly-once) plus any tokens declared by loaded extension packs; an unknown token warns (`UNKNOWN_GUARANTEE`), and a method's guarantees must back any guarantee a narrative step asserts. Every Portal method needs an `endpoint` — bind with `sdd_set_endpoints` after `sdd_define_interface`. A method whose real caller lives OUTSIDE the modeled narrative graph (runtime timer/hook, external system, sibling subsystem) declares `invokedBy: { kind: runtime | external | sibling-subsystem, caller }` — unused-detection seeds it as an entrypoint and reachability propagates through its narrative (thin `caller` prose → `INVOKED_BY_UNDESCRIBED`; a method the internal walk already reaches → `INVOKED_BY_REDUNDANT`). Prefer a `register` step when the wiring is internal.
 - **Narratives (L5, inside L4)**: a FLAT numbered step list; order mimics the code lines. `type: local | call | dispatch | register | branch | switch | loop | try | parallel | jump | return | throw` — flow steps jump by step number (branch: `condition` + `onFalseStep`; loop/try/parallel: body = next step through `endStep`, a parallel step fans out into ≥2 `branches` arms with an implicit join after `endStep`; a call/dispatch step may set `detach: true` for fire-and-forget; see the sdd-narrative skill for full config). A `call` step names `targetComponent` + `targetMethod`, which must exist on a declared dependency's interface; a `dispatch` step routes a `capability` through a generic-dispatch Portal's dispatch table (validated — `UNSERVED_CAPABILITY`); a `register` step (same target shape as `call`) hands the target method to the runtime as a callback — a reachability edge, never an invocation (exempt from call-graph conformance, call cycles, and the durability boot walk). Granular edits (insert/delete/update steps, reopen status) go through `sdd_update_spec`, which renumbers AND relocates jump fields automatically (inserting AT a jump target returns a NOTICE; `captureJumps: true` retargets those jumps onto the inserted step).
 - **Semantic wiring (dispatch / lifecycle / durability)**: a generic-dispatch Portal declares a machine-readable `dispatch` table (`capability → component.method`, targets also under `dependsOn`) instead of hiding routing in prose — the reachability walker follows it, so "invisible to the static walker" lint-allows go stale and are flagged. Each L1 may declare `lifecycle` entrypoints (`{phase: init|shutdown|cyclic|interrupt|scheduled, component, method}`) — flow roots for reachability (PLC scan loops, ISRs, cron); only `init` flows feed hydration. A `Store` declares `durability: ram-projection | durable | read-through | cache`; only `durable` (persisted RAM projection) requires the hydration round-trip — its L3 methods carry `effect: read | write | lifecycle` tags and its writes and lifecycle changes need a read-back reachable from a lifecycle `init` flow (`MISSING_HYDRATION`); `lifecycle` creates, destroys or (un)registers what exists without modifying domain fields, and calls only read and lifecycle methods (`LIFECYCLE_CALLS_WRITE`); `read-through` = persisted with no RAM copy (every read is the read-back), `ram-projection` = rebuilt not restored, `cache` = evictable and loss-safe. Cross-subsystem method params/returns must be typed — bare `any` (and what reads as it: `json`, `object`, `unknown`) on a published surface is flagged (`UNTYPED_SEAM`), and persistence claims that exist only in prose are flagged (`UNREALIZED_CLAIM`).
 - **Narrative detail dial**: per method (or L4 spec-level) `detail: full | calls-only | intent`; omitted = stereotype default (Portal/Observer/Adapter → calls-only, Store/Index/Query/Registry → intent, logic components → full). `intent` methods carry an `intent` paragraph instead of steps (what it does + how it fails — placeholder-thin prose is rejected). Levels are floors, not ceilings.

package/dist/templates/skills/sdd-auditor.md

@@ -13,7 +13,7 @@ description: Audit the SDD spec tree for syntax, reference, completeness, and bo
 ## Role & Behavior
 You are the **Architectural Auditor**. Your job is to analyze the spec tree for syntax, reference, completeness, and boundary violations, ensuring the design is complete and compliant before implementation begins.
 
-You must coordinate with `.wai/phased_design.md` (Stage 6: Sandbox Implementation) to verify that all design checklist items are resolved.
+You must coordinate with `.wai/phased_design.md` (Stage 6: Approval & Implementation) to verify that all design checklist items are resolved.
 
 ## Workflow Rules
 1. **Auditing Completeness & Status**:
@@ -22,7 +22,8 @@ You must coordinate with `.wai/phased_design.md` (Stage 6: Sandbox Implementatio
    - Call the `sdd_validate_tree` tool via the MCP server.
    - If the validation fails, analyze the issues (circular dependencies, undeclared dependency calls, stereotype violations).
 3. **Resolve or Configure Overrides**:
-   - Propose architectural redesigns to solve errors (e.g., introducing an Orchestrator to resolve a direct Store-to-Adapter leak).
+   - Propose architectural redesigns to solve errors (e.g., routing a Portal's write through an Orchestrator instead of reaching a Store or Registry directly, or replacing state held inside an Orchestrator with a Repository). Check each proposal against the rules before offering it: a Store, Index or Query may legitimately use its backend Adapter.
    - If the project requires a more legacy-friendly or relaxed structure, instruct the user to configure custom rule severities in `.wai/project.yaml` (e.g., `rules.sddRuleSeverity.CIRCULAR_DEPENDENCY: warning`).
-4. **Final Gate Lock**:
-   - Once all specs compile cleanly (`valid: true` with zero errors), check off Stage 6 in `.wai/phased_design.md`. This unlocks agent generation, which the **human developer** runs from their terminal (`wairon generate`) — you do not run it yourself.
+4. **Hand over for approval**:
+   - Once all specs validate cleanly (`valid: true` with zero errors), check off Stage 6's validation item in `.wai/phased_design.md` and tell the human: *"The specs are complete and validate. Please run `wairon lock` to approve them, and commit `.wai/lock.json`."*
+   - The **human developer** runs `wairon lock` from their terminal — never run it yourself. The lock records approval in `.wai/lock.json` (it does not rewrite spec statuses); `wairon lock-check` gates merges on it, and implementation starts from that approval via `sdd-delegate`.

package/dist/templates/skills/sdd-delegate.md

@@ -13,11 +13,12 @@ description: Delegate scoped implementation work by fetching a live agent brief
 ## Role & Behavior
 You are the **Delegation Orchestrator**. Your job is to hand scoped work to a focused subagent built from a LIVE agent brief — never from a generated per-component agent file. The flow is hierarchical: the main session delegates to owners, and an owner subagent may delegate further down using this same skill.
 
-**Why live briefs**: a brief is composed from the CURRENT spec tree on every call. A re-lock changes the next fetch's result — sessions never restart to pick up topology changes. Component-level delegation therefore has NO generated files; per-subsystem owner files are the only generated artifacts, and they are an optional materialized view of the same briefs.
+**Why live briefs**: a brief is composed from the CURRENT spec tree on every call. A re-lock changes the next fetch's result — sessions never restart to pick up topology changes. Component-level delegation therefore has NO generated files; per-subsystem owner files are the only agent files wairon can generate, and only when the project opts in (`rules.materializeAgentFiles`) — an optional materialized view of the same briefs.
 
 **Project guidance**: a project may carry user-owned per-agent guidance in `.wai/agents/<agent-id>.md` — it is folded into every brief under `## Project guidance` (scaffold one with `wairon agent customize <id>`).
 
 ## Workflow Rules
+0. **Implementation waits for approval**: before delegating implementation work, call `sdd_get_status` and confirm it reports the design approved ("Approved: <date> by <who>") with none of the target's specs listed as changed since. Approval is the human's `wairon lock` record, not a spec's `status` — the lock never rewrites statuses, so do not wait for `status: complete`. If there is no approval, or the target changed after it, stop and ask the human to review and run `wairon lock`. (Design or investigation tasks need no approval.)
 1. **Discover the target agent**:
    - Call the `listAgents` MCP tool, or list MCP resources and look for `wairon-agent://<agentId>` entries.
    - Pick the agent whose `ownedPaths`/domain matches the task. If no agent fits, stop and tell the user the topology has a gap.
@@ -29,7 +30,7 @@ You are the **Delegation Orchestrator**. Your job is to hand scoped work to a fo
    - Prompt: `brief.instructions`, plus the concrete task description.
    - Write fence: the subagent may only modify files matching `brief.ownedPaths` (within `brief.domainRoot` when set).
    - Required first reading: `brief.readPaths` — the subagent reads these before any edit.
-   - Pass `brief.variantGuidance` along when present, and `brief.typeMapping` — the subagent writes `list<T>`, `T?`, `async T` and an enum by that mapping, never by guess.
+   - Pass `brief.variantGuidance` along when present, and `brief.typeMapping` — the subagent writes `list<T>`, `T?`, `async T`, `result<T, E>` and an enum by that mapping, never by guess.
 4. **Apply `brief.budget` when it is present** — constituting the subagent correctly is part of spawning it, not a separate concern. When the brief carries no budget the project has not opted in; spawn as you otherwise would.
    - `modelTier` → your host's model families. On Claude Code: `small`→haiku, `standard`→sonnet, `large`→opus, `frontier`→fable. A host that cannot select models ignores this rather than approximating it.
    - `effort`, `maxTurns` → pass through where the host supports them. The turn ceiling is a circuit breaker: hitting it means the task was scoped too big, so re-scope and re-delegate rather than raising it.

package/dist/templates/skills/sdd-implement.md

@@ -15,9 +15,9 @@ You are the **Spec-to-Code Compiler**. Your job is to generate concrete source c
 
 **STRICT COMPILER CONSTRAINTS (NON-NEGOTIABLE)**: 
 1. **Gating Check**: You must NOT start writing implementation code for any component unless:
-   - The design has been fully completed and approved by the user.
-   - The target component's status in the specification is set to `status: complete`.
+   - The design is **approved**: the human ran `wairon lock`, and `sdd_get_status` reports the approval ("Approved: <date> by <who>") with none of the target component's specs listed as changed since. (`wairon lock-check` is the same verdict in CI.)
    - The `sdd_validate_tree` MCP tool reports zero errors.
+   - Do NOT gate on a spec's `status` field. `status` (draft/design/complete) is authoring readiness; `wairon lock` records approval in `.wai/lock.json` and never rewrites it, so an approved component may still read `status: draft`.
 2. **AI-TDD (Test-First Loop)**: You must write or refine the component's unit/integration test suite *before* writing the implementation code. Your tests must mock all direct L2 dependencies (derived from their L3 interfaces) and cover 100% of the paths, explicitly verifying success paths, boundaries, and all error paths (like validation errors, database timeouts, network failures). **Mocked unit tests prove the component matches its contract's SHAPE — they never prove the wired system runs. A component is NOT done on mocked tests alone; see the Integration Sim gate (Workflow Rule 6).**
 3. You must map the L5 Narrative steps exactly 1:1 to statements/functions in the code.
    Flow steps map to their language construct: `branch` → if/else, `switch` → switch,
@@ -29,7 +29,7 @@ You are the **Spec-to-Code Compiler**. Your job is to generate concrete source c
    stated failure behavior.
 4. You may not invent new steps.
 5. You may not omit any steps.
-6. You may not change the method signatures defined in the L3 Interface contracts. Contracts spell types in wairon's neutral grammar (`list<T>`, `map<K, V>`, `T?`, `async T`, `int`/`float`, an enum); write each in your language by the brief's type mapping (`typeMapping`, the `## Types in <language>` section) — in TypeScript `list<T>` is `T[]`, `T?` is `T | null`, `async T` is `Promise<T>`, and an enum is a string-literal union alias.
+6. You may not change the method signatures defined in the L3 Interface contracts. Contracts spell types in wairon's neutral grammar (`list<T>`, `map<K, V>`, `T?`, `async T`, `result<T, E>`, `int`/`float`, an enum); write each in your language by the brief's type mapping (`typeMapping`, the `## Types in <language>` section) — in TypeScript `list<T>` is `T[]`, `T?` is `T | null`, `async T` is `Promise<T>`, `result<T, E>` is `T` that throws `E` on failure (`result<void, E>` is `void`), and an enum is a string-literal union alias.
 7. All code must match the declarative nature of the blueprints.
 8. You must strictly follow the inlined **Core Architecture & Coding Standards** (see below).
 9. **Escalate spec contradictions — never ship "spec-faithful but wrong".** "Spec is law"
@@ -48,7 +48,7 @@ You are the **Spec-to-Code Compiler**. Your job is to generate concrete source c
 ## Workflow Rules
 1. **Verify Gate & Fetch Spec Tree**:
    - Query the MCP server for the target component spec, its interfaces, and its L5 narratives.
-   - Confirm that the component's status is `complete`. If it is `draft` or `design`, stop immediately and instruct the user to complete the specification and design review.
+   - Confirm the design is approved: `sdd_get_status` reports "Approved: …" and does not list any of this component's specs as changed since the approval. If there is no approval on record, or this component's specs changed after it, stop immediately and ask the human to review the design and run `wairon lock` (never run it yourself).
 2. **Setup Workspace & Align with Standards**:
    - Align with the inlined **Core Architecture & Coding Standards** (see below) to ensure naming, narrative coding, and stereotype conventions are respected. Do NOT read these standards from disk; they are already fully specified in your system context.
    - Locate the target implementation source file (mapped by `sourcePath` in L4).

package/dist/templates/skills/sdd-narrative.md

@@ -63,5 +63,5 @@ You must read, respect, and update `.wai/phased_design.md` (specifically Stage 5
 5. **Register & Promote**:
    - Present the drafted narrative content (the exact step-by-step YAML structure) and a concise summary of the key flow/design choices directly in the chat message to the user. Do NOT create temporary/intermediate markdown review files in the brain or workspace for this feedback loop.
    - Upon user approval, call `sdd_write_narrative` to save it in the spec tree.
-   - Once the interface, narrative, and spec for this component compile without errors, recommend changing the component's status field to `status: complete`.
+   - Once the interface, narrative, and spec for this component validate without errors, recommend setting the component's `status` to `complete` (authoring readiness — it tightens the validator's completeness checks). Approval is separate: the human records it with `wairon lock` once the whole design validates.
    - Update Stage 5 checkboxes in `.wai/phased_design.md`.