@wairon/cli 5.1.1-dev.112 → 5.1.1-dev.114

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

@@ -51,6 +51,7 @@ You must read, respect, and update the living quest log file: `.wai/phased_desig
         The moment any need involves **storing, persisting, caching, or tracking state** — a config, a permission set, a session map, anything — give that state a component of its own, choosing the **smallest sound shape** from the held-state guidance below.
         Design the SMALLEST sound system: count the components against the endpoints and the state they serve. Ten endpoints over two simple tables is a handful of components, not thirty; every block you add must buy a rule it enforces or a seam it opens.
      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).
+        When a Portal needs what an Adapter does (a client Adapter to a sibling subsystem, an external API), the call goes in the Orchestrator the Portal already dispatches to — never a new Orchestrator whose only job is to forward one call. A forwarder is the price only when nothing else is in the path; for a sibling subsystem in the same process, prefer a `trustedLink` on the calling subsystem, which lets the Portal (or any component) depend on the sibling's published Portal directly, with no client Adapter and no forwarder.
      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.
@@ -110,11 +111,13 @@ schemas:
 - **Libraries are called directly**: another project's `InProcess` Portal (a crate, a package, a jar, an FFI/DLL surface) is called from ANY component — `alias::portal` in `dependsOn`, `alias::portal.verb` in a call step — with no client Adapter. Pure logic may call only library verbs declared `effect: none`, read logic also `effect: read` (`LIBRARY_CALL_IMPURE`); a native library (no `abi`) called from another `targetLanguage` needs `abi: c` or `abi: wasm` (`LANGUAGE_BRIDGE_MISSING`). Wrapping a volatile third-party API in your own Adapter is a good habit, not a rule. Within one project a sibling subsystem is still reached through a client Adapter or a `trustedLink`.
 - **Transport and naming**: name a Portal for what it serves, not its wire (`order_portal`, not `http_handler`); the `transport` says the wire. Method names follow the project's method casing — camelCase for TypeScript and Java, snake_case for Rust and Python, from `targetLanguage` unless `rules.naming` says otherwise — and a wire name that differs (an HTTP path, a CLI command like `lock-check`, a JSON-RPC method like `tools/call`) lives on the method's `endpoint`, never in the method name.
 - **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.
-- **Declare planned code at design time**: give each implementation the `sourcePath` its code will live at (and a method its own `sourcePath` when its body lives elsewhere) — and each TYPE the `sourcePath` of the file that will declare it (with `symbol` when the code name differs): a type without one is never compared with the code's shape, which is `MISSING_TYPE_SOURCE_PATH` (a notice while its subsystem has no code, a warning once it has). Code linkage — `sourcePath`, `symbol`, `exportedVia`, `simPath`, `injectedParams`, conformance tiers — is not part of the approval, so declaring or changing it never asks for a re-lock. A file not written yet is `SOURCE_FILE_PLANNED` (a notice, never a `--ci` failure) until the component's realization begins; never strip a planned path to quiet anything. A team that wants CI to demand code for every designed implementation sets `rules.conformance.requireCode: true`.
+- **Declare planned code at design time**: give each implementation the `sourcePath` its code will live at (and a method its own `sourcePath` when its body lives elsewhere) — and each TYPE the `sourcePath` of the file that will declare it (with `symbol` when the code name differs): a type without one is never compared with the code's shape, which is `MISSING_TYPE_SOURCE_PATH` (a notice while its subsystem has no code, a warning once it has).
+  - **Plan type files per owner, not one file for all**: each implementer brief fences the files its component's specs ALONE name, so the type files decide what can be implemented in parallel. A type one component realizes (its `componentClass`, an aggregate's entity) or only its own contracts use goes in that component's own file or its own types file (`src/habits/types.ts`); value types several components share go in ONE subsystem types file that no component owns — every brief then lists it under shared, and the spawning session gives it one writer. Never put every type of the system in one `src/types.ts`: two Stores' entity types in one file put the same file in front of two agents.
+  - **`injectedParams` are NOT design-time**: leave them out of every `sdd_write_narrative` call. They record a parameter a framework imposes on code that exists (a request handle, a context), and the implementer declares them once its code takes one; constructor wiring guessed now (`db`, `deps`, `config`, `req, res`) is linkage nothing takes, which the gate reports. Code linkage — `sourcePath`, `symbol`, `exportedVia`, `simPath`, `injectedParams`, conformance tiers — is not part of the approval, so declaring or changing it never asks for a re-lock. A file not written yet is `SOURCE_FILE_PLANNED` (a notice, never a `--ci` failure) until the component's realization begins; never strip a planned path to quiet anything. A team that wants CI to demand code for every designed implementation sets `rules.conformance.requireCode: true`.
 - **Externals — the pin gates, live drift is visible**: declare a project this one consumes with `sdd_add_external` (alias; source `../sibling`, `hosted:<id>`, `<git url>` or `<git url>#<commit>`; optional `project`, `use`, `description`) instead of editing `.wai/project.yaml`. It refuses in one sentence what cannot be declared, takes the declaration back out when the producer contradicts it (another id, an unexported `use` name), and pins it by default. The owner's gate judges each external against its pin; `sdd_validate_tree` and `sdd_get_status` add ADVISORY live-drift findings (`EXTERNAL_LIVE_INCOMPATIBLE`, `EXTERNAL_DRIFTED`, `EXTERNAL_LIVE_UNCOMPARED`) that never make the tree invalid — adapt the uses, then the human re-pins. `wairon externals status` is the human's opt-in live gate.
 - **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.
