session-orchestrator 5.6.0 → 5.8.0

package/skills/session-start/SKILL.md

@@ -326,7 +326,7 @@ Operator-selected issues (from Phase 6) are appended AFTER this loop, not interl
 
 ## Phase 7.1: Issue Premise Verification (#730/H3)
 
-> Skip for `housekeeping` sessions (Phase 7 already skips deep research there).
+> Housekeeping too (#1521).
 > Runs on the shortlisted candidate issues from Phase 6 Pattern Recognition
 > (cap: 8 issues — cost control; prioritize the issues most likely to enter scope).
 
@@ -354,7 +354,7 @@ Invokes `buildLiveSignals` (single SSOT for the signals shape) then `selectMode(
 
 > Skip silently when `persistence: false` (no ledger for the event). Runs BEFORE the first writing action; everything not stated here is in `skills/_shared/fleet-protocol.md`.
 
-Build the check-in JSON (fields per the reference; `session` from `.orchestrator/current-session.json`, `modus` = session type, `kandidaten` = the issue numbers you intend to claim) and pipe it into `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-checkin.mjs"` — it validates, stores `checkin/<session_id>.json` (0600) under `~/.config/navigator/` and emits `orchestrator.fleet.checkin`. Its stdout carries `navigator_state` and `navigator_adresse` (the lease's validated `adresse`, else `null`): on `active`, and only when `navigator_adresse` is non-null and reachable via `ListAgents`, send ONE hint to exactly that name, naming the file path — never expect or wait for a reply (CSM-004). Then read `auflagen/<session_id>.json`; if it is still absent at the stdout's `fallback_due_at`, the reference's Standard-Auflagen apply (the CLI computes that deadline: `zeit` plus `CHECKIN_FALLBACK_MIN` while a navigator is active, `zeit` itself — immediately — otherwise). Reading work and edits in the own worktree continue meanwhile.
+Build the check-in JSON (fields per the reference; `session` from `.orchestrator/current-session.json`, `modus` = session type, `kandidaten` = the issue numbers you intend to claim) and pipe it into `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-checkin.mjs"` — it validates, stores `checkin/<session_id>.json` (0600) under `~/.config/navigator/` and emits `orchestrator.fleet.checkin`. Its stdout carries `navigator_state` and `navigator_adresse` (the lease's validated `adresse`, else `null`): on `active`, and only when `navigator_adresse` is non-null and reachable via `ListAgents`, send ONE hint to exactly that name, naming the file path — never expect or wait for a reply (CSM-004). Then read `auflagen/<session_id>.json` via `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-auflagen.mjs" <session_id>` (only a file whose `repo` resolves to this repo's git common dir is `accepted`; a `rejected` one counts as absent); if it is still absent at the stdout's `fallback_due_at`, the reference's Standard-Auflagen apply (the CLI computes that deadline: `zeit` plus `CHECKIN_FALLBACK_MIN` while a navigator is active, `zeit` itself — immediately — otherwise). Reading work and edits in the own worktree continue meanwhile.
 
 ## Phase 8: Structured Presentation & Q&A
 

package/skills/session-start/phase-7-1-premise-check.md

@@ -18,6 +18,7 @@ For each claim, run exactly ONE Grep or Read against the actual codebase (or
 transcript discipline as `.claude/rules/parallel-sessions.md` § PSA-006.
 Budget: this phase is a spot-check, not a deep audit. If one grep cannot
 ground the claim, mark UNVERIFIED and move on — do not rabbit-hole.
+Per issue, also run `git log --grep='#<N>'`: fixes often land without closing the issue.
 
 ## Verdicts
 
@@ -44,4 +45,4 @@ decomposing) without re-running the greps.
 
 - Re-verifying every sentence of every issue — cap 3 claims/issue, 8 issues.
 - Treating UNVERIFIED as a blocker — it is informational only.
-- Running this for housekeeping sessions — predefined tasks carry no premise risk worth the latency.
+- Skipping it in housekeeping — items go stale there too (#1521: 4 of 7 were fixed).

package/skills/session-start/references/operations-contract.md

@@ -50,7 +50,10 @@ workflow with its own verified scope, tests and review; it does not turn this en
 into a fabricated wave session.
 Before the first writing action, write the fleet check-in and read the fleet's constraints —
 the same step as session-start Phase 7.6 (`scripts/fleet-checkin.mjs`; fields and the
-Standard-Auflagen in `skills/_shared/fleet-protocol.md`). If no `auflagen/` file has appeared by
+Standard-Auflagen in `skills/_shared/fleet-protocol.md`). Read the Auflagen with
+`node scripts/fleet-auflagen.mjs <session_id>`, never the file directly: only a file whose `repo`
+resolves to this repo's git common dir is `accepted`, and a `rejected` one counts as absent
+(`skills/_shared/fleet-protocol.md` § `auflagen/<session_id>.json`). If no `auflagen/` file has appeared by
 the `fallback_due_at` on the CLI's stdout, the Standard-Auflagen apply: the CLI sets it
 `CHECKIN_FALLBACK_MIN` after `zeit` while a navigator is active, and to `zeit` itself —
 immediately — otherwise. A hint to the navigator is optional and never awaited.

package/skills/tmux-layout/SKILL.md

@@ -6,6 +6,7 @@ description: >
   layout. Read-only side-channel observability — the coordinator chat stays in the operator's original
   terminal. Trigger phrases: "tmux layout", "split panes for ci watch", "visualize session side-channels",
   "show me state-md tail and ci".
+user-invocable: true
 model: inherit
 color: cyan
 tools: Read, Bash, Grep, Glob

package/skills/vault-mirror/SKILL.md

@@ -10,6 +10,7 @@ description: >
   notes to vault", "vault-mirror failed at session close". <example>Context: session-end is finalizing,
   vault-integration.mode is "warn". user: "/close" assistant: "Running vault-mirror to write
   50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped."</example>
+user-invocable: false
 model: haiku
 ---
 
@@ -59,7 +60,10 @@ One JSON line is written to stdout for each non-empty JSONL entry processed. Exi
 | `skipped-collision-resolved` | A file at the target path has the generator marker but a different `id`; a disambiguated slug was used instead. |
 | `skipped-foreign-owner` | A generator note at the target path was rendered from another record (#1503), and this write must not replace it. **Sessions:** its `source-record` differs from this write and occurs nowhere in this `--source` ledger (`reason: "source-record mismatch"`), or its `id` names a different session (`reason: "id mismatch"`). **Learnings:** only for the disambiguated `<slug>-<uuid8>.md` file — a mismatch on the main `<slug>.md` is routed to disambiguation instead (`skipped-collision-resolved`, see Idempotency rule 6). One `SKIP foreign owner` line goes to stderr; `--force` does not bypass it. A leak in the foreign note is masked in place — owner, content and `source-record` kept — and the line carries `healed_leak: true`. A note without `source-record` (written before #1503) stays writable. |
 | `skipped-invalid` | Entry is missing one or more required fields; entry skipped, processing continues. |
-| `skipped-quality-low` | Entry failed the quality gate (PRD F1.2): learning `confidence` below `vault-mirror.quality.min-confidence` (CLI: `--quality-min-confidence`, default `0.5`), or session rendered-narrative length below `vault-mirror.quality.min-narrative-chars` (CLI: `--quality-min-narrative-chars`, default `400`). The emitted JSON line includes a `reason` field describing the violated threshold and `path: null` (no file was created). The quality gate runs **before** `--force`; `--force` does not bypass it. |
+| `skipped-quality-low` | Learning `confidence` below `vault-mirror.quality.min-confidence` (CLI: `--quality-min-confidence`, default `0.5`), or a metrics-only session whose note ALREADY exists (left untouched; the pruner decides). Carries `reason` and `path: null`. Runs **before** `--force`; `--force` does not bypass it. |
+| `skipped-metrics-only` | Session record below the narrative gate (#1513, see Retention): no note; one row was added to the month rollup `50-sessions/<repo>/_rollup-YYYY-MM.md` (`path`). An unchanged rollup is `skipped-noop`. |
+| `skipped-expired` | Learning past its `expires_at` with no note yet (#1513): nothing is created. |
+| `skipped-duplicate-insight` | A mirror-owned, non-archived note in the same namespace (or the flat layout) already carries the same normalised insight (#1513); `path` names it. Only consulted where a NEW file would be created. |
 
 ### Output line shape
 
@@ -92,10 +96,32 @@ The numeric prefix (`50-sessions/`, `40-learnings/`) follows the vault folder or
 
 **Path contract note:** Issue #187 shipped the flat numeric-prefix layout (deferring the per-`<repo>` subfolder it sketched). Issue #660 adds that per-repo subfolder for write-isolation (above) while keeping the numeric-prefix ordering. If you need a different layout, file a new issue — do NOT silently change the script.
 
-**Learning-coverage self-healing after a store recovery (#740).** vault-mirror always mirrors the CURRENT `learnings.jsonl` store contents at run time — if an earlier session's store was truncated or corrupted and later recovered (e.g. from a `.bak`), the resulting transient coverage gap in the vault is closed automatically by the next mirror run, with no manual backfill required. Note also that `vault-mirror.quality.min-narrative-chars` (see Failure Modes → `skipped-quality-low` below) gates **sessions only** — `processLearning` never applies a narrative-length filter, so a short learning `insight` is never skipped for length; only the confidence gate (`vault-integration.quality.min-confidence`) applies to learnings.
+**Learning-coverage self-healing after a store recovery (#740).** vault-mirror always mirrors the CURRENT `learnings.jsonl` store contents at run time — if an earlier session's store was truncated or corrupted and later recovered (e.g. from a `.bak`), the resulting transient coverage gap in the vault is closed automatically by the next mirror run, with no manual backfill required. Note also that `vault-mirror.quality.min-narrative-chars` (see Retention below) gates **sessions only** — `processLearning` never applies a narrative-length filter, so a short learning `insight` is never skipped for length; only the confidence gate (`vault-integration.quality.min-confidence`) applies to learnings.
 
 **Host-local pseudonym mapping (Epic #725 D5).** Without a map, EVERY owner-leaky repo namespace collapses to a single `redacted-repo/` subdir — which breaks the #660 write-isolation (N private repos share one directory → id/slug collisions) and destroys cross-repo attribution. A host-local **pseudonym map** fixes this: each real repo slug is assigned a stable, non-leaky pseudonym, so the vault gets `40-learnings/<pseudonym>/` (and matching `source-repo` frontmatter, via W2's attribution threading) instead of everyone landing in `redacted-repo/`. The map is a JSON object `{ "real-slug": "pseudonym-slug", … }` at a host-local path referenced by `owner.yaml` → `paths.namespace-map-path` (env `SO_NAMESPACE_MAP` overrides; precedence env > owner.yaml > unset). `resolveRepoNamespace()` consults the map ONLY at the redaction site (i.e. only when a repo would otherwise be redacted), looking up both the sanitised segment and the raw identifier; a hit returns the pseudonym and skips redaction, so clean/public repos never touch the map (or its lazy owner.yaml read). **Privacy guarantee:** the map file lives OUTSIDE every repo (alongside `owner.yaml` under `~/.config/session-orchestrator/`) and is never committed — only the pseudonyms reach the vault, the real names stay host-local. Each pseudonym is validated (must be a kebab slug AND must not itself be owner-leaky); invalid or leaky pseudonyms are dropped with a WARN. **Fallback:** an absent, unreadable, or malformed map — and any UNMAPPED owner-leaky repo — still redacts to `redacted-repo`, identical to pre-#725 behaviour. Implementation: `scripts/lib/vault-mirror/pseudonym-map.mjs` (`loadPseudonymMap`) + `namespace.mjs`.
 
+## Retention (#1513)
+
+The mirror used to write every record and never mark or remove anything; by 2026-10-03 the two zones were 78 % of the Meta-Vault, 91 % of the session notes carried nothing beyond git, and 2.826 expired learnings still read `status: draft`. The rules live in ONE module, `scripts/lib/vault-mirror/retention.mjs`, shared by the mirror and the pruner:
+
+1. **Narrative gate (sessions).** A record gets its own note only when its free-text fields `notes`, `narrative`, `summary` (strings or string arrays, whitespace collapsed) reach `vault-mirror.quality.min-narrative-chars` (default `400`; `0` disables). Wave/agent/file tables are not narrative. All three renderer generations print exactly these fields into `## Notes` (`sessionNarrativeText`), which is what the pruner measures; an existing note with less free text than its record is rewritten once (heal), and when a ledger holds the same `session_id` twice the winning record inherits the narrative fields it lacks from the line it supersedes. Below the gate the record becomes one row (date, session id, type, waves, agents, files) in `50-sessions/<repo>/_rollup-YYYY-MM.md`, keyed by session id, sorted and rendered deterministically — re-runs are no-ops. Calibration (Jev audit, 3.003 notes): free text under 300 chars held 1 of 2.802 notes scored >= 2.5 "beyond git"; from 800 chars on, 18 of 55.
+2. **Legacy slug (learnings).** The pre-#725 slug (subject without the whitespace → hyphen pre-map) is recognised: when only that variant of THIS record's note exists, it is updated in place instead of a canonical twin being created. New notes always get the canonical slug.
+3. **Write-time dedupe (learnings).** Before a new file is created, the normalised `## Insight` (case, whitespace, typographic quotes/dashes, trailing punctuation ignored) is looked up among the mirror-owned, non-archived notes of the namespace, and among flat notes whose `source-repo` is this namespace → `skipped-duplicate-insight`. Placeholder insights (`(legacy record …`, `(none recorded)`, …) and keys under 40 characters never count as the same learning.
+5. **Namespace alias.** Folders equal modulo hyphens are one namespace; the one with more hyphens is canonical (`gotzendorferv2` → `gotzendorfer-v2`). The mirror resolves this before every write and for its auto-commit scope; the pruner uses the same function (`canonicalAmong`).
+4. **Expiry and leaving the store (learnings).** An expired record (`expires_at` before today) is never created; its existing note is re-rendered with `status: archived` + `archived-reason: expired`. After the live pass, `--kind learning` also reads the sibling `learnings-archive.jsonl` and marks each archived record's existing note `archived` with `archived-reason: expired` (`_archive_reason: expired`) or `superseded` (every other reason) — never creating one, never touching a note a live record still owns. `archived` + `archived-reason` instead of `status: expired|superseded` on purpose: the vault frontmatter status enum (SSOT projects-baseline) has no such values, and a status outside it fails vault-sync in any vault that validates the mirror zones.
+
+**Bestand: `scripts/vault-mirror-prune.mjs`.** Applies the same rules to notes written before them. Dry run is the default and writes nothing; `--manifest PATH` writes the JSON manifest (`path`, `reason`, `action`, `target`, `keep`, `rollup`). Expiry is decided first, so an expired or archived copy is never the one kept. Reasons: `duplicate` (canonical copy among the LIVE copies: own namespace folder > any namespace folder > `status: verified` > later `expires` > `source-record` > post-#725 slug > newer `updated`), `superseded` (same slug modulo hyphens, different insight; newest kept), `expired`, `metrics-only-session` (its rollup row is written first), `namespace-alias` (a folder that equals another modulo hyphens and has fewer of them, or `--alias FROM=TO`), `flat-relocate` (flat note whose `source-repo` names its namespace). `--apply` writes the rollups, then moves archived notes to `90-archive/mirror/<zone>/<same path>` with `status: archived` + `archived-reason`, then renames the relocated ones — never deletes, never touches a note without the `_generator` marker, re-checks ownership right before each move, refuses any source or target that resolves outside the vault (realpath of the nearest existing ancestor), writes a note whose archive target is occupied by OTHER content beside it as `<name>.dup-<hash8>.md` (listed under `applied.suffixed` in the manifest), and is idempotent (a second run plans nothing). `90-archive/` is outside vault-sync's checked zones but inside its link-target register, so wiki-links into archived notes keep resolving; the mirror's source-session index walks `90-archive/mirror/50-sessions/` for the same reason, and `backfill-learnings-from-vault.mjs` falls back to `90-archive/mirror/40-learnings/`.
+
+**Order (runbook).** (1) Update the plugin on EVERY host that runs session-end against this vault (M4 and M5): an old mirror re-creates every note the pruner moved. (2) Run one mirror pass per repo ledger so session notes written before the narrative fields were rendered are healed — otherwise the pruner reads them as metrics-only. (3) Dry run, read the manifest. (4) `--apply`, then commit the vault.
+
+```bash
+# (2) per repo, from its canonical checkout
+node scripts/vault-mirror.mjs --vault-dir <vault> --source <repo>/.orchestrator/metrics/sessions.jsonl --kind session --repo-root <repo> --no-commit
+# (3) + (4)
+node scripts/vault-mirror-prune.mjs --vault-dir <vault> --manifest /tmp/vault-prune-manifest.json   # plan
+node scripts/vault-mirror-prune.mjs --vault-dir <vault> --apply --manifest /tmp/vault-prune-applied.json
+```
+
 ## Idempotency
 
 vault-mirror is safe to run multiple times against the same JSONL source:

package/skills/vault-sync/SKILL.md

@@ -10,6 +10,7 @@ description: >
   vault-sync". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true,
   vault-sync.mode="hard". user: "/close" assistant: "vault-sync found 2 frontmatter errors in
   vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close."</example>
+user-invocable: false
 model: haiku
 ---
 
@@ -28,9 +29,8 @@ Phase 1 ships a self-contained validator that reads every `.md` file under `VAUL
 ### Files
 
 - `validator.mjs` — Node.js ESM validator. Uses `zod` + `yaml` npm packages. Reads `VAULT_DIR` (env or default cwd), walks the tree, skipping `node_modules/`, `.git/`, `.obsidian/`. `90-archive/` is walked but never *checked* (#833): archived notes stay in the link-target register — so an inbound `[[wiki-link]]` to an archived note resolves instead of dangling — while their frontmatter is skipped and counted in `archived_skipped_count`. For each `.md`: parses frontmatter, validates against the inline Zod schema, extracts `[[wiki-links]]`, verifies each target resolves. Emits JSON report on stdout.
-- `validator.sh` — Thin POSIX wrapper. Resolves `VAULT_DIR` from arg 1 or env, self-bootstraps deps via `pnpm install --silent` on first run, execs the Node validator. Session-end and other callers use this entry point.
-- `package.json` — Declares `zod` (`^3.24.0`, matching projects-baseline) and `yaml` (`^2.5.0`) as deps. `pnpm-lock.yaml` is committed; `node_modules/` is gitignored.
-- `tests/validator.bats` — 16 BATS cases covering clean vaults, broken frontmatter, missing required fields, dangling links, no-vault skipping, README-style files, nested directories, and archive/obsidian exclusion.
+- `validator.sh` — Thin POSIX wrapper. Resolves `VAULT_DIR` from arg 1 or env, checks that `zod` and `yaml` resolve from the skill directory, execs the Node validator. It never installs anything: unresolvable deps exit 2 with `"reason":"setup-required"` and the one setup command, `npm ci` in the plugin root (#1070). Session-end and other callers use this entry point.
+- `package.json` — Declares `zod` (`^3.24.0`, matching projects-baseline) and `yaml` (`^2.5.0`) as deps. No lockfile is committed (`skills/vault-sync/package-lock.json` is gitignored at the repo root); `node_modules/` is gitignored.
 - `tests/fixtures/` — Seven fixture vaults matching each test scenario.
 
 ### Schema source
@@ -41,9 +41,9 @@ The inline Zod schema is vendored from the canonical source at `projects-baselin
 
 `skills/vault-sync/package.json` pins `yaml ^2.5.0` / `zod ^3.24.0` — intentionally NOT the root's `yaml ^2.9.0` / `zod ^3.25.76`. This is not drift to fix:
 
-- Both CI hosts install this sub-package on its own, independent of the root install (`.gitlab-ci.yml:121` and `.github/workflows/test.yml:93`, both: `(cd skills/vault-sync && npm install --no-audit --no-fund)`).
-- The root `package.json` declares no `workspaces`, so `npm ci` at the root never touches this folder's deps; `skills/vault-sync/node_modules/` is the only place `zod` resolves for this skill (`scripts/lib/vault-archive.mjs:19-21`).
-- The `zod ^3.24.0` pin deliberately tracks the projects-baseline version, not this repo's own (`scripts/release.mjs:488`).
+- Nothing installs this sub-package. Neither CI host runs a nested install any more — both run only the root `npm ci`, and `.husky/pre-push` links only the root `node_modules/` into its tracked-tree clone. The nested install was dropped on 2026-10-05: it pulled unlocked `zod`/`yaml` versions (this folder's lockfile is gitignored) that the root `npm audit` never saw, and the vault-sync test files ran 125 passed / 0 failed without it.
+- The root `package.json` declares no `workspaces`, so `npm ci` at the root never touches this folder's deps. Node resolves `zod`/`yaml` from this folder via the root's own `dependencies` (`yaml ^2.9.0`, `zod ^3.25.76`) — measured 2026-10-05 via `import.meta.resolve('zod')` from this folder → `<root>/node_modules/zod`. That is the runtime path in CI, in every worktree and for every end user, so the root dependencies must stay. A stale local `skills/vault-sync/node_modules/` from an older manual install would still win resolution; delete it if versions disagree.
+- The `zod ^3.24.0` pin deliberately tracks the projects-baseline version, not this repo's own (`scripts/release.mjs:622`).
 
 The root's dependency versions are NOT the SSOT for this folder — do not "fix" this pin to match the root.
 

package/skills/vault-sync/validator.sh

@@ -8,13 +8,18 @@
 # Behavior:
 #   - Resolves VAULT_DIR from arg 1 or env.
 #   - Ensures `node` is available.
-#   - Auto-installs deps on first run (pnpm install --silent) if node_modules missing.
+#   - Checks that `zod` and `yaml` resolve from this directory. They are
+#     runtime dependencies of the ROOT package (package.json `dependencies`),
+#     so Node resolves them from the plugin root's node_modules/. Missing →
+#     exit 2 with status `setup-required` and the one npm-canonical setup
+#     command. Never installs anything itself (#1070 AC3/AC6).
 #   - Execs validator.mjs; propagates exit code.
 #
 # Exit codes (mirror validator.mjs):
 #   0 — vault valid (or skipped: no vault)
 #   1 — validation errors
-#   2 — infrastructure error (missing node / pnpm, missing validator.mjs)
+#   2 — infrastructure error (missing node, missing validator.mjs,
+#       dependencies not installed → status `setup-required`)
 #
 # Output: JSON report on stdout (machine-readable).
 
@@ -36,18 +41,32 @@ if ! command -v node >/dev/null 2>&1; then
   exit 2
 fi
 
+# Emit the infra-error envelope via node so a path containing a quote or a
+# backslash still yields valid JSON (paths travel through env, never through
+# the JSON text). Args: reason [detail] [setup].
+infra_error() {
+  SO_VS_REASON="$1" SO_VS_DETAIL="${2:-}" SO_VS_SETUP="${3:-}" node -e '
+    const o = { status: "infra-error", reason: process.env.SO_VS_REASON };
+    if (process.env.SO_VS_DETAIL) o.detail = process.env.SO_VS_DETAIL;
+    if (process.env.SO_VS_SETUP) o.setup = process.env.SO_VS_SETUP;
+    console.error(JSON.stringify(o));' >&2
+}
+
 if [[ ! -f "$VALIDATOR_MJS" ]]; then
-  echo "{\"status\":\"infra-error\",\"reason\":\"validator.mjs not found at $VALIDATOR_MJS\"}" >&2
+  infra_error "validator.mjs not found at $VALIDATOR_MJS"
   exit 2
 fi
 
-# ── Self-bootstrap node_modules on first run ───────────────────────────────
-if [[ ! -d "$SCRIPT_DIR/node_modules" ]]; then
-  if ! command -v pnpm >/dev/null 2>&1; then
-    echo '{"status":"infra-error","reason":"pnpm not found; cannot bootstrap dependencies"}' >&2
-    exit 2
-  fi
-  (cd "$SCRIPT_DIR" && pnpm install --silent) >&2
+# ── Dependency readiness (no install, no foreign package manager) ─────────
+# `zod`/`yaml` come from the root package's `dependencies`; a nested
+# skills/vault-sync/node_modules/ is NOT required. Probe resolution from this
+# directory instead of testing for a particular node_modules folder, so an npm
+# install (deps hoisted above the package) and a plugin checkout both pass.
+if ! (cd "$SCRIPT_DIR" && node --input-type=module \
+      -e "import.meta.resolve('zod'); import.meta.resolve('yaml');") >/dev/null 2>&1; then
+  PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+  infra_error "setup-required" "zod/yaml not resolvable from $SCRIPT_DIR" "cd $(printf %q "$PLUGIN_ROOT") && npm ci"
+  exit 2
 fi
 
 # ── Execute validator ──────────────────────────────────────────────────────

package/skills/wave-executor/references/wave-loop-scope-manifest.md

@@ -87,7 +87,7 @@ Before each wave dispatch:
 
    The per-agent path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and File-Scope Injection (#1020) consume. Never write a `$TMPDIR` copy: it degrades to a signal-free allow when an injector cannot find the addressable wave-keyed file. The coordinator's record is materialized as `coordinator.json` and included in the aggregate, so its direct edits are covered by the two checks below.
 
-   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs before the union exists, so writing these files reports `bash-write-verify: N file(s) changed by a Bash call OUTSIDE the wave's allowedPaths` naming `filescopes/wave-<N>/*.json`. Expected once per wave rollover at this step; it is information, not a scope violation. Never widen `allowedPaths` to silence it — that would grant agents write access to the deconfliction record itself.
+   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs before the union exists, so `hooks/post-bash-write-verify.mjs` drops these files from its out-of-scope report the same way it drops `wave-scope.json` — keyed on the active manifest's state dir (`isScopeDeclarationPath`, #1027 Pkt 5) — and writing them reports nothing. Never widen `allowedPaths` instead: that would grant agents write access to the deconfliction record itself.
 
    **3.1a — a peer session's declared paths are their OWN record (#1195).** When a reachable peer session runs in this same checkout and has sent a Peer-Scope-Union request (`skills/_shared/parallel-aware-auq.md` § Peer-Scope-Union), carry its complete path list into the record array as exactly ONE record `{"id":"peer-session-<id>","files":[…]}` — `<id>` being the peer's semantic session id. Never merge peer paths into an agent's record: an agent record is a territory ONE agent may write, and a peer's paths are a territory NO agent of this wave may write. Keeping them separate is also what makes the disjointness check meaningful — a peer path colliding with an agent's scope is a real collision that must surface at 3.2, not be laundered by living in that agent's own record. Mechanically, a peer record takes part in `--assert-disjoint` and is EXCLUDED from `--union` (`unionFileScopes`, `scripts/lib/scope-gate.mjs`), so `allowedPaths` never grants a peer's paths to this wave's agents — which is precisely what keeps them a territory no agent may write. It also gets NO per-agent shape-(a) file: `materialize-wave-scope.mjs` writes peer records into the aggregate only, because `$AGENT_FILESCOPE_JSON` is addressed by an agent id at dispatch and no agent is dispatched for a peer session. `hooks/post-bash-write-verify.mjs` reads the same aggregate sidecar and reports a change under a `peer-session-*` record as a peer write instead of a violation — reachable only BECAUSE the union excludes it (the hook sees a path only while it is outside `allowedPaths`).
 
@@ -121,9 +121,11 @@ Before each wave dispatch:
 
    > **Fail-closed:** an ABSENT or unrecognised `role` does **not** expand. Omitting it fails loudly (an agent's write to its own test is blocked, recoverable by one re-union); the opposite default would silently hand a Quality phase-1 simplification agent write access to the suite. `{ enabled: false }` is the unconditional opt-out and `{ enabled: true }` the explicit opt-in — both override the role.
 
-   **It emits a GLOB, never a computed concrete path.** Resolve via the production file's basename, e.g. `foo.mjs` → `tests/**/foo*.test.mjs` — the same form `§ 4. Test-consolidation branch` already uses, stated once. Measured over all **439** tracked production `.mjs` in THIS repo (production = `scripts/**` + `hooks/**` + `skills/**`; tests = a top-level `tests/**` mirror with the `scripts/` prefix dropped): a same-basename test exists somewhere under `tests/` for **375/439 (85.4%)**, whereas a naive 1:1 mirror path resolves for only **272/439 (62.0%)**. So the glob is right ~85% of the time and *harmless* when wrong — it grants write access to a path that may not exist; a computed concrete path would be wrong ~38% of the time **and still deny the real test**. The ~15% residual is real, mostly semantic naming (`scripts/lib/learnings/*.mjs` → `tests/unit/learnings.test.mjs`): when an agent's test sibling does not match the glob, add it by hand to that agent's "Files:" scope in the session plan. This is an 85% default, not a guarantee.
+   **It emits a GLOB, never a computed concrete path.** Resolve via the production file's basename, e.g. `foo.mjs` → `tests/**/foo*.test.mjs` — the same form `§ 4. Test-consolidation branch` already uses, stated once. The measurement is `scripts/lib/test-sibling-coverage.mjs`, not a count restated here — run `node scripts/lib/test-sibling-coverage.mjs --json` and cite its envelope (it carries its own definition, `ref` and the uncovered list). It counts production files by negation (every tracked file a sibling-rule source matches that is not test-side) and reports three figures: **glob** (the scope gate's own `testSiblingsFor()` + `pathMatchesPattern()`), **exact** (a `tests/**/<stem>.test.mjs` exists), **mirror** (the naive 1:1 path `tests/<path minus scripts/>.test.mjs`). Measured at `HEAD=af58a173`, 2026-10-03, index clean, over the script's population (tracked `.mjs` matched by the sibling-rule source minus every test-side path, 571 files): glob **511/571 (89.5 %)**, exact **491/571 (86.0 %)**, mirror **353/571 (61.8 %)**. So the glob is right ~9 times in 10 and *harmless* when wrong — it grants write access to a path that may not exist; a computed mirror path would be wrong ~38 % of the time **and still deny the real test**. The residual is real, mostly semantic naming (`scripts/lib/learnings/*.mjs` → `tests/unit/learnings.test.mjs`) and untested root config files: when an agent's test sibling does not match the glob, add it by hand to that agent's "Files:" scope in the session plan. This is a default, not a guarantee.
 
-   > Measured at `HEAD=730ee9d`, 2026-08-03, clean-tree, via `git ls-files | grep -E '^(scripts|hooks|skills)/.*\.mjs$'` for the denominator, matched against `git ls-files | grep -E '^tests/.*\.test\.mjs$'` by basename (85.4% figure) and by mirrored path (62.0% figure). Re-measure before citing these downstream — a count re-briefed later is a claim about the past (`.claude/rules/parallel-sessions.md` § PSA-006).
+   > Re-measure before citing these figures downstream — a count re-briefed later is a claim about the past (`.claude/rules/parallel-sessions.md` § PSA-006). The previous hand count (`730ee9d`, 2026-08-03: 375 / 272 of 439, denominator `scripts/` + `hooks/` + `skills/` only) is superseded by the script (#1030 P3).
+
+   > **Over-grant ceiling (#1030):** the glob is a basename *prefix* (`tests/**/{basename}*.test.mjs`, `scripts/lib/scope-gate.mjs:312`), so a production file sharing a basename with another receives the other's test siblings — and a stem that prefixes another (`cli` → `cli-flags`) does too, so the figure below is a lower bound. Measured at `HEAD=0e0c4b08`, 2026-10-03: `git ls-files '*.mjs' | grep -v '^tests/' | xargs -n1 basename | sort | uniq -d | wc -l` → **34** colliding basenames, covering **80 of 572** production `.mjs` (**14.0 %**; population = tracked `.mjs` outside `tests/` at `0e0c4b08`, which still counts the one co-located test `skills/vault-sync/tests/schema-drift.test.mjs` — the whole gap to the script's 571, the same recipe also gives 572 at `af58a173`; files via `… | sort | uniq -D | wc -l`, denominator via `git ls-files '*.mjs' | grep -v '^tests/' | wc -l`; top: `schema.mjs` 8×). The error direction is the harmless one — a too-wide grant, never a denied write. **Revisit-Trigger:** a plan author disables the sibling expansion to dodge a false-positive collision between two same-named production files — then scope the glob by directory, but NOT by a raw `{dir}`: `renderSiblingTemplate` fills it with `scripts/lib`, while the test tree drops the `scripts/` prefix (`tests/lib/`), so a raw `{dir}` would deny real test writes; it needs a source→test prefix mapping first.
 
    **The sibling rule is repo-configurable, not a hardcoded layout.** THIS repo has zero `__tests__/` directories and no co-located tests; consumer-repo shapes (`<file>.test.*` beside the source, `<dir>/__tests__/**`, `supabase/migrations/** → supabase/tests/**`) are configured per repo and do not apply here.
 

package/skills/write-executable-plan/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: write-executable-plan
 description: Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects "TBD", "TODO", "add error handling", "similar to Task N".
+user-invocable: true
 model: inherit
 color: green
 tools: Read, Grep, Glob, Bash, Write