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

package/docs/design/supervisor-doctrine.md

@@ -0,0 +1,110 @@
+# Supervisor and Actor doctrine: supervision state, shared data, the lifecycle effect
+
+## The problem
+
+Two rules left the process layer without an honest shape.
+
+- Held state lives in a dedicated data component, but a Supervisor could not
+  depend on a Store, Registry, Repository, Index or Query at all
+  (`ARCHITECTURE_VIOLATION_SUPERVISOR_DEP`). A Supervisor's own bookkeeping —
+  restart counts, the set of live children, the brackets of the runs it starts —
+  had nowhere to live.
+- A component depending on a live Actor had to also depend on a Supervisor that
+  supervises it (`ACTOR_REACHED_WITHOUT_SUPERVISOR`). Real callers do not go
+  through the Supervisor: they look the Actor's live handle up by id in a
+  registry the Supervisor keeps. The remedy pushed a ceremonial edge instead of
+  the real lookup hop.
+
+## The rules
+
+1. **Supervision state.** A Supervisor may `owns` a Store or Registry that is its
+   own: one hop, private, read and written in full. It owns nothing else, and
+   nobody else depends on that state.
+2. **Shared data.** A Supervisor may call a data component it does not own only
+   through methods whose declared effect is `read` or `lifecycle`. A write goes
+   through a workflow: the Supervisor depends on the Orchestrator that does it.
+   Judged from the Supervisor's narrative call steps against the callee's
+   declared effect; a callee that declares no effect is refused too.
+3. **The lifecycle effect.** A third method effect, `lifecycle`: the method
+   creates, destroys, or (un)registers an entity's existence or membership and
+   never modifies its domain fields. It is closed under composition: a lifecycle
+   method calls only read and lifecycle methods besides construction and local
+   steps.
+4. **Supervised reach.** A component depending on a live Actor reaches it through
+   its supervision when it also depends on a Supervisor that supervises the
+   Actor, or on a Registry such a Supervisor maintains — by owning it, or by
+   calling it with lifecycle-effect methods.
+
+**Honest limit.** A `read` made on behalf of a request still passes. In practice
+the paired write is refused, which forces the marshalling workflow out, and the
+read moves with it.
+
+## Codes
+
+| Code | Severity | Rule | Reported on | Meaning |
+|---|---|---|---|---|
+| `SUPERVISOR_CONTAINMENT` | error | pattern-containment | the Supervisor | it owns something other than a Store or Registry |
+| `SUPERVISION_STATE_INTRUSION` | error | member-visibility | the intruder | "X depends on Y, which Supervisor Z owns as its supervision state" |
+| `SUPERVISOR_WRITE_SHORTCUT` | error | supervisor-shared-data (new) | the Supervisor's implementation | a call to a write-effect or untagged method on data it does not own |
+| `LIFECYCLE_CALLS_WRITE` | error | lifecycle-effect-closure (new) | the implementation | a lifecycle-effect method calls a write-effect method |
+| `ARCHITECTURE_VIOLATION_SUPERVISOR_DEP` | error | entrypoint-dependencies | the Supervisor | kept, narrowed: a Supervisor depending on a presentation block |
+| `ACTOR_REACHED_WITHOUT_SUPERVISOR` | error | entrypoint-dependencies | the caller | kept, widened: Registry reach counts; the remedy names the Registry, or says to model one |
+| `BLOCK_OWNS_MEMBERS` | error | pattern-membership | the block | kept: a Supervisor is exempt |
+| `SHARED_OWNED_MEMBER` | error | pattern-membership | the later claimant | kept: Supervisors claim like patterns |
+| `UNUSED_LINT_ALLOW` | warning | lint-allows | the allowing spec | kept: an allow naming an error now says an error cannot be allowed |
+
+The existing readers of `effect` read `lifecycle` as a mutation:
+`PORTAL_WRITE_SHORTCUT` refuses a Portal's direct lifecycle call as it refuses a
+write, and a durable Store needs a hydration read-back for its lifecycle methods
+as for its writes (`MISSING_HYDRATION`). The invariant registry still asks only
+write-effect methods to assert invariants, since a lifecycle method never
+modifies domain fields.
+
+Within the brief, three choices were made:
+
+- Exclusivity is its own code rather than a reworded `VISIBILITY_VIOLATION`:
+  the remedy differs (there is no facade to depend on instead; the state is
+  either shared data or reached through the Supervisor).
+- An owned Registry counts as maintained for supervised reach, as decided. A
+  caller depending on it is then still an intruder, so that shape reports
+  `SUPERVISION_STATE_INTRUSION` once and no actor finding: a lookup Registry
+  callers share is shared data the Supervisor keeps through lifecycle calls.
+- The lint-allow audit decides "error" from what the run saw on that spec (a
+  finding of the code landed there as an error) or, when nothing fired there,
+  from the code's resolved severity (project override, profile, default). The
+  validator now hands the rule context each code's default severity.
+
+## How the four motivating cases validate
+
+1. **An orchestrator calls an Actor whose handle it resolves through a router
+   that is really a Registry of live handles, mistyped as a Store.** Typed as a
+   Store, the caller reaches the Actor through no supervision and
+   `ACTOR_REACHED_WITHOUT_SUPERVISOR` fires on the caller. Retyped as a
+   Registry whose register/unregister methods are `lifecycle` and whose lookup
+   is `read`, with the Supervisor registering each started Actor through a
+   lifecycle call, the caller depending on that Registry and the Actor is
+   supervised reach, and the Supervisor's calls pass `SUPERVISOR_WRITE_SHORTCUT`.
+   A standalone Registry still needs a Store to write to
+   (`REGISTRY_WITHOUT_STORE`, a warning) — give the handles a Store, or wrap both
+   in a Repository the Supervisor keeps through lifecycle calls.
+2. **A component that spawns and owns Actors is typed Orchestrator but is a
+   fused Supervisor and workflow.** It depends on the Actor with no Supervisor
+   anywhere: `ACTOR_REACHED_WITHOUT_SUPERVISOR`, whose remedy says to give the
+   Actor a Supervisor that maintains a handle Registry. Split into a Supervisor
+   (spawns, restarts, registers handles) and a workflow (looks the Actor up in
+   that Registry), the tree validates.
+3. **A scheduler Supervisor reads guard state and brackets run lifetimes on a
+   shared repository.** The edge to the repository is no longer a finding. Its
+   calls — read the guard, open a run, count live runs, close the run — are
+   `read`, `lifecycle`, `read`, `lifecycle`: quiet. Tagging open or close as
+   `write`, or leaving them untagged, fires `SUPERVISOR_WRITE_SHORTCUT`; a
+   lifecycle open that also updates the run's fields fires
+   `LIFECYCLE_CALLS_WRITE` on the repository's implementation.
+4. **The same Supervisor reads and writes a shared object heap on behalf of a
+   call.** The read passes; the write fires `SUPERVISOR_WRITE_SHORTCUT`. Moving
+   the work into a marshalling Orchestrator the Supervisor calls — the read goes
+   with it — validates.
+
+All four, and a fire and a control for every new or changed code, are fixtures
+in `tests/rules-matrix/families/boundaries-supervision.fixtures.ts`; the
+lint-allow case is in `references-lint-allows.fixtures.ts`.