+- **Renames keep a trace**: rename with `sdd_rename_component`, `sdd_rename_method` and `sdd_rename_type` (a contract or an implementation on its own with `sdd_rename_spec`), move methods with `sdd_move_methods` and a component or a type to another subsystem with `sdd_move_spec` — never by deleting and re-adding a spec or editing an id or a subsystem 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 (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.

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

@@ -24,7 +24,7 @@ You are the **Delegation Orchestrator**. Your job is to hand scoped work to a fo
    - Pick the agent whose `ownedPaths`/domain matches the task. If no agent fits, stop and tell the user the topology has a gap.
 2. **Fetch the LIVE brief**:
    - Call `sdd_get_agent_brief(agentId)` (or read the `wairon-agent://<agentId>` resource).
-   - The brief carries: `agentId`, `name`, `template`, `domainRoot?`, `ownedPaths`, `readPaths?`, `instructions`, `variantGuidance?`, `typeMapping?` (how the contracts' neutral types are spelled in the language the agent's code is written in, also folded into `instructions` under `## Types in <language>`; TypeScript's table is the one code conformance reads back, while Rust's and Python's are mapping-only tables the code analyzer does not check, and the table says so), `codeFence?` (where the agent may write code: exactly the files its specs alone name — its implementation, method, simPath and binding files and the files of the types it owns — planned ones included, never a folder glob, so parallel fences never overlap), `sharedPaths?` (files it may touch but does not own: files other components' specs name too, such as a shared type module, and the module setup on the way to its code — manifests, compiler settings, package roots — plus unnamed helpers beside it), an `## Externals used` section for a component reaching another project (each alias, the names it uses, the producer's transport and abi, the pinned snapshot `.wai/externals/<alias>.yaml`, which joins `readPaths` — code against the pin, never the producer's source — and the binding modules its implementations name), and — when the project opted into `execution.tier` — `profile` and `budget`.
+   - The brief carries: `agentId`, `name`, `template`, `domainRoot?`, `ownedPaths`, `readPaths?`, `instructions`, `variantGuidance?`, `typeMapping?` (how the contracts' neutral types are spelled in the language the agent's code is written in, also folded into `instructions` under `## Types in <language>`; TypeScript's table is the one code conformance reads back, while Rust's and Python's are mapping-only tables the code analyzer does not check, and the table says so), `codeFence?` (where the agent may write code: exactly the files its specs alone name — its implementation, method, simPath and binding files and the files of the types it owns — planned ones included, never a folder glob, so parallel fences never overlap), `sharedPaths?` (files it may touch but does not own: files other components' specs name too, such as a shared type module, and the module setup on the way to its code — manifests, compiler settings, package roots, a planned one included (a Portal's `mod.rs`, where its sibling adds only the line declaring its module) — plus unnamed helpers beside it), an `## Externals used` section for a component reaching another project (each alias, the names it uses, the producer's transport and abi where the pin records them, the pinned snapshot `.wai/externals/<alias>.yaml`, which joins `readPaths` — code against the pin, never the producer's source — or, for a member project, its L0 export table read live, with the names spelled as that table exports them; and the binding modules its implementations name), a `## Handler shape` section for a Portal (the contract's own parameters per verb, the handles named in `injectedParams`, the `router` linkage), a `## Code linkage you own` section (when to declare `injectedParams`, and the ones declared now, which may be design-time guesses to remove), and — when the project opted into `execution.tier` — `profile` and `budget`.
    - **Never reuse a brief across delegations or after a re-lock** — fetch fresh per delegation; the call is cheap and the brief is always current.
 3. **Spawn a GENERIC subagent from the brief**:
    - Prompt: `brief.instructions`, plus the concrete task description.
@@ -65,6 +65,11 @@ Point the subagent at that skill and spend the brief on what only you know:
   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.
+* **For a Portal, what its handler shape section cannot know** — the brief's
+  `## Handler shape` states the rule; add the framework this project uses and the
+  handles it really hands each function, so the subagent declares exactly those in
+  `injectedParams` (and removes any guessed earlier). A subagent left to guess
+  writes `(req, res)` handlers, and the gate reads those as substitutions.
 
 One design decision never goes into a brief as an instruction: **an entry**. A
 subagent that meets an unreached Portal verb (`UNUSED_COMPONENT` /

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

@@ -184,6 +184,15 @@ All implementation work must strictly adhere to these rules:
      - A Portal's verbs are reached by the callers the design models or by the outside callers its `invokedBy` entry names. Serve exactly those: the Portal's L4 `router` is the entry its file exports for whatever process hosts it. Never add a verb, route or command the contract does not declare, and never ask for an entry to make an `UNUSED_*` finding go away — report the unreached verb instead.
      - Another project's library (an `InProcess` Portal) is imported and called directly from the component the narrative names — no wrapper Adapter unless the design has one. Keep pure and read logic to the library verbs whose `effect` the design allows.
      - Function names follow the contract's method names in the language's casing; a wire name that differs (an HTTP path, a CLI command, a JSON-RPC method) belongs to the endpoint binding — route it there, do not rename the function after it.
+   - **Handler shape — the green path for a framework handler** (no design change, no re-lock):
+     - A verb's function takes the contract's OWN parameters, in order, under the contract's names. `cancelOrder(req, res)` realizing `cancelOrder(orderId, customerId)` is reported as two substitutions (`UNREALIZED_PARAM` + `UNDECLARED_PARAM`), annotated or not; so is a request object, or any object sharing none of the record's fields, where the contract declares a record.
+     - What a framework hands the function besides those — a context, a request, a response, `next` — is wiring: name it in the implementation's `injectedParams` with `sdd_update_spec` (code linkage, outside the approval). It is matched with or without its leading underscore, at the START or the END of the list: `handler(ctx, req, orderId, customerId, res)` with `injectedParams: [ctx, req, res]` is green.
+     - Two honest shapes: (a) the router unpacks the path, query and body and calls `cancelOrder(orderId, customerId)` (handles injected around them if the framework insists); (b) the framework hands the handler the request alone — inject it and read each contract parameter off it **by its own name** (`req.params.orderId`, `req.query['limit']`, `const { orderId } = req.params`), which realizes the parameter through the handle. A contract parameter never read is still `UNREALIZED_PARAM`.
+     - An injection no handler takes is `UNUSED_INJECTED_PARAM` — drop it. A leading `_` marks a parameter the body provably never reads; a used `_secret` is judged like any other.
+   - **`injectedParams` are yours to set, when the code exists** (any component, not only a Portal): declare one only once your code takes a parameter its framework or wiring imposes beside the contract's own — with `sdd_write_narrative` (`injectedParams`) or `sdd_update_spec` (`{"injectedParams": ["ctx"]}`). A dependency the code holds as a field or receives in a constructor is not one. A list already on the implementation may be a guess written at design time, before any code existed (`db`, `deps`, `config`, `req, res`): keep the names your functions really take and remove the rest — `sdd_update_spec` with `{"injectedParams": [{"value": "db", "action": "delete"}]}`, or `[]` to clear it. It is code linkage, so neither change asks for a re-lock; the brief's **Code linkage you own** section lists what is declared now.
+     - `conformance: off` (on the implementation or one method) is for code wairon is not meant to compare with its contract — generated or vendored code. It switches the realization checks off (method, parameters, async, forward call claims), never the doctrine: an unnarrated write, a write shortcut and a call the analysis cannot follow are still reported.
+   - **Routers**: set the Portal implementation's `router` (code linkage) to the entry its file exports (`handleOrderRequest`), or to a central module's table or entry (`src/routes.ts#ROUTES`), or to the module alone (`src/routes.ts`). Write routes in a readable idiom: guards on `<request>.method` and `parts[i]`, or a route table — an array of `{ method, path }` objects or an object keyed `VERB /path` (template-literal keys over constants, and a table returned in place, are read). Table paths are written under the prefix the router strips, and that prefix must be the Portal's `basePath`.
+   - **Another project's code** is reached through what it exports — its member alias or a pinned external — or through a binding module the implementation declares in `bindings`. Importing a name straight out of its source tree that it does not export is `CROSS_PROJECT_SOURCE_IMPORT`.
    - **Strict Layer Isolation & No Persistence Shortcuts**:
      - 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.

package/docs/cli.md

@@ -28,6 +28,8 @@ re-run `wairon init` for an independent project).
 **What to commit.** All of `.wai/` — the specs, `project.yaml`, `lock.json`,
 `externals/` and `externals.lock.yaml`, vendored packs: the gate reads committed
 files only (a migration's scratch folder, `.wai/transactions/`, ignores itself).
+The one exception is `.wai/.spec-write.lock`, the short-lived lock spec writers
+take so two sessions never lose a write: add it to `.gitignore`.
 The generated `CLAUDE.md`/`GEMINI.md`, `.claude/` (or `.gemini/`) skills and
 `.mcp.json` hold no machine path: commit them and every clone's assistant starts
 with them, or ignore them and run `wairon generate` after a clone — either way
@@ -151,14 +153,19 @@ warnings as errors (notices are printed and counted, never fatal).
   declare the producer's names in the binding itself), or its component reaches
   neither a pinned external nor a member project that exports something. Both
   ES module exports and CommonJS exports are read (`exports.X = { … }`,
-  `module.exports.X = function (…) {…}`, each property of `module.exports =
-  { … }`). Return types are not compared. A binding into a contained **member**
+  `module.exports.X = function (…) {…}` or `= X`, each property of
+  `module.exports = { … }` — a shorthand `{ Client }` included —
+  `module.exports = class X { … }`, a TypeScript `export = X`, and JSDoc
+  `@typedef`/`@property`), a bare identifier through the module's own
+  declaration of it; a `_private` class or object member is not compared, and
+  an object tagged as a whole has each member judged against its tag. Return types are not compared. A binding into a contained **member**
   project (declared under `members`, never pinned — named by its alias or its
   project id) is compared the same way with what the member's L0 exports now
   (its exported contracts and types, and the types they name), so a
   `rename-param` or `rename-field` in the member reaches its parent's binding
   at `validate` time as `BINDING_DRIFT` with the rename to follow; a member is
-  never told to pin — one that exports nothing is told to export there. A git
+  never told to pin — one that exports nothing is told to export there. A
+  member in a `../` sibling checkout is a contained one here. A git
   member is pinned like an external (`wairon externals pin <alias>`) and
   compared with that pin. A file of another project imported directly from its
   source tree is not a binding: it is the producer's own code.
@@ -198,7 +205,8 @@ warnings as errors (notices are printed and counted, never fatal).
   `MISSING_SOURCE_FILE` (error) and a contract method naming no file is
   `METHOD_SOURCE_PATH_MISSING` (warning). `rules.conformance.requireCode: true`
   in `project.yaml` reports the two notices as errors, for a CI that must say
-  every designed implementation has code.
+  every designed implementation has code. It is code-conformance configuration,
+  outside the approval identity: flipping it never stales a lock (see `lock-check`).
 - **Types are linked to code too.** A type spec without a `sourcePath` is
   `MISSING_TYPE_SOURCE_PATH` — a notice before its subsystem has code, a
   warning after. Plan a type's `sourcePath` when you plan the implementations'.
@@ -263,6 +271,79 @@ warnings as errors (notices are printed and counted, never fatal).
   that Portal is realized by the link, never reported `UNREALIZED_DEPENDENCY`:
   never add an import across a network boundary to satisfy a check.
 
+#### Framework handlers, injected handles and routers
+
+The parameter check pairs a verb's contract parameters with the function that
+realizes it, in order. A framework handler is green without any design change:
+
+- **Take the contract's own parameters, under its names.** `cancelOrder(req, res)`
+  realizing `cancelOrder(orderId, customerId)` is two substitutions
+  (`UNREALIZED_PARAM` + `UNDECLARED_PARAM`), however the handles are typed (a
+  hand-written `type Req = { params: … }` included) and wherever the contract's
+  types live (a member project's `shared::order_id` is read live): a parameter
+  named as a transport handle (req, res, ctx, request, response, next, reply) where
+  the contract declares an argument of its own is never a silent pairing. Neither
+  is a platform transport class (`IncomingMessage`, a fetch `Request`) or an
+  object sharing none of a record's fields where the contract declares that
+  record; an object holding every field under another name is a rename
+  (`PARAM_NAME_MISMATCH`), and one object carrying several of the contract's
+  parameters (`cancelOrder(input: { orderId, customerId })`) leaves each of them
+  unrealized.
+- **A record parameter is typed as the record.** Where the contract declares a
+  record, a parameter typed `any`, `unknown`, `object` or
+  `Record<string, unknown>` (or not annotated at all, in TypeScript) names no field
+  to compare, and an object missing the record's fields or adding its own
+  (`{ stops; secret }`) is another shape: both are `PARAM_TYPE_MISMATCH`. The check
+  fails closed on them, as it does on an `any` receiver.
+- **Declare what the framework hands you as wiring.** Name the handles in the
+  implementation's `injectedParams` (code linkage: `sdd_update_spec`, no
+  re-lock). A name matches with or without its leading `_`, at the start or the
+  end of the list — `handler(ctx, req, orderId, customerId, res)` with
+  `injectedParams: [ctx, req, res]`. An injection no handler takes is
+  `UNUSED_INJECTED_PARAM`, a notice: it hides nothing, so drop it when you see it.
+- **Or read the parameters off the request.** Where the framework hands the
+  handler the request alone, inject it and read each contract parameter off it by
+  its own name (`req.params.orderId`, `req.query.limit`, `req.body.code`,
+  `const { orderId } = req.params`, `url.searchParams.get('limit')` on a
+  `new URL(req.url, base)`): that realizes the parameter through the handle. So
+  does a helper the request is passed to, written in the same file or in a module
+  no implementation claims (`const { orderId } = pathParams(req)`), and the one
+  record parameter is realized by reading the body whole (`req.body`). A
+  parameter never read off it stays `UNREALIZED_PARAM`.
+- **`conformance: off`** on an implementation or a method is for code wairon is
+  not meant to compare with its contract (generated or vendored code). It switches
+  the realization checks off — method, parameters, async, whether narrated calls
+  are found — and never the doctrine: an unnarrated write
+  (`UNDECLARED_WRITE_CALL`), a call the analysis cannot follow, a Portal write
+  shortcut and route coverage are judged whatever it says. A dial turned off is
+  said: `REALIZATION_UNCHECKED` (a notice per implementation) and a
+  `Conformance off:` line in `wairon status`.
+
+A Portal's `router` (code linkage) names the entry its own file exports
+(`handleOrderRequest`), a central module's entry or table
+(`src/routes.ts#ROUTES`), or a module alone (`src/routes.ts`, every route-bearing
+export read). Several Portals may name one router — a module, or one table both
+name (`router: routes`) — and a route is declared when any of them declares it.
+Guards on `<request>.method` and `parts[i]` are read, and so are route tables — an
+array of `{ method, path }` objects or an object keyed `VERB /path`
+(template-literal keys over constants included), bound to a const or returned in
+place, spreading other tables (`[...ingestRoutes, ...statsRoutes]`) from any
+module. Route coverage is never silently off: a Portal whose contract binds HTTP
+endpoints and whose implementation names no router gets a `ROUTER_UNDECLARED`
+notice naming `router:`, and a router that cannot be read is
+`UNREADABLE_ROUTER`. A table is read under the ONE prefix its router strips off the
+path (`path.slice(BASE.length)`), so that prefix must be the Portal's `basePath`:
+another one is `UNDECLARED_ROUTE` + `UNROUTED_ENDPOINT`, naming both.
+
+Another project's code is reached through what it publishes — its member alias, a
+pinned external — or through a binding module the implementation declares in
+`bindings`. An import that resolves into its source under a name it does not
+export is `CROSS_PROJECT_SOURCE_IMPORT` (warning); one into a module realizing its
+Store is the persistence shortcut past its surface. A claimed call into a
+component whose code is in another language (a Rust member behind a binding) is
+not judged by the TypeScript call graph: it is said once per project and language
+as `CALL_ACROSS_LANGUAGE` (notice), never as an unrealized call.
+
 #### Technologies and their packages
 
 `TECH_LEAKAGE_IN_CODE` compares each import's package with the packages of the
@@ -332,8 +413,16 @@ When any spec is still `draft` or `design`, the lock says how many of how many,
 per kind (subsystems, components, contracts, implementations, types), and that
 it approves them as they stand. Re-running it when nothing it records moved
 keeps the record on file — its `lockedAt` included — so `.wai/lock.json` stays
-unmodified; a change of approver, verdict, member pin or wairon release writes
-a new record.
+unmodified; a change of approver, verdict or member pin writes a new record. A
+new wairon release writes nothing by itself: when its built-in design rules are
+the same as the ones the record was taken under (the record's `gateParts.release`
+is unchanged), the approval simply still matches and the record — its release
+stamp included — is left as it is; when they moved, the approval carries over
+by re-validation and one `wairon lock` refreshes the stamp (see *Upgrading
+wairon* under `lock-check`). Evidence recorded *beside* the approval (the code
+results with the analyzer's version, the design counts, gate parts, a release
+stamp that is missing, no version or newer than the running wairon) is refreshed
+and named; the summary says when this run left the file untouched.
 
 **What it certifies is the design.** Only design findings can refuse a lock.
 Code-conformance findings (the code↔spec checks) are recorded **beside** the
@@ -419,11 +508,28 @@ whole design's, so it is refused as a first approval (run `wairon lock`), and
 refused whenever a spec outside the subsystem — or an input the identity covers
 besides the design (rule tuning, packs, network, a pin, a member's approval,
 the release) — moved since the approval; when it passes, the rest stays approved
-exactly as it was, and the record is the one a full lock would write. When
-nothing changed, `lock` leaves the approval on record as it is — its `lockedAt`,
-release stamp and restamp trace — and `.wai/lock.json` untouched; only evidence
+exactly as it was, and the record is the one a full lock would write. A
+member project's subsystem (`--subsystem payments_svc::payments` at a parent) is
+refused: a member's subsystem is approved at the member's own root
+(`wairon lock --subsystem payments` in its folder), then the parent locks to pin
+its new approval. When
+nothing changed, `lock` leaves the approval on record as it is — its `lockedAt`
+and restamp trace — and `.wai/lock.json` untouched by that run; only evidence
 recorded *beside* the approval (the code results, the design counts, gate parts
-that are missing or do not match the identity) is refreshed, and it says which.
+that are missing or do not match the identity, a release stamp that is missing,
+no version or newer than this wairon — replaced with this release) is refreshed,
+and it says which. When a lock records the project's own inputs for the first
+time (a first approval, or a record from before gate parts) or the rule tuning
+or packs moved, it prints the inputs it records — projectType, each rule
+severity override, the selected packs, a declared network, `composition` — so
+the tuning you approve is shown, not only digested.
+
+**In a family, lock bottom-up.** A parent's record pins each member's approval,
+so lock every member that is not approved at its own root first, then the
+parent: three projects cost three locks. A parent locked first records the
+member as drifted, its `lock-check` fails until the member re-locks, and it
+must lock again to pin the new approval — `lock` warns before it writes when a
+direct member is not covered by its own approval.
 Another approver locking an unchanged design records their own approval. A shell
 with no terminal and no `--yes` writes nothing.
 
@@ -439,8 +545,10 @@ record counts too, so commit it before you rely on a local pass.
 | **`locked`** — the approval still covers this design | pass (0) | pass (0) |
 | **`stale`** — the design moved past its approval | **fail (1)** | **fail (1)** |
 | **`unlocked`** — nothing was ever approved | pass, with a notice (0) | **fail (1)** |
-| no `.wai/specs` in this directory at all | pass, saying so (0) | **fail (1)** |
-| a member project has spec changes nobody approved at its own root | **fail (1)** | **fail (1)** |
+| no `.wai/specs` in this directory at all, and no approval on record | pass, saying so (0) | **fail (1)** |
+| no `.wai/specs` (or none left), while `.wai/lock.json` approves spec files | **fail (1)**: the tree was deleted | **fail (1)** |
+| `.wai/project.yaml` missing while an approval is on record | **fail (1)**, naming the file | **fail (1)** |
+| a member project's own approval does not cover it (spec changes, inputs that moved, a record that predates recorded inputs) | **fail (1)**, in the member's own terms | **fail (1)** |
 | a member project was never approved by anyone | pass, naming it as *not gated* (0) | **fail (1)** |
 | only a member's own approval moved (it re-locked) | **fail (1)**, naming the member: re-lock here to pin its new approval | **fail (1)** |
 
@@ -488,8 +596,30 @@ them; later upgrades then carry over*, and `wairon lock` takes a real approval
 (never a restamp). The same holds for gate parts that do not break down the
 `stateId` beside them (they are ignored, with a notice; when the identity still
 matches, `wairon lock` rewrites them keeping the approval), and for a release
-stamp that is no wairon version or is *newer* than the running wairon — a record
-*written by a newer wairon* is never re-judged by an older one.
+stamp that is no wairon version or is *newer* than the running wairon when the
+identity no longer matches — a record *written by a newer wairon* is never
+re-judged by an older one. When the identity still matches, the identity
+decides: the approval holds, and every surface (`lock-check`, `status`,
+`sdd_get_status`, `validate`) reports the stamp as a notice (`its release stamp
+"banana" is no wairon version`, `… says wairon 9.9.9 took it, a newer release than
+this one`); `wairon lock` replaces it with the running release. A matching
+record that carries no gate parts at all gets the same notice `{}` gets, and
+`lock` rewrites them. A `lock.json` that names one key twice (what a careless
+conflict resolution leaves) cannot be read, like one with conflict markers.
+
+**What the identity covers, and what it leaves out.** The project's own *design*
+rule tuning — `projectType`, `sddRuleSeverity` overrides of design rules, the
+other design settings under `rules` — its pack selection, network declaration
+and `composition` are inputs: changing one stales the approval. A selected pack
+that cannot load (not installed, not vendored) leaves the approval *owed* —
+`lock-check` fails, naming the pack — because the doctrine it was judged under
+cannot be read. **Code-conformance configuration is deliberately outside the
+identity:** `rules.conformance` (`requireCode` included) and severity overrides
+of rules that judge code govern how the *code* is held to the design, not what
+the design is, so flipping `requireCode` changes what `validate --ci` fails on
+and never stales an approval — exactly as adding a `sourcePath` never does. The
+analyzer's doctrine is recorded beside the claim (`code.analyzer.doctrineDigest`)
+instead.
 
 **It is optional by construction.** By default only a moved approval (or a
 member's unapproved changes) refuses, and neither can happen in a project that
@@ -1015,10 +1145,14 @@ content — `as:` only asserts it (a contradiction is `MEMBER_KIND_MISMATCH`):
   `partOf: { project: <parent id>, path: <parent root> }`.
 - A **project** is an independent boundary: its tree declares an id, holds an L0
   or carries a lock. It is reached only as `alias::name` through its L0 exports,
-  judged by its own gate and locked at its own root. A project stored outside
-  this project (`../x`, git, `hosted:`) is a **referenced** project: this
-  project's gate judges it against its pin (`wairon externals pin`), and the
-  family run opens it where it is stored and composes it per use.
+  judged by its own gate and locked at its own root. A project contained in this
+  project, or in a `../x` sibling checkout beside it, is followed by the family
+  scan and composed **live**: its exports are read where it is stored, its own
+  gate runs in the family run, and nothing is pinned (`wairon externals pin`
+  says so for a member alias). A project fetched from git or a `hosted:` record
+  is a **referenced** project: this project's gate judges it against its pin
+  (`wairon externals pin`), and the family run opens it where it is stored and
+  composes it per use. A hosted instance never reads a `../` source.
 
 Boundaries are earned: grow a system from subsystems, to parts when a piece
 needs its own folder or repository, to projects only when it needs its own team,
@@ -1097,7 +1231,7 @@ widen it (`EXPORT_WIDENS_AUDIENCE`).
 | `wairon member move <alias> <path>` | Move a contained member's directory and point its `members` entry there (a legacy L1 mount is moved into `members` first) |
 | `wairon member attach <alias> <path> [--description <text>]` | Make the **existing** project at `<path>` a member, keeping its L0, subsystems, packs and lock; its id is declared when it only defaulted one (the id its lock approved, else its effective id). `<path>` reads as `member add` reads a location: inside this project, or a sibling with a leading `../`. Refused when its id collides with a family project's, and for any other path out of this project (`not-contained`) |
 | `wairon member detach <alias> [--widen]` | Take a member out of the family: this project and every family consumer reach it as an external by `source.path`, this project's pinned. Refused (`audience-too-narrow`, each export named with its users) while a family project uses a name the member exports only to the family; `--widen` instead widens exactly those used exports to `instance` in the member's L0, each shown in the plan |
-| `wairon member adopt <alias>` | Make this project's external found by a path inside it a member again — detach's inverse |
+| `wairon member adopt <alias>` | Make this project's external found by path a member again — detach's inverse. Its source reads as `member attach` reads a location: inside this project, or a sibling with a leading `../` (a sibling member is composed live like a contained one, never pinned) |
 | `wairon member rename-alias <old> <new>` | Rename one alias of this project (a member or an external) and respell this project's references through it; no member or sibling changes |
 | `wairon member internalize <alias> [--into <subsystem>] [--packs adopt\|drop] [--export <name>…]` | Fold a member into this project's own specs folder. A **part** is a storage move: its subsystems move in and nothing else changes. A **project** is demoted first — its own metadata goes to a home (its L0 vision onto the `--into` subsystem, its boundaries, requirements and databases into this L0, its language, profile and depth onto the moved subsystems, its members and externals into this configuration, its packs adopted or dropped), what has no home (its lock, pins, derived outputs) is deleted and listed, and every family project that consumed it is re-pointed here |
 | `wairon project rename <new-id> [--project <alias path>]` | Move a project's id — this project's, or a member's named by its alias path — and every reference to the old id family-wide; the old id is kept in `previousIds`. Lists every project it writes to re-lock |
@@ -1217,14 +1351,14 @@ project, so it holds nothing machine-specific: it runs `wairon mcp serve` from t
 and the server attaches to the project it is started in. A `--global` registration is
 machine-wide and names the running CLI by its absolute path.
 
-The local server offers 47 tools:
+The local server offers 49 tools:
 
 | Group | Tools |
 |-------|-------|
 | Topology (read) | `listAgents`, `getAgent`, `listDomains`, `validateTopology`, `getProjectConfig` |
-| Authoring | `sdd_initialize_system`, `sdd_add_subsystem`, `sdd_set_public_interfaces`, `sdd_add_component`, `sdd_define_interface`, `sdd_set_endpoints`, `sdd_write_narrative`, `sdd_add_type`, `sdd_update_spec` (dry run), `sdd_delete_spec` (dry run, force) |
+| Authoring | `sdd_initialize_system`, `sdd_add_subsystem`, `sdd_set_public_interfaces`, `sdd_add_component`, `sdd_define_interface`, `sdd_set_endpoints` (dry run), `sdd_write_narrative`, `sdd_add_type` (dry run), `sdd_update_spec` (dry run, search), `sdd_delete_spec` (dry run, force, search) |
 | Reading and checking | `sdd_get_spec`, `sdd_get_status`, `sdd_validate_tree` |
-| Renames and moves (in this tree) — each with `dryRun` | `sdd_rename_component`, `sdd_rename_method`, `sdd_rename_param`, `sdd_rename_type`, `sdd_rename_field`, `sdd_move_methods` |
+| Renames and moves (in this tree) — each with `dryRun` | `sdd_rename_component`, `sdd_rename_method`, `sdd_rename_param`, `sdd_rename_type`, `sdd_rename_field`, `sdd_rename_spec` (a contract or an implementation on its own), `sdd_move_methods`, `sdd_move_spec` (a component or a type to another subsystem) |
 | Members | `sdd_add_member`, `sdd_move_member` |
 | Family migrations (each takes `dryRun`) | `sdd_externalize_subsystem`, `sdd_promote_member`, `sdd_demote_member`, `sdd_internalize_member`, `sdd_attach_member`, `sdd_detach_member`, `sdd_adopt_member`, `sdd_rename_project`, `sdd_rename_member_alias` |
 | Externals | `sdd_add_external`, `sdd_update_external`, `sdd_remove_external`, `sdd_pin_externals`, `sdd_get_externals_status` |
@@ -1233,6 +1367,15 @@ The local server offers 47 tools:
 | Packs | `sdd_pack_impact` |
 | Delegation | `sdd_get_agent_brief` (the live brief for one agent; also served as the `wairon-agent://` resource) |
 
+Every tool description ends with its argument names (`Arguments: id, newId, dryRun?.`). Every write
+tool refuses a spec of another project — a member's spec read through this tree is written from the
+member's own root, and the refusal names its folder and the call to make there. `sdd_delete_spec` and
+a contract method removed through `sdd_update_spec` report `published` (the public names a consumer
+reaches what goes through) and `breaks` (the consumers in reach, and in the `search` folders, that use
+one), as the renames do; a removed contract method takes its implementation entries with it
+(`cascaded`) and is refused while another spec still calls it. A delta never changes a spec's id or
+subsystem: `sdd_rename_spec` and `sdd_move_spec` do, with every reference and published entry.
+
 A hosted server adds its own `sdd_host_*` and `sdd_landscape_*` tools; see the
 [hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md).
 
@@ -1347,7 +1490,7 @@ return the impact of every pack they applied in their results.
 | `wairon externals pin [alias…] [--json]` | Pin declared externals into `.wai/externals/<alias>.yaml` and `.wai/externals.lock.yaml`. The snapshot is rewritten whenever anything it carries moved — not only the signatures the digest covers: a producer that added `abi: c`, changed a transport or a role, or recorded a rename is refreshed by a re-pin. Exits 1 when an alias could not be pinned (unresolved or unreachable — its previous pin stays) |
 | `wairon externals status [--json]` | Each pin compared with its live producer per used member — `unchanged`, `changed`, `renamed` (with the new name), `removed`, `unlocked`, `unavailable` — and each external's health (`incompatible`, `not compared`, `drifted`, `ok`); a pinned snapshot that no longer carries what the producer says (a stale `abi`, transport or role) is `drifted`, never `ok`, and names the stale facts. A use the lock does not hold is still compared with the live producer: gone from it, it is `removed` or `renamed`. Git producers are fetched. The opt-in **live** gate: exits 1 when any external is incompatible, 2 when nothing is incompatible but something could not be compared (never a pass), 0 otherwise |
 | `wairon externals list [--json]` | The declared externals, how each resolves and what is pinned; a malformed declaration, and an orphaned pin whose declaration is gone, are listed with their problem, never hidden |
-| `wairon surface export \| import \| list [--audience <level>] [--format native\|openapi] [--portal <id>] [--out <path>] [--source <path>]` | Exchange a public surface document: export this project's (native snapshot or one OpenAPI 3.1 document per portal), import one, or list them. OpenAPI defaults to the `project` audience, so every HTTP Portal of the project's own is described — one its L0 export table never exports included (a wider `--audience` narrows to what the table shares there); the native snapshot defaults to `instance`. In the OpenAPI document a path placeholder — `{name}`, or the Express spelling `:name`, which is rewritten to `{name}` — is a parameter `in: path`, the other params the query of a GET/DELETE or the JSON body of a POST/PUT/PATCH — the one object-typed param left IS the body, as a client sends it (named under `x-wairon-body-param`, so `surface import` puts it back), and several are the properties of a body object. The Portal's `basePath` is joined into every path (the document carries no `servers` entry: where it is served is deployment, not design). The parameter that carries the credential the Portal's `auth` binds (a bearer `token`, say) is left out of the parameters and the body — `security` describes it — and named under `x-wairon-credential-param` so a wairon reader can restore it. Each operation answers its success code — `204` with no content for a method returning nothing; `201 Created` for a POST that creates: a method whose `effect` is `lifecycle`, or one whose effect is undeclared, `write` or `io` and whose name says it creates (`createHabit`, `placeOrder`, `signUp`); else `200` (a cancel, an archive, a log-in) — and a method returning `result<T, E>` also answers a `default` error response carrying E's schema (`surface import` reads both back). A `custom` auth becomes an `apiKey` scheme only when the Portal's `auth.name` (with `auth.in`, default header) names where the credential travels; naming none, it is an `http` scheme `custom` with the design's description — no header name is invented. Two operations of one Portal on the same verb and path (placeholders compared by position) are refused naming both, never dropped (`validate` reports them as `ENDPOINT_ROUTE_DUPLICATE`). A type another project publishes resolves from its pin, or — for a member project — from what the member exports now; a type nothing resolves is named in a warning (`The document has no schema for N type(s) it names: …`), never passed under a ✔. Every status line goes to stderr, so `surface export --format openapi > api.json` writes the JSON alone; an export that publishes nothing, or of a design `validate` refuses (its error count and codes), is a warning, never a ✔. An unknown `--portal` is refused naming the portals the surface renders |
+| `wairon surface export \| import \| list [--audience <level>] [--format native\|openapi] [--portal <id>] [--out <path>] [--source <path>]` | Exchange a public surface document: export this project's (native snapshot or one OpenAPI 3.1 document per portal), import one, or list them. OpenAPI defaults to the `project` audience, so every HTTP Portal of the project's own is described — one its L0 export table never exports included (a wider `--audience` narrows to what the table shares there); the native snapshot defaults to `instance`. In the OpenAPI document a path placeholder — `{name}`, or the Express spelling `:name`, which is rewritten to `{name}` — is a parameter `in: path`, the other params the query of a GET/DELETE or the JSON body of a POST/PUT/PATCH — the one object-typed param left IS the body, as a client sends it — an optional one or a `T?` too, the body then optional or nullable, never wrapped under its name (named under `x-wairon-body-param`, so `surface import` puts it back), and several are the properties of a body object. The Portal's `basePath` is joined into every path (the document carries no `servers` entry: where it is served is deployment, not design). The parameter that carries the credential the Portal's `auth` binds (a bearer `token`, say) is left out of the parameters and the body — `security` describes it — and named under `x-wairon-credential-param` so a wairon reader can restore it. Each operation answers the success `status` its endpoint states (`sdd_set_endpoints` `status`: `202` Accepted, a `3xx` redirect with a `Location` header and no body, a `201` for a workflow verb that files something), else its conventional code — `204` with no content for a method returning nothing; `201 Created` for a POST that creates: a method whose `effect` is `lifecycle`, or one whose effect is undeclared, `write` or `io` and whose name says it creates (`createHabit`, `placeOrder`, `signUp`); else `200` (a cancel, an archive, a log-in) — and a method returning `result<T, E>` also answers a `default` error response carrying E's schema (`surface import` reads both back). A `custom` auth becomes an `apiKey` scheme only when the Portal's `auth.name` (with `auth.in`, default header) names where the credential travels; naming none, it is an `http` scheme `custom` with the design's description — no header name is invented. Two operations of one Portal on the same verb and path (placeholders compared by position) are refused naming both, never dropped (`validate` reports them as `ENDPOINT_ROUTE_DUPLICATE`). A type another project publishes resolves from its pin, or — for a member project — from what the member exports now; a type nothing resolves is named in a warning (`The document has no schema for N type(s) it names: …`), never passed under a ✔. The components are exactly the types the operations reach, each ONCE — a member's type reached under its alias, its project id or another producer's closure is one component, keyed `<alias>.<id>` (a qualified id's `::` written `.`, so every key matches `^[a-zA-Z0-9._-]+$`); a field or parameter typed `T?` is not `required` (it stays nullable), and a field's description is carried on its property. Every status line goes to stderr, so `surface export --format openapi > api.json` writes the JSON alone; an export that publishes nothing, or of a design `validate` refuses (its error count and codes), is a warning, never a ✔. An unknown `--portal` is refused naming the portals the surface renders |
 | `wairon surface diff [--against <ref\|file>] [--json]` | The public-surface changelog: this project's export table now against the same table at its last **committed** approval (or at a git revision, or in a saved native snapshot from `surface export`) — every exported name and contract method `added`, `removed`, `renamed` (from its rename trace) or `changed` (signature or type shape), and how many a consumer may have to follow. A field renamed per its trace keeps its own row beside its type's rename (traced, or a changed public name of the same definition — never "removed + added"), and an exported type reshaped only by a rename it embeds says which (`embeds renamed field "money.currency" → "currencyCode"`). Against a revision it also covers the project's own HTTP Portals (its service API, exported or not), with every type they name from a pinned external or a member project expanded from the pin or member of each side: a re-pin that reshapes the project's own wire format (`GET /routes/:id/tiles` answering a renamed field) is a change of its own surface, named on the verb. What a producer writes release notes from before it re-locks; `wairon externals consumers --search <dir>` then says who uses what. Read-only. With no approval ever committed it says so (lock and commit first, or name `--against`). An L0 export entry added since that publishes nothing (a wildcard over a subsystem that publishes nothing) is listed as such, never read as no change. `--against` takes a native snapshot or a git revision: an OpenAPI document, or a file the native schema does not read, is refused in one line. `sdd_surface_diff` is the same answer for an assistant |
 | `wairon produce <notion\|miro> [--page <id>] [--token <token>]` | Project the local spec tree to Notion or Miro (the token comes from `--token`, the environment, else a prompt; nothing is stored) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wairon/cli",
-  "version": "5.1.1-dev.112",
+  "version": "5.1.1-dev.114",
   "description": "SYW Waffle AIron — CLI for managing AI coding agent topology across projects",
   "keywords": [
     "ai",