@wairon/cli 5.1.1-dev.11 → 5.1.1-dev.110

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.

package/docs/design/execution-budgets.md

@@ -0,0 +1,199 @@
+# Execution budgets — the resource axis of the topology
+
+> Status: **implemented**. Written against wairon 5.1.x. The measurements below
+> come from three archived Claude Code sessions of this project's own
+> development, read out of the session transcripts rather than estimated.
+
+---
+
+## The problem
+
+The derived topology answered one question about each agent — *what does it own*
+— and nothing about a second one that turns out to cost real money: *what does
+its work cost to do*.
+
+In a delegating workflow that gap has a specific, measurable shape. A Claude
+Code subagent's `model` field defaults to `inherit`. An agent file that omits it
+silently adopts the parent session's model. With a frontier-tier parent and no
+agent files on disk at all, **1,860 of 2,176 subagent turns ran on the most
+expensive tier** across the three sessions measured — not by anyone's decision,
+but by a default nobody had reason to look at.
+
+Two things are worth stating because they are commonly assumed and were both
+wrong here:
+
+- **Per-spawn startup duplication is not the problem.** Subagents do reload
+  CLAUDE.md and tool schemas from scratch — measured at 13.5k–32.5k tokens
+  against a main session's 44–46k. But the whole CLAUDE.md chain came to ~2,400
+  tokens: 8% of a subagent's startup and **0.2% of subagent spend**. Eliminating
+  it entirely would save ~2%.
+- **Delegation was still correct.** Running the same work inline in a session
+  already averaging 271k context would have added a large context-carry
+  surcharge on every turn, and would have forced repeated compaction. The
+  problem was never *whether* to delegate; it was that every delegation was
+  constituted by default.
+
+A default that expensive cannot be fixed by instruction text. A prompt asking an
+orchestrator to choose models deliberately competes for attention with the task,
+and loses — the sessions measured had exactly such a policy, stated by the
+maintainer, and it lost 85% of the time. It has to be configuration.
+
+---
+
+## The model
+
+Four layers, tool-agnostic until the last. The split is what lets one derivation
+serve a local Claude Code session, a hosted MCP client, and a tool that cannot
+select models at all.
+
+| Layer | File | Holds |
+|-------|------|-------|
+| **Execution profile** | `models/execution.ts`, `core/execution_profile.ts` | What the work *is like*: `breadth`, `writes`, `reasoningDepth`, `delegates`. Says nothing about models. |
+| **Budget policy** | `core/budget_policy.ts` | What that *earns*: capability tier, effort, turn ceiling, tool class, delegation rights, MCP access. Named in tiers, never vendor models. |
+| **Target emitter** | `exporters/claude.ts` | The per-tool *encoding*. Deliberately not generic. |
+| **Brief** | `core/agent_resolver.ts` | The same budget, carried advisory to whoever spawns from it. |
+
+### Derivation needs no spec authoring
+
+Every input already exists on a resolved `AgentRecord`:
+
+- `reasoningDepth` reads the **component stereotype**, which the vocabulary
+  already encodes. A Store, Index, Registry or Adapter is plumbing that its L3
+  contract and L5 narrative fully describe. An Orchestrator, Supervisor or
+  Specialist carries the decisions. Inventing a second classification alongside
+  the stereotype would have meant two things to keep in agreement.
+- `breadth` reads owned-path spread and whether `readPaths` sweeps the tree.
+- `writes` reads the **role**, not the path count — see the reversals below.
+- `delegates` reads the template.
+
+### Tiers, not model names
+
+`ExecutionBudget.modelTier` is `small | standard | large | frontier`. Mapping a
+tier onto a real model is the *consumer's* job, because only the consumer knows
+what its host tool understands. The Claude Code exporter maps to model
+**aliases** (`haiku`, `sonnet`, `opus`, `fable`) rather than pinned ids, so
+generated files keep working across model releases.
+
+### The dial
+
+`execution.tier` defaults to `off`, and each step is a strict superset of the
+constraints below it — raising it can only tighten a budget, never loosen one.
+That property is what makes the dial safe to turn without auditing every agent.
+
+`free` is defined as having *no* quality tradeoff, which is why it expresses no
+model choice at all: picking a model is a quality decision. An absent
+`modelTier` is not the same as a default one, and the exporter omits the field
+rather than substituting.
+
+---
+
+## Enforce versus advise
+
+Both delivery paths carry the budget, and they are not equivalent:
+
+- A **generated agent file** can *enforce*. Front-matter binds: `model`,
+  `effort`, `maxTurns`, `tools`, `mcpServers` are read by the host before the
+  agent runs.
+- A **live brief** can only *advise*. The caller spawning from the brief is what
+  applies it.
+
+That asymmetry is deliberate rather than a gap — a brief is consumed by tools
+wairon does not control. It also matters practically: `materializeAgentFiles`
+defaults to **off**, so the brief is the path most projects actually use, and a
+budget that only reached generated files would have reached almost nobody.
+
+The same line explains the hosted story. Budgets are declarative data and travel
+fine over the hosted MCP surface as an advisory block on the brief. Front-matter,
+hooks and settings are filesystem artifacts and only the local CLI can write
+them. This is the same split hosted pack management already draws — declarative
+over the API, code packs via filesystem — rather than a second rule.
+
+---
+
+## Two things derivation deliberately never produces
+
+### `frontier` is not an owner tier
+
+Derivation caps deep reasoning at `large`, at every dial setting including
+`aggressive`. `frontier` is reachable only by an explicit per-agent override.
+
+The reasoning is that a frontier-capable model is a **sparring partner** for a
+question the specs do not settle, not a way to operate a component day to day.
+Given a tree that is already specced and decided, an owner that genuinely needs
+frontier capability to function is usually a component doing too much — the same
+smell `GOD_COMPONENT` reports, arrived at from a different direction. So it stays
+a decision only the user can make, and `wairon execution show` surfaces every
+agent pinned there.
+
+### `orchestrate` is not derived either
+
+The `orchestrate` tool class — the thin grant that withholds bulk-content tools
+from a pure router — exists because a manager that can read files will read
+them, and then it accumulates context exactly like a main session, which is the
+whole thing delegation was supposed to avoid.
+
+But **every agent in a wairon topology owns and authors something**. Domain
+owners write the specs and source they own; even a chained-subproject owner
+writes its mount spec. Stripping their write tools would not make them cheaper,
+it would make them broken. The genuine pure router in this workflow is the
+human's own main session, which is not a wairon agent at all.
+
+So `orchestrate` stays in the vocabulary as an override-selectable class for a
+manager someone defines by hand, and derivation never assigns it.
+
+---
+
+## Reversals worth recording
+
+Both were found by generating into a real project rather than by reading the
+code, and both are pinned by regression tests.
+
+**`writes` was inferred from owned-path count.** An implementer whose source
+path could not be inferred came out with zero owned paths, therefore
+`writes: false`, therefore `tools: Read, Grep, Glob` — an implementer that
+cannot implement, produced silently. `writes` is now a property of the role. A
+missing path is a topology gap to fix, not a reason to demote an agent.
+
+**Budget front-matter leaked into other targets.** `cursor`, `copilot` and
+`codex` all reuse `ClaudeExporter` for the agent-file shape. Enabling budgets
+therefore wrote `model`, `maxTurns` and `mcpServers` into files for tools that do
+not implement Claude Code's subagent contract. Those keys would be ignored, which
+is worse than absent: a budget sitting in the file reads as enforced when nothing
+enforces it. The shape is still shared; the encoding is now per-tool, opt-in at
+the exporter registry once a target's own fields are verified.
+
+---
+
+## Deliberately out of scope
+
+**Session-hygiene hooks and a context statusline.** Both would cut real tokens —
+rewriting noisy commands so their output does not enter context verbatim, and
+showing live context size instead of periodically re-measuring it. Neither
+belongs here. They are identical for every project regardless of its spec tree,
+so wairon would be deriving them from nothing, and wiring them means writing into
+a hand-maintained `settings.json` with no marker-based reconcile available,
+unlike every other file wairon generates. Generated skills are not a precedent:
+those *are* wairon's domain.
+
+**A conformance rule for frontier overrides.** `validate` gates the spec tree;
+an override lives in project config, and `lint.allow` attaches to specs. The
+finding actually wanted — "this component is doing too much" — is already
+`GOD_COMPONENT`. The override warning lives in `wairon execution show`, where the
+config it reports on lives.
+
+---
+
+## Open
+
+- **Precedence between an agent file's `model:` and the
+  `CLAUDE_CODE_SUBAGENT_MODEL` environment variable is unverified.** The env var
+  short-circuits Claude Code's model-resolution chain when set to anything but
+  `inherit`; whether explicit front-matter still wins decides whether a global
+  floor and per-role pinning compose or conflict.
+- **Whether `effort`, `maxTurns` and `mcpServers` in agent front-matter are
+  honoured** by a given Claude Code build. Documented, not yet measured.
+- **Topology scale.** A large project generates 30–50 subsystem agents (and would
+  generate 1000+ with component implementers on). Because briefs resolve on
+  demand by id, nothing needs a materialized catalog — but agent *discovery*
+  still enumerates everything, which argues for scoping discovery to a domain.
+  Separate concern from budgets.