package/docs/extending-wairon.md

@@ -9,7 +9,7 @@ rules) that wairon reads and imports. A product built this way (a
 wairon installation: no fork, no build step, and wairon core never learns
 the platform exists.
 
-A working wrapper lives at [`examples/wrapper/`](../examples/wrapper/) and
+A working wrapper lives at [`examples/wrapper/`](https://github.com/SYW-Apps/Waffle-AIron/blob/main/examples/wrapper/) and
 is guarded by `tests/examples/wrapper-example.test.ts`, so it cannot
 silently rot.
 
@@ -98,9 +98,10 @@ arguments** — each selection carries its own source, so one command restores a
 project's doctrine anywhere:
 
 ```yaml
-- uses: SYW-Apps/Waffle-AIron/.github/actions/setup-wairon@v5
+- uses: SYW-Apps/Waffle-AIron/.github/actions/setup-wairon@v<version>   # the version you lock with (see docs/cli.md)
   with:
     packs: sync          # sync (default) | none (bundled repos) | explicit sources
+- run: npm ci            # a TS/JS project with code: its own dependencies first (see docs/cli.md)
 - run: wairon validate --ci
 ```
 
@@ -267,7 +268,7 @@ wairon pack add ./my-product-pack --global   # machine-wide
 
 The installer injects once and leaves — from then on plain `wairon
 validate` enforces the doctrine, and `wairon pack remove` undoes it. See
-[`examples/wrapper/install.js`](../examples/wrapper/install.js) for the
+[`examples/wrapper/install.js`](https://github.com/SYW-Apps/Waffle-AIron/blob/main/examples/wrapper/install.js) for the
 template. A spec-only product (implementation lives on a cloud platform)
 needs nothing more: the wrapped repository holds specs + docs, wairon holds
 the gate.
@@ -595,7 +596,7 @@ project's externals against their live producers, and the family checks),
 `globalPacksDir`, `discoverPacks`, `setProjectRoot`, the `SddRule` /
 `RuleContext` / `LoadedExtensions` / `DeclarativePack` types, `SDD_RULES`,
 `composeRuleSequence`, and the spec loaders/savers. See
-[`examples/wrapper/wrapper.js`](../examples/wrapper/wrapper.js).
+[`examples/wrapper/wrapper.js`](https://github.com/SYW-Apps/Waffle-AIron/blob/main/examples/wrapper/wrapper.js).
 
 ## Spec-only wrappers
 

package/docs/network.md

@@ -6,14 +6,14 @@ wairon derives a system's network from its design. The inputs are the calls you
 
 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.
 
-Every command runs at the project you are in. At a project that declares members, the commands cover its whole family; `--no-recursive` limits them to that project alone. Run them at the family root: only the family run can narrow a `network` entry to the callers it really has.
+Every command runs at the project you are in. At a project that declares members, the commands cover its whole family; `--no-recursive` limits them to that project alone. Inside a member, they answer from the enclosing family — the parent's network declaration and the callers the parent models, the same answer the family root gives — and `--no-recursive` judges the member alone. Only the family run can narrow a `network` entry to the callers it really has.
 
 ## The outputs, and what each is for
 
 | 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. A design that fails the gate exits 1: the refused flows are left out and named at the head of the file. |
+| `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. A design that fails the gate exits 1. |
+| `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. A design name the bindings leave unbound also exits 1. |
 | `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 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. |
@@ -69,7 +69,11 @@ outside:                           # what "outside" means for a policy
 - `outside` lists the CIDR blocks admitted for callers from outside, for example the internet, a load balancer range or an intranet. Without it, nothing from outside is admitted.
 - A source in another namespace gets a `namespaceSelector` on `kubernetes.io/metadata.name`. A network-wide source bound without a namespace matches in any namespace (`namespaceSelector: {}`).
 
-**Nothing is guessed.** A design name the bindings do not map is selected by the placeholder label `wairon.dev/workload: <name>`, which matches no pod until you bind it or label one. It is listed in the document and on stderr, and at the top of the output under `# UNBOUND:`. MessageBus flows travel through the broker rather than pod to pod, so they are listed as `# NOT EXPRESSED` instead of opening ingress. Default deny is implied: each policy selects its workload and admits only what the design allows.
+**Nothing is guessed.** A design name the bindings do not map is selected by the placeholder label `wairon.dev/workload: <name>`, which matches no pod until you bind it or label one. It is listed in the document and on stderr, and at the top of the output under `# UNBOUND:`, and `policy` exits 1 so a pipeline notices. MessageBus flows travel through the broker rather than pod to pod, so they are listed as `# NOT EXPRESSED` instead of opening ingress. Default deny is implied: each policy selects its workload and admits only what the design allows.
+
+**Renamed projects.** A bindings key, or a name in an observed-flow file, that is a project's former id (its rename trace, `previousIds`) still resolves to the renamed project, and the output carries a `# NOTE` naming the rename, so you can update the key at your pace instead of finding a policy that selects nothing or a legitimate flow filed as unexpected. `wairon project rename` lists the binding and telemetry keys to rename in its plan.
+
+**Mixed reach.** A NetworkPolicy cannot split traffic by path. When one workload serves verbs of different reach on one port — a verb entered from `outside` and a verb only the network may call — its policy has to admit the union, and `policy` says so in a `# NOTE` naming the verbs. To keep the narrower verb narrow at L4, bind the Portal on its own (a `<project>::<portal>` key with its own selector or port): it then gets a policy of its own.
 
 ## The observed-flow format
 
@@ -93,6 +97,7 @@ Or JSON with the same fields, as a list or as `{ "flows": [...] }`:
 - A row without `method` and `path` is an L4 observation: it exercises every allowed flow between the pair.
 - A row with both is checked at L7 against the verbs' bindings. `{id}` and `:id` path segments match any value, and gRPC paths (`/pkg.Service/Method`) match the `service/method` binding.
 - A malformed row (no source or destination, or a non-integer count) is refused with its row number, and nothing is half-read.
+- A name that is a project's former id is mapped to the renamed project, with a `# NOTE` (see **Renamed projects** above).
 
 ## A typical loop
 

package/docs/roadmap.md

@@ -4,7 +4,7 @@
 
 wairon is an AIDD support tool built around Spec-Driven Development. This roadmap
 reflects what is actually shipped in `src/` and what is planned. The
-[CHANGELOG](../CHANGELOG.md) has the per-release detail.
+[CHANGELOG](https://github.com/SYW-Apps/Waffle-AIron/blob/main/CHANGELOG.md) has the per-release detail.
 
 ---
 
@@ -79,7 +79,7 @@ reflects what is actually shipped in `src/` and what is planned. The
   and SSO; a state-scoped `lock` with approval requests; hosted members as
   records of their own; git-backed projects; Notion / Miro producers; a web UI
   (canvas, specs, admin). Self-host via Docker. See the
-  [hosted server guide](design/hosted-mcp-server.md).
+  [hosted server guide](https://github.com/SYW-Apps/Waffle-AIron/blob/main/docs/design/hosted-mcp-server.md).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wairon/cli",
-  "version": "5.1.1-dev.107",
+  "version": "5.1.1-dev.109",
   "description": "SYW Waffle AIron — CLI for managing AI coding agent topology across projects",
   "keywords": [
     "ai",
@@ -30,7 +30,13 @@
     "schemas",
     "README.md",
     "docs/*.md",
-    "docs/standards/**"
+    "docs/standards/**",
+    "docs/design/supervisor-doctrine.md",
+    "docs/design/pack-scoping.md",
+    "docs/design/connecting-agent-entrypoint.md",
+    "docs/design/execution-budgets.md",
+    "docs/design/approval-baseline.md",
+    "CONTRIBUTING.md"
   ],
   "workspaces": [
     "sdk"
@@ -72,6 +78,7 @@
     "js-yaml": "^4.1.0",
     "ora": "^5.4.1",
     "swagger-ui-dist": "^5.32.9",
+    "typescript": "^5.5.2",
     "yaml": "^2.9.1",
     "zod": "^3.23.8"
   },
@@ -87,7 +94,6 @@
     "rimraf": "^5.0.7",
     "tsup": "^8.1.0",
     "tsx": "^4.15.7",
-    "typescript": "^5.5.2",
     "vitest": "^4.1.9",
     "zod-to-json-schema": "^3.25.2"
   }

package/schemas/design-export-2.json

@@ -638,6 +638,12 @@
                           },
                           "description": {
                             "type": "string"
+                          },
+                          "formerly": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
                           }
                         },
                         "required": [
@@ -1096,7 +1102,15 @@
                   "properties": {
                     "id": {
                       "type": "string",
-                      "pattern": "^[a-z0-9-_]+$"
+                      "maxLength": 64,
+                      "allOf": [
+                        {
+                          "pattern": "^[a-z0-9-_]+$"
+                        },
+                        {
+                          "pattern": "^(?!(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$)"
+                        }
+                      ]
                     },
                     "description": {
                       "type": "string",