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

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

@@ -48,7 +48,8 @@ You must read, respect, and update the living quest log file: `.wai/phased_desig
    - Do NOT design components or interfaces for the entire system all at once. Proceed **one subsystem at a time** to ensure focused, manageable design reviews.
    - For the active subsystem:
      1. Design and add all L2 Components (Portals, Orchestrators, Stores, etc.) using `sdd_add_component` (defaulting to `status: draft`).
-        The moment any need involves **storing, persisting, caching, or tracking state** — a config, a permission set, a session map, anything — apply the **held-state recipe** below BEFORE adding a bare Store.
+        The moment any need involves **storing, persisting, caching, or tracking state** — a config, a permission set, a session map, anything — give that state a component of its own, choosing the **smallest sound shape** from the held-state guidance below.
+        Design the SMALLEST sound system: count the components against the endpoints and the state they serve. Ten endpoints over two simple tables is a handful of components, not thirty; every block you add must buy a rule it enforces or a seam it opens.
      2. Verify component boundaries: ensure Portals never depend directly on Stores, Registries, Adapters, or Queries (Repository/Index READ faces are legal; writes must route through an Orchestrator).
      3. Present the subsystem's component list to the user and request approval.
      4. Once approved, define the L3 Interfaces (`.interface.yaml`, via `sdd_define_interface`) for each component in this subsystem.
@@ -78,13 +79,12 @@ The full standard is the source of truth; this is the summary you design against
    - **No wildcard block**: decompose instead. Held or derived state → Store/Index/Repository; behaviour over a value's own fields → a type method; external I/O → Adapter; logic → an Orchestrator with the narrowest `dependencyClass` that holds; one live thing → Actor. `Specialist` and `Gateway` are retired (`STEREOTYPE_RETIRED`): `wairon doctor --fix` retypes a Specialist as an Orchestrator, and a Gateway becomes the Portal it owned, with the `gateway` variant.
 2. **Patterns** (named compositions; set `owns`): `Repository` — the data-access component for one aggregate: owns one Store + its Registry + Indexes + Queries + optional Adapter; consumers use the facade only, never the inner blocks. A `Query` lives only inside a Repository and depends only on its Store, a backend Adapter or pure logic. Reads across aggregates go through a read Orchestrator (or a read-model Repository whose Query runs the join), and an outbox is a sibling Repository. A pattern owns only building blocks, never another pattern — compose patterns at the subsystem (L1) level.
    - **Variants** (`variant:` on a component): the built-in `arbiter`, `projector`, `composer` and `codec` (on Orchestrator) and `gateway` (on Portal: authenticates, authorizes, validates or rate-limits before it dispatches, with its inbound auth in `auth`), then any global and project variants, a later layer overriding by id. A variant carries guidance; what an Orchestrator may depend on is its own `dependencyClass`.
-   - **No Persistence Shortcuts**: Every domain entity requiring state preservation (even simple settings, configurations, permissions, or in-memory rules) **must** utilize a proper `Repository` composed of `Store`, `Registry`, and `Index` blocks. Under no circumstances may you skip repositories/stores, store state inside an `Orchestrator` directly, or combine `Store`, `Registry`, and `Index` roles into a single "storage" or "helper" component.
-   - **Held-state recipe (apply the moment state appears — do not wait for a refused link):**
-     1. `sdd_add_component` the members: `<x>_store` (Store), `<x>_registry` (Registry — write path), `<x>_index` (Index — read path).
-     2. `sdd_add_component` the facade: `<x>_repository` (Repository, `owns: [<x>_store, <x>_registry, <x>_index]`).
-     3. Point every consumer at the `<x>_repository` facade — never at the inner blocks.
-     - *Lightweight exception*: for genuinely simple held state, a deliberately **standalone Store** is sanctioned — consumers from the workflow layer only (a workflow Orchestrator or an Actor), acknowledged with a `lint.allow` reason on the `UNOWNED_STORE` warning. The state stays VISIBLE as a component either way.
-     - *Never*: hold state as fields inside an Orchestrator because a Store link was refused. A refused link means "apply this recipe", not "inline the state" — state hidden inside a logic component is invisible to the spec and unrecoverable.
+   - **No Persistence Shortcuts**: held state always lives in a data component of its own — never as fields inside an `Orchestrator`, and never merged with logic into a "storage" or "helper" component. WHICH data shape is the smallest one that is sound for the state at hand:
+   - **Held-state guidance (apply the moment state appears — do not wait for a refused link), smallest first:**
+     1. **Genuinely simple state** — a settings record, a table read and written by key, a small set — is **one standalone `Store`**. This is the sanctioned shape, not a shortcut: its consumers are on the workflow layer (a workflow Orchestrator or an Actor; a Portal reaches it through that Orchestrator), and you acknowledge the `UNOWNED_STORE` warning with a `lint.allow` reason ("simple keyed state, no lookups beyond the key"). Do NOT add a Registry, Index or Repository around it to make it look complete.
+     2. **State with real lookup or index needs** — reads by something other than the key (by owner, by date range, by status), several read projections, or a write path that must keep invariants across them — is the **`Repository` pattern**: `<x>_store` (Store), `<x>_registry` (Registry — write path), one `<x>_index` per real lookup (Index — read path), and the `<x>_repository` facade that `owns` them; every consumer points at the facade. Add an Index only for a lookup a narrative actually performs; a Repository with one Index that only re-reads by key is the simple case dressed up — use step 1.
+     3. Never split Store/Registry/Index for state that step 1 covers, and never combine their roles into one component when step 2 applies.
+     - *Never*: hold state as fields inside an Orchestrator because a Store link was refused. A refused link means "give the state its component", not "inline the state" — state hidden inside a logic component is invisible to the spec and unrecoverable.
 3. **owns vs dependsOn**: `owns` = a pattern's private member blocks (exactly one hop), or a Supervisor's supervision state (its own Stores and Registries). `dependsOn` = collaborators (other facades / standalone blocks). Never depend on a block privately owned by another pattern.
 4. **Decoupling**: Registry (write) and Index (read) are independent — both work on the Store; the Registry never updates Indexes (Indexes share the Store's references and project structural changes). A Store is depended *upon*; it never depends on a Registry/Index. An Index depends on its Store, a backend Adapter or pure logic; only when one projection is itself worth re-presenting another way may a derived Index depend on another Index — owned by the same Repository, never in a cycle (`ARCHITECTURE_VIOLATION_INDEX_DEP` otherwise). Keep it the exception: it is not a way to chain lookups.
 5. **Behaviour placement**: behaviour lives where it can be performed autonomously over its own state (`order.total()`, `dog.bark()`); behaviour needing an external actor lives on the *acting* component, taking the entity as an argument (a `Carrier` ships an order — not `order.ship()`). Prefer composition + interfaces over inheritance.
@@ -101,7 +101,7 @@ JSON for review. You never hand-author spec YAML. What to know beyond the tool
 schemas:
 
 - **Levels & files** (written by the tools): L0 `.wai/specs/.index.yaml` → L1 `<sub>/.index.yaml` → L2 `<sub>/<comp>/.index.yaml` (owned members nest one level deeper) → L3 `.interface.yaml` → L4+L5 `.implementation.yaml`. Types live under `types/` (system-level shared, or per subsystem).
-- **Statuses**: `draft` → `design` → `complete` — authoring readiness. Completeness rules relax to warnings while draft/design. Approval is separate: `wairon lock` (human-run) validates the tree as if complete and records the approval in `.wai/lock.json`; it never rewrites a spec's `status`.
+- **Statuses**: `draft` → `design` → `complete` — authoring readiness. Completeness rules relax to warnings while draft/design. Approval is separate: `wairon lock` (human-run) validates the tree as if complete and records the approval in `.wai/lock.json`; it never rewrites a spec's `status`. A status is readiness, never design: it is left out of the approval, so promoting a spec to `complete` after the lock never reopens it (and never needs a re-lock).
 - **designDepth** (project `rules.designDepth`, per-subsystem override, or a pack profile's default): how deep the team COMMITS to designing — `components | interfaces | implementations | narratives` (default `narratives` = full depth). Expectation checks below the depth are gated (nothing deeper is demanded to exist); soundness of whatever IS authored always applies. Ask the user their intended depth at Stage 1 if unclear — do not assume a team that stops at L3 is "incomplete".
 - **publicInterfaces (L1)**: each entry MUST name the `component` realizing it. Its export kind is DERIVED from the backing Portal's `transport` — never author a `type`. Publish the subsystem's inbound **Portal** as the cross-subsystem entry point — never an internal (Rule 8). A contract consumers IMPLEMENT rather than call (a trait, a callback, a webhook) is exported with `role: implement` (typically the Adapter holding the port); the consumer's interface declares `implements: alias::name` and states every method with the same signature. Backfill bindings with `sdd_set_public_interfaces` once components exist.
 - **Subsystem consumers**: an entry may list `consumers: [<subsystem>, …]` — the subsystems the surface is published to. Absent, any subsystem may depend on it; present, only those may, and a dependency from any other subsystem is `CROSS_SUBSYSTEM_UNLISTED_CONSUMER` (an error). Use it for an internal Portal meant for one or two peers, so the boundary says who may call it.

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

@@ -24,7 +24,7 @@ You are the **Delegation Orchestrator**. Your job is to hand scoped work to a fo
    - Pick the agent whose `ownedPaths`/domain matches the task. If no agent fits, stop and tell the user the topology has a gap.
 2. **Fetch the LIVE brief**:
    - Call `sdd_get_agent_brief(agentId)` (or read the `wairon-agent://<agentId>` resource).
