session-orchestrator 4.1.0 → 4.2.0

package/docs/USER-GUIDE.md

@@ -96,7 +96,7 @@ enforcement: warn
 vcs: github
 ```
 
-If you skip this step, the plugin uses sensible defaults: `feature` type, 6 agents per wave, 5 waves, and auto-detected VCS. See [`docs/session-config-template.md`](session-config-template.md) for the full field walkthrough.
+If you skip this step, the plugin uses sensible defaults: `feature` type (a fixed 3-wave shape — see [`docs/session-config-reference.md`](session-config-reference.md#session-shapes) § Session Shapes for the full per-type wave/agent-cap table), 6 agents per wave, and auto-detected VCS. See [`docs/session-config-template.md`](session-config-template.md) for the full field walkthrough.
 
 ### Run your first session
 
@@ -198,6 +198,22 @@ You can also run the bootstrap flow explicitly, outside of any session:
 
 `--retroactive` is the recommended path for existing repos that predate the Bootstrap Gate — it adds the missing `CLAUDE.md` structure and lock file without touching your existing code or configuration.
 
+### Use a configured baseline
+
+Standard and Deep bootstrap can read the validated archetype contract from your
+configured local baseline. Existing project markers select a matching archetype;
+an empty or unrecognized project presents the baseline's available choices.
+The selected contract supplies templates, runtime and package-manager versions,
+commands, CI expectations, and required rules. Existing project files are
+preserved and reported for review.
+
+Configuration resolves from `SO_BASELINE_PATH`, a matching named baseline,
+`owner.yaml` paths, then the project's `plan-baseline-path`. Lookup is offline
+and does not install packages. An absent baseline uses the bundled public
+templates; an invalid configured contract stops before writing files. Missing
+quality gates are reported as unavailable. See [Baseline integration](baseline.md)
+for the contract and configuration details.
+
 ### Anti-bureaucracy promise
 
 - **Normal flow:** exactly 1 question (tier confirmation)
@@ -285,29 +301,47 @@ Structured requirement gathering, PRD generation, and issue creation. Accepts on
 
 **Optional:** `plan-baseline-path` in Session Config (for `/plan new` repo scaffolding from your own baseline). When absent, `/bootstrap` falls back to plugin-bundled minimal templates. Not required for `/plan feature` or `/plan retro`.
 
+**Optional private capability context:** For new-project or session planning, you can
+supply a small catalog excerpt or authorize a particular offline, read-only local
+catalog lookup and state that its planning destination is private/internal. The
+planner uses at most five matches to explain reuse alternatives and remaining
+contract checks. Existing authorization carries forward. Missing or unsuitable
+context leaves ordinary planning available; a match does not authorize adoption.
+Private findings stay out of public output and generated repositories. This needs
+no new Session Config key; see the [shared procedure](../skills/_shared/private-capability-context.md).
+
 ---
 
 ## 4. Session Types
 
-### Housekeeping
+Wave count, roles, and per-wave agent caps are resolved by one module — `scripts/lib/session-shape.mjs` — not derived by hand from `waves`/`agents-per-wave`. Run the CLI yourself to see exactly what a given mode resolves to before starting a session:
+
+```
+node scripts/session-shape.mjs --repo-root "$PWD" --session-type <housekeeping|feature|deep> \
+  [--profile ultradeep] [--known-scope true|false] --no-event
+```
+
+It prints one JSON line (`totalWaves`, `waves[]` with each wave's `role`/`agentCap`/`maxTurns`/`verification`, `discovery`, `wavesConfigHonored`, `notes`) and, without `--no-event`, records `orchestrator.session.shape_resolved` to `.orchestrator/metrics/events.jsonl`.
+
+### Housekeeping — the maintenance loop
 
 Best for: git cleanup, SSOT refresh, CI fixes, branch merges, documentation updates.
 
-- **Execution model:** Serial (no wave structure)
-- **Agents:** 1-2 per task
+- **Execution model:** **1 coordinator-direct wave.** Housekeeping *is* the maintenance loop: drift-check → expired-learnings sweep → `/evolve analyze` → `/reconcile` → `/evolve dialectic` → `/memory-cleanup`, then any operator-selected housekeeping issues appended in the order picked. No wave-executor dispatch for the loop itself — most of those steps are `AskUserQuestion`-gated, and AUQ does not exist inside a dispatched subagent.
+- **Agents:** 0 dispatched for the loop (the coordinator runs it directly); the dialectic step dispatches the read-only `dialectic-deriver` subagent.
 - **Typical duration:** Short
-- **Use when:** Your repo needs maintenance, not new features
+- **Use when:** Your repo needs maintenance, not new features — or when the session-start `maintenance-due` banner tells you it's overdue.
 
 ```
 /session housekeeping
 ```
 
-### Feature
+### Feature — 3 waves
 
 Best for: frontend/backend feature work, implementing issues, standard development.
 
-- **Execution model:** 5 waves with parallel agents
-- **Agents:** 4-6 per wave (configurable)
+- **Execution model:** 3 waves — Impl-Core → Impl-Polish+Quality → Finalization.
+- **Agents:** capped at 4 / 4 / 2 respectively (subject to `agents-per-wave`).
 - **Typical duration:** Medium
 - **Use when:** You have feature issues to implement
 
@@ -315,12 +349,12 @@ Best for: frontend/backend feature work, implementing issues, standard developme
 /session feature
 ```
 
-### Deep
+### Deep — 5 waves (4 when scope is already known)
 
 Best for: complex backend work, security audits, database refactoring, architecture changes.
 
-- **Execution model:** 5 waves with parallel agents
-- **Agents:** Up to 10-18 per wave (configurable)
+- **Execution model:** 5 waves — Discovery → Impl-Core → Impl-Polish → Quality → Finalization. When the agreed scope is already fully known (`--known-scope true`), Discovery is dropped and the rest renumbered to 4 waves.
+- **Agents:** capped at 8 / 10 / 8 / 6 / 4 per wave respectively (subject to `agents-per-wave`).
 - **Typical duration:** Longer
 - **Use when:** The work requires extensive discovery, testing, or touches critical systems
 
