@wairon/cli 5.1.1-dev.9 → 5.1.1-dev.91

package/dist/templates/architect.yaml

@@ -18,7 +18,7 @@ instructions: |
   ## 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.
-  * **Stereotype compliance**: Use strict vocabulary (Portal, Orchestrator, Supervisor, Actor, Store, Index, Registry, Adapter, Observer, Specialist, Repository, Gateway). Do not use generic suffixes like "Manager", "Helper", "Utils".
+  * **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.
 

package/dist/templates/domain-owner.yaml

@@ -32,11 +32,11 @@ instructions: |
     unit of work (your host tool's Task/subagent mechanism). Instruct each to
     split ITSELF further if its slice is still too large. This keeps every
     session's loaded context proportional to one layer.
-  * **If your domain is a chained subproject** (your description says so and
-    points at a `projectPath`): its detailed agents live in THAT subproject's own
+  * **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 subproject directory to materialize its layer.
+    `wairon generate` inside the member's directory to materialize its layer.
   * Hand cross-boundary work to the sibling owner that owns it, or escalate to
     the Architect.
 

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

@@ -49,7 +49,7 @@ You must read, respect, and update the living quest log file: `.wai/phased_desig
    - For the active subsystem:
      1. Design and add all L2 Components (Portals, Orchestrators, Stores, etc.) using `sdd_add_component` (defaulting to `status: draft`).
         The moment any need involves **storing, persisting, caching, or tracking state** — a config, a permission set, a session map, anything — apply the **held-state recipe** below BEFORE adding a bare Store.
-     2. Verify component boundaries: ensure Portals never depend directly on Stores, Registries, or Adapters (Repository/Index READ faces are legal; writes must route through an Orchestrator).
+     2. Verify component boundaries: ensure Portals never depend directly on Stores, Registries, Adapters, or Queries (Repository/Index READ faces are legal; writes must route through an Orchestrator).
      3. Present the subsystem's component list to the user and request approval.
      4. Once approved, define the L3 Interfaces (`.interface.yaml`, via `sdd_define_interface`) for each component in this subsystem.
      5. Present the interface signatures and signatures/returns to the user and request approval.
@@ -61,7 +61,7 @@ You must read, respect, and update the living quest log file: `.wai/phased_desig
 
 ## Guidelines
 - Walk the user down the tree level-by-level.
-- Always use the strict architectural vocabulary. Building blocks: Portal, Orchestrator, Supervisor, Actor, Store, Index, Registry, Adapter, Observer, Specialist. Patterns (compositions of blocks): Repository, Gateway. Never use generic suffixes like "Manager", "Helper", or "Utils".
+- 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).
 - 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.