-   - The brief carries: `agentId`, `name`, `template`, `domainRoot?`, `ownedPaths`, `readPaths?`, `instructions`, `variantGuidance?`, `typeMapping?` (how the contracts' neutral types are spelled in the language the agent's code is written in, also folded into `instructions` under `## Types in <language>`), and — when the project opted into `execution.tier` — `profile` and `budget`.
+   - The brief carries: `agentId`, `name`, `template`, `domainRoot?`, `ownedPaths`, `readPaths?`, `instructions`, `variantGuidance?`, `typeMapping?` (how the contracts' neutral types are spelled in the language the agent's code is written in, also folded into `instructions` under `## Types in <language>`; TypeScript's table is the one code conformance reads back, while Rust's and Python's are mapping-only tables the code analyzer does not check, and the table says so), `codeFence?` (where the agent may write code — for a subsystem owner also the project's shared setup files: manifest, compiler settings, crate or package root), an `## Externals used` section for a component reaching another project (each alias, the names it uses, the producer's transport and abi, and the pinned snapshot `.wai/externals/<alias>.yaml`, which joins `readPaths` — code against the pin, never the producer's source), and — when the project opted into `execution.tier` — `profile` and `budget`.
    - **Never reuse a brief across delegations or after a re-lock** — fetch fresh per delegation; the call is cheap and the brief is always current.
 3. **Spawn a GENERIC subagent from the brief**:
    - Prompt: `brief.instructions`, plus the concrete task description.