@@ -328,6 +362,19 @@ Best for: complex backend work, security audits, database refactoring, architect
 /session deep
 ```
 
+### Ultradeep — 7 fixed waves (a profile over `deep`)
+
+Best for: sessions that outgrow 5 waves — large audits, work needing web research before implementation, or a release that benefits from an independent review panel.
+
+- **Execution model:** a **fixed 7-wave shape** — Research+Code-Discovery → Synthesis-Gate (coordinator-direct, 0 agents, blocking `AskUserQuestion`) → Impl-Core → Impl-Polish → Review-Panel (read-only) → Quality → Release/Finalization. It IGNORES the `waves` Session Config value outright (`wavesConfigHonored: false`) — there is no "waves < 7 is an error" check; the profile just reports that it ignored the configured number.
+- **Agents:** capped at 18 / 0 / 8 / 8 / 3 / 6 / 4 per wave respectively; `max-turns` is set PER WAVE (40 / — / 25 / 25 / 25 / 25 / 15), not one flat number.
+- **Typical duration:** Longest
+- **Use when:** `/session deep` would work but the scope needs research first, or you want a dedicated review panel before Quality.
+
+```
+/session deep --profile ultradeep    # or the /session ultradeep alias, per commands/session.md
+```
+
 ---
 
 ## 5. Session Config Reference
@@ -372,8 +419,8 @@ Add a `## Session Config` section to your project's Session Config host file to
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `agents-per-wave` | integer | `6` | Maximum number of parallel subagents per wave. Higher values increase parallelism but use more resources. |
-| `waves` | integer | `5` | Number of execution waves for feature and deep sessions. |
+| `agents-per-wave` | integer | `6` | Maximum number of parallel subagents per wave. Higher values increase parallelism but use more resources. Supports the per-type override syntax `6 (deep: 18)` — see [§ 4 Session Types](#4-session-types). |
+| `waves` | integer | `5` | Base wave count. The wave count actually used is resolved per session type by `scripts/session-shape.mjs` (see [§ 4 Session Types](#4-session-types)) — `feature` and `deep` each have one natural shape and ignore a disagreeing `waves` value; the `ultradeep` profile ignores it outright. |
 | `pencil` | string | none | Path to a `.pen` design file (relative to project root). Enables design-code alignment reviews after Impl-Core and Impl-Polish waves. |
 | `cross-repos` | list | none | Related repositories under `~/Projects/`. The orchestrator checks their git state and critical issues during session start. |
 | `ssot-files` | list | none | Single Source of Truth files to track for freshness (e.g., `STATUS.md`, `STATE.md`). Flagged if older than 5 days. |
@@ -414,7 +461,7 @@ Add a `## Session Config` section to your project's Session Config host file to
 | `cold-start.silence-after-sessions` | integer | `1` | Consecutive silent sessions (no commits, no learnings) before the cold-start detector fires a nudge. PRD F1.3 / issue #500. |
 | `enforcement` | string | `warn` | Hook enforcement level for scope and command restrictions: `strict`, `warn`, or `off`. |
 | `isolation` | string | `auto` | Agent isolation mode: `worktree`, `none`, or `auto`. `auto` resolves per-wave via the graduated default (#194): ≤2 agents → `none`, 3–4 agents on feature/deep → `worktree`, ≥5 agents → `worktree`, housekeeping 3–4 → `none`. See Section 15 "Isolation Graduation" below. |
-| `max-turns` | integer or string | `auto` | Max agent turns before PARTIAL. Auto: housekeeping=8, feature=15, deep=25. |
+| `max-turns` | integer or string | `auto` | Max agent turns before PARTIAL. Auto-resolves per session shape (`scripts/lib/session-shape.mjs`): 8 for housekeeping, 15 for feature, 25 for deep — applied to every wave. The `ultradeep` profile sets it PER WAVE instead (40 for Research+Code-Discovery, 25 for Impl-Core/Impl-Polish/Quality, 15 for Release/Finalization). See [§ 4 Session Types](#4-session-types). |
 
 > **Security:** Do not embed credentials, API keys, or auth tokens in Session Config fields — especially `health-endpoints` URLs. These values are stored in your config host file (`CLAUDE.md` / `AGENTS.md`) which may be committed to version control. Use header-based auth or separate secret management instead.
 
@@ -434,7 +481,7 @@ See [examples](examples/) for project-specific configurations (Next.js, Express
 
 ## 6. The Wave Pattern
 
-Feature and deep sessions execute work in structured waves, each assigned one of 5 roles. Each wave has a specific purpose, and agents within a wave run in parallel.
+Feature and deep sessions execute work in structured waves drawn from the same 5 named roles (some combined into one wave, depending on session type — see [§ 4 Session Types](#4-session-types)). Each wave has a specific purpose, and agents within a wave run in parallel.
 
 ### Wave Structure
 
@@ -448,14 +495,15 @@ Feature and deep sessions execute work in structured waves, each assigned one of
 
 ### Role-to-Wave Mapping
 
-Roles map dynamically to the configured wave count (default: 5):
+**As of 2026-09-09, this mapping is resolved by `scripts/session-shape.mjs` per session type — it is no longer a function of the `waves` config value.** The former table (`waves: 3/4/5/6+` → a re-combined role mapping) is retired; a `waves` value that disagrees with a type's natural shape is now IGNORED and reported in the shape's `notes`, never used to re-combine roles. See [§ 4 Session Types](#4-session-types) for the CLI, and the per-type wave lists there:
 
-| `waves` | Mapping |
-|---------|---------|
-| 3 | W1=Discovery+Impl-Core, W2=Impl-Polish+Quality, W3=Finalization |
-| 4 | W1=Discovery, W2=Impl-Core+Impl-Polish, W3=Quality, W4=Finalization |
-| 5 | W1=Discovery, W2=Impl-Core, W3=Impl-Polish, W4=Quality, W5=Finalization |
-| 6+ | W1=Discovery, W2-W3=Impl-Core (split), W4-W5=Impl-Polish (split), W6=Quality+Finalization |
+| Session type | Waves | Roles |
+|---|---|---|
+| `housekeeping` | 1 | Housekeeping (coordinator-direct maintenance loop) |
+| `feature` | 3 | Impl-Core → Impl-Polish+Quality → Finalization |
+| `deep` (scope not yet known) | 5 | Discovery → Impl-Core → Impl-Polish → Quality → Finalization |
+| `deep` (scope known) | 4 | Impl-Core → Impl-Polish → Quality → Finalization |
+| `deep` + `ultradeep` profile | 7 (fixed, ignores `waves`) | Research+Code-Discovery → Synthesis-Gate → Impl-Core → Impl-Polish → Review-Panel → Quality → Release/Finalization |
 
 ### Wave Details
 
@@ -476,13 +524,15 @@ One or two agents update SSOT files, close or update issues, write session hando
 
 ### Agent Counts by Session Type
 
+These are the shape table's RAW per-wave ceilings (`agentCapRaw` in the `scripts/session-shape.mjs` JSON) — not a range the orchestrator picks within by feel:
+
 | Session Type | Discovery | Impl-Core | Impl-Polish | Quality | Finalization |
 |-------------|-----------|-----------|-------------|---------|-------------|
-| housekeeping | 2 | 2 | 1 | 1 | 1 |
-| feature | 4-6 | 6 | 4-6 | 4 | 2 |
-| deep | 6-8 | 6-10 | 6-8 | 6 | 2-4 |
+| housekeeping | — | — (0, coordinator-direct) | — | — | — |
+| feature | — | 4 | 4 (combined w/ Quality) | *(combined)* | 2 |
+| deep | 8 | 10 | 8 | 6 | 4 |
 
-The `agents-per-wave` config value caps the maximum. These counts are guidelines — the orchestrator adjusts based on task complexity.
+**The number actually used (`agentCap`) is `min(raw, agents-per-wave)`.** With the documented default `agents-per-wave: 6`, a `deep` session's Discovery/Impl-Core/Impl-Polish waves are clipped DOWN to 6 — the 8/10/8 above only apply once you raise the cap for that type, e.g. `agents-per-wave: 6 (deep: 18)` (this plugin's own committed config). `feature`'s 4/4/2 already sit under the default 6 and are unaffected by it. These are still ceilings, not targets — the orchestrator adjusts DOWN based on task complexity, per the tier guidance below.
 
 The **Quality column is a cap, not a target**: since this version, test-writing capacity is need-gated on measured demand — roughly one test-writer per three HIGH/MED gaps the review panel actually found, capped by the number above. If no gaps were measured, the Quality wave writes no tests and is skipped (the read-only review panel still runs); with no measurement signal at all, the orchestrator allocates a conservative 1-2 rather than the full cap.
 
@@ -546,18 +596,21 @@ After you choose a direction, the orchestrator decomposes the work into a role-b
 ```
 ## Wave Plan (Session: feature)
 
-### Wave 1: Discovery (4 agents)
-- Agent 1: Audit API endpoint structure → src/api/ → map current routes
-- Agent 2: Verify database schema → prisma/schema.prisma → check relations
-...
+A `feature` session resolves to 3 waves — no Discovery wave; see [§ 4 Session Types](#4-session-types).
 
-### Wave 2: Impl-Core (6 agents)
+### Wave 1: Impl-Core (4 agents)
 - Agent 1: Implement new API route → src/api/users.ts → endpoint returns 200
+- Agent 2: Add database migration → prisma/schema.prisma → check relations
+...
+
+### Wave 2: Impl-Polish+Quality (4 agents)
+- Agent 1: Build frontend form component → src/components/ → wired to the new route
+- Agent 2: Write and run tests → tests/api/users.test.mjs → passing
 ...
 
 ### Inter-Wave Checkpoints
 - After Impl-Core: Design review (Pencil configured)
-- After Quality: Full quality gate
+- After Impl-Polish+Quality: Full quality gate
 
 Ready to execute? Use /go to begin.
 ```
@@ -573,13 +626,12 @@ You can request changes to the plan. When satisfied:
 Waves execute automatically. Agents within each wave run in parallel. Between waves, the orchestrator reviews results, runs checks, and adapts the plan if needed. You see progress updates after each wave:
 
 ```
-## Wave 2 (Impl-Core) Complete ✓
+## Wave 1 (Impl-Core) Complete ✓
 - Agent 1: done — API route implemented, returns correct schema
 - Agent 2: done — Database migration created
-- Agent 3: done — Frontend form component built
 - Tests: 3 new passing | TypeScript: 0 errors
 - Design: ALIGNED
-- Adaptations for Impl-Polish: none
+- Adaptations for Impl-Polish+Quality: none
 ```
 
 ### Step 5: Close the session
@@ -954,7 +1006,7 @@ Session Orchestrator persists session state so you can resume after crashes, pau
 
 ### STATE.md
 
-Lives at `.claude/STATE.md` in your project. Contains YAML frontmatter (`session-type`, `branch`, `issues`, `started`, `status`, `current-wave`, `total-waves`) and a Markdown body tracking the Current Wave, Wave History, and any Deviations from the plan. Written by the wave-executor after each wave; read by session-start on the next `/session` invocation.
+Lives at `.claude/STATE.md` in your project. Contains YAML frontmatter (`session-type`, `branch`, `issues`, `started`, `status`, `current-wave`, `total-waves`) and a Markdown body tracking the Current Wave, Wave History, and any Deviations from the plan. Written by the wave-executor after each wave; read by session-start on the next `/session` invocation. <!-- path-check: example -->
 
 ### Session Continuity
 
@@ -1163,7 +1215,7 @@ Read-only display of all active learnings with confidence scores and expiry date
 
 ## 18. Adaptive Wave Sizing
 
-Instead of fixed agent counts, the orchestrator scores session complexity and adjusts agent allocation dynamically.
+Instead of always dispatching a wave's full agent-cap ceiling, the orchestrator scores session complexity and relaxes agent allocation downward when the briefed work does not need the full cap.
 
 ### Complexity Scoring
 Three factors are scored (0-2 points each):
@@ -1177,18 +1229,11 @@ Three factors are scored (0-2 points each):
 ### Complexity Tiers
 - **Simple** (0-1 points): fewer agents per wave
 - **Moderate** (2-3 points): standard allocation
-- **Complex** (4-6 points): maximum agents per wave
+- **Complex** (4-6 points): up to the wave's cap
 
-### Dynamic Scaling Between Waves
-After each wave, agent count is adjusted based on performance:
-- All agents fast + no issues → reduce next wave
-- Failures or broken code → add fix agents
-- Scope expansion → scale up
-- Quality regressions → targeted fix agents
+The tier score relaxes agent count **downward only** — a simple-tier session may plan fewer agents than the wave's `agentCap` where the briefed work does not fill it. It never raises the count above that cap; a moderate or complex tier does not scale it up. The cap itself comes from the resolved session shape (`waves[].agentCap`, see [`docs/session-config-reference.md`](session-config-reference.md#session-shapes) § Session Shapes) — it is not derived from the tier, and the `agents-per-wave` config value is the ceiling that cap was already built against.
 
-The `agents-per-wave` config value always caps the maximum.
-
-> **Note:** Housekeeping sessions skip complexity scoring and use fixed counts.
+> **Note:** Housekeeping has no tier at all — it is a single coordinator-direct wave (0 dispatched agents) running the fixed maintenance loop, not a scored/scaled wave.
 
 ---
 
@@ -1281,7 +1326,7 @@ Yes. Between each wave, the orchestrator reviews results and can adapt the plan.
 
 ### How many agents run in parallel?
 
-This is controlled by the `agents-per-wave` setting in your Session Config. The default is 6. For deep sessions, you can increase this to 10-18. All agents within a single wave run in parallel; the orchestrator waits for all of them to complete before starting the next wave.
+This is controlled by the `agents-per-wave` setting in your Session Config, using the override form `6 (deep: 18)` to raise the ceiling for deep sessions specifically — see [`docs/session-config-reference.md`](session-config-reference.md#session-shapes) § Session Shapes for the full per-wave cap table. Note that a plain `deep` session's own raw wave caps top out at 10 (the Impl-Core wave) regardless of the override value configured; an override of 18 only actually binds under the `ultradeep` profile (`/session ultradeep`), whose Research+Code-Discovery wave is the one wave sized at 18. All agents within a single wave run in parallel; the orchestrator waits for all of them to complete before starting the next wave.
 
 ### Do I need Pencil?
 
@@ -1377,6 +1422,28 @@ If agents consistently time out during wave execution:
 - Switch from `deep` to `feature` session type if you do not need the extra agent count
 - Check that your machine has sufficient resources for parallel agent execution
 
+### Import-probe warnings and missing ESLint
+
+The post-edit import probe checks edited `.mjs`, `.js`, and `.cjs` files only when the path is listed in the project's `hooks/_lib/hook-import-set.json` and the hook is enabled. It reports likely hook breakage as a warning and always exits 0. Its two checks have different coverage:
+
+- **C1 — ESLint:** reports `no-undef` and fatal/parse errors. Install ESLint with the project's package manager and enable `no-undef` in the **project's ESLint configuration**; the probe does not enable that rule itself. Other lint rules remain the full lint command's responsibility.
+- **C2 — import:** loads allowlisted files under `scripts/lib/**` in a child process to detect errors during module loading. It does not import hook entrypoints or call exported functions. An undefined identifier reached only when a function runs can therefore escape C2 even when importing the module succeeds.
+
+ESLint lookup tries these paths in order: the project's `node_modules/.bin/eslint`, the project's `node_modules/eslint/bin/eslint.js`, then the same two paths under the plugin root. A consumer installation may have no plugin development dependencies, so the project's ESLint installation matters. `SO_IMPORT_PROBE_ESLINT` overrides this search with an explicit script path; use an absolute path to the ESLint entry script. An empty or nonexistent override disables C1 **without falling back** to either installation.
+
+When no ESLint is available, C1 is normally silent and only eligible C2 checks remain. For an edit that reaches the checks, `SO_IMPORT_PROBE_TRACE=1` writes `probe:eslint-unavailable` to stderr when ESLint cannot be located. This trace diagnoses unavailable ESLint; it does not diagnose every timeout or configuration failure. A timed-out ESLint or an unreadable/non-JSON report is skipped, so silence does not prove that C1 ran successfully.
+
+The shipped event wiring is:
+
+| Harness | Import-probe event |
+|---------|--------------------|
+| Claude Code | `PostToolUse` for edit/write tools |
+| Cursor | `postToolUse` and `afterFileEdit` |
+| Pi | `tool_result` for edit/write tools |
+| Codex | **Unwired:** the current Codex hook manifest has no import-probe handler |
+
+Codex does not currently run this probe automatically, and reinstalling the same bundle does not add that missing handler. Use the project's normal lint and tests for verification there. Implementation: [`hooks/post-edit-import-probe.mjs`](../hooks/post-edit-import-probe.mjs); event manifests: [Claude Code](../hooks/hooks.json), [Cursor](../hooks/hooks-cursor.json), [Pi](../hooks/hooks-pi.json), [Codex](../hooks/hooks-codex.json).
+
 ### Design review skipped unexpectedly
 
 If you configured `pencil` but design reviews are not running:

package/docs/agent-authoring.md

@@ -1,4 +1,4 @@
-<!-- Moved in v4.0.0 from `agents/AGENTS.md` (audit 2026-09-06 § 5A). It never was an agent: Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it — only pseudo-frontmatter (`name: agents-authoring-spec`, `tools: Read`) kept the false registration bounded. Living under `docs/` removes the registration instead of bounding it. -->
+<!-- Moved in v4.0.0 from `agents/AGENTS.md` (audit 2026-09-06 § 5A). It never was an agent: Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it — only pseudo-frontmatter (`name: agents-authoring-spec`, `tools: Read`) kept the false registration bounded. Living under `docs/` removes the registration instead of bounding it. --> <!-- path-check: historical -->
 
 # Sub-Agent Authoring Conventions (`agents/**`)
 
@@ -11,7 +11,7 @@
 > plugin loader registers every `agents/*.md` as a dispatchable agent by
 > directory convention, and the manifest's `agents` key is documented as
 > *additive* ("in addition to those in the `agents/` directory"), so it cannot
-> exclude a path. As `agents/AGENTS.md` this file was therefore a registered
+> exclude a path. As `agents/AGENTS.md` this file was therefore a registered <!-- path-check: historical -->
 > agent — first an unnamed one with **full tool access**, later a contained one
 > whose pseudo-frontmatter capped `tools` at `Read`. Moving it out of the
 > directory removes the registration rather than bounding it. The same applies

package/docs/baseline.md

@@ -19,7 +19,61 @@ A separate git repository (not vendored, not a submodule, not on npm) carrying:
   rules are read **from the baseline**, not from this plugin, so the plugin had to
   learn the baseline's frontmatter convention rather than the other way round.
 
-## How the plugin finds it
+## How bootstrap finds it
+
+Bootstrap resolves only explicit local configuration, in this order:
+
+1. `SO_BASELINE_PATH`
+2. A matching entry in the host-local `owner.yaml` `baselines` list
+3. `owner.yaml` `paths.baseline-path`
+4. `plan-baseline-path` in the repository's Session Config
+
+`scripts/baseline-archetypes.mjs --repo <repo>` reuses the existing configuration
+resolvers. Their diagnostics are contained in a bounded local process so paths
+and private match names cannot leak through the bootstrap CLI. An absent or
+missing directory keeps the public fallback. An existing directory with a
+missing producer, unsupported schema, invalid metadata or unsafe source is an
+explicit error; bootstrap does not silently switch to a public default.
+
+The local producer is the baseline's `archetype-manifest.mjs export` CLI. Its reduced v1
+JSON owns IDs, ordering, declarative detection signals, runtimes, package
+managers, UI/API/deploy metadata, command documentation, quality gates, CI,
+browser automation, and rule targets. No private package inventory or source
+evidence is imported into the plugin. Marker inference uses exported priorities;
+an unknown result is `insufficient-evidence`, requiring a selection from the
+returned catalog for Standard/Deep. `--archetype <id>` validates an explicit ID.
+
+The CLI is read-only, offline and dependency-free without a baseline. Commands
+in its JSON are data and are never evaluated. Only the explicit scaffold action
+in [`private-contract.md`](../skills/bootstrap/private-contract.md) invokes the
+configured baseline's local renderer, into temporary staging. It preserves
+existing destination files and excludes staged rules. Deep retains baseline CI
+and its exemption/requirement instead of generating a public Node pipeline.
+New instruction-file command slots come from exactly matching declared gate
+IDs. Missing test/typecheck/lint gates are reported as unavailable and use
+`false` placeholders, never inferred npm commands. Private verification reports
+declared gates separately from unavailable slots; the generic quality runner
+is unchanged and an unavailable slot must not be reported as a passed check.
+
+S99 recomputes the complete exported rule union after rendering, including
+dependency-conditional targets, and validates the baseline's local `rules`
+projection against it. Sources must stay under `.claude/rules/` or
+`templates/shared/.claude/rules/`, with no symlinks. All basenames owned by
+`rules/_index.md` are excluded, including scoped entries: `rules-sync.mjs` remains
+their sole writer. `syncBootstrapRules` passes the contract's required plugin
+basenames to that writer after validating the local export, so a public scope
+tag cannot silently omit a private requirement. Private S99 adds missing local rules and preserves existing
+ones; the public opt-in fetch retains its existing remote behavior with the
+same plugin-ownership exclusion. No baseline is downloaded or located by
+guessing sibling/private host paths.
+
+New private quality policies use the same exact `test`, `typecheck`, and `lint`
+gate IDs as new Session Config blocks. Missing slots use `false` with an
+unavailable explanation; existing owner policies remain unchanged. Bootstrap
+accumulates actual created relative paths through inherited tiers and stages
+those files individually.
+
+## Legacy vault and maintenance resolution
 
 Never by a hardcoded path. Resolution is host-local, most specific first:
 

package/docs/ci-setup.md

@@ -123,7 +123,7 @@ jobs, so a half-revert or a template refresh flipping one site back to
    check diffs real content rather than passing on a broken comparison.
 
 Per `.claude/rules/security.md` § SEC-005, this token's lifecycle belongs in
-`.claude/docs/SECRETS-INVENTORY.md` once one exists — that file is not present
+`.claude/docs/SECRETS-INVENTORY.md` once one exists — that file is not present <!-- path-check: example -->
 in this repo (measured 2026-09-02: no `.claude/docs/` directory tracked), so
 the inventory is not adopted here and this section remains the sole record.
 

package/docs/codex-setup.md

@@ -255,6 +255,7 @@ codex plugin list --available --json
 - **The `kanevry` marketplace points at another source:** confirm the conflict with `codex plugin marketplace list --json`, run `codex plugin marketplace remove kanevry`, then rerun the installer from the intended clone so it performs the public marketplace add and plugin add lifecycle.
 - **`go` or `close` is missing from the skill picker:** follow [the refresh steps](#refresh-and-explicit-cache-invalidation), verify the installed version, and restart Codex if reopening the picker does not load the new entries. Use the namespaced skill form from [Usage](#usage), rather than selecting the unrelated native Goal command.
 - **Plugin is installed and enabled but hooks do not fire:** start a fresh task or fully restart Codex, run `/hooks`, and review the trust state. Installation does not imply hook approval.
+- **No import-probe warning after an edit:** the post-edit import probe is currently **unwired in Codex**. Reinstalling the same bundle does not add it. Use normal project lint and tests; see [the probe's harness wiring and ESLint requirements](USER-GUIDE.md#import-probe-warnings-and-missing-eslint).
 - **Other pre-public plugin/config/cache/hook-state residue is suspected:** this state is unsupported. Do not modify private Codex files. File an issue with `codex --version`, `codex plugin list --available --json`, and `codex plugin marketplace list --json` output so the public recovery path can be diagnosed.
 - **Agent dispatch fails:** verify Codex multi-agent support and inspect the bundled or project-level role TOMLs.
 - **Hooks report that Node is unavailable:** expose Node 24+ on the Codex hook PATH or set `SO_NODE_BIN` to the absolute Node executable.

package/docs/components.md

@@ -56,7 +56,7 @@ Codex uses the curated six-event project subset `SessionStart`, `PreToolUse`, `P
 - **Cursor:** `.cursor-plugin/plugin.json` registers canonical skills and `.mcp.json` using Cursor's native manifest format. Additional native component discovery is explicitly disabled; `scripts/cursor-install.mjs` supplies the existing command and hook adapters. The former standard root manifest was moved to prevent [Codex manifest interception](codex-setup.md#manifest-compatibility).
 - **Pi:** `package.json` `pi` manifest, `pi/extensions/session-orchestrator.ts` bridge, `hooks/hooks-pi.json`, `scripts/pi-install.mjs`.
 - **Portable cross-harness surface (generated, never hand-edited):** root `AGENTS.md` (byte-identical copy of `CLAUDE.md`) and `.agents/skills/<name>/SKILL.md` — mirrors carrying only spec-legal frontmatter plus a pointer body. These two surfaces are written by `scripts/generate-agents-skills.mjs` and drift-checked via its `--check` form inside `scripts/validate-plugin.mjs`. Native plugin manifests are maintained separately, with versions updated by `scripts/release.mjs`.
-- **Scripts:** deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot) plus shared lib under `scripts/lib/*.mjs`, all covered by the vitest suite.
+- **Scripts:** deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot, session-shape) plus shared lib under `scripts/lib/*.mjs` — e.g. `session-shape.mjs` (the one wave-shape resolver for `/session` mode + `--profile`), `maintenance-due-banner.mjs` (the single session-start probe for the whole maintenance loop), `session-end/tail-runner.mjs` (the mechanical apply-half of Phase 3.6.4's Expired-Learnings Sweep), `issue-budget-reconcile.mjs` (close-time recorded-vs-charged cross-check), and `telemetry/pricing.mjs` (per-model USD-per-token rates for cost estimation) — all covered by the vitest suite.
 
 ## `/harness-audit` — Anthropic large-codebase rubric
 
@@ -88,7 +88,7 @@ Both [`maestro-orchestrate`](https://github.com/josstei/maestro-orchestrate) and
 
 | Axis | session-orchestrator | maestro-orchestrate |
 |---|---|---|
-| Execution model | 5 typed waves (Discovery → Impl-Core → Impl-Polish → Quality → Finalization) with inter-wave quality gates and confidence-scored session-reviewer | 4-phase sequential model with parallel subagents |
+| Execution model | typed waves resolved from the session mode by `scripts/session-shape.mjs` (housekeeping 1 · feature 3 · deep 5 · ultradeep 7) with inter-wave quality gates and confidence-scored session-reviewer | 4-phase sequential model with parallel subagents |
 | Runtime coverage | Claude Code + Codex CLI + Cursor IDE + Pi (4) | Gemini CLI + Claude Code + Codex + Qwen Code (4) |
 | VCS integration | GitLab + GitHub (auto-detected); hook events + commands wire to both | Runtime-agnostic; VCS work delegated to user |
 | Cross-session learning | Confidence-scored entries surfaced at session-start; opt-in `/evolve` review | Session archival without explicit learning extraction |

package/docs/cursor-setup.md

@@ -96,5 +96,6 @@ Switch freely between Claude Code, Codex, and Cursor on the same project — all
 - **`/session` missing**: Confirm `.cursor/commands/session.md` exists. Reload Cursor. If this is another project, re-run `node scripts/cursor-install.mjs .`
 - **Rules not loading**: Ensure `.cursor/rules/` exists with `.mdc` files; `000-session-orchestrator.mdc` has `alwaysApply: true`
 - **Hooks not firing**: Confirm `.cursor/hooks.json` exists. Open Cursor Settings → Hooks. Restart Cursor if it was open during install.
+- **No import-probe warning after an edit**: Cursor wires the probe through `postToolUse` and `afterFileEdit`; it still needs an eligible file and ESLint with the project's `no-undef` rule enabled for C1. See [import-probe coverage and ESLint troubleshooting](USER-GUIDE.md#import-probe-warnings-and-missing-eslint).
 - **`'node' not found` in hook PATH**: See README troubleshooting. `hooks/run-node.sh` resolves Homebrew/nvm Node.
 - **State files not created**: Check `.cursor/` is writable

package/docs/events-schema.md

@@ -121,7 +121,10 @@ namespace we own. The validator + regex live in `scripts/lib/events-schema.mjs`
 | `orchestrator.reconcile.completed` | `scripts/lib/reconcile/engine.mjs` (`emitReconcileCompleted`, called from the thin `runReconcile` wrapper; name const `RECONCILE_EVENT`) | one record per `runReconcile` call (#1192) — from the WRAPPER, so all three return points are covered: the empty short-circuit, the normal tail, and the never-throws catch. An inline emit would have missed two of them, including the empty corpus and the error path — the two runs an operator most needs recorded (`.claude/rules/host-resources.md` § HR-105). Same shape as `narrative_mirrored`'s wrapper, and the emit is try/catch-wrapped because `emitEvent` THROWS `EventValidationError`, which would otherwise break `runReconcile`'s never-throws contract. **Payload, all ALWAYS present including as `0`** (each was measured over the whole run, like `mirror_run_completed`'s counters): `trigger` (`skill` | `session-end` | `phase-skip` | `unknown` — written always, so the per-trigger denominator is complete; the two markdown callers depend on a coordinator passing it, hence the honest `unknown` default), `dry_run`, `learnings_total`, `eligible`, `proposals`, `rejected`, `capped`, `already_materialized` (`summary.alreadyMaterialized` — the REAL idempotent-skip count, #484), `written`, `duration_ms`. **Optional, absent-is-not-zero:** `targets` (the caller's effective target list; absent ⇒ none asserted), `store_records_dropped` (`summary.skipped` — absent ⇒ the candidate store was never INSPECTED: under `dryRun`, on the empty short-circuit, on the error path; a `0` there would be a false all-clear), and `aborted: 'engine-error'` + `reason` (clamped to 300 chars) — present ONLY when the never-throws guard fired; their absence means "ran to the end", never "unknown". **`dry_run` is the discriminator, not the event's absence:** the `phase-skip` caller runs dry on EVERY close and is the highest-volume trigger, so consumers filter `dry_run: false` for real runs. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling back to `SO_PROJECT_DIR` — most engine tests pass none, and the fallback would append synthetic records to the real fleet ledger on every `npm test` (#1119, same contract as `express_path.evaluated` and `narrative_mirrored`); a regression test pins it. **Engine identities — the counters are NOT a flat partition, and a live payload reads as inconsistent without them** (source: `scripts/lib/reconcile/engine.mjs:64-83`): `learnings_total === proposals + rejected`, and `capped` + `already_materialized` are DIAGNOSTIC SUB-COUNTS *inside* `rejected`, not siblings of it — each capped or already-materialized learning is also counted as rejected. Within the eligible set: `eligible − proposals − capped === already_materialized`. Worked against a live record: `learnings_total 164 = proposals 10 + rejected 154`, and `eligible 102 − proposals 10 − capped 72 = already_materialized 20` — with `capped 72` and `already_materialized 20` both sitting inside those 154. `already_materialized` is computed BEFORE the volume brake, so a terminal learning never consumes a new learning's quota. `session_id` / `semantic_session_id` / `wave` / `schema_version` are stamped by `emitEvent()` |
 | `orchestrator.evolve.completed` | `scripts/lib/learnings/evolve-telemetry.mjs` (`emitEvolveCompleted`), called from `scripts/sweep-expired-learnings.mjs`'s `--prune --apply` exit path (#1206) for the success form, and from `skills/evolve/SKILL.md` Phase 1 (persistence/no-session-data aborts, skill-prose via `scripts/emit-event.mjs` — no mechanical pipeline call site precedes either gate) for the two abort forms | once per `/evolve analyze` run (default mode; #1200, mechanized #1206) — the success form is now the SAME command that performs the Step 3.5(5) store write, so the event can no longer be forgotten independently of the write it reports on (previously a separate `emit-event.mjs` call in skill prose, one edit away from drifting out of sync). Until #1200 `/evolve` reported completion in prose only — the whole class of `orchestrator.evolve.*` / `orchestrator.dialectic.*` events was **0 records across 164k fleet events** despite every run reporting success. **Payload (success), all FOUR counters ALWAYS present including as `0`** (same contract as `mirror_run_completed`'s counters): `appended` (new learnings written, Step 3.5(4)), `boosted` (existing learnings reinforced, Step 3.5(2)), `pruned` (`$PRUNE.archived` — this SAME call's own returned `archived` total, across every `_archive_reason`), `promoted` (always `0` from THIS call site — promotion to `public` scope is a separate CLI, `npm run share:hw-learnings -- --promote`, never invoked by `/evolve analyze` itself), `duration_ms`. **Optional, absent-is-not-zero:** `skipped` (HR-105 — an array of optional-step slugs, e.g. `skill-evolution-off` \| `vault-mirror-off`, that RAN but were themselves skipped this run; present only when non-empty, and distinct from the `aborted` form below — "ran, a step inside it skipped" is not "did not run at all"). **Payload (abort):** `aborted` (`persistence-disabled` \| `no-session-data`), `reason` (the abort message shown to the user, clamped to 300 chars), `duration_ms`. A `--prune --dry-run` preview run emits NOTHING — a preview never wrote anything, so it must not report a completed run either; `emitEvolveCompleted()` also refuses to emit (stderr WARN, never a throw) without an explicit `repoRoot`, same #1119 fail-closed contract as `emitReconcileCompleted` |
 | `orchestrator.dialectic.completed` | `scripts/lib/learnings/evolve-telemetry.mjs` (`recordDialecticRun`), called from `scripts/dialectic-deriver.mjs`'s `runDialecticDeriver()` for its FOUR return-based outcomes (`empty-input`, `budget-exceeded`, `would-empty-card`, and the dry-run `ok` success form — all four are values the function itself returns, so it records each one mechanically at the exact return point), and from `skills/evolve/SKILL.md` Step 6.4's apply branch / Step 6.5's two THROWN outcomes (`unknown-model` from `validateModel()`, `subagent-crash` from a failed `dispatchAgent`/`Agent()` call — neither is a `runDialecticDeriver()` return value, so only the skill-prose catcher one layer up can record them; apply-mode success similarly needs the post-merge `mergePeerCard()` stats `runDialecticDeriver()` does not have) | once per `/evolve --dialectic` run (#1200, mechanized #1206). Same fleet-zero gap as `evolve.completed` above, now closed the same way: the pipeline function records itself for every outcome it alone can determine, and only the two throw-based aborts (of Step 6.5's five-slug abort enum) plus apply-mode's merge-dependent success remain a skill-prose call site. **Payload (success):** `mode` (`dry-run` \| `apply`), `user_deltas`, `agent_deltas` (dry-run: `countManagedSections()` on the proposed diff text — a pure helper counting `<!-- BEGIN MANAGED: … -->` sentinels, or 1 for a bare full-body replacement with none; apply: `mergePeerCard()`'s own `stats.replaced + stats.appended` per target), `tokens_in`, `tokens_out`, `duration_ms`. **Payload (abort):** `aborted` (`unknown-model` \| `budget-exceeded` \| `would-empty-card` \| `empty-input` \| `subagent-crash`), `duration_ms`. Same #1119 refusal as `emitEvolveCompleted` — `recordDialecticRun()` skips the emit (stderr WARN) without an explicit `repoRoot` |
-| `orchestrator.dialectic.nudge_decided` | `scripts/lib/auto-dialectic.mjs` (`decideAndRecordAutoDialectic`, wrapping `shouldDispatchAutoDialectic` with an additive `emitEvent` call) | once per `decideAndRecordAutoDialectic()` call made with `record !== false` (#1200 part c) — the MECHANICAL sibling of the two skill-prose events above: those two cover a manual `/evolve` run, this one covers the session-end Phase 3.6.7 auto-dialectic NUDGE DECISION itself, which previously computed a trigger every close and recorded nothing. Emitted on ALL FOUR `shouldDispatchAutoDialectic()` return paths (kill-switch, no-new-input, cadence-threshold-met, under-threshold) — try/catch-wrapped, because `emitEvent()` throws `EventValidationError` on a malformed record and a telemetry failure must never change the decision the caller already has in hand. **Payload:** `decided` (boolean, mirrors `trigger` verbatim), `reason`, `cadence`, `sessions_since`, `learnings_since`, plus `session_id`/`semantic_session_id` via `sessionAttribution` (omitted, never fabricated, without a readable `session.lock`). **Deliberately never emitted** when the caller passes `record: false` — the read-only PROBE call site (`scripts/lib/session-end/phase-skip.mjs`'s Phase-3.6.x tail-skip aggregator) keeps calling the un-wrapped `shouldDispatchAutoDialectic()` directly instead, so its own documented side-effect-free contract ("reads only … writes NOTHING") is not broken by this event's write |
+| `orchestrator.dialectic.nudge_decided` | **HISTORICAL — no emission since 2026-09-09.** The producer wrapper (`decideAndRecordAutoDialectic` in `scripts/lib/auto-dialectic.mjs`, #1200 part c) was REMOVED in #1288 after its only caller — session-end Phase 3.6.7 — was retired; the session-start `maintenance-due` probe (`scripts/lib/maintenance-due-banner.mjs`) reads the side-effect-free `shouldDispatchAutoDialectic()` instead. | never — no emitter exists. Row kept so records written before 2026-09-09 stay readable. **Payload (historical):** `decided` (boolean, mirrored `trigger`), `reason`, `cadence`, `sessions_since`, `learnings_since`, plus `session_id`/`semantic_session_id` via `sessionAttribution`. |
+| `orchestrator.learnings.sweep_applied` | `scripts/lib/session-end/tail-runner.mjs` (`runExpiredSweep`, emit in `emitSweepApplied`; name const `SWEEP_EVENT`) | once per APPLIED session-end Phase 3.6.4 Expired-Learnings Sweep — emitted only on the write path, never on a plan-skip, a no-plan call, or the never-throws error branch, so a record's presence is proof the active store was actually rewritten. This event exists because the apply path did not: until #723-B4 was wired here, `sweepExpiredLearnings` had no session-end caller at all (census 2026-09-09 — definition, the `dryRun: true` probe in `phase-skip.mjs`, the standalone CLI, tests), so 0 sweeps were ever applied across three consumer repos while 628 learnings stayed resident. The sweep CLI (`scripts/sweep-expired-learnings.mjs:210`) deliberately emits nothing, and `orchestrator.evolve.completed` covers only the `--prune --apply` sibling — this is the ONLY record of a time-driven sweep. **Payload:** `scanned` (entries read from `learnings.jsonl`), `archived` (entries moved to `learnings-archive.jsonl`; a measured `0` is emitted, since the planner can legitimately RUN on a fail-open probe-error), `source` (always `session-end-3.6.4`, separating this producer from any future one), plus `session_id` / `semantic_session_id` via `sessionAttribution(repoRoot)` — the SAME root the record is pinned to via `emitEvent(..., {repoRoot})`, both keys OMITTED rather than fabricated when no `session.lock` is readable. Emission is best-effort and wrapped in its own catch: a telemetry failure never changes the sweep's return value, and — like the sweep itself — can never block a session close. |
+| `orchestrator.session.shape_resolved` | `scripts/lib/session-shape.mjs` (`resolveAndRecordSessionShape`, emit in `_emitShapeResolved`; name const `SESSION_SHAPE_EVENT`), reachable as an entrypoint via `scripts/session-shape.mjs` | once per session-shape resolution, at the moment the coordinator turns the confirmed mode into an execution plan. Until this event existed the shape lived in PROSE at 27 sites contradicting each other in 8 answers (measured 2026-09-09), so "how many waves did this session actually run" was unanswerable from the ledger — which is why 6 consumer-repo `housekeeping` sessions ran the full 5-wave deep shape unnoticed. **Payload:** `session_type` (always), `total_waves`, `waves_config_honored` (false exactly when the ultradeep profile ignored the Session Config `waves` value — the fixed 7-wave shape of `skills/session-plan/SKILL.md` § Role-to-Wave Mapping; PRD AC-9's `waves < 7` rejection was dropped 2026-09-09), `discovery`, `agent_caps` (one clamped cap per wave, in wave order — `min(tier raw, agents-per-wave)`, `0` on a coordinator-direct wave), `coordinator_direct_waves` (the 1-based `n` of every coordinator-direct wave; `[]` is a MEASURED empty list, not an omission — a housekeeping shape must read `[1]` and a plain deep shape `[]`), `shape_version` (the `SESSION_SHAPE_VERSION` contract the record was produced under). **Optional, absent-is-not-zero:** `session_profile` (OMITTED, never `null`/`''`, when the session has no profile — a written null would read as "measured, no profile"; value set is the closed `VALID_SESSION_PROFILES`), `task_count`, plus `session_id`/`semantic_session_id` via `sessionAttribution(repoRoot)` — the SAME root the record is pinned to, omitted rather than fabricated without a readable `session.lock`. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling through to `SO_PROJECT_DIR` (#941), and `--no-event` skips it entirely so a planning dry-run cannot record a session that never ran. `events.mjs` is imported lazily so a pure-resolver consumer does not gain `platform.mjs` and its module-load filesystem walk-ups |
+| `orchestrator.issue_budget.reconciled` | `scripts/lib/issue-budget-reconcile.mjs` (`reconcileIssueBudget`, emit in `emitIssueBudgetReconciled`; name const `ISSUE_BUDGET_RECONCILED_EVENT`) | once per session close — the cross-check between what the session RECORDED as created (`record.issues_created.length`) and what the issue-budget ledger CHARGED. It exists because `readBudgetState` returns a ZEROED state for a MISSING counter file, so "the hook never ran for a single create" and "the session created nothing" are byte-identical in its return value; measured 2026-09-09 on a real session record with **26** recorded creations, **0** charged and no counter file under either accounting key. **Payload:** `verdict` (always — `match` \| `escaped` \| `no-ledger` \| `stale-record`; `no-ledger` is the absent-ledger case above, `stale-record` the inverse), `recorded`, `charged`, `exempt`, `overflow`, `escaped` (= `max(0, recorded − charged − exempt)`), and `ledgers` — one record per accounting key looked up (`key`: `semantic`\|`raw`, `path` — **repo-RELATIVE** `.orchestrator/runtime/issue-budget/<hash>.json`, never absolute: this payload also travels over the optional Clank webhook with no redaction, and an absolute ledger path names the operator's home directory and the private repo slug; the absolute form stays in the local WARN text only, `found`, `charged`, `exempt`); a fifth verdict `corrupt-ledger` marks a file that exists but has a non-integer `count`. **BOTH keys are read and SUMMED**, because the accounting key is semantic only when `current-session.json` verified the raw id (`resolveIssueBudgetSessionId`) — measured in one consumer repo: 25 of 36 counter files keyed semantic, 11 keyed raw, so reading one key reports a phantom escape for every session that used the other. `found` is measured with `existsSync` BEFORE the read and is the only thing that separates `no-ledger` from a real zero — read an absent `found` as "not measured", never as "no spend". Plus `session_id`/`semantic_session_id` via `sessionAttribution`. **A missing `repoRoot` SKIPS the emit with a stderr WARN** rather than falling through to `SO_PROJECT_DIR` (#941); `events.mjs` is imported lazily so no consumer of the reconcile module gains `platform.mjs`'s module-load filesystem walk-ups |
 
 Non-orchestrator names still present in the stream: `tmux-layout.{invoked,completed,degraded}`
 (tmux-layout skill) and `stagnation_detected`. The latter keeps its legacy bare name

package/docs/instruction-delivery.md

@@ -105,7 +105,7 @@ to remove.
 Note the shape of the mistake, because this repo already has a rule for it: a census
 keyed on the payload (`loadApplicableRules` in `*.mjs`) misses every consumer that
 pins only the channel (`print-applicable-rules.mjs` invoked from prose). See
-`.claude/rules/anti-pattern-a-protocol-migration-census-keyed-on-the-payload-misses-every-consumer-that-pins-only-the-channel-18f3d0a.md`.
+`.claude/rules/measurement-discipline.md`.
 
 ### 1.3 A second delivery source outside this repo's control
 

package/docs/memory-proposal-flow.md

@@ -1,4 +1,4 @@
-<!-- Moved in v4.0.0 from `agents/memory-proposal-collector.md` (audit 2026-09-06 § 5A). It never was a dispatchable agent — it documents a coordinator-direct flow — but Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it. Living under `docs/` removes the registration instead of bounding it. -->
+<!-- Moved in v4.0.0 from `agents/memory-proposal-collector.md` (audit 2026-09-06 § 5A). It never was a dispatchable agent — it documents a coordinator-direct flow — but Claude Code's plugin loader registers every `agents/*.md` by directory convention and the manifest's `agents` key is additive-only, so no manifest entry could exclude it. Living under `docs/` removes the registration instead of bounding it. --> <!-- path-check: historical -->
 
 # Memory Proposal Collector (Reference Documentation)
 
@@ -270,13 +270,13 @@ resolver, which is the correct failure mode.
 | `scripts/lib/memory-proposals/sink.mjs` | `promoteAndClear()` (composes `writeApproved()` + `clearProposalsJsonl()` behind the write-before-clear guard, #797/#828), `archiveRejected()` |
 | `agents/dialectic-deriver.md` | Similar coordinator-invoked pattern (compare: deriver dispatches as a subagent because it only reads files; this flow does not dispatch because it calls AUQ) |
 | `.claude/rules/ask-via-tool.md` §AUQ-004 | Authoritative rule prohibiting AUQ inside subagents |
-| `.claude/STATE.md` Wave History — D3 | Locked decisions: pagination=4, FIFO order, label format, decision tree |
+| `.claude/STATE.md` Wave History — D3 | Locked decisions: pagination=4, FIFO order, label format, decision tree <!-- path-check: example --> |
 
 ---
 
 ## Design Decisions (Locked — D3, Wave 1)
 
-These decisions are recorded in `.claude/STATE.md` Wave History line D3 and are not open
+These decisions are recorded in `.claude/STATE.md` Wave History line D3 and are not open <!-- path-check: example -->
 for revision within this session:
 
 - **Batch size**: 4 proposals per AUQ call (not 3, not 5).

package/docs/migration-v4.md

@@ -45,7 +45,7 @@ change list: [CHANGELOG.md](../CHANGELOG.md).
 | `node scripts/fleet-instruction-scan.mjs`, `lifecycle-sim-v6.mjs`, `upload-social-preview.mjs` | **removed** | No replacement. | <!-- path-check: historical -->
 | dispatching `AGENTS.md` as an agent | **removed as a dispatch target** | It was never an agent — it is the authoring spec, now [`docs/agent-authoring.md`](./agent-authoring.md). Read it; do not dispatch it. |
 | dispatching `memory-proposal-collector` as an agent | **removed as a dispatch target** | Now [`docs/memory-proposal-flow.md`](./memory-proposal-flow.md). |
-| citing `skills/_shared/model-selection.md` | **removed** | No replacement; it had zero consumers. |
+| citing `skills/_shared/model-selection.md` | **removed** | No replacement; it had zero consumers. <!-- path-check: historical --> |
 | Session Config `autopilot.bg-isolation` | **removed** | No replacement — delete the `autopilot:` block from your `CLAUDE.md`/`AGENTS.md`, it was the block's only field and is now inert (`scripts/parse-config.mjs` never parsed it). |
 | Session Config `webhooks.<kind>.url` | **removed** (pre-4.0.0, `ce6a28aa`) | No replacement — `scripts/lib/webhook-url.mjs` had zero callers. The still-live Clank Event Bus webhook (`CLANK_EVENT_SECRET`/`CLANK_EVENT_URL`) is unrelated and unaffected. | <!-- path-check: historical -->
 
@@ -221,7 +221,7 @@ node scripts/validate-plugin.mjs
 
 **Nothing breaks at runtime.** A citation in a consumer repo's `CLAUDE.md` (or `AGENTS.md`) to
 `daily`, `skill-creator`, `ubiquitous-language`, `contract-version-bump`, `journey-audit`,
-`domain-model` or `skills/_shared/model-selection.md` is prose. No loader resolves it, no hook
+`domain-model` or `skills/_shared/model-selection.md` is prose. No loader resolves it, no hook <!-- path-check: historical -->
 reads it, and the session starts normally.
 
 **But `claude-md-drift-check` may flag it** as a dangling citation, and if you run it with