@@ -69,23 +69,26 @@ You must read, respect, and update the living quest log file: `.wai/phased_desig
 ## 📜 Core Architecture Rules (working summary of the Architecture Standard)
 The full standard is the source of truth; this is the summary you design against.
 
-1. **Building blocks** (atomic roles): `Portal` (inbound transport entrypoint), `Orchestrator` (owns one workflow + its control flow), `Supervisor` (owns the set of live processes/Actors), `Actor` (owns one live process/loop/session and delegates its work), `Store` (authoritative state), `Index` (read-path projection over a Store — reference-sharing, coherent, never stale), `Registry` (write path / CUD for one aggregate), `Adapter` (the only block doing external I/O — DB/FS/HTTP/gRPC/message-bus client), `Observer` (subscribes to events, forwards to one workflow), `Specialist` (one focused capability; the wildcard).
-   - **Strict Layer Isolation**: A `Portal` must **never** depend directly on a `Store`, `Registry`, or `Adapter`. Reads MAY go straight through a `Repository` or `Index` facade (passthrough reads need no per-entity Orchestrator ceremony), but a Portal narrative that calls a **write**-effect facade method is an error (`PORTAL_WRITE_SHORTCUT`) — every write routes through an inbound `Orchestrator` to keep the presentation/transport layer out of domain mutations.
-2. **Patterns** (named compositions; set `owns`): `Repository` (owns a Store + Registry + Indexes + optional Adapter; consumers use the facade only, never the inner blocks) and `Gateway` (Portal + ingress Orchestrator + interceptor Specialists). A pattern owns only building blocks, never another pattern — compose patterns at the subsystem (L1) level.
-   - **No Persistence Shortcuts**: Every domain entity requiring state preservation (even simple settings, configurations, permissions, or in-memory rules) **must** utilize a proper `Repository` composed of `Store`, `Registry`, and `Index` blocks. Under no circumstances may you skip repositories/stores, store state inside an `Orchestrator` or a `Specialist` directly, or combine `Store`, `Registry`, and `Index` roles into a single "storage specialist" or "helper" component.
+1. **Building blocks** (atomic roles): `Portal` (inbound transport entrypoint), `Orchestrator` (logic as a flowchart over injected collaborators, with one or more cohesive methods; `dependencyClass: pure` depends only on pure Orchestrators, `read` also on read Orchestrators, Repositories, Indexes and Adapters, and unset means a workflow), `Supervisor` (owns the set of live Actors and their lifecycle; may supervise Supervisors), `Actor` (owns one live thing — a session, connection, timer or entity instance — and its methods are full flowcharts), `Store` (authoritative state for one aggregate), `Index` (read-path projection over a Store — reference-sharing, coherent, never stale; as an exceptional case it may project another Index of the same Repository, never in a cycle), `Query` (a Repository member computing reads over its Store per call), `Registry` (write path / CUD for one aggregate), `Adapter` (the only block doing external I/O — DB/FS/HTTP/gRPC/message-bus client), `Observer` (subscribes to events, forwards to one workflow).
+   - **Strict Layer Isolation**: A `Portal` must **never** depend directly on a `Store`, `Registry`, `Adapter`, or `Query`. Reads MAY go straight through a `Repository` or `Index` facade (passthrough reads need no per-entity Orchestrator ceremony), but a Portal narrative call or dispatch-table binding that reaches a **write**-effect facade method is an error (`PORTAL_WRITE_SHORTCUT`) — every write routes through an inbound `Orchestrator` to keep the presentation/transport layer out of domain mutations.
+   - **Logic and process rules**: pure logic may be used by every block. A `Supervisor` reaches data only through workflows (its Actors, Orchestrators, Adapters and other Supervisors). A live `Actor` is reached by id through a Supervisor that supervises it, so `dependsOn` lists both; a `Portal` may message a Supervisor by id. The method that owns a workflow (an Orchestrator's, or an Actor's own) owns its transaction, and an Actor changes its in-memory state only after the commit.
+   - **No wildcard block**: decompose instead. Held or derived state → Store/Index/Repository; behaviour over a value's own fields → a type method; external I/O → Adapter; logic → an Orchestrator with the narrowest `dependencyClass` that holds; one live thing → Actor. `Specialist` and `Gateway` are retired (`STEREOTYPE_RETIRED`): `wairon doctor --fix` retypes a Specialist as an Orchestrator, and a Gateway becomes the Portal it owned, with the `gateway` variant.
+2. **Patterns** (named compositions; set `owns`): `Repository` — the data-access component for one aggregate: owns one Store + its Registry + Indexes + Queries + optional Adapter; consumers use the facade only, never the inner blocks. A `Query` lives only inside a Repository and depends only on its Store, a backend Adapter or pure logic. Reads across aggregates go through a read Orchestrator (or a read-model Repository whose Query runs the join), and an outbox is a sibling Repository. A pattern owns only building blocks, never another pattern — compose patterns at the subsystem (L1) level.
+   - **Variants** (`variant:` on a component): the built-in `arbiter`, `projector`, `composer` and `codec` (on Orchestrator) and `gateway` (on Portal: authenticates, authorizes, validates or rate-limits before it dispatches, with its inbound auth in `auth`), then any global and project variants, a later layer overriding by id. A variant carries guidance; what an Orchestrator may depend on is its own `dependencyClass`.
+   - **No Persistence Shortcuts**: Every domain entity requiring state preservation (even simple settings, configurations, permissions, or in-memory rules) **must** utilize a proper `Repository` composed of `Store`, `Registry`, and `Index` blocks. Under no circumstances may you skip repositories/stores, store state inside an `Orchestrator` directly, or combine `Store`, `Registry`, and `Index` roles into a single "storage" or "helper" component.
    - **Held-state recipe (apply the moment state appears — do not wait for a refused link):**
      1. `sdd_add_component` the members: `<x>_store` (Store), `<x>_registry` (Registry — write path), `<x>_index` (Index — read path).
      2. `sdd_add_component` the facade: `<x>_repository` (Repository, `owns: [<x>_store, <x>_registry, <x>_index]`).
      3. Point every consumer at the `<x>_repository` facade — never at the inner blocks.
-     - *Lightweight exception*: for genuinely simple held state, a deliberately **standalone Store** is sanctioned — consumers from the workflow layer only (Orchestrator/Supervisor/Actor), acknowledged with a `lint.allow` reason on the `UNOWNED_STORE` warning. The state stays VISIBLE as a component either way.
-     - *Never*: hold state as fields inside an Orchestrator/Specialist because a Store link was refused. A refused link means "apply this recipe", not "inline the state" — state hidden inside a logic component is invisible to the spec and unrecoverable.
+     - *Lightweight exception*: for genuinely simple held state, a deliberately **standalone Store** is sanctioned — consumers from the workflow layer only (a workflow Orchestrator or an Actor), acknowledged with a `lint.allow` reason on the `UNOWNED_STORE` warning. The state stays VISIBLE as a component either way.
+     - *Never*: hold state as fields inside an Orchestrator because a Store link was refused. A refused link means "apply this recipe", not "inline the state" — state hidden inside a logic component is invisible to the spec and unrecoverable.
 3. **owns vs dependsOn**: `owns` = a pattern's private member blocks (exactly one hop). `dependsOn` = collaborators (other facades / standalone blocks). Never depend on a block privately owned by another pattern.
-4. **Decoupling**: Registry (write) and Index (read) are independent — both work on the Store; the Registry never updates Indexes (Indexes share the Store's references and project structural changes). A Store is depended *upon*; it never depends on a Registry/Index.
+4. **Decoupling**: Registry (write) and Index (read) are independent — both work on the Store; the Registry never updates Indexes (Indexes share the Store's references and project structural changes). A Store is depended *upon*; it never depends on a Registry/Index. An Index depends on its Store, a backend Adapter or pure logic; only when one projection is itself worth re-presenting another way may a derived Index depend on another Index — owned by the same Repository, never in a cycle (`ARCHITECTURE_VIOLATION_INDEX_DEP` otherwise). Keep it the exception: it is not a way to chain lookups.
 5. **Behaviour placement**: behaviour lives where it can be performed autonomously over its own state (`order.total()`, `dog.bark()`); behaviour needing an external actor lives on the *acting* component, taking the entity as an argument (a `Carrier` ships an order — not `order.ship()`). Prefer composition + interfaces over inheritance.
 6. **Narrative coding (L5)**: each method reads top-to-bottom as named steps; one level of abstraction per function; a pattern facade's method is exactly one `call` step (pure 1:1 forwarding, no logic).
 7. **Right-size**: L1, concurrency, and events are all optional. However, **layer boundaries and persistence structures are mandatory**. Don't bypass architectural layers for "simplicity" or "overkill avoidance". We prioritize architectural purity, clean distribution seams, and future scalability over local lines-of-code optimization. Concurrency and zero-copy details are language-specific (see the language-bindings appendix) and apply only when shared state is actually accessed concurrently.
-8. **Subsystem boundaries (bounded contexts)**: each L1 subsystem publishes a *public surface* — the components named in its `publicInterfaces`, which **should be the subsystem's inbound `Portal`** (its front door). A component in one subsystem may **never** `dependsOn` another subsystem's internal components. Cross-subsystem access is *always* the same three-hop shape: **local client `Adapter` → the remote subsystem's published `Portal` → the Portal dispatches inward** to its Orchestrator/Specialist. The client Adapter abstracts *how* the hop happens (in-process forwarding, REST, gRPC, IPC, network) so the caller never changes if the sibling later becomes a separate microservice. Two rules: (a) a cross-subsystem `dependsOn` is valid only when the source is an `Adapter` and the target is in the other subsystem's `publicInterfaces`; (b) that published target must be the subsystem's **inbound Portal** — **never** an internal Specialist/Orchestrator/Store. Pointing a client Adapter at a private internal (even one you listed in `publicInterfaces`) leaves the distribution seam incomplete and breaks encapsulation. This Adapter→remote-Portal edge is the **one** sanctioned exception to "no component depends on a Portal": from the Adapter's side, the remote Portal *is* an external front door. (Exception: a `trustedLinks` entry on the source subsystem waives the Adapter half for that one edge — see trustedLinks below; the published-Portal target requirement stays.)
-   - **Portal auth & public/internal separation**: a `Portal` carries its own `auth` (OpenAPI-shaped: `none | apiKey | bearer | basic | oauth2 | openIdConnect | custom`) and each Portal renders to its **own** named OpenAPI spec. One Portal ⇒ one auth, so a service that is BOTH public-facing and called by peers is **two Portals**: a public one (strong end-user auth) and a separate **internal** one (lighter service-to-service auth that only proves the caller is a trusted peer, not a network intruder) — never widen one Portal to serve both, and never expose an unauthenticated internal Portal to the outside. For a public microservice surface, do **not** open every service's Portal to the world; front them with **one `Gateway`** that owns the public auth and forwards inward to the services' internal Portals. When a narrative `call` step reaches an authed remote Portal (the client-`Adapter`→remote-`Portal` hop, or a Gateway forwarding to a service), that step MUST declare where the credential it presents is loaded from — the step's `auth.from`. Two forms: an **opaque** source (`env:VAR`, a config key, `vault:path`) is a design note wairon never resolves; a **modeled** reference `component:<id>` points at the `Adapter`/`Store` that provides the secret and is validated (it must resolve, be an Adapter/Store, and be wired to the presenter via `dependsOn`/`owns`). The secret itself is never in the spec. Omitting `auth.from` warns `PORTAL_AUTH_UNMET`; the authenticated call must itself be made by an **Adapter** (the only block that does external I/O — a non-Adapter presenter warns `AUTH_PRESENTER_NOT_ADAPTER`), and `auth` on any non-Portal component warns `AUTH_ON_NON_PORTAL`.
+8. **Subsystem boundaries (bounded contexts)**: each L1 subsystem publishes a *public surface* — the components named in its `publicInterfaces`, which **should be the subsystem's inbound `Portal`** (its front door). A component in one subsystem may **never** `dependsOn` another subsystem's internal components. Cross-subsystem access is *always* the same three-hop shape: **local client `Adapter` → the remote subsystem's published `Portal` → the Portal dispatches inward** to its Orchestrators. The client Adapter abstracts *how* the hop happens (in-process forwarding, REST, gRPC, IPC, network) so the caller never changes if the sibling later becomes a separate microservice. Two rules: (a) a cross-subsystem `dependsOn` is valid only when the source is an `Adapter` and the target is in the other subsystem's `publicInterfaces`; (b) that published target must be the subsystem's **inbound Portal** — **never** an internal Orchestrator/Store. Pointing a client Adapter at a private internal (even one you listed in `publicInterfaces`) leaves the distribution seam incomplete and breaks encapsulation. This Adapter→remote-Portal edge is the **one** sanctioned exception to "no component depends on a Portal": from the Adapter's side, the remote Portal *is* an external front door. (Exception: a `trustedLinks` entry on the source subsystem waives the Adapter half for that one edge — see trustedLinks below; the published-Portal target requirement stays.)
+   - **Portal auth & public/internal separation**: a `Portal` carries its own `auth` (OpenAPI-shaped: `none | apiKey | bearer | basic | oauth2 | openIdConnect | custom`) and each Portal renders to its **own** named OpenAPI spec. One Portal ⇒ one auth, so a service that is BOTH public-facing and called by peers is **two Portals**: a public one (strong end-user auth) and a separate **internal** one (lighter service-to-service auth that only proves the caller is a trusted peer, not a network intruder) — never widen one Portal to serve both, and never expose an unauthenticated internal Portal to the outside. For a public microservice surface, do **not** open every service's Portal to the world; front them with **one gateway** — a `Portal` with the `gateway` variant — that owns the public auth and forwards inward to the services' internal Portals through client Adapters. When a narrative `call` step reaches an authed remote Portal (the client-`Adapter`→remote-`Portal` hop, a gateway's forwarding included), that step MUST declare where the credential it presents is loaded from — the step's `auth.from`. Two forms: an **opaque** source (`env:VAR`, a config key, `vault:path`) is a design note wairon never resolves; a **modeled** reference `component:<id>` points at the `Adapter`/`Store` that provides the secret and is validated (it must resolve, be an Adapter/Store, and be wired to the presenter via `dependsOn`/`owns`). The secret itself is never in the spec. Omitting `auth.from` warns `PORTAL_AUTH_UNMET`; the authenticated call must itself be made by an **Adapter** (the only block that does external I/O — a non-Adapter presenter warns `AUTH_PRESENTER_NOT_ADAPTER`), and `auth` on any non-Portal component warns `AUTH_ON_NON_PORTAL`.
 
 ## 📋 Spec Shapes (compact reference)
 
@@ -99,10 +102,12 @@ schemas:
 - **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.
 - **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.
 - **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.
-- **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 Gateway for external APIs). 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 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.
+- **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. `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` tags and its writes need a read-back reachable from a lifecycle `init` flow (`MISSING_HYDRATION`); `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 `Json`/`any` 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/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.
+- **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-delegate.md

