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

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
@@ -76,7 +95,8 @@ warnings as errors (notices are printed and counted, never fatal).
   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**, 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;
+  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.
@@ -116,9 +136,20 @@ 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
+  `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
@@ -153,6 +184,11 @@ 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
 opts in — write the agent files from the spec-derived topology.
@@ -194,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.
 
@@ -331,12 +373,17 @@ merging is the thing that was reviewed.
 
 #### Using it in GitHub Actions
 
-This repository publishes it as a **reusable workflow**. **6.0.0 is the first
-release that ships the workflow and the `lock-check` command** — earlier releases
-have neither, and no `v6.0.0` tag exists before that release. On a dev build (and
-until 6.0.0 is out), pin the dev tag matching `wairon --version` instead: a CLI
-reporting `5.1.1-dev.107` pins `@v5.1.1-dev.107` with `wairon-version:
-'5.1.1-dev.107'`. 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
@@ -344,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
 ```
 
@@ -354,10 +401,10 @@ 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)
@@ -380,10 +427,13 @@ directory (`validate: false` turns it off). Point `working-directory` at 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. A fresh
-checkout has none until the project's dependencies are installed, and then every
-file is analyzed below exact grade and `--ci` fails on `CONFORMANCE_DEGRADED` —
-a finding about the runner, not your design. So before `validate --ci` the job
+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` →
@@ -411,9 +461,9 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
-      - run: npm install --global @wairon/cli@6.0.0   # the version you lock with
+      - 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
+      - run: npm ci                                    # the project's dependencies: the gate reads your code with your TypeScript (5 or 6)
       - run: wairon validate --ci
 ```
 
@@ -1060,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.

package/docs/design/connecting-agent-entrypoint.md