package/docs/cli.md

@@ -97,6 +97,29 @@ 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.
+- **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
+  below it) says there is nothing to check.
+- **Unknown keys are reported.** A key a spec's schema does not know (an
+  `exports:` table in the L0 — the export table is `publicInterfaces`; a
+  misspelt field) is `UNKNOWN_SPEC_KEY`, and an unknown setting in
+  `.wai/project.yaml` is `UNKNOWN_CONFIG_KEY` (both warnings): the parse would
+  otherwise drop them without a word.
+- **Code that crosses the design.** A call through a constructor-injected
+  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
+  `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.
 
 ### `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
@@ -164,11 +187,27 @@ digests read each spec's **design**: where it is realized — `sourcePath`,
 out (`specsReading: design`). Linking code to an approved design, or a change and
 its revert, never stales the lock; declare planned `sourcePath`s at design time.
 
-A **format-2** record (written before this reading) still passes `lock-check`
-while nothing it covered moved. `wairon doctor --fix` re-expresses it as format 3
-in place — keeping `lockedAt`, `lockedBy`, the results and the member pins, and
-recording `reexpressed: { at, fromAlgorithm, fromReading, by }`. A format-2 record
-that no longer matches reads stale once; one `wairon lock` clears it for good.
+**Readiness is not part of the approval either.** A spec's `status` (`draft`,
+`design`, `complete`) says how far authoring is, never what the design says, so
+it is left out of the design view: promoting a spec to `complete` after the lock
+never reopens it. A format-3 record taken while the view still carried `status`
+keeps passing when nothing but a status moved — it is judged in the reading it
+was taken in, each spec's approved status recovered from its digest — and
+`wairon doctor --fix` carries it into the current reading without a review.
+
+A **format-2** record (written before code linkage left the approval) still passes
+`lock-check` while nothing it covered moved. `wairon doctor --fix` re-expresses it
+as format 3 in place — before any other repair touches a spec — keeping
+`lockedAt`, `lockedBy`, the results and the member pins, and recording
+`reexpressed: { at, fromAlgorithm, fromReading, by }`. When no spec file moved
+but the record still does not match, what moved is the **gate** it was judged
+under — the design rules of a newer wairon release, the project's rule tuning,
+`composition`, the network declaration, consumed contracts or a member's
+approval — never your design: `lock-check` and `doctor` say exactly that, `doctor
+--fix` still carries the record into the design reading (its claim stays as
+certified, so it reads stale for that stated cause), and one `wairon lock`
+re-approves the unchanged design. A format-2 record whose specs moved reads stale
+once; one `wairon lock` clears it for good.
 
 It writes **nothing into your spec tree**. The approval is one sha256 per spec
 (over its design view) on `.wai/lock.json`, the record that was always committed — so your