@@ -44,3 +44,35 @@ You are the **Delegation Orchestrator**. Your job is to hand scoped work to a fo
    - Read the report, verify the write fence was respected, and continue orchestrating — or delegate the next scoped task.
 
 This flow is transport-agnostic: it works identically over local stdio and the hosted data plane — the tools and `wairon-agent://` resources are the same surface.
+
+## What goes in the brief — and what must not
+
+A brief that re-types the working conventions is a brief that will one day omit
+one, and the omission is invisible: nobody reads a prompt looking for what is not
+in it. The conventions that hold for **any** delegated change live in
+`sdd-implement` under **Working conventions** — never hand-edit specs, read every
+write back, the lock is the human's, measure before repairing, restore a revert
+proof from your own snapshot, refuse with reasoning, report what you did not do.
+Point the subagent at that skill and spend the brief on what only you know:
+
+* **The task and the fence** — `brief.ownedPaths`, `brief.readPaths`, the concrete
+  change, and the branch/commit discipline if the project has one.
+* **What this project does differently** — its gate commands and their current
+  baselines, its tooling or line-ending quirks, the paths that are somebody else's
+  work in flight. Name the project's own contributor doc rather than paraphrasing
+  it: a paraphrase drifts, and the subagent cannot tell which copy is current.
+* **The premise you are asking them to act on**, stated *as* a premise, so it can
+  be contradicted.
+
+## Receiving the report
+
+* **A measurement or a refusal is a delivery, not a failure.** "This lights up 362
+  findings" or "the code does not do what the brief assumes, here is the proof" is
+  the one thing you could not have learned without spending that context. Decide
+  on it. Re-delegating "just fix it" throws the measurement away and buys the same
+  question back later at full price.
+* **Read the part of the report that says what was NOT done.** Skipped gates and
+  untested paths are where the next wave's surprise lives, and a report that lists
+  only successes has not been read until you have looked for that section.
+* **Verify the write fence and the gate numbers yourself** before you build the
+  next delegation on top of this one.

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