@@ -0,0 +1,167 @@
+# Teaching the connecting agent — the MCP entrypoint
+
+> Status: 7.1–7.5 all shipped. Written against wairon 5.1.0.
+> Source request: "Teaching the connecting agent: wairon needs the entrypoint,
+> packs only adjust it" (2026-07-27).
+
+---
+
+## The governing principle
+
+**wairon owns the SDD model, so wairon must teach it.** If an agent connecting to
+a wairon MCP server does not know what SDD is, what the stereotypes mean, or in
+what order to use the `sdd_*` tools, supplying that is wairon's default — not
+each wrapper's. A pack appends its **platform delta** ("and here is what each of
+those means in Make.com") and never restates the model, which would drift on
+every wairon release.
+
+Every item below is shaped by that split.
+
+---
+
+## Shipped
+
+### 7.1 — `instructions` on `initialize`
+
+`createMcpServer` returns MCP `instructions`, the protocol's field for "how to
+use this server", which clients inject into the agent's system prompt. Composed
+by `instructions_specialist` (`src/core/instructions.ts`), it carries the L0→L5
+tree shape, the authoring order by tool name, the fact that the `sdd_*` schemas
+are self-describing, the bound project's governing `projectType`/profile, the
+loaded packs, and the directive to read `wairon-skill://sdd-architect` **before**
+authoring — with a pointer per published skill resource.
+
+Deliberately short and pointer-heavy (~2.9 KB for this repo; a test pins a 6 KB
+ceiling): the depth lives in `templates/skills/*.md`, and this is the map that
+sends an agent to read them.
+
+Composed **per `createMcpServer` call**, so the hosted per-request scoped server
+(`server/request.ts:652`) reports its own bound project rather than a snapshot.
+Never throws — a failed pack load or an uninitialized project degrades to
+wairon's own briefing, because a connecting agent must always be taught
+something.
+
+Path: `mcp_server` → `mcp_skills_adapter` → `skills_portal` →
+`skills_resource_orchestrator` → `instructions_specialist`. `sdd_mcp` stays a
+transport subsystem.
+
+### 7.2 — pack-contributed instruction blocks
+
+`DeclarativePackSchema.instructions` accepts a bare string, one block, or a list,
+normalized to `PackInstructionBlock[]`:
+
+```yaml
+instructions:
+  - text: Applies to every project this pack governs.
+  - text: Router branches never appear in a spec — model them as narrative branch steps.
+    profile: [make-automation]
+```
+
+Appended after wairon's text under `## From pack "<name>"`, in **pack load
+order** — the one merged field whose order is semantic, so blocks are never
+deduped or overwritten. `profile` scopes a block to the governing profile exactly
+as declarative assertions scope theirs; a block scoped to a profile that cannot
+be resolved is **withheld**, so platform doctrine never leaks into an unrelated
+project.
+
+---
+
+## Shipped (continued)
+
+### 7.4 — skills as MCP prompts — SHIPPED
+
+Resources are pull-only; prompts are what makes a skill *discoverable* to a human
+driving an agent (as a slash command or attachable context).
+
+- Register a prompts capability mirroring `listSkillResources()` — the SDK
+  exposes `registerPrompt`, so the set cannot drift from the resource mirror.
+- Prompt name = skill id (`sdd-architect`, `appenser-make-implementer`); the
+  handler returns the skill markdown as a message.
+- Resources stay for programmatic reads. Hosted inherits this via the shared
+  factory, as the resource mirror already does.
+- Test over an in-memory transport (`client.listPrompts()` / `getPrompt()`),
+  matching `tests/mcp/skill-resources.test.ts`.
+
+### 7.5 — variant guidance over MCP — SHIPPED
+
+`agent_resolver.buildVariantGuidance` (`src/core/agent_resolver.ts:216`) is the
+right hook for platform implementation guidance — it attaches to the component
+the implementer is holding, with no doctrine duplication. But it only reaches
+**generated agent files**, so hosted/cloud agents never see it.
+
+- **Lift the composition into `src/core/variants.ts`** so the agent renderer and
+  the MCP path share one implementation instead of a second copy that drifts.
+- `sdd_get_spec` on a variant-tagged component returns the resolved variant
+  guidance and its same-variant siblings as a clearly-derived, **read-only**
+  field, documented in the tool description as not part of the spec.
+- Naming the active variants in the `initialize` instructions was **not** built —
+  see the outcome note below. The request said "and/or", and the `sdd_get_spec`
+  half is the substantive one.
+
+### 7.3 — pack skills that EXTEND a builtin — SHIPPED
+
+Today `PackSkillSchema` is `{id, source, targets}` and pack skills are namespaced
+`<pack>-<id>` so they cannot shadow `sdd-*`. A platform delta can therefore only
+exist as a **parallel** skill (`appenser-make-implementer` beside `sdd-implement`),
+leaving the agent to notice both and reconcile them — and tempting every wrapper
+to fork the builtin wholesale, which is worse for everyone.
+
+```yaml
+skills:
+  - extends: sdd-implement          # builtin skill name
+    source: skills/make-implementer/SKILL.md
+  - id: make-control-plane          # unchanged: a genuinely new skill
+    source: skills/make-control-plane/SKILL.md
+```
+
+- `PackSkillSchema` becomes a union; `extends` must name a builtin
+  (`SKILL_NAMES`), and an unknown target **fails the pack load loudly** — the
+  `assertions` precedent: an old wairon must never silently not-apply a newer
+  pack's doctrine.
+- The pack section is appended to the builtin under `## Platform: <pack>`
+  (multiple packs in load order), on install **and** on `resources/read`. The
+  builtin stays wairon's, so an upgrade still updates it.
+- An extending skill contributes **no separate resource** — it composes into the
+  builtin's descriptor.
+
+**The trap:** `checkSkillFreshness` (`src/core/skills.ts:166`) byte-compares the
+installed file against the raw builtin template. Left alone, every extended skill
+reports permanently **stale** in `wairon doctor`. It must compare against the
+*composed* expectation.
+
+Also touched: `exportSddSkills` (write composed), `readSkillResource` /
+`readResource` (return composed), `listSkillResources` (descriptors), and the
+`pack_skill` type spec.
+
+---
+
+## Sequencing (as built)
+
+7.4 → 7.5 → 7.3, in ascending order of blast radius, after the pack-scoping work
+(`docs/design/pack-scoping.md`) had settled the selection model — 7.3's
+composition runs over whatever pack set resolution yields.
+
+---
+
+## Outcome notes
+
+**7.5 — one half deliberately not built.** The request said "include the resolved
+variant guidance in `sdd_get_spec` … **and/or** name the active variants in the
+`initialize` instructions". The first is done. The second is not: reading the
+variant registry from the instructions composer would be an `sdd_skills` →
+`sdd_core` hop onto an internal Adapter, which the boundary rules refuse, and
+routing it through the core portal would mean a barrel import cycle for what is
+only a pointer. The substantive requirement — guidance reaching a hosted agent —
+is satisfied by the tool that hands an implementer its component.
+
+**7.3 — the trap was real.** `checkSkillFreshness` byte-compared installed skills
+against the raw builtin template. Left alone, every extended skill would have
+reported permanently *stale* in `wairon doctor`, telling users to run `generate`
+on a loop. It now compares against what `exportSddSkills` would write.
+
+**A latent bug found while testing 7.5.** `requireSpecs()` in `mcp/server.ts`
+lazily required a relative path, which does not resolve under the test runner — so
+every `sdd_*` tool built on it failed with a module error instead of running. No
+test had ever driven one through an MCP client, so nothing caught it. The
+remaining lazy requires in that file (loader / validation / provision) are the
+same latent landmine for any future test that exercises those tools.