@@ -348,9 +387,12 @@ The design changes, so one `wairon lock` follows. After it, declare the entries
 the migration cannot know — a CLI, a stdio tool surface (`JSONRPC`), a library
 (`InProcess`) — and model a caller or remove each verb still reported unreached.
 
-`--fix` also re-expresses a format-2 lock record that still provably covers the
-tree as format 3 (see `wairon lock`), keeping who approved it and when; when it
-no longer covers the tree, doctor says that one `wairon lock` is needed.
+`--fix` also re-expresses an earlier lock record — format 2, or format 3 taken
+while `status` was still in the approval — in the current reading, first, before
+any repair touches a spec (see `wairon lock`), keeping who approved it and when.
+A format-2 record over a tree no file of which moved is carried into the design
+reading even when the gate it was judged under moved; doctor then says the cause
+(the gate, not the design) and that one `wairon lock` re-approves it.
 
 ### `wairon list` (alias `ls`) / `wairon show <id>`
 List, or show full details of, the agents resolved from the spec tree
@@ -544,7 +586,18 @@ promise and how a consumer follows renames).
 - A tree without an L0 is refused. The JSON Schema ships in the package as
   `schemas/design-export-1.json`, and the library twin is `exportDesign()`.
 
-### `wairon network flows|policy|diagram|check|why`
+### `wairon type rename-field <type> <field> <new-name>`
+Renames a field of a type and respells every reference to it — each foreign
+key `references: <type>.<field>` naming it, the type's own included. The field
+keeps its place, type and description; its old name joins the field's rename
+trace (`previousNames`), which `wairon export` shows as `formerly`, so a
+consumer holding the old name reads a rename, not a removal and an addition.
+Traces and prose are never rewritten. It refuses, writing nothing, a type or
+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 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
 gateways), never addresses. Run at the family root.
@@ -562,6 +615,9 @@ gateways), never addresses. Run at the family root.
   unknown verb.
 - `why <from> <to>` prints the modelled chain behind one flow. It exits 1
   when nothing allows it.
+- `declare [--description <text>]` writes the project's `network` declaration
+  into `.wai/project.yaml`; `undeclare` removes it (the assistant's twin is
+  `sdd_set_network`). It changes which rules fire: validate, then re-lock.
 
 [Derived networking](network.md) describes every output, the bindings file
 and the observed-flow format.
@@ -611,6 +667,60 @@ then move the pin with `wairon member update`. An uncached git part offline is
 declared `externals`, the name a public name in that project's L0 export table.
 An id without `::` is local — a part's subsystems included.
 