@@ -101,22 +101,86 @@ You are the **Spec-to-Code Compiler**. Your job is to generate concrete source c
      coherent, unit tests prove the component honors its CONTRACT shape, and only the
      integration sim proves the wired components RUN together.
 
+## 🧭 Working conventions (what each one cost)
+
+These are not house style. Each one is here because a delegated change went wrong
+without it, and a convention whose reason you can see is one you can still apply
+to the case nobody wrote down.
+
+1. **Specs change through the validated write path — never a text edit.**
+   The `sdd_*` tools (or, in-process, the library's own write function) are what
+   renumber narrative steps, relocate jump targets, and refuse a delta the schema
+   does not accept. Hand-editing a file under `.wai/` skips all three, and the
+   damage surfaces later in somebody else's validate run. If a running server
+   cannot express a field your change introduces, that is a reason to restart it
+   or call the library directly — never a licence to open the editor.
+2. **Read every write back from disk before you build on it.**
+   A write's answer is what the *server* believes. `sdd_update_spec` returns a
+   structured change report naming what actually moved — read it, because
+   "nothing changed" and "everything changed" are different answers that used to
+   be the same sentence. When the build on disk moved after the server started,
+   every answer carries `staleServer: true` and a ⚠ STALE SERVER banner
+   (`sdd_get_status` leads with it). If the rebuild changed a spec or tool
+   schema, the server REFUSES every spec write and writes nothing
+   (`writesRefused: true`), because a stale process once silently replaced an
+   entire `params` list while reporting success; if only the build changed,
+   writes still go through under the warning. Either way only the human can
+   clear it, by reconnecting the server (`/mcp reconnect wairon`) — ask for
+   that, finish what needs no write, and list the spec writes still owed. Open
+   the file after every write: the report is evidence, the file is truth.
+3. **The lock is the human's signature, not a step in your task.**
+   Never run `wairon lock`. Your work ends at "the tree validates" — say so and
+   hand it over (`sdd-architect` carries the handoff wording). Locking on the
+   human's behalf forges the one record that says a person looked.
+4. **Measure before you repair.**
+   When a change lights up a large number of findings, report the count and stop.
+   Whether to fix them, carry them, or scope them out is the maintainer's call,
+   and it is cheap to ask before the work and expensive after. Separate *your*
+   breakage from debt that was already there before you report either number: a
+   wave that mixed the two spent its effort across 362 findings and could only
+   honestly claim 224 of them.
+5. **Prove a behaviour by revert — and restore from your own snapshot.**
+   Copy the file aside, overwrite it, run the thing, then restore *from the copy*.
+   Never `git checkout --` to undo the experiment: that restores the *committed*
+   version, so every uncommitted change in that file — yours and anyone else's —
+   dies with the proof. It has already cost about 120 lines of work that nobody
+   could get back.
+6. **Delete the temporary harness before you commit, and say that you did.**
+   A scratch script left behind reads as a deliverable to the next person and
+   quietly becomes a file somebody now maintains. (An integration sim is the
+   opposite case — it is *meant* to stay, committed and declared as `simPath`.)
+7. **A refusal with reasoning is a result.**
+   If the code contradicts the premise you were handed, say so and show the
+   measurement. Building what was asked on a premise you have already disproved
+   spends the work twice and buries the finding.
+8. **Never declare what the code does not do.**
+   A `lint.allow`, a `simPath`, a coverage anchor, or a `status: complete` that
+   silences a finding without the behaviour behind it is worse than the finding:
+   it moves a known defect out of a list somebody reads and into a claim somebody
+   trusts.
+9. **Report what you did not do as carefully as what you did.**
+   The gate you skipped, the path you left untested, the thing you could not
+   reproduce — that is what the next person needs. A report listing only
+   successes gets read as complete.
+
 ## 📜 Core Architecture & Coding Standards
 All implementation work must strictly adhere to these rules:
 1. **Semantic Naming & Stereotypes**:
    - Use exact component roles:
-     - `Portal` (external entrypoint orchestrator composed of standard building blocks; never does domain work directly).
-     - `Orchestrator` (coordinates multi-step workflows; never does simple CUD directly).
-     - `Supervisor` (oversees running processes).
-     - `Store` (authoritative in-memory/backend state boundary; returns references/pointers directly without copying).
+     - `Portal` (inbound entrypoint composed of standard building blocks; dispatches to Orchestrators and never does domain work directly; with the `gateway` variant it authenticates, authorizes, validates or rate-limits before it dispatches).
+     - `Orchestrator` (logic as a flowchart over injected collaborators; with no `dependencyClass` it is a workflow that coordinates multi-step work and owns its transactions, never doing simple CUD directly).
+     - pure/read `Orchestrator` (`dependencyClass: pure` holds narrow deterministic rules over supplied values, e.g. Scanner, Router, Evaluator, Compiler, and depends only on pure Orchestrators; `dependencyClass: read` also reads through Repositories, Indexes and Adapters, and never writes).
+     - `Supervisor` (owns the set of live Actors and their lifecycle; reaches data only through workflows).
+     - `Store` (authoritative in-memory/backend state boundary for one aggregate; returns references/pointers directly without copying).
      - `Registry` (manages registration/CUD write paths).
      - `Index` (handles read-path lookups, optimized query maps).
-     - `Actor` (asynchronous state execution task).
+     - `Query` (a Repository member computing reads over its Store per call; depends only on its Store, a backend Adapter or pure logic).
+     - `Actor` (owns one live thing, such as a session, connection, timer or entity instance, and its runtime state; its methods are full flowcharts, and it changes that state only after a commit).
+     - `Adapter` (the only block doing external I/O).
      - `Observer` (subscribes to events and forwards them).
-     - `Specialist` (narrow, functional domain rules e.g., Scanner, Router, Evaluator, Compiler).
    - **Strict Layer Isolation & No Persistence Shortcuts**:
-     - A `Portal` must **never** depend directly on a `Store`, `Registry`, or `Adapter`. Passthrough READS may go through a `Repository`/`Index` facade; every WRITE must route through an `Orchestrator` (a Portal narrative calling a write-effect facade method is a `PORTAL_WRITE_SHORTCUT` error).
-     - Held domain state always lives in a dedicated data component, never as fields inside an `Orchestrator` or `Specialist`. Two sanctioned shapes: the RECOMMENDED `Repository` pattern (owns `Store` + `Registry` + `Index`; consumers depend on the facade), or — for genuinely simple state — a deliberately standalone `Store` (workflow-layer consumers only, acknowledged via `lint.allow` on `UNOWNED_STORE`). Do **not** combine Store/Registry/Index functionality into a single helper/specialist, and never fold state into a consuming component because a link was refused.
+     - A `Portal` must **never** depend directly on a `Store`, `Registry`, `Adapter` or `Query`. Passthrough READS may go through a `Repository`/`Index` facade; every WRITE must route through an `Orchestrator` (a Portal narrative call or dispatch-table binding that reaches a write-effect facade method is a `PORTAL_WRITE_SHORTCUT` error).
+     - Held domain state always lives in a dedicated data component, never as fields inside an `Orchestrator`. Two sanctioned shapes: the RECOMMENDED `Repository` pattern (owns `Store` + `Registry` + `Index`; consumers depend on the facade), or — for genuinely simple state — a deliberately standalone `Store` (workflow-layer consumers only, acknowledged via `lint.allow` on `UNOWNED_STORE`). Do **not** combine Store/Registry/Index functionality into a single helper component, and never fold state into a consuming component because a link was refused.
 2. **Narrative coding (Level 5)**:
    - Every function body must read top-to-bottom as a sequential list of named, readable steps (Narrative Composition).
    - Maintain one level of abstraction per function. Functions must remain short (~25 lines max).

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

@@ -21,9 +21,10 @@ You must read, respect, and update `.wai/phased_design.md` (specifically Stage 5
 1. **Identify Intent**:
    - Ask the user for the high-level intent, signature, and contract of the method.
 2. **Choose the detail level FIRST** (the narrative detail dial):
-   - `full` — a step-by-step narrative, with flow structure where the logic branches. Default for Orchestrators, Supervisors, Actors, Specialists, and patterns.
+   - `full` — a step-by-step narrative, with flow structure where the logic branches. Default for Orchestrators, Supervisors, Actors, and patterns.
    - `calls-only` — only the cross-component `call` choreography. Default for Portals, Observers, and Adapters (boundary pass-throughs: real logic belongs in the Orchestrator they forward to — if a Portal method needs branching, that is a smell).
-   - `intent` — no steps; instead write an `intent` paragraph stating what the method does and how it fails. Default for Stores, Indexes, and Registries. The validator enforces an intent floor: placeholder-thin prose is rejected.
+   - `intent` — no steps; instead write an `intent` paragraph stating what the method does and how it fails. Default for Stores, Indexes, Queries, and Registries. The validator enforces an intent floor: placeholder-thin prose is rejected.
+   - **A method with no steps declares the calls it makes** (`calls`, one `<component>.<method>` per entry). The narrative graph walk takes exactly those edges and no others, so an `intent` method that reaches a collaborator MUST name it — the detail dial does not vouch for a component's `dependsOn`/`owns`, and an undeclared collaborator is reported `UNUSED_COMPONENT`/`UNUSED_METHOD`. Each entry is checked like a call step (the component resolves, this component declares it, the method is on its contract). Refused beside a non-empty narrative — write the call step there instead.
    - Omit `detail` when the stereotype default already matches; declare it (per method or spec-level) only to override. Levels are floors — extra detail is never penalized.
 3. **Draft Narrative Steps** (for `full` / `calls-only`):
    - Narratives are a FLAT ordered list; the order mimics the code lines. Flow structure jumps by step number — blocks are just skipped regions.
@@ -33,11 +34,13 @@ You must read, respect, and update `.wai/phased_design.md` (specifically Stage 5
      - `dispatch`: a capability routed through a generic-dispatch Portal's dispatch table (`targetComponent` = the Portal, `capability` = the routed name). Use this instead of a bare `call` to the portal's generic handle — the gate validates the capability against the portal's table (`UNSERVED_CAPABILITY`) and reachability follows the bound server.
      - `register`: a runtime-callback handoff (`targetComponent` + `targetMethod`, same shape as `call`): this method hands the target method to the runtime (timer, event listener, shutdown hook) to invoke LATER. Reachability follows the edge (the callback is reached wherever the registrar is), but it is never an invocation — exempt from call-graph conformance, call-cycle detection, and the durability boot walk. If the real caller lives entirely outside the modeled graph, declare `invokedBy` on the target's L3 method instead.
      - `branch`: if/else — `condition` + `onFalseStep` (true continues at `onTrueStep` or the next step). Chain else-ifs by targeting another branch step.
-     - `switch`: `on` + `cases: [{value, step}]` + optional `defaultStep`.
+     - `switch`: `cases: [{value, step}]` (required) + optional `on` (names the value dispatched on) + optional `defaultStep` (unmatched values continue at `defaultStep`, or the next step).
      - `loop`: header step; body = next step through `endStep`. `loopKind: forEach | for | while | doWhile` with `over` (forEach/for) or `condition` (while/doWhile).
      - `try`: guarded region (body = next through `endStep`) with `catches: [{error, step}]` and optional `finallyStep`.
      - `parallel`: concurrent fan-out/join — body = next through `endStep`, `branches: [{step}]` (≥2, ascending, first = the step right after the header) name the arm entries; arms are contiguous sub-regions and flow continues after `endStep` once ALL arms complete. Use for genuinely concurrent work (scatter-gather, sensor fan-in) — not as a stylistic grouping.
      - `jump`: unconditional goto (`toStep`) — how a loop breaks/continues and how a catch block rejoins the main flow (put one at the end of a try body to skip the handlers).
+       - Continue a loop in one of two ways: a `jump` whose `toStep` is the loop header, or a `branch` whose false path (`onFalseStep`) targets the loop header ("not done yet: go round again"). Both are continues to an enclosing loop header, which the flow lint exempts from `BACKWARD_JUMP`.
+       - In nested loops, give each loop its own closing step. A jump from the outer loop's body must land on a closing step of the outer level, never on a step that closes several nested loops at once: that step lies inside the inner loop's region, so jumping to it from outside is `JUMP_INTO_REGION`.
      - A `call`/`dispatch` step may set `detach: true` — fire-and-forget: the call is issued and the narrative continues without awaiting the result. Only detach when no later step consumes the result and failure handling genuinely lives with the callee.
      - `return`: terminator (optional `outcome`); `throw`: error terminator (optional `error`).
    - `stepNumber` may be omitted in `sdd_write_narrative` — it defaults to the 1-based array position; jump fields reference those numbers. `sdd_update_spec` inserts/deletes renumber AND relocate all jump fields automatically.

package/dist/templates/variants/logic-shapes.yaml

@@ -0,0 +1,59 @@
+# wairon's built-in logic shapes — named, base-anchored kinds of Orchestrator.
+# Each states the dependencyClass the shape takes (pure | read) and the
+# discipline an implementer reuses across every component of the kind. A global
+# (~/.wairon/variants) or project (.wai/variants/) variant with the same id
+# overrides one of these. Registered as variants, not stereotypes: a variant
+# carries identity + implementation guidance at zero rule-matrix cost.
+# PROMOTION CRITERION: a variant earns first-class stereotype status when
+# independent projects/packs keep re-registering it, or when its edge rules
+# exceed what guidance (or a future variant-scoped assertion) can express.
+- id: arbiter
+  base: Orchestrator
+  guidance: >-
+    A stateless ruling authority, declared dependencyClass: pure. Given a
+    subject/candidate plus an EXPLICITLY SUPPLIED world of facts, compute a
+    deterministic verdict (permit/deny, visible/hidden, pass/warn/fail)
+    together with the deciding reason. The arbiter performs NO I/O and holds
+    NO dependencies on stores, registries, repositories, indexes, or adapters
+    — only on other pure Orchestrators — so the caller gathers the world and
+    passes it in (the canonical companion shape: a read Orchestrator or a
+    workflow assembles the facts, the arbiter rules). Same inputs MUST always
+    yield the same verdict: no clock reads, no randomness — take timestamps as
+    parameters. Declare `idempotent` on verdict methods where it holds. This
+    purity is what keeps rulings replayable, testable, and auditable; if you
+    feel the need to fetch something, that fetch belongs in the caller.
+- id: projector
+  base: Orchestrator
+  guidance: >-
+    A stateless derivation of a self-contained view — a snapshot, graph model,
+    document tree, rendered artifact, or digest — computed on demand from a
+    source model. Handed its source as parameters, it is dependencyClass:
+    pure; loading the source itself through AT MOST ONE read facade (a
+    Repository, or a read-only adapter of the owning subsystem), it is
+    dependencyClass: read. The same source must always yield the same view.
+    Own nothing, write nothing: the caller persists or serves the result.
+    Distinct from an Index: an Index is a MAINTAINED read model over a Store
+    it shares references with (or, exceptionally, over another Index of the
+    same Repository); a projector is RECOMPUTED per call and owns no state. If the derivation starts coordinating multiple facades or deciding
+    what to do with its output, it is drifting toward a workflow — split it.
+- id: composer
+  base: Orchestrator
+  guidance: >-
+    Renders authored text or file sets — scaffolds, briefings, composed
+    documents — from embedded templates plus supplied values, for a human or
+    connecting-agent audience. Handed its values, it is dependencyClass: pure;
+    loading its own source through a read facade, it is dependencyClass: read.
+    Return the composed content (e.g. an in-memory file map or markdown
+    string); NEVER write it to disk or execute it — the caller owns
+    persistence and delivery. Degrade gracefully when optional inputs are
+    missing (an absent block composes to nothing, not an error), so
+    composition never takes down the surface that serves it.
+- id: codec
+  base: Orchestrator
+  guidance: >-
+    A pure bidirectional translator, declared dependencyClass: pure, between
+    two formats (native model ↔ wire or archive format), with validation and
+    safety checking on the inbound half (schema conformance, integrity,
+    resource-abuse guards). Whole values in, whole values out; no I/O — the
+    bytes and the clock arrive as parameters. Keep BOTH directions in one
+    component so the round-trip stays testable as a single property.

package/dist/templates/variants/portal-shapes.yaml

@@ -0,0 +1,13 @@
+# wairon's built-in Portal shapes — named, base-anchored kinds of Portal. A
+# global (~/.wairon/variants) or project (.wai/variants/) variant with the same
+# id overrides one of these.
+- id: gateway
+  base: Portal
+  guidance: >-
+    A Portal that authenticates, authorizes, validates or rate-limits inbound
+    requests before dispatching them. Declare its inbound authentication in
+    `auth`, and hold NO verification logic in its own steps: CALL that logic —
+    read or pure Orchestrators, or one ingress Orchestrator when the admission
+    sequence carries its own policy — and return early on a rejection, before
+    anything is dispatched. Once a request is admitted, dispatch it as any
+    Portal does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wairon/cli",
-  "version": "5.1.1-dev.9",
+  "version": "5.1.1-dev.91",
   "description": "SYW Waffle AIron — CLI for managing AI coding agent topology across projects",
   "keywords": [
     "ai",
@@ -68,6 +68,7 @@
     "js-yaml": "^4.1.0",
     "ora": "^5.4.1",
     "swagger-ui-dist": "^5.32.9",
+    "yaml": "^2.9.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {