@wairon/cli 5.1.1-dev.107 → 5.1.1-dev.109

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

@@ -110,7 +110,7 @@ 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). 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). 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.

package/docs/architecture.md

@@ -71,7 +71,7 @@ to the artifacts the host AI tool consumes:
   (`runWithProjectRoot`) — reusing the core, validation, and MCP layers unchanged.
 - **Everything is file-based** under `.wai/` — no database, and no daemon for the
   core workflow. `wairon serve` is an **opt-in** hosting daemon (see the
-  [hosted server guide](design/hosted-mcp-server.md)) that serves the same
+  [hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md)) that serves the same
   file-based tools over HTTP.
 
 ---

package/docs/cli.md

@@ -25,6 +25,16 @@ nothing and printing the exact `wairon member add <alias> <path> --project` to
 run from the parent (or: make the folder its own repository with `git init` and
 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 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
+`wairon generate` / `wairon doctor --fix` refreshes them.
+wairon writes no `.gitignore` — your toolchain's own entries (`node_modules/`,
+`dist/`, …) are all it needs.
+
 #### Which project a command acts on
 Every command, the MCP server (`wairon mcp serve`) and `wairon dev` bind the same
 project: from the folder you are in, the nearest folder whose `.wai/specs` holds
@@ -36,6 +46,15 @@ repository the walk is unbounded. Each command that acts on a project prints
 `project <id> at <root>` on stderr first, so `wairon export` and every `--json`
 output keep a pure stdout.
 
+#### When a command refuses
+A refusal is one `✖` line and a non-zero exit — never a Node stack trace, whatever
+the input. A `.wai/project.yaml` that does not parse as YAML (most often a key
+written twice, e.g. a second `rules:` block appended by hand) stops every command
+the same way, naming the file, the line and the key —
+`✖ .wai/project.yaml:33: duplicated mapping key "rules" — …` — and `wairon doctor`
+diagnoses it too; no command runs on defaults instead. To report a bug, set
+`WAIRON_DEBUG=1` and the stack is printed after the line.
+
 ### `wairon status [--subsystem <id>] [--no-recursive] [--all]`
 Print the SDD spec tree as a hierarchy. Its percentages measure **authoring
 progress** — 80% once a component's component, contract and implementation specs
@@ -74,8 +93,12 @@ warnings as errors (notices are printed and counted, never fatal).
   **family root** (the project that declares the members). A member validated on
   its own judges its own gate with its `network` entries counted as declared, and
   says so in one line, so a green member run is never read as a proven one.