+**Authoring the L0 export table.** What another project may reference is the
+project's **L0 export table**: the `publicInterfaces` list of the L0 spec
+(`.wai/specs/.index.yaml`). It is authored in two steps, both through the MCP
+tools (an assistant runs them; a human may edit the YAML the same way):
+
+1. Each subsystem publishes its own surface — its inbound Portal, and the types
+   it shares — with `sdd_set_public_interfaces` (an L1 `publicInterfaces`).
+2. The L0 **re-exports** from those subsystems with `sdd_update_spec` on kind
+   `system`, delta `publicInterfaces`. Each entry names a subsystem in `from`;
+   `from` alone re-exports everything it publishes, `component` (optionally
+   narrowed with `interface`) or `typeDef` picks one item, `as` renames it
+   (the public name consumers write after `alias::`), `role: implement` marks
+   an extension point consumers implement, and `audience` decides who may see
+   it (below).
+
+```yaml
+# .wai/specs/.index.yaml (excerpt)
+publicInterfaces:
+  - from: distance            # everything the distance subsystem publishes
+  - from: tiles
+    component: tile_portal
+    as: tiles                 # consumers write geo::tiles
+    audience: external
+  - from: shared
+    typeDef: coordinate       # a shared type, as geo::coordinate
+```
+
+The key is `publicInterfaces` — an `exports:` (or any other key the schema does
+not know) is reported as `UNKNOWN_SPEC_KEY`, never silently ignored, and an
+unknown setting in `.wai/project.yaml` as `UNKNOWN_CONFIG_KEY`. A reference to a
+name the producer does not export is `EXTERNAL_NOT_EXPORTED`.
+
+**Export audiences.** Each L0 entry carries an `audience` (default `instance`)
+that decides who may see the public name. Narrowest first:
+
+| Audience | Who sees it |
+|----------|-------------|
+| `project` | Only this project's family: its members, its parent and their siblings. |
+| `department` | The family, and — on a hosted instance — the projects of the owning department. A local sibling checkout or git consumer does **not** see it. |
+| `instance` | The default. Any project on the instance, and any local consumer by path or git. |
+| `partner` | Also consumers outside the instance that a partner grant admits. |
+| `external` | Publicly consumable. |
+
+A consumer is read at one audience: a family project at `project`, so it sees
+everything; a path, git or hosted consumer outside the family at `instance`, so
+it sees `instance`, `partner` and `external` entries only. A name exported to a
+narrower audience is refused by `externals add` (and `externals use`), naming
+the export's audience, the consumer's and this ranking. Because a project cannot
+tell from its own tree whether its consumers are hosted department units,
+`validate` notes every `department` export (`EXPORT_AUDIENCE_NARROW`, a
+notice): widen it to `instance` when a sibling checkout or a git consumer uses
+it, or keep it and allow the notice. A re-export can narrow an audience, never
+widen it (`EXPORT_WIDENS_AUDIENCE`).
+
 | Command | Description |
 |---------|-------------|
 | `wairon member add <alias> <source> [--project] [--description <text>]` | Create a member at `<source>` (`path`, `../path` or `git-url[#commit]`) and declare it by the shorthand. A **part** by default: a specs folder (and, outside this project, its `partOf`). With `--project` a project: its `project.yaml` declaring `<alias>` as its id and its L0, each only when absent. A git member is never scaffolded: it is pinned at the commit given, else the default branch head, and its content decides what it is |
@@ -740,7 +850,7 @@ The local server offers 38 tools:
 | 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` |
 | 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_pin_externals`, `sdd_get_externals_status` |
+| Externals | `sdd_add_external`, `sdd_update_external`, `sdd_remove_external`, `sdd_pin_externals`, `sdd_get_externals_status` |
 | Packs | `sdd_pack_impact` |
 | Delegation | `sdd_get_agent_brief` (the live brief for one agent; also served as the `wairon-agent://` resource) |
 
@@ -851,10 +961,13 @@ return the impact of every pack they applied in their results.
 
 | Command | Description |
 |---------|-------------|
