session-orchestrator 3.20.0 → 3.21.0

package/skills/session-end/session-metrics-write.md

@@ -19,19 +19,13 @@
 
 1. Ensure `.orchestrator/metrics/` directory exists: `mkdir -p .orchestrator/metrics`
 
-1-pre. **`memory_cleanup_at` always-stamp (#699)** — Before emitting the record, if `/memory-cleanup` ran THIS session in any mode (dry-run, apply-pending, OR healthy no-op), stamp `memory_cleanup_at = completed_at` on the record using `stampMemoryCleanup()` from `scripts/lib/memory-cleanup-stamp.mjs`:
+1-pre. **`memory_cleanup_at` is DERIVED, not remembered (#699 + 2026-08-17 follow-up)** — there is **no coordinator step here any more**. Do not set a `ranMemoryCleanupThisSession` boolean and do not call `stampMemoryCleanup()` by hand at session-end.
 
-   ```js
-   import { stampMemoryCleanup } from '../../scripts/lib/memory-cleanup-stamp.mjs';
+   `scripts/emit-session.mjs` derives the field itself: it calls `deriveMemoryCleanupSignal()` (`scripts/lib/memory-cleanup-stamp.mjs`), which reads the sibling `events.jsonl` for `orchestrator.memory.cleanup_completed` records whose `timestamp` falls inside this session's own `[started_at, completed_at]` window (and whose `semantic_session_id`, when present, matches). The emitting side is the LAST step of every `/memory-cleanup` run — see `skills/memory-cleanup/SKILL.md` § "Session-End Signal".
 
-   // ranCleanup: true when /memory-cleanup ran this session (ANY outcome)
-   metricsEntry = stampMemoryCleanup(metricsEntry, {
-     ranCleanup: ranMemoryCleanupThisSession, // boolean
-     completedAt: metricsEntry.completed_at,
-   });
-   ```
+   **Contract:** a no-op run (MEMORY.md already healthy, no files mutated) is still a cleanup, so it still emits and therefore still stamps. When `/memory-cleanup` did not run, no event exists, nothing is derived, and the field is simply absent — never `null`. An EXPLICIT `memory_cleanup_at` already present on the record WINS over derivation and is never overwritten; that path is for backfills and tests, not for normal operation.
 
-   **Contract:** A no-op run (MEMORY.md already healthy, no files mutated) is still a cleanup — `memory_cleanup_at` MUST be stamped. This advances `readDreamSignals` → `lastCleanupAt` in `auto-dream.mjs` so `shouldDispatchAutoDream` does not fire a false nudge. When `/memory-cleanup` did not run, omit the field entirely (do NOT set null). The helper is no-throw and pure — it returns the record unchanged on bad inputs.
+   **Why this stopped being a coordinator instruction.** It was one until 2026-08-17, and it measurably failed: a `/memory-cleanup` ran on 2026-08-14 with a documented yield, the prose step above was not executed, and all three session records of that day carried `memory_cleanup_at: null` — so the session-start banner reported "last cleanup 29 days ago" against the operator's own "3 days". `stampMemoryCleanup()` had **zero production callers** at that point; every reference to it was an instruction asking an LLM to remember. Same failure class as the STATE.md write-race Epic #583 replaced with a lock: Disziplin statt Mechanik.
 
    > **#701.2 DOC NOTE — `completed_at >= started_at` guard:** This invariant is enforced mechanically by `scripts/emit-session.mjs`. The writer applies `clampTimestampsMonotonic()` (from `scripts/lib/session-schema/timestamps.mjs`) before `validateSession()`, clamping any inversion of `completed_at < started_at` to `started_at` and recording forensics in `_clamped: true` / `_original_completed_at`. Previously-inverted entries (e.g. `main-2026-06-21-session-4`) are already corrected. **No per-session coordinator action is needed** — the writer enforces the invariant at write time. Do not add defensive clamping logic here; the canonical guard lives in `emit-session.mjs`.
 

package/skills/session-plan/SKILL.md

@@ -275,7 +275,7 @@ mission-status:
 - `status`: always `brainstormed` at plan emission. Terminal values are updated at gate transitions by wave-executor: `brainstormed` → `validated` (user confirms via `/go`) → `in-dev` (agent dispatched) → `testing` (Quality wave) → `completed` (Quality gate green). session-end Phase 1.9 reads the current value to classify the item.
 
 **Transition gates (summary):**
-At plan time, all items start at `brainstormed`. When the user runs `/go` to approve the plan, wave-executor updates each item to `validated`. When an agent for a wave-plan item is dispatched, wave-executor updates that item to `in-dev`. When the Quality wave begins, items from prior waves move to `testing`. When the Quality gate passes, items finalize at `completed`. Rollback to `brainstormed` is permitted from any state. All transitions are validated against the schema in `scripts/lib/mission-status-schema.mjs`.
+At plan time, all items start at `brainstormed`. When the user runs `/go` to approve the plan, wave-executor updates each item to `validated`. When an agent for a wave-plan item is dispatched, wave-executor updates that item to `in-dev`. When the Quality wave begins, items from prior waves move to `testing`. When the Quality gate passes, items finalize at `completed`. Rollback to `brainstormed` is permitted from any state. This ordering is **coordinator convention, not a mechanical gate** — nothing validates a transition before it is written (see "Default and transitions" below).
 
 **Omission rule:** When the plan has 0 wave-plan items (e.g., pure express-path coord-direct with no sub-agent tasks), do NOT emit the `### Wave-Plan Mission Status (machine-readable)` block.
 
@@ -298,7 +298,7 @@ Every wave-plan item carries a `status` field drawn from a 5-value enum. The fie
 - **Default at plan creation:** `brainstormed` — all items start here.
 - **Transitions are coordinator-level orchestration** (not inside individual agent prompts). See `skills/wave-executor/SKILL.md` "Mission-Status Updates (#340)" for when each transition fires.
 - **Rollback:** any item may return to `brainstormed` from any state (e.g. if work is discarded or re-planned).
-- **Schema validation:** transitions are validated against `scripts/lib/mission-status-schema.mjs` before being written to STATE.md.
+- **No mechanical validation — by design.** The `status` values come from the 5-value enum in the table above, but nothing checks a transition before it is written. `setMissionStatus` (`scripts/lib/state-md/mission-status.mjs`) mirrors whatever string it is handed onto BOTH the body section and the frontmatter array, deliberately without an enum gate: gating it would reintroduce the exact body-says-X/frontmatter-says-Y divergence that sync exists to remove. An out-of-enum value therefore lands visibly on both surfaces instead of being silently rejected on one. Keeping the enum honest is the coordinator's job.
 
 #### Status field in wave-plan items
 

package/skills/session-plan/wave-template.md

@@ -18,7 +18,7 @@ For each wave, define agents with:
 
 - `Isolation: worktree` means the wave-executor will pass `isolation: "worktree"` to the Agent tool, giving each agent its own git worktree copy
 - `MaxTurns` is enforced via the agent prompt — wave-executor includes a turn limit instruction in each agent's prompt
-- `status` is the mission-status enum value for this wave-plan item (#340). Always `brainstormed` in the initial plan. Wave-executor updates it at gate transitions (validated → in-dev → testing → completed). Values are validated against `scripts/lib/mission-status-schema.mjs`. Rollback to `brainstormed` is allowed from any state.
+- `status` is the mission-status enum value for this wave-plan item (#340). Always `brainstormed` in the initial plan. Wave-executor updates it at gate transitions (validated → in-dev → testing → completed). Rollback to `brainstormed` is allowed from any state. The five values are listed in `SKILL.md` § Mission-Status Enum; nothing validates them mechanically — `setMissionStatus` writes the string it is given to both STATE.md surfaces on purpose, so keeping the value in-enum is the coordinator's job.
 
 > **Deconfliction rule:** Before finalizing agent specs for a wave, verify that no two agents in the same wave list overlapping `Files:` paths. If overlap is found, either merge the agents into one or move one task to a later wave. Two agents editing the same file in parallel causes merge conflicts that require manual resolution.
 

package/skills/session-start/SKILL.md

@@ -785,7 +785,19 @@ Group issues by:
 
    Non-blocking. Cross-reference: `scripts/lib/ci-status-banner.mjs` (the sibling project-facing probe) and `.claude/rules/test-value.md` § TV-005 (why structural gates beat unit-test volume).
 
-   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `reconcile-nudge-banner.mjs` is absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `sessions-integrity-banner.mjs` is absent (pre-#958 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install) or `claude-md-budget-lint.mjs` is absent (pre-#878 plugin install), skip silently.
+   Additionally, invoke the mirror-issues probe (`scripts/lib/mirror-issues-banner.mjs`) via `await checkMirrorIssues({ repoRoot })`. This is the only probe that deliberately queries the platform the session did NOT auto-detect. `skills/gitlab-ops/SKILL.md` § VCS Auto-Detection selects exactly one platform via if/else, so in a repo whose `origin` is GitLab and whose `github` remote is a public mirror, no code path ever reads the mirror's issue tracker — issues filed there by external reporters are structurally invisible to every session. The VCS family is therefore hard-pinned to `'github'` inside the module rather than auto-detected. It takes no Session Config key: `resolveRepoSpec({ repoRoot, vcs: 'github' })` derives the `gh -R` spec from `git remote`, which makes the probe self-disabling — a repo with no GitHub mirror resolves to `undefined`, returns `null`, and spawns no subprocess.
+
+   The return contract has THREE states, not the usual two, and the third is the point: `null` means either "no mirror remote" or "queried successfully, zero open issues"; `{ severity, message, count, repoSpec, issues }` means N > 0; and `{ severity, message, repoSpec, degraded }` means the query did NOT succeed, where `degraded` is one of `cli-missing | timeout | parse-error | auth-error | query-failed`. Render `result.message` verbatim in either non-null case. A `degraded` result must be read as *"the mirror's state is unknown"* — never as clean. `scripts/lib/ci-status-banner.mjs` collapses all three of missing-CLI, unparseable output and absent-remote onto `null`, which in the banner contract reads as "all clear"; that collapse is why this gap survived unseen. Do not reproduce it.
+
+   Additionally, invoke the git-config-drift probe (`scripts/lib/git-config-drift.mjs`) via `checkGitConfigDrift({ repoRoot })` (synchronous — no await; `env` defaults to `process.env`). It reads `git config --local --list` with a FILTERED environment, so an ambient `GIT_DIR` cannot redirect the probe itself at a foreign repository and let it call this one clean. **Three states, not two:** `null` = read and clean; `{ severity: 'warn', message, findings }` = at least one unexpected entry (a local identity override, a local `commit.gpgsign`, a remote on a reserved fixture host, a `core.hooksPath` not pointing at `.husky/_`, or `GIT_DIR`/`GIT_WORK_TREE` set in the environment); `{ …, degraded }` = the config could NOT be read — **never render that as clean.** Render `result.message` alongside the other banners.
+
+   This is the only probe that inspects `.git/config`, and that is the whole point: `git status` cannot see that file. On 2026-08-19 a coordinator diagnostic exported `GIT_DIR` at this repository while the suite ran; test fixtures wrote a foreign remote and their own `user.email`/`user.name` into the local config, and the identity then authored two commits that reached both remotes. A recovery pass checked HEAD, the index and all 1614 tracked files, found everything clean, and missed it — because none of those surfaces show `.git/config`. It surfaced two hours later, from an agent measuring something else.
+
+   The complementary halves live elsewhere and are not duplicates of this probe: `tests/setup/scrub-git-env.mjs` (wired via `setupFiles` in `vitest.config.mjs`) removes the redirecting variables before any test runs, and `scripts/lib/validate/check-test-git-config-target.mjs` censuses untargeted state-mutating git calls in `tests/**`. The census is WARN-only by measurement — its first cut was 11 hits, all false positives — and it explicitly reports `gitDirInheritable`, the population it cannot close, because the incident's own call sites passed a correct `cwd` and were redirected anyway.
+
+   Non-blocking. Cross-reference: `scripts/lib/vcs-repo-spec.mjs` (`isQueryFailure` — the same absence-vs-query-failure split this probe's `degraded` state implements).
+
+   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `reconcile-nudge-banner.mjs` is absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `sessions-integrity-banner.mjs` is absent (pre-#958 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install) or `claude-md-budget-lint.mjs` is absent (pre-#878 plugin install) or `mirror-issues-banner.mjs` is absent (pre-#1022 plugin install), skip silently.
 
 ## Phase 4.5: Resource Health (v3.1.0)
 

package/skills/spinout/SKILL.md

@@ -2,7 +2,11 @@
 name: spinout
 user-invocable: true
 model: sonnet
-description: Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path, confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo, remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'.
+description: >
+  Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its
+  incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path,
+  confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo,
+  remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'.
 ---
 
 # spinout — Guided Project-Extraction Runbook

package/skills/sunset-review/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: sunset-review
-description: Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events only) with static reference scanning, classifies every surface item into Active / Investigate / Demote / Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer wants to prune dead weight. user: "/sunset-review" assistant: "Running the sunset walk — classifying skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision." <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker, presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
+description: >
+  Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in
+  the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events
+  only) with static reference scanning, classifies every surface item into Active / Investigate / Demote /
+  Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for
+  human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer
+  wants to prune dead weight. user: "/sunset-review" assistant: "Running the sunset walk — classifying
+  skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate
+  / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision."
+  <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker,
+  presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
 model: inherit
 color: amber
 ---

package/skills/tmux-layout/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: tmux-layout
-description: Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug 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".
+description: >
+  Use this skill when the operator wants a prepared tmux visualization layout for the session's
+  side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug
+  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".
 model: inherit
 color: cyan
 tools: Read, Bash, Grep, Glob
@@ -47,7 +52,7 @@ The skill prints a one-line tmux command. Paste it into a SECOND terminal (do no
 |---|---|---|
 | 1 | **Shell** (operator scratch — NOT claude) | `bash` (interactive) |
 | 2 | STATE.md tail | `tail -F <state-dir>/STATE.md` |
-| 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status --pipeline-id LATEST --output json \| jq ...; sleep 15; done` |
+| 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status -R <spec> --output json \| jq -r '.jobs[] \| ...'; sleep 15; done` |
 | 4 | events.jsonl wave/gate filter | `tail -F .orchestrator/metrics/events.jsonl \| jq --unbuffered 'select(.event \| test("wave\|gate\|spiral"))'` |
 | 5 | agent-status telemetry (#565, only with `--with-status-pane`) | `while true; do clear; jq . .orchestrator/runtime/agent-status-current.json 2>/dev/null \|\| echo ...; sleep 2; done` |
 

package/skills/vault-mirror/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: vault-mirror
-description: Use when you need to populate the Meta-Vault with machine-generated notes derived from session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when `vault-integration.enabled=true` and `vault-integration.mode != "off"`. Idempotent: re-runs safely; skips hand-authored notes. Triggers: "mirror to vault", "sync session notes to vault", "write learning 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>
+description: >
+  Use when you need to populate the Meta-Vault with machine-generated notes derived from
+  session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and
+  `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and
+  `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when
+  `vault-integration.enabled=true` and `vault-integration.mode != "off"`. Idempotent: re-runs safely;
+  skips hand-authored notes. Triggers: "mirror to vault", "sync session notes to vault", "write learning
+  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>
 model: haiku
 ---
 

package/skills/vault-sync/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: vault-sync
-description: Use when you need to validate the Meta-Vault's Markdown frontmatter and wiki-link integrity before closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes: `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: "vault validation failed at session close", "fix vault frontmatter errors", "check vault wiki-links", "why is session-end blocked by 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>
+description: >
+  Use when you need to validate the Meta-Vault's Markdown frontmatter and wiki-link integrity before
+  closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any
+  `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes:
+  `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from
+  Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: "vault validation failed at
+  session close", "fix vault frontmatter errors", "check vault wiki-links", "why is session-end blocked by
+  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>
 model: haiku
 ---
 

package/skills/vault-sync/validator.mjs

@@ -254,6 +254,14 @@ for (let i = 0; i < args.length; i++) {
 //   ?     — any single character except `/`
 //   literal path separators and characters otherwise
 // Operates on POSIX-style forward-slash relative paths.
+// `**` compiles to a SEGMENT-ANCHORED alternative, not a free `(?:.*?)` (#1013).
+// The free form ended anywhere, including mid-segment, so every `**/` pattern
+// silently grew a suffix-match: `**/README.md` matched `MYREADME.md`, and
+// `**/archive/**` matched `90-archive/...`. This matcher answers "is this path
+// EXCLUDED from validation", so an over-approximation is not a harmless
+// widening — it is a false negative: the file is never checked and the
+// validator still reports 0 errors. Anchoring narrows exclusion, i.e. it can
+// only ever add files to the checked set.
 function globToRegExp(glob) {
   // Normalise input
   const g = glob.replace(/\\/g, '/');
@@ -262,12 +270,18 @@ function globToRegExp(glob) {
     const c = g[i];
     if (c === '*') {
       if (g[i + 1] === '*') {
-        // `**` — match across path segments
-        // Also swallow a following `/` so that `**/foo` matches `foo` at root.
-        const nextSlash = g[i + 2] === '/';
-        re += '(?:.*?)';
-        if (nextSlash) i += 2;
-        else i += 1;
+        if (g[i + 2] === '/') {
+          // `**/` — zero or more WHOLE path segments. Zero repetitions is what
+          // makes `**/foo` match `foo` at the vault root, and it is why the
+          // trailing `/` is swallowed here rather than emitted literally.
+          re += '(?:[^/]+/)*';
+          i += 2;
+        } else {
+          // Trailing or standalone `**` (e.g. `a/**`) — everything below the
+          // preceding literal, segment boundaries included.
+          re += '.*';
+          i += 1;
+        }
       } else {
         re += '[^/]*';
       }
@@ -658,6 +672,21 @@ const errors = [];
 const warnings = [];
 let filesChecked = 0;
 let filesSkippedNoFrontmatter = 0;
+// The paths behind the count (#1013). A bare count made "0 errors" ambiguous:
+// it meant "everything CHECKED is valid", never "everything is valid", and the
+// operator had no way to see WHICH files were never checked. The list is
+// emitted only by the branches that actually ran the validation pass — so an
+// ABSENT `files_skipped_no_frontmatter_paths` means "never inspected" (mode=off,
+// no vault) while an EMPTY one means "inspected, nothing skipped". Same
+// absence-preserving contract as `scripts/lib/reconcile-nudge-banner.mjs`
+// (`skippedCandidates`), which distinguishes never-checked from checked-clean.
+const filesSkippedNoFrontmatterPaths = [];
+// Ceiling: 50 paths keeps the envelope bounded on a vault that has never been
+// backfilled (real measurement 2026-08-15: 2 of 8574 files in the live vault).
+// `paths.length < files_skipped_no_frontmatter` is itself the truncation
+// signal, so no extra flag is needed. Revisit if a consuming vault routinely
+// reports more than 50 — then the right fix is a backfill, not a bigger cap.
+const SKIPPED_PATHS_CAP = 50;
 let excludedCount = 0;
 let archivedSkippedCount = 0;
 
@@ -686,6 +715,9 @@ for (const rec of records) {
 
   if (!fm.hasFrontmatter) {
     filesSkippedNoFrontmatter++;
+    if (filesSkippedNoFrontmatterPaths.length < SKIPPED_PATHS_CAP) {
+      filesSkippedNoFrontmatterPaths.push(rel);
+    }
     continue;
   }
 
@@ -737,6 +769,19 @@ for (const rec of records) {
 
 const hasErrors = errors.length > 0;
 
+// Silence is not success: a skipped file contributes to neither `errors` nor
+// `files_checked`, so a bare "0 errors" line would let an unvalidated file pass
+// unremarked at the session-end hard gate (#1013). Surface the count on stderr
+// too — stdout stays pure JSON per the caller contract.
+if (filesSkippedNoFrontmatter > 0) {
+  const shown = filesSkippedNoFrontmatterPaths.slice(0, 5).join(', ');
+  const more = filesSkippedNoFrontmatter - Math.min(5, filesSkippedNoFrontmatterPaths.length);
+  process.stderr.write(
+    `WARN: ${filesSkippedNoFrontmatter} file(s) NOT validated — no frontmatter: ` +
+      `${shown}${more > 0 ? ` (+${more} more)` : ''}\n`,
+  );
+}
+
 // ── mode=baseline ─────────────────────────────────────────────────────────
 // Serialize current errors + warnings as a snapshot, then exit 0.
 if (mode === 'baseline') {
@@ -774,6 +819,7 @@ if (mode === 'diff') {
       excluded_count: excludedCount,
       archived_skipped_count: archivedSkippedCount,
       files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+      files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
       errors,
       warnings,
     });
@@ -794,6 +840,7 @@ if (mode === 'diff') {
       excluded_count: excludedCount,
       archived_skipped_count: archivedSkippedCount,
       files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+      files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
       errors,
       warnings,
     });
@@ -816,6 +863,7 @@ if (mode === 'diff') {
     excluded_count: excludedCount,
     archived_skipped_count: archivedSkippedCount,
     files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+    files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
   });
 
   process.stderr.write(
@@ -839,6 +887,7 @@ emit({
   excluded_count: excludedCount,
   archived_skipped_count: archivedSkippedCount,
   files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+  files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
   errors,
   warnings,
 });

package/skills/wave-executor/wave-loop.md

@@ -433,7 +433,7 @@ This replaces the older prose slot "Relevant patterns from `<state-dir>/rules/`"
 
 **Gate:** runs when `.orchestrator/metrics/learnings.jsonl` exists. When it does not — or when nothing clears the confidence floor, or the corpus is unreadable — the CLI prints nothing and exits 0. Same best-effort convention as every injector above (Grounding `:307`, Frontmatter-Guard `:386`, Path-Cousin-Guard `:208`): silent no-op on any failure, **never blocks dispatch**. Any non-zero exit means "inject nothing, continue".
 
-**Zero new coordinator obligations.** The per-agent file scope this needs is the SAME `$AGENT_FILESCOPE_JSON` temp file the Pre-Dispatch Scope-Union Assertion (#796, see `## Scope Manifest` § 3) already requires you to write for every agent in every `Agent()` batch. Reuse that file — do not write a second one.
+**Zero new coordinator obligations.** The per-agent file scope this needs is the SAME `$AGENT_FILESCOPE_JSON` — `<state-dir>/filescopes/wave-<N>/<agent-id>.json` — that `## Scope Manifest` § 3.1 already requires you to write for every agent, and that the Scope-Union Assertion (#796) then consumes. Reuse that file — do not write a second one, and never a temp copy.
 
 **Invocation:** once per agent, immediately after that agent's `$AGENT_FILESCOPE_JSON` is written, capture stdout as `$LEARNINGS_INDEX`:
 
@@ -455,6 +455,21 @@ When it is empty (no corpus, no qualifying entries, or any CLI failure), dispatc
 
 **Instrumentation (why this one is measurable and its neighbours are not).** The rule injection above is a SHOULD and emits no signal either way, so "did the coordinator actually inject?" has been unanswerable after the fact — a gap the #1014 discovery wave had to leave open. This CLI emits `orchestrator.learnings.index.injected` to `.orchestrator/metrics/events.jsonl` (via `scripts/emit-event.mjs`, the canonical `emitEvent()` path — the same route `scripts/compute-grounding-injection.sh` uses for `orchestrator.grounding.injected`), carrying `count`, `scope_matched`, `global_count`, `candidates`, `truncated`, `bytes`, and `scope_source`. The before/after measurement is therefore a fact in the event log, not a matter of prose compliance. Emission is best-effort and suppressible with `--no-event`; a failed emit never blocks dispatch.
 
+#### Pre-Dispatch: File-Scope Injection (#1020)
+
+> **Read this first — this block is PER AGENT, unlike `#### Pre-Dispatch: Glob-Scoped Rule Injection (#336/#694)` above, which states "Per-wave scoping (not per-agent): the rule set is computed ONCE per wave".** Model it on **Pre-Dispatch Grounding Injection (#85)** — same cadence, same per-agent source. This injector legitimately has BOTH cadences (per-agent for the brief, per-wave for the § Scope Manifest union), which is exactly what makes the collapse tempting: reuse ONE agent's block for the whole batch and every agent reads the territory of every OTHER agent as its own. Deconfliction would then be **lifted rather than enforced**, and the double assignment § 3.2 exists to catch becomes invisible in the one channel where an agent could still notice it.
+
+**Invocation:** for each agent, read `<state-dir>/filescopes/wave-<N>/<agent-id>.json` (= `$AGENT_FILESCOPE_JSON`) — the SAME file written in § Scope Manifest 3.1, not a re-derivation from the session plan and not a temp copy — and prepend its entries to that agent's prompt, one path per line:
+
+    FILE-SCOPE — exactly these:
+    ```
+    <one path or glob per line, verbatim from that agent's scope file>
+    ```
+
+Marker line plus fenced block, in that order: `hooks/pre-task-scope-disjoint.mjs` extracts the scope from the prompt by finding the marker and taking the FIRST fenced block after it, so this shape is what makes an agent's declared territory machine-readable at dispatch time. An unparseable or absent block resolves to ALLOW there, so a malformed injection degrades to today's behaviour rather than blocking dispatch. When the scope file is missing or empty (Discovery waves), inject nothing and dispatch unchanged.
+
+> **Registration note.** That hook was armed in `hooks/hooks.json` on 2026-08-14, after a green Full Gate. Its `PreToolUse` matcher is **`Agent`** — measured over 12 archived transcripts of this repo, `Agent` accounts for 147 of 147 dispatch `tool_use` blocks. A `Task` matcher would hit the unrelated todo family (`TaskCreate`/`TaskUpdate`/`TaskGet`/…) and never once fire on a dispatch: armed and inert, the failure mode that reads as done. It is deliberately absent from `hooks-codex.json` / `hooks-cursor.json` / `hooks-pi.json` — those platforms have no `Agent` dispatch tool, so the asymmetry is registered in `DOCUMENTED_ASYMMETRIES` rather than papered over with a matcher that can never fire.
+
 #### Structured Reasoning (STATE:/PLAN:) — opt-in via `reasoning-output: true` (#79)
 
 When `$CONFIG.reasoning-output` is `true`, append the following block to every agent prompt. The pattern is adapted from the BitGN PAC Agent's Soft-SGR: short structured transparency lines before tool invocations, without forcing structured output. Leave the block OUT when the flag is `false` (default) — this preserves exact legacy prompt behavior.
@@ -1099,19 +1114,34 @@ Before each wave dispatch:
    ```
    The `gates` field (optional) mirrors `enforcement-gates` from Session Config (#77). When present, hooks check each gate individually via `gate_enabled()`. Missing gate entries default to enabled, preserving default behavior.
 2. Validate by piping through `node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs"` (where `$PLUGIN_ROOT` is `$CLAUDE_PLUGIN_ROOT`, `$CODEX_PLUGIN_ROOT`, or `$CURSOR_RULES_DIR` per platform — see `skills/_shared/config-reading.md`). If validation fails (exit 1), fix the JSON based on stderr errors and retry.
-3. `allowedPaths` is the UNION of all agent file scopes for this wave
-   To compute `allowedPaths`: read each agent's specification from the session plan. Each agent lists its "Files:" scope (e.g., `skills/session-end/SKILL.md`, `scripts/*.sh`). Collect all file paths and glob patterns from all agents in this wave into a single flat array. Deduplicate entries. If an agent's scope uses globs (e.g., `scripts/*.sh`), include the glob pattern as-is — the enforcement hook resolves globs at check time.
+3. **`allowedPaths` is COMPUTED from per-agent scope files — never hand-transcribed (#1020).** Transcribing the union by hand produced 5 scope divergences in ONE session. Three steps, in this order; none of them is a judgement call. Globs stay verbatim (`scripts/*.sh`) — the enforcement hook resolves them at check time.
 
-   **Test-Sibling Expansion (#970):** an `allowedPaths` entry that names a production file but NOT its test sibling makes the wave's own regression test unwritable — the scope guard then mechanically enforces exactly the inconsistency the quality gate exists to catch. Cross-repo evidence, three occurrences in ONE session: a migrations glob without the SQL-test directory (the regression test could not be written); a lone `.actions.ts` file (the wave's cross-tenant security test stayed red); a dead-export deletion whose importing test lay outside every scope (the suite ended red). Do NOT hand-derive the sibling paths — expand through the shared helper so the hook, the validator and this prose state one rule:
+   **3.1 — one file per agent.** Write each agent's "Files:" scope from the session plan, verbatim, as a JSON array of strings to `<state-dir>/filescopes/wave-<N>/<agent-id>.json`. That path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and the File-Scope Injection (#1020) already consume. Do not write a second copy anywhere, and **never to a `$TMPDIR` temp path**: the injector and `hooks/pre-task-scope-disjoint.mjs` need an addressable, wave-keyed location that a temp file cannot be. Reading `$AGENT_FILESCOPE_JSON` as "some temp file" is the one failure that costs no error — the injector finds nothing, no `FILE-SCOPE` block reaches the prompt, `extractScopeFromPrompt` returns `[]`, and the dispatch is ALLOWed exactly as it was before #1020, signal-free. The coordinator's OWN planned direct edits go into `<state-dir>/filescopes/wave-<N>/coordinator.json` in the identical form and take part in both steps below: 2 of those 5 divergences were coordinator-direct edits, for which no agent scope file exists by construction, and the commit guard caught them only at the commit boundary.
 
-   ```js
-   import { expandTestSiblings } from '$PLUGIN_ROOT/scripts/lib/scope-gate.mjs';
+   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs BEFORE the union of 3.3 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.
+
+   **3.2 — assert disjointness BEFORE computing the union.** Build the sidecar — an ARRAY of `{id, files}` records (never an object map: a duplicated agent id must stay visible), one record per file written in 3.1, `coordinator.json` included — and run:
 
-   // unionScopes: the deduplicated flat array from the paragraph above.
-   // role: this wave's role, verbatim from the session plan — the helper GATES on it.
-   const allowedPaths = expandTestSiblings(unionScopes, { role });
+   ```bash
+   node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs" \
+     --assert-disjoint "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
    ```
 
+   Exit 1 (one stderr message per collision) means two agents were handed the same file: fix the session plan, rewrite the affected 3.1 files, re-assert. Never widen the union to make it pass. This runs **before** 3.3 because a union computed over colliding scopes launders the defect into the very artefact meant to prevent it — `allowedPaths` then grants the file and every later gate sees a legal write.
+
+   **3.3 — compute the union.** `--union` is a QUERY MODE that still requires a schema-valid manifest on stdin, so write the skeleton first with `"allowedPaths": []`, then:
+
+   ```bash
+   node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs" \
+     --union "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
+   ```
+
+   It prints the computed `allowedPaths` array as JSON on stdout **instead of** the manifest echo — one JSON document per run, the flag decides which. Insert that array as `allowedPaths`, then write the final `wave-scope.json`. It already applies the Test-Sibling Expansion below (`expandTestSiblings(unionFileScopes(scopes), { role })`, role read from the manifest), so do not also run the helper by hand.
+
+   **The `--assert-subset` assertion (#796, below) stays unchanged and keeps running.** It checks a DIFFERENT property — each agent's scope ⊆ the union — and a double assignment is structurally invisible to it: a file claimed twice is a subset twice over. `--assert-disjoint` is an addition, never a replacement.
+
+   **Test-Sibling Expansion (#970):** an `allowedPaths` entry that names a production file but NOT its test sibling makes the wave's own regression test unwritable — the scope guard then mechanically enforces exactly the inconsistency the quality gate exists to catch. Cross-repo evidence, three occurrences in ONE session: a migrations glob without the SQL-test directory (the regression test could not be written); a lone `.actions.ts` file (the wave's cross-tenant security test stayed red); a dead-export deletion whose importing test lay outside every scope (the suite ended red). Do NOT hand-derive the sibling paths — step 3.3's `--union` runs `expandTestSiblings(…, { role })` for you, so the hook, the validator and this prose state one rule.
+
    The helper is pure (same input → same output, no filesystem writes) and is also surfaced by `scripts/validate-wave-scope.mjs`. **The role decides, inside the helper** — `scripts/lib/scope-gate.mjs` `TEST_SIBLING_EXPANSION_ROLES` is THE list (currently `Impl-Core`, `Impl-Polish` — exactly where the incident occurred), and #5/#6 below describe that gate rather than restating it. Pass the role string; do not pre-filter by role in prose, and do not hand-roll the equivalent `{ enabled: … }`. Matching is trimmed + case-insensitive, so `impl-core` behaves as `Impl-Core`.
 
    > **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.
@@ -1123,11 +1153,11 @@ Before each wave dispatch:
    **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.
 
    Three ordering constraints, all load-bearing:
-   - Expand each agent's `fileScope` **before** the overlap/deconfliction check, so a test file newly shared by two agents is visible to the check that exists to catch that collision.
+   - The deconfliction check (3.2) runs on the DECLARED per-agent scopes, **before** the union expands anything. Named ceiling: two agents whose production files share a basename receive the same emitted sibling glob, which a declared-scope check cannot see — revisit if a wave is ever scoped by basename family instead of by directory.
    - Expand **before** `wave-scope.json` is written, in ONE pass. `hooks/post-bash-write-verify.mjs` fingerprints `allowedPaths` via `scopeSignature()` and fires a control notice on change, so a later mutation reads as tampering.
    - Skip **absolute** entries entirely — expanding a Gate-5b out-of-repo grant would sprout a synthetic `tests/**` sibling outside the repo.
 
-   **Pre-Dispatch Scope-Union Assertion (#796):** `wave-scope.json` is GLOBAL per wave — `hooks/enforce-scope.mjs` Gate 7 checks EVERY agent against the same `allowedPaths` union, so a union that (re)written for only ONE agent silently denies its siblings' legitimate writes. Before each `Agent()` batch, mechanically assert — for EVERY agent in the batch — that its fileScope ⊆ `wave-scope.allowedPaths`. Write the agent's "Files:" scope as a JSON array of strings to a temp file (`$AGENT_FILESCOPE_JSON`) and run:
+   **Pre-Dispatch Scope-Union Assertion (#796):** `wave-scope.json` is GLOBAL per wave — `hooks/enforce-scope.mjs` Gate 7 checks EVERY agent against the same `allowedPaths` union, so a union that (re)written for only ONE agent silently denies its siblings' legitimate writes. Before each `Agent()` batch, mechanically assert — for EVERY agent in the batch — that its fileScope ⊆ `wave-scope.allowedPaths`. `$AGENT_FILESCOPE_JSON` is that agent's § 3.1 file — `<state-dir>/filescopes/wave-<N>/<agent-id>.json`, already written above and shared with every other consumer. Do not re-write it to a temp path here (§ 3.1 says why that degrades silently); just run:
 
    ```bash
    node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs" \
@@ -1158,4 +1188,4 @@ Before each wave dispatch:
    5. Delete `<state-dir>/wave-scope.json`
    6. Write Phase 2 wave-scope.json with test file allowedPaths (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
    7. Dispatch test/review agents
-7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup)
+7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup). Delete `<state-dir>/filescopes/` in the same step — the per-agent scope files (§ 3.1) are wave-local working state, and a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified.

package/scripts/lib/mission-status-schema.mjs

@@ -1,114 +0,0 @@
-/**
- * Mission-Status Enum + Transition Validator (issue #340).
- *
- * Pure ESM, no I/O, no external dependencies. All functions are deterministic.
- *
- * Five-state lifecycle for wave-plan items:
- *
- *   brainstormed → validated → in-dev → testing → completed
- *
- * Rollbacks to `brainstormed` are permitted from any state (user can reset scope).
- * Idempotent self-transitions are always allowed.
- * All other transitions are rejected.
- */
-
-/**
- * Canonical ordered list of valid mission-status values.
- *
- * @type {readonly string[]}
- */
-export const MISSION_STATUS_VALUES = Object.freeze([
-  'brainstormed',
-  'validated',
-  'in-dev',
-  'testing',
-  'completed',
-]);
-
-/**
- * Allowed forward transitions (excluding self-transitions and rollback to
- * 'brainstormed', which are handled separately in isValidMissionStatusTransition).
- *
- * @type {ReadonlyMap<string, string>}
- */
-const FORWARD_TRANSITIONS = new Map([
-  ['brainstormed', 'validated'],
-  ['validated', 'in-dev'],
-  ['in-dev', 'testing'],
-  ['testing', 'completed'],
-]);
-
-/**
- * Returns true when `value` is one of the five canonical status strings.
- *
- * @param {unknown} value
- * @returns {boolean}
- */
-export function isValidMissionStatus(value) {
-  return typeof value === 'string' && MISSION_STATUS_VALUES.includes(value);
-}
-
-/**
- * Returns true when the transition from `from` → `to` is permitted.
- *
- * Allowed transitions:
- *   - Forward: brainstormed→validated, validated→in-dev, in-dev→testing, testing→completed
- *   - Idempotent: any state → itself
- *   - Rollback: any state → brainstormed
- *
- * All other transitions return false.
- *
- * @param {string} from - current status value
- * @param {string} to   - target status value
- * @returns {boolean}
- */
-export function isValidMissionStatusTransition(from, to) {
-  if (!isValidMissionStatus(from) || !isValidMissionStatus(to)) return false;
-  // Idempotent self-transition
-  if (from === to) return true;
-  // Rollback to brainstormed from any state
-  if (to === 'brainstormed') return true;
-  // Forward transition
-  return FORWARD_TRANSITIONS.get(from) === to;
-}
-
-/**
- * Validates a mission-status entry object.
- *
- * Expected shape:
- *   { id: string, task: string, wave: number, status: <MISSION_STATUS_VALUES> }
- *
- * @param {unknown} obj
- * @returns {{ ok: boolean, errors: string[] }}
- */
-export function validateMissionStatusEntry(obj) {
-  const errors = [];
-  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
-    return { ok: false, errors: ['entry must be a non-null, non-array object'] };
-  }
-  const entry = /** @type {Record<string, unknown>} */ (obj);
-
-  // id — non-empty string
-  if (typeof entry.id !== 'string' || entry.id.trim() === '') {
-    errors.push('id must be a non-empty string');
-  }
-
-  // task — non-empty string
-  if (typeof entry.task !== 'string' || entry.task.trim() === '') {
-    errors.push('task must be a non-empty string');
-  }
-
-  // wave — integer >= 1
-  if (!Number.isInteger(entry.wave) || /** @type {number} */ (entry.wave) < 1) {
-    errors.push('wave must be a positive integer');
-  }
-
-  // status — one of MISSION_STATUS_VALUES
-  if (!isValidMissionStatus(entry.status)) {
-    errors.push(
-      `status must be one of [${MISSION_STATUS_VALUES.join(', ')}], got: ${JSON.stringify(entry.status)}`,
-    );
-  }
-
-  return { ok: errors.length === 0, errors };
-}