-  **In CI, run `wairon validate --ci` at the family root**; a member in its own
-  repository adds the root's run to its pipeline or relies on the root
+  **In CI, run `wairon validate --ci` at the family root**, after installing
+  the project's dependencies (`npm ci` or your package manager's equivalent —
+  the gate reads TypeScript/JavaScript code with the project's own TypeScript
+  when it is 5 or 6, and with the copy wairon ships otherwise;
+  see [Using it in GitHub Actions](#using-it-in-github-actions)); a member in
+  its own repository adds the root's run to its pipeline or relies on the root
   repository's.
 - **Externals, compared live (advisory: the pin gates).** The gate judges each
   external against its pin. Then every external the run did not compose is
@@ -97,6 +120,9 @@ warnings as errors (notices are printed and counted, never fatal).
   `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.
+- **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'.
 - **What the closing line says.** Plain `validate` passes with warnings and
   says so — `Passed with N warning(s)` (`--ci` fails on them); `All checks
   passed` means none. A tree holding no design yet (no L0, or an L0 with nothing
@@ -110,16 +136,58 @@ warnings as errors (notices are printed and counted, never fatal).
   collaborator is collaboration whatever the import's form: when its type comes
   from a component the caller never declared, even through `import type`, it is
   `UNDECLARED_DEPENDENCY`; a Portal calling a write- or lifecycle-effect method
-  of a Repository, Index, Store or Registry that way is
+  of a Repository, Index, Store or Registry is
   `PORTAL_WRITE_SHORTCUT_IN_CODE` (error, the code twin of
-  `PORTAL_WRITE_SHORTCUT`); and a file importing a technology's package — a
-  package named by one of the technology's declared tokens (its name, or its
-  `matches`), never a guessed vendor list — outside the components that bind it
-  is `TECH_LEAKAGE_IN_CODE`. An Adapter's call step to a verb of a Portal that
-  declares an out-of-process transport (HTTP, gRPC, a database, a bus, a CLI…)
-  is the link the design models: it is never resolved to the remote Portal's
-  file, so it never reads as `CALL_ORIGIN_UNRESOLVED`; the call to the Adapter
-  stays checked.
+  `PORTAL_WRITE_SHORTCUT`). A Portal's calls are resolved by the TypeScript
+  type checker, so how the receiver is written does not matter: the call lands
+  on the method the checker resolves it to, and a call through an interface or
+  type — a port declared in the Portal's own contracts file included — lands on
+  every class of the project that realizes it (the ones that say `implements`
+  when any does, else every class the checker finds assignable). A call the
+  checker cannot resolve because its receiver is typed `any` or `unknown`, cast
+  to either, or typed nothing, under the name of a data component's write, is
+  `PORTAL_CALL_UNRESOLVED` (a warning, so `--ci` fails): give the receiver its
+  type. An Orchestrator (or any component) whose code calls a write- or
+  lifecycle-effect method of another component that its narrative never
+  claims is `UNDECLARED_WRITE_CALL`. And a file importing a technology's package
+  outside the components that bind it is `TECH_LEAKAGE_IN_CODE`. A technology's
+  packages are its declared tokens (its name, or its `matches`) plus the common
+  packages wairon knows for it — see [Technologies and their
+  packages](#technologies-and-their-packages). An Adapter's call step to a verb
+  of a Portal that declares an out-of-process transport (HTTP, gRPC, a
+  database, a bus, a CLI…) is the link the design models: it is never resolved
+  to the remote Portal's file, so it never reads as `CALL_ORIGIN_UNRESOLVED`;
+  the call to the Adapter stays checked. Likewise the Adapter's `dependsOn` to
+  that Portal is realized by the link, never reported `UNREALIZED_DEPENDENCY`:
+  never add an import across a network boundary to satisfy a check.
+
+#### Technologies and their packages
+
+`TECH_LEAKAGE_IN_CODE` compares each import's package with the packages of the
+technologies an implementation binds. A design writes the technology the way
+people say it (`postgres`) while the code imports its driver (`pg`), so wairon
+knows the common packages of the common technologies by default:
+
+| Technology (any of these names) | Packages |
+| --- | --- |
+| `postgres`, `postgresql`, `pg` | `pg`, `postgres`, `pg-promise`, `@neondatabase/serverless`, `@vercel/postgres` |
+| `mysql`, `mariadb` | `mysql2`, `mysql`, `mariadb` |
+| `redis`, `valkey` | `redis`, `ioredis`, `@redis/client` |
+| `mongodb`, `mongo` | `mongodb`, `mongoose` |
+| `sqlite`, `sqlite3` | `better-sqlite3`, `sqlite3`, `sqlite` |
+| `kafka` | `kafkajs`, `node-rdkafka` |
+| `rabbitmq`, `amqp` | `amqplib`, `amqp-connection-manager` |
+
+An HTTP client (`fetch`, `axios`, `got`, `undici`) is never a technology — it is
+how an Adapter reaches anything — so no entry names one. To extend the list,
+write the technology as `{ name, matches }` (each `matches` token is a package
+too), or have a pack contribute `technologyPackages: { <technology>: [<package>,
+…] }`.
+
+A package of a technology that **no** implementation binds is reported too:
+the code uses a technology the design never placed, so every importer is
+outside its (missing) home. Bind it on the data-layer component that owns the
+vendor call (`technologies: [redis]`), and that component becomes its home.
 
 ### `wairon generate [--target <name>] [--domain <id>] [--domains <ids>] [--root] [--family] [--no-prune] [--global] [--dry-run]`
 Reconcile the generated guides, skills and context, and — only when the project
@@ -162,7 +230,13 @@ approval lives in `.wai/lock.json`. Implementation gates on that approval —
 **What it certifies is the design.** Only design findings can refuse a lock.
 Code-conformance findings (the code↔spec checks) are recorded **beside** the
 claim in the record's `code` block, with the analyzer that produced them, and
-printed as `code: N error(s), … recorded beside the claim`. CI enforces them:
+printed as `code: N error(s), … recorded beside the claim`, with the analysis
+**grade** — the weakest any analyzed file got: `exact` (read with the project's
+TypeScript compiler API: declarations, imports and calls resolved), `pattern`
+(read through the language's declaration and import patterns — recognized, not
+resolved), `generic` (word-boundary identifiers only, the floor for any
+language), or `none` (no file analyzed yet: no code, or none the specs name).
+CI enforces them:
 `wairon validate --ci` still fails on a code error. A design can be approved
 before its code exists.
 
@@ -299,9 +373,17 @@ merging is the thing that was reviewed.
 
 #### Using it in GitHub Actions
 
-This repository publishes it as a **reusable workflow** (from v6.0.0 — the
-workflow and the `lock-check` command do not exist in earlier releases). Add one
-job to your own workflow:
+This repository publishes it as a **reusable workflow**. Pin it — and the CLI it
+installs — to **the version you lock with**: the one `wairon --version` prints
+where you run `wairon lock`. Every published version has a git tag `v<version>`
+and the same version on npm: a release `X.Y.Z` is `@vX.Y.Z` with
+`wairon-version: 'X.Y.Z'`; a dev build `X.Y.Z-dev.N` is `@vX.Y.Z-dev.N` with
+`wairon-version: 'X.Y.Z-dev.N'` (the npm `dev` dist-tag names the newest dev
+build, but it moves — pin the exact version). Check that the version you pin is
+on npm before you commit the job: `npm view @wairon/cli@<version> version`. The
+workflow and the `lock-check` command first ship with 6.0.0 and its dev builds;
+an older version has neither. Below, `<version>` stands for yours. Add one job
+to your own workflow:
 
 ```yaml
 # .github/workflows/ci.yml in YOUR repository
@@ -309,9 +391,9 @@ on: [pull_request]
 
 jobs:
   approved-design:
-    uses: SYW-Apps/Waffle-AIron/.github/workflows/lock-check.yml@v6.0.0
+    uses: SYW-Apps/Waffle-AIron/.github/workflows/lock-check.yml@v<version>
     with:
-      wairon-version: '6.0.0'
+      wairon-version: '<version>'
       strict: true      # a deleted .wai/lock.json fails instead of switching the gate off
 ```
 
@@ -319,12 +401,13 @@ With inputs (all optional):
 
 ```yaml
   approved-design:
-    uses: SYW-Apps/Waffle-AIron/.github/workflows/lock-check.yml@v6.0.0
+    uses: SYW-Apps/Waffle-AIron/.github/workflows/lock-check.yml@v<version>
     with:
       working-directory: packages/api   # where the .wai/ tree lives (default: .)
-      wairon-version: '6.0.0'           # version or npm dist-tag, 6.0.0 or later (default: latest)
+      wairon-version: '<version>'       # the version you lock with, or an npm dist-tag (default: latest)
       strict: true                      # fail when nothing was approved — use it once you have locked (default: false)
       validate: true                    # also run `wairon validate --ci` there (default: true)
+      install: auto                     # the project's dependencies before validate: auto | none | <command> (default: auto)
       node-version: '20'                # (default: '20')
       runs-on: ubuntu-latest            # (default: ubuntu-latest)
 ```
@@ -343,6 +426,47 @@ directory (`validate: false` turns it off). Point `working-directory` at the
 **family root** — the project that declares the members — so that run is the
 family run, which judges the network proofs no member's own gate can.
 
+**The project's dependencies come first.** The conformance gate reads
+TypeScript/JavaScript code with the project's own TypeScript compiler when it is
+TypeScript 5 or 6, and with the copy wairon ships otherwise — a fresh checkout,
+a project without TypeScript, or one on TypeScript 7 (whose native compiler has
+no JavaScript API) is still read at exact grade, and `CONFORMANCE_DEGRADED` is
+left for a file the compiler could not read at all. Installing the project's
+dependencies keeps the analysis on the project's own compiler. So before
+`validate --ci` the job
+installs them with the project's own package manager (`install: auto`, the
+default): nothing without a `package.json`; otherwise the nearest lockfile from
+`working-directory` up to the repository root decides — `package-lock.json` →
+`npm ci`, `pnpm-lock.yaml` → `pnpm install --frozen-lockfile`, `yarn.lock` →
+`yarn install` (`--immutable`, or `--frozen-lockfile` for Yarn 1). `install:
+none` skips it; any other value is run as the install command. The approval
+check alone (`validate: false`) installs nothing.
+
+#### Without the reusable workflow
+
+The same gate as plain steps — for another CI system, or a job of your own. For
+a TypeScript/JavaScript project with code, **install the project's dependencies
+before `wairon validate --ci`** (`npm ci`, `pnpm install --frozen-lockfile` or
+`yarn install --immutable`, whichever your lockfile is for):
+
+```yaml
+# .github/workflows/design.yml in YOUR repository
+on: [pull_request]
+
+jobs:
+  design:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install --global @wairon/cli@<version>   # the version you lock with (wairon --version)
+      - run: wairon lock-check --strict
+      - run: npm ci                                    # the project's dependencies: the gate reads your code with your TypeScript (5 or 6)
+      - run: wairon validate --ci
+```
+
 **A failing job does not block a merge on its own.** A workflow can only fail;
 making a failing job stop a merge is a branch-protection / ruleset setting on
 your repository ("Require status checks to pass" → add this job). No workflow
@@ -597,6 +721,20 @@ field that does not exist, a name that is not an identifier, and a name another
 field of the type holds or retired. The MCP twin is `sdd_rename_field`. As with
 any design edit, the next `wairon lock` approves it.
 
+### `wairon method rename-param <component> <method> <param> <new-name>`
+Renames a parameter of a contract method. The parameter moves on every
+interface of the component that declares the method, keeping its place, type,
+description and optionality; its old name joins the parameter's rename trace
+(`previousNames`), which `wairon export` shows as `formerly`, so a generator or
+consumer reads a rename, not a signature change. Each signature is re-derived
+from the params (a method whose `signatureFrom` names this one follows by
+itself), and an HTTP endpoint path placeholder `{old}` on the method's own
+binding is respelled — the URL a caller sends is unchanged. Prose is never
+rewritten. It refuses, writing nothing, a component, method or parameter that
+does not exist (or a parameter the method takes from a `signatureFrom`), a name
+that is not an identifier, and a name another parameter of the method holds or
+retired. The MCP twin is `sdd_rename_param`. The next `wairon lock` approves it.
+
 ### `wairon network flows|policy|diagram|check|why|declare|undeclare`
 Networking derived from the design: the reach the validator already models
 (modelled calls, Portal entries and their scopes, declared networks and their
@@ -767,7 +905,13 @@ included); applying it stages every change with a backup under each project's
 `.wai/transactions/<id>/` (never committed) and swaps them in, restoring every
 backup on any failure. A crash mid-swap leaves a journal: `wairon status` and
 `wairon validate` show it as a notice, and `wairon doctor --fix` rolls it back.
-No verb ever locks — each names the projects to re-lock. A member stored in a
+No verb ever locks — each names the projects to re-lock. A promote (or `externalize --as project`) re-roots every
+source path that moves with the new project: a path inside the new project's folder becomes
+member-relative, and one outside it (source code you have not moved yet) becomes a member-relative
+*planned* path — `SOURCE_FILE_PLANNED`, never a path that escapes the root — so the new project
+validates on day one and you move the code when you are ready. A topic finding
+(`UNCONSUMED_TOPIC`, `UNSOURCED_SUBSCRIPTION`) is sited at its topic: an allow names it
+with `at: <topic>`. A member stored in a
 `../` sibling checkout on the same volume joins the same transaction: its files
 change all-or-nothing with the family's, the coordinator's journal names every
 owner (so `wairon doctor --fix` recovers from either root), and the plan says
@@ -841,21 +985,23 @@ 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 38 tools:
+The local server offers 47 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`, `sdd_delete_spec` |
 | Reading and checking | `sdd_get_spec`, `sdd_get_status`, `sdd_validate_tree` |
-| Renames and moves (in this tree) | `sdd_rename_component`, `sdd_rename_method`, `sdd_rename_type`, `sdd_move_methods` |
+| Renames and moves (in this tree) | `sdd_rename_component`, `sdd_rename_method`, `sdd_rename_param`, `sdd_rename_type`, `sdd_rename_field`, `sdd_move_methods` |
 | Members and family migrations (each takes `dryRun`) | `sdd_add_member`, `sdd_move_member`, `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` |
+| Public surface (the producer's side) | `sdd_list_consumers`, `sdd_surface_diff` |
+| Network | `sdd_set_network`, `sdd_get_network_flows`, `sdd_explain_flow` |
 | Packs | `sdd_pack_impact` |
 | Delegation | `sdd_get_agent_brief` (the live brief for one agent; also served as the `wairon-agent://` resource) |
 
 A hosted server adds its own `sdd_host_*` and `sdd_landscape_*` tools; see the
-[hosted server guide](design/hosted-mcp-server.md).
+[hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md).
 
 ---
 
@@ -865,7 +1011,7 @@ A hosted server adds its own `sdd_host_*` and `sdd_landscape_*` tools; see the
 projects behind one endpoint — a public **data plane** (the `sdd_*` tools over
 streamable HTTP, per-project API-key scoped) and an admin **control plane**
 (project & key lifecycle, state-scoped lock). See the
-[hosted server guide](design/hosted-mcp-server.md) for the architecture, Docker
+[hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md) for the architecture, Docker
 self-hosting, auth, and sizing.
 
 ### `wairon serve [--host <h>] [--port <p>] [--admin-host <h>] [--admin-port <p>] [--data-dir <path>] [--no-auth]`
@@ -964,18 +1110,19 @@ return the impact of every pack they applied in their results.
 | `wairon externals add <alias> [<source>] [--project <id>] [--ref <ref>] [--dir <dir>] [--use a,b\|'*'] [--description <text>] [--no-pin] [--dry-run] [--json]` | Declare one external in `.wai/project.yaml`. The source is the location grammar members use: `../sibling`, `hosted:<id>`, `<git url>` or `<git url>#<commit>` (the commit is the ref the pin follows, fixed there); omit it when the family provides the producer. Text that is no location (braces, quotes, whitespace) is refused. The declaration is checked against the producer it reaches **before** anything is written — `--dry-run` included: one answering to another id, or not exporting a `use` name to this project, is refused naming the id, the closest exported names, or the narrower audience the name is exported to (see Export audiences). Pins by default; a producer that cannot be read leaves it declared and unpinned, saying why, and exits 2 (nothing was pinned). A refusal is one sentence naming the accepted form, and exits 1 |
 | `wairon externals use <alias> [--add a,b\|'*'] [--remove c] [--dry-run] [--json]` | Change one declared external's `use` imports, so the specs may name the producer's public names bare (e.g. so an `implements` of the producer's trait spells its types as the producer does — though `alias::name` and the bare imported name compare as one type either way). An added name the producer does not export to this project is refused. The pin is untouched. Exits 1 on a refusal |
 | `wairon externals remove <alias> [--dry-run] [--json]` | Remove one external: its declaration and its pin (`.wai/externals/<alias>.yaml` and its lock entry) together. An orphaned pin — one whose declaration was deleted by hand, which `externals list` shows — is removed too. Exits 1 when the alias is neither declared nor pinned |
-| `wairon externals consumers [--json]` | From a producer's root: the family projects in reach that consume it — each with the alias and section it declares it under and the public names its specs use — so a producer sees who breaks before it changes its surface. A sibling checkout, git or hosted consumer outside the family declares its dependency on its own side and is not visible here |
+| `wairon externals consumers [--search <dirs...>] [--json]` | From a producer's root: the projects that consume it — each with the alias and section it declares it under and the public names its specs use — so a producer sees who breaks before it changes its surface. Without `--search`, the family read from the highest root in reach. `--search ..` (any folders) also scans those folders and the project roots directly under them for projects declaring this one as an external by a path that resolves here, or by git — a sibling checkout is found this way. A hosted consumer, or one on another machine, declares its dependency on its own side and is not visible here (`sdd_list_consumers` is the same answer for an assistant) |
 | `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 document per portal), import one, or list them |
+| `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 — a `{name}` segment of an endpoint path is a parameter `in: path`, the other params the query of a GET/DELETE or the JSON body of a POST/PUT/PATCH), import one, or list them. 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. 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`). `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) |
 
 ## Tooling
 
 | Command | Description |
 |---------|-------------|
-| `wairon dev [--port <port>] [--open]` | A local single-project dev server: the wairon web UI over the current project, no login or tenancy (loopback only) |
+| `wairon dev [--port <port>] [--open]` | A local single-project dev server: the wairon web UI over the current project, no login or tenancy (loopback only). It serves the same project over MCP (streamable HTTP) at `POST http://127.0.0.1:<port>/mcp?project=local` — the current project is registered as `local`; without `?project=local` the endpoint answers 403. For an AI tool on the same machine the stdio server (`wairon mcp serve`, what `wairon mcp install` registers) remains the usual route |
 | `wairon update [--check] [--channel <name>]` | Check/install the latest release; switch channel |
 | `wairon aliases list` | Show command aliases (`wai`) and their status |
 | `wairon aliases enable <name>` / `disable <name>` | Create / remove an alias |

package/docs/design/approval-baseline.md

@@ -0,0 +1,257 @@
+# Approval baselines — what `lock` approves, and why it stopped writing
+
+> Status: **implemented**. Written against wairon 5.1.x. The "problem" section
+> describes the behaviour as it was BEFORE this work, not as it is now.
+
+---
+
+## The problem
+
+`wairon lock` had grown two jobs fused into one. The first is the one it was
+designed for: **a human reviews the design and approves it**. The second was
+bookkeeping — and the bookkeeping is what people actually experienced.
+
+Three symptoms, all the same cause:
+
+**It flooded the working tree.** Approving ratcheted every spec's `status` from
+`draft` to `complete` on disk. On this project's own tree that is **786 files**
+rewritten for a decision that changed no design. A lock scoped to one subsystem
+still rewrote everything it could reach, and the specs a human had actually
+edited were buried under files whose content had not changed.
+
+**It reported a verdict nobody could act on.** `wairon status` printed:
+
+```
+Lock: STALE — the specs or the governing doctrine changed since 2026-08-12,
+so this lock no longer holds. Re-run `wairon lock`.
+```
+
+…on a tree validating **0 errors / 0 warnings**. The banner named nothing to
+look at, offered no way to approve part of the change, and asked for work that
+produced no new information. It could only ever say "something moved", because
+a `StateId` is a hash: it answers *did anything change*, never *what*.
+
+**It fought the maintainer's own workflow.** `.wai/phased_design.md` records the
+blanket draft→complete freeze being reverted by hand **four times** (lines 18,
+27, 34, 41), once annotated *"product gap: lock needs phase awareness"*.
+
+And a second gate had grown on top of the first — see
+[the removed `promote` step](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md#4-state-scoped-lock).
+
+---
+
+## The model
+
+One addition retires five concepts: **record what was approved per spec, not one
+hash of the whole tree.**
+
+A review needs two things — the current tree and the tree as it stood when
+someone approved it. wairon had the first and only a whole-tree fingerprint of
+the second. With **one content digest per spec file**, the question changes from
+*"did anything move?"* to *"what moved?"*, which is the only form a human can
+review.
+
+`src/core/approval.ts` derives it; `.wai/lock.json` carries it. Three properties
+are load-bearing.
+
+### It is committed, and it is one file
+
+The approval rides in the lock record, which was always committed. That is what
+lets a **teammate, a fresh clone and CI** see the same approval the approver saw
+— an earlier revision of this design kept it in `~/.wairon/baselines/`, where
+nobody else could read it, so every other checkout judged an approved tree as
+unapproved.
+
+Digests rather than content is what makes that affordable: for this project's
+786 specs, **~90 KB instead of ~2 MB**. And no consumer ever needed the content
+— `diffAgainstApproval` and `settledSpecPaths` only ever ask whether a spec
+still matches. For the content itself there is already git: the record is
+committed, so `git diff <lock commit> -- .wai/specs` is the real diff, and
+better.
+
+Keys are written **sorted**, so re-approving a one-spec change produces a
+**two-line diff** — the timestamp and that spec's digest — in a 96 KB file.
+Measured on this repo. That is a good signal in a PR rather than noise, and it
+is categorically different from the ratchet this replaced, which rewrote
+hundreds of *spec* files for a decision that changed no design. A test asserts
+the spec tree is byte-identical after `lock`.
+
+Digests **normalize line endings** before hashing. This is not tidiness: git
+rewrites line endings on checkout (`core.autocrlf`), so an approval taken on
+Windows would otherwise report every spec as drifted on a Linux CI runner. The
+defect was unreachable while the record was machine-local — sharing it is what
+made it live.
+
+### It is per project root, and members are pinned by their subjects
+
+Every `.wai` owns its own lock record, including each member project. A
+parent's approval never freezes a member's in-flight work, a member cloned on
+its own carries its approval with it, and a parent lock writes nothing below
+itself.
+
+What crosses between them is a **composition subject**: the `stateId` in the
+member's own lock record, read and never recomputed. Each direct member's
+subject is an input of the parent's gate identity, and the parent's record
+(format 2) lists it under `members` with the member's state as the parent saw
+it — `approved` (its lock matches its tree), `drifted` (it has a lock, its tree
+changed) or `never` (no lock). Approval is transitive by hashing: a member's
+subject already includes its own members' subjects, so nothing recurses into a
+member's files. A member editing its own specs does not appear in the parent's
+diff or move the parent's identity — the decisions are separate — until the
+member re-locks; then its subject moves and the parent's approval reads stale.
+`wairon status` prints the pin tree (each member's state from its own root,
+and whether the parent's pin `matches`, has `moved`, or is `unpinned`).
+
+A parent may require its members' approvals with
+`composition.requireApprovedMembers: true`: its lock then refuses while a
+direct member is drifted or never approved, naming each. By default it proceeds
+and records their states.
+
+This replaced a stage-1 `children` map that copied each child's `StateId` into
+the parent's record without ever re-verifying it; `children` is still read for
+one release and never written.
+
+### Settledness is derived, not stored
+
+This is what replaced the on-disk `status` ratchet, and it needed care, because
+the ratchet was doing real work. The MCP authoring tools **always** write
+`status: 'draft'` (`src/mcp/server.ts:825, 1027, 1125, 1331`); draft specs get
+`COMPLETENESS_RULES` findings downgraded from error to warning; and `lock` was
+the only thing that ever promoted. Delete it naively and the gate goes
+**permanently soft** — which is exactly how an `UNEXPECTED_IMPLEMENTATION_METHOD`
+came to surface days late in real use.
+
+The record already knows which specs were approved and which have moved, so a
+spec that is *approved and unchanged* is presented to the rules as `complete` —
+in memory, restored in `finally`, the same mechanism `treatAllAsComplete`
+already used (`src/core/validation.ts`). Nothing is written.
+
+Two things get strictly better than the ratchet:
+
+- **It is bidirectional.** The on-disk version was one-way by design
+  (`allowStatusDemotion` exists to stop a re-add reopening a locked spec), so an
+  edited spec stayed marked complete and in-flux work kept being judged at full
+  strictness with no way back short of a manual demotion. A spec that drifts
+  after approval now returns to draft context by itself.
+- **It cannot drift.** Derived state has no second copy to fall out of sync.
+
+---
+
+## What `lock` does now
+
+1. Capture the gate identity (own specs, design doctrine, declared inputs,
+   `composition`, each direct member's subject).
+2. Validate as complete (full strictness, no draft relaxation, mutates nothing).
+   Only the **design** half may refuse; code-conformance results are recorded
+   beside the claim (`code`, with the analyzer that produced them) and enforced
+   by `validate --ci`, not by the lock.
+3. Report what moved since the last approval, the code results, and each direct
+   member's state; refuse under `composition.requireApprovedMembers` if a member
+   is not approved.
+4. Ask.
+5. Confirm the gate identity is still the captured one (refuse, writing nothing,
+   if an input moved while the lock ran).
+6. Record the approval — a digest per own spec, `members`, `code` — on
+   `.wai/lock.json` (format 2), together with who approved and how that identity
+   was established.
+7. Regenerate this project's derived topology (`generate --family` walks the
+   members; a lock never does).
+
+A hosted lock runs the same steps. A hosted lock *request* also records the
+gate identity it was made about; if the tree moved after the request, the
+approved execution refuses, writes nothing, and cancels the request with the
+reason.
+
+A scoped approval (`--subsystem x`) approves **only what it covers**; everything
+outside keeps the approval it already had. Whole-tree capture under a scoped
+flag would silently mark the rest of the tree reviewed, which is a worse bug
+than the one being removed.
+
+---
+
+## Who approved
+
+`lockedBy` is `{ id, name?, source }`, and the `source` is the point. A `hosted`
+identity was **authenticated** by the instance that issued the caller's
+credential. `git` and `os` are self-declared, read from the machine's own
+config. Recording which keeps the record honest instead of leaving a bare name
+to imply more than it can.
+
+Locally the preference is the **git author identity**, because it is the one
+identity the repository already attributes work to — a reviewer can match it
+against the author of the commit that carries the lock, and that matching is the
+whole value. The fallback is `user@hostname`, which is what Terraform records as
+a lock's holder and what git itself synthesizes when no identity is configured; a
+bare OS username is strictly worse, because in CI it is `runner` and identifies
+nobody. Deliberately not a MAC address or other hardware id: modern systems
+randomize MACs, they differ per interface and VPN, and collecting one is device
+fingerprinting for a field that is not authentication anyway.
+
+Hosted is the one surface where wairon genuinely authenticated the approver, and
+it was **throwing that away** — `executeApprovedLock` wrote the constant
+`admin:master` while its caller held a resolved principal. It now records the
+subject. On the approval path the **decider** is recorded, not the requester:
+the requester did not have the authority, and the decision is what conferred it.
+The requester is not lost — the `ApprovalRequest` and the audit event carry them.
+
+None of this is proof. The trust anchor is the commit that introduces
+`lock.json` — signed commits, a protected branch, a reviewed PR. `lockedBy` is a
+convenience copy that earns its place only where git does not follow: a
+`.waitree` archive, a `remote push` into a hosted instance, a tarball.
+
+---
+
+## Reversals worth recording
+
+**Keeping the approval outside the repo was wrong, and only sharing it showed
+why.** The first revision put it in `~/.wairon/baselines/` on the reasoning that
+"approving must not dirty the repo". That reasoning conflated two very different
+writes: rewriting 786 *spec* files, and one lockfile changing the way lockfiles
+do. The cost was that no teammate, clone or CI run could see the approval at
+all. Moving it into the committed record — as digests, so it fits — keeps the
+property that mattered and drops the one that did not.
+
+**Two defects were only reachable once the record was shared.** Hashing raw
+bytes meant a Windows approval reported all 786 specs as drifted on a Linux
+checkout; digests now normalize line endings, and a test rewrites the whole
+fixture tree to CRLF to hold that. And the hosted lock **published before
+writing the record**, so the commit shipping the specs did not contain the
+approval certifying them — harmless when the record was four bookkeeping fields,
+not when it *is* the approval. Neither was observable while the approval sat on
+one machine.
+
+**The signature change was caught by a test, not by the compiler.** Adding an
+`approver` parameter to `executeApprovedLock` silently re-bound an existing
+three-argument call to the new slot. `tsconfig.json` excludes `tests/`, so
+nothing typechecks the suite — vitest transpiles without checking. The test
+failed loudly and the fix was obvious, but the compiler should have said so
+first.
+
+**`--subsystem` nearly became a silent whole-tree approval.** Removing the
+ratchet left nothing scoping the capture. Two existing lock tests failed and
+named it. Scoped capture was added rather than discovered later.
+
+**The first e2e assertion was written before it could pass.** *"Approving writes
+nothing into the project"* is the property the design exists for, so it was
+asserted first; it failed on the status ratchet, was narrowed to what was true
+that day with a comment saying where it stopped, and tightened to byte-identity
+once the ratchet was gone. A test that encodes a temporary truth is worse than
+one that admits its scope.
+
+---
+
+## Deliberately out of scope
+
+**A local wairon account.** The CLI has no identity of its own: `remote attach`
+stores a bearer token, but resolving it to a person would need a `whoami`
+endpoint and a network call, and `lock` is deliberately an offline command. The
+git identity is the honest local answer until that changes.
+
+**Storing the approved content.** Digests cannot show what changed *inside* a
+spec. Git already can, against the lock's own commit, so keeping a second copy
+of the tree to duplicate it is not worth its weight.
+
+**Separation of duties.** `promote` was the hook for "two people must sign off".
+It never worked, and it was removed rather than kept as a placeholder. If it
+returns, it belongs on the approval — where *"approved by X at StateId S"* is a
+reviewable, committed fact — not as a status string nothing reads.