-| `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. It is checked against the producer it reaches: one answering to another id, or not exporting a `use` name to this project, takes the declaration back out and names the id or the closest exported names. Pins by default; a producer that cannot be read leaves it declared and unpinned, saying why. A refusal is one sentence naming the accepted form, and exits 1 |
-| `wairon externals pin [alias…] [--json]` | Pin declared externals into `.wai/externals/<alias>.yaml` and `.wai/externals.lock.yaml`; 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`). 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 is listed with its problem, never hidden |
+| `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 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 produce <notion\|miro> [--page <id>] [--token <token>]` | Project the local spec tree to Notion or Miro (the token comes from `--token`, the environment, else a prompt; nothing is stored) |
 

package/docs/network.md

@@ -1,6 +1,8 @@
 # Derived networking: `wairon network`
 
-wairon derives a system's network from its design. The inputs are the calls you model, the entries you declare on Portals (`invokedBy: {kind: entry, scope: outside | network}`), the networks your projects declare (`network: true` in `.wai/project.yaml`) and the gateways on them (`variant: gateway`). From these it answers who may talk to whom, and on what grounds.
+wairon derives a system's network from its design. The inputs are the calls you model, the entries you declare on Portals (`invokedBy: {kind: entry, scope: outside | network}`), the networks your projects declare (`network` in `.wai/project.yaml`, written by `wairon network declare [--description <text>]` — `undeclare` removes it — or by the assistant's `sdd_set_network` tool) and the gateways on them (`variant: gateway`). From these it answers who may talk to whom, and on what grounds.
+
+**The gate comes first.** Every network command reads the design as the validator judges it. A flow an error sits on (`GATEWAY_BYPASSED`, ...) is **refused**: the matrix marks its row `REFUSED` with the findings, a policy never admits it (and `policy` exits 1, naming it at the head of the file), `why` answers that the gate refuses it, and `check` files an observed flow that only a refused flow would allow as disallowed. A warning (`ENTRY_UNPROVEN`, ...) only marks its row. Each command prints the findings it was judged against.
 
 Specs never hold an address, a port, a namespace or a label. Those deployment facts come from a **bindings file** that the team keeps outside `.wai/` and passes when generating policy. The design stays logical, and the deployment stays yours.
 
@@ -11,17 +13,20 @@ Every command runs at the project you are in. At a project that declares members
 | Command | Output | What a team does with it |
 |---|---|---|
 | `wairon network flows [--format json\|csv\|markdown] [--out <file>]` | The **allowed-flows matrix**: one row per flow (from, to, transport, binding, networks crossed, gateway, evidence) | Review it in pull requests as the authoritative "who talks to whom". A design change that adds a dependency shows up as a new row before any code or firewall change exists. The CSV suits spreadsheets and audits, and the Markdown suits review comments. |
-| `wairon network policy --bindings <file> [--out <file>]` | **Kubernetes `NetworkPolicy`** YAML: one ingress policy per called workload | Commit it to the deployment repository and diff it in CI. A design change becomes a policy diff that the security reviewer reads in the same PR. |
+| `wairon network policy --bindings <file> [--out <file>]` | **Kubernetes `NetworkPolicy`** YAML: one ingress policy per called workload | Commit it to the deployment repository and diff it in CI. A design change becomes a policy diff that the security reviewer reads in the same PR. A design that fails the gate exits 1: the refused flows are left out and named at the head of the file. |
 | `wairon network diagram [--out <file>]` | A **Mermaid** flowchart: declared networks as nested boundaries, gateways on them, an `outside` node, and flows aggregated per workload pair | Use it as the data-flow diagram with trust boundaries that threat modelling starts from: each boundary an edge crosses is a place to ask the STRIDE questions. It also works for onboarding and on architecture pages. The hosted canvas draws the same picture in its **Network** view (`/canvas/<project>/network`; the system spec's `diagram.defaultView: network` opens the canvas there). |
-| `wairon network check --observed <file> [--bindings <file>]` | **Unexpected** flows (seen, but nothing allows them), **unknown verbs** (an allowed pair, but a method and path no contract declares) and **unexercised** flows (allowed, never seen) | Audit a live system against its design. Exits 1 on anything unexpected or unknown, so it can gate a pipeline. Unexercised flows are review items, such as dead dependencies or rules to tighten, and never fail the command. |
-| `wairon network why <from> <to>` | The modelled chain behind a flow: the entry or call step, each network entered, the gateway, and the verb with its binding | Answer a firewall change request or an incident question ("why does checkout talk to payments?") from the design, in one command. Exits 1 when nothing allows the flow, and names what does reach the target instead. |
+| `wairon network check --observed <file> [--bindings <file>]` | **Unexpected** flows (seen, but nothing allows the pair), **disallowed** flows (a verb the destination declares, but not allowed from that source, or only by a flow the gate refuses), **unknown verbs** (an allowed pair, but a method and path no contract of the destination declares) and **unexercised** flows (allowed, never seen) | Audit a live system against its design. Exits 1 on anything unexpected, disallowed or unknown, so it can gate a pipeline. Unexercised flows are review items, such as dead dependencies or rules to tighten, and never fail the command. |
+| `wairon network why <from> <to>` | The modelled chain behind a flow: the entry or call step, each network entered, the gateway, and the verb with its binding | Answer a firewall change request or an incident question ("why does checkout talk to payments?") from the design, in one command. Exits 1 when nothing allows the flow, and names what does reach the target instead; says so when the gate refuses the flow, when a name is unknown (a typo, not a refusal), and — exiting 0 — when the callee is reached in-process, which is never a network flow. |
+| `wairon network declare [--description <text>]` / `undeclare` | Writes (or removes) `network` in `.wai/project.yaml` | Declare the boundary without a hand edit. It changes which rules fire, so validate, then re-lock. |
 
-The MCP server offers the same reads to an assistant while it designs: `sdd_get_network_flows` (optionally `to: <project | portal | portal.verb>`) and `sdd_explain_flow` (`from`, `to`). The hosted server serves the view model at `GET /web/projects/network?projectId=…`.
+The MCP server offers the same reads to an assistant while it designs: `sdd_get_network_flows` (optionally `to: <project | portal | portal.verb>`) and `sdd_explain_flow` (`from`, `to`), and the declaration as `sdd_set_network` (`declared`, `description`). The hosted server serves the view model at `GET /web/projects/network?projectId=…`.
 
 ### What becomes a flow
 
 - Only **network transports** produce flows: HTTP, gRPC, GraphQL, MessageBus and Custom. In-process libraries, CLI commands, IPC and JSON-RPC over stdio never do.
 - A **modelled call** into a network verb from another subsystem or project is a flow from the calling component. It names the networks it enters and the gateway it passes.
+- A verb's **binding** is the path a cluster sees: an HTTP endpoint is joined under its Portal's `basePath` (`basePath: /v1` and `POST /orders` bind `POST /v1/orders`), so L7 checks match real paths.
+- An **Adapter's transport** is its target Portal's: the Adapter calls the Portal's verbs over it. An Adapter may state one (`sdd_add_component` fills it in from the Portal its `dependsOn` names); a stated transport that disagrees with the target's is `ADAPTER_TRANSPORT_MISMATCH`, so changing a Portal's transport shows its impact on every Adapter that calls it.
 - An **`outside` entry** is a flow from outside the verb's innermost network. For an outermost network that is the world (`outside`); for a nested network it is the next network out (`network:<parent>`). Scopes are relative.
 - A **`network` entry** is a flow from anywhere inside the network. At the family root, when modelled callers prove the entry, the blanket row is replaced by those callers. The matrix is therefore least-privilege by construction: "the network may reach this" becomes "these two Adapters reach this".
 
@@ -36,7 +41,7 @@ The MCP server offers the same reads to an assistant while it designs: `sdd_get_
 - A component, as `project::component` or bare for the root's own.
 - On the receiving end, also `project::portal.verb`.
 
-Each party has a **default workload name**: a member's project key, or for the root project's own components their subsystem. When the root's component reaches into another project, the caller is named by its component.
+Each party has a **default workload name**: a member's project key, or for the root project's own components their subsystem — also when the root's component reaches into another project: the caller is named by its workload (its subsystem, the pod it runs in), with the component kept for the evidence, so a bindings file written per service keeps covering it after a callee is promoted.
 
 ## The bindings file
 

package/package.json

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

package/schemas/design-export-2.json

@@ -1036,6 +1036,12 @@
                     },
                     "references": {
                       "type": "string"
+                    },
+                    "formerly": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
                     }
                   },
                   "required": [