session-orchestrator 3.24.0 → 4.0.1

package/skills/_shared/parallel-aware-preamble.md

@@ -2,6 +2,7 @@
 
 > Single source of truth for the parallel-session-detection preamble.
 > Referenced by: autopilot, session-start, session-plan, wave-executor, session-end (5 orchestrator entry-points).
+> Design history: the 2026-05-26 parallel-aware-sessions spec is superseded on lock liveness (heartbeat, not PID) — see `docs/README.md` § Superseded design notes.
 
 ## Purpose
 

package/skills/_shared/platform-tools.md

@@ -70,7 +70,7 @@ Lifecycle: `spawn_agent` (launch, one per wave task) → `list_agents` (enumerat
 - **session-reviewer** — quality review; spawn as a separate agent rather than reviewing in the main session
 
 **On Cursor IDE:**
-No native Agent() tool or typed agent roles inside the Composer session — wave tasks run sequentially there, and `agents-per-wave` is ignored. This is a statement about the IDE session only: coordinator-side foreign dispatch to Cursor models via the headless `cursor-agent` CLI does exist (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150 — detached worktree, filesystem-measured result, `orchestrator.foreign_dispatch.completed` telemetry, mandatory Claude review, `NEVER_FOREIGN_ROLES` lock). Measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. Slash commands live in `.cursor/commands/`. There is no Skill tool — Read `skills/<name>/SKILL.md` instead.
+No native Agent() tool or typed agent roles inside the Composer session — wave tasks run sequentially there, and `agents-per-wave` is ignored. This is a statement about the IDE session only: coordinator-side foreign dispatch to Cursor models via the headless `cursor-agent` CLI does exist (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150 — detached worktree, filesystem-measured result, `orchestrator.foreign_dispatch.completed` telemetry, mandatory Claude review, `NEVER_FOREIGN_ROLES` lock in `scripts/lib/wave-executor/dispatch-common.mjs`). Measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. Slash commands live in `.cursor/commands/`. There is no Skill tool — Read `skills/<name>/SKILL.md` instead.
 
 **On Pi:**
 No Session Orchestrator Pi subagent dispatcher exists in v1. Execute wave tasks sequentially in the active Pi session. Treat `agents-per-wave` as advisory until the SDK-based dispatcher lands.

package/skills/_shared/state-ownership.md

@@ -147,7 +147,7 @@ This is the wave-plan-time analog of PSA-007 (subagents never race the shared gi
 
 The rule above deconflicts writers *inside one wave*. The same working copy is also shared across SESSIONS, and `<state-dir>/wave-scope.json` is the one control artefact that constrains writes rather than describing them. It lives in the working copy, not in the session — so before #1123 a manifest written by session A governed session B's every Edit. Measured 2026-08-22 (#1082): a Discovery wave's `allowedPaths: []` — prescribed for every Discovery wave — denied all writes of an unrelated parallel session, with a deny reason that could only tell it to fix a wave plan it does not own.
 
-**The manifest is SESSION-BOUND since #1123.** The coordinator that writes it names itself in two optional fields, `session` (raw `session_id`) and `semantic_session`, both from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`) — see `skills/wave-executor/wave-loop.md` § Scope Manifest 1. `hooks/enforce-scope.mjs` Gate 3b classifies the manifest with `readProcessLocalSessionIds()` + `classifyManifestSession()` (`scripts/lib/session-identity/own-session.mjs`) — process-local tiers only (hook payload, `CLAUDE_CODE_SESSION_ID`), never the repo-global `session.lock`, which is shared by every session in the checkout and made a peer's manifest read `own` (#1194):
+**The manifest is SESSION-BOUND since #1123.** The coordinator that writes it names itself in two optional fields, `session_id` (the raw harness session id) and `semantic_session_id` (renamed from `session` / `semantic_session` in #1153 P2 to match `session.lock` and `current-session.json`; the legacy pair is still READ until the next minor release), both from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`) — see `skills/wave-executor/wave-loop.md` § Scope Manifest 1. `hooks/enforce-scope.mjs` Gate 3b classifies the manifest with `readProcessLocalSessionIds()` + `classifyManifestSession()` (`scripts/lib/session-identity/own-session.mjs`) — process-local tiers only (hook payload, `CLAUDE_CODE_SESSION_ID`), never the repo-global `session.lock`, which is shared by every session in the checkout and made a peer's manifest read `own` (#1194):
 
 - **`foreign`** (ids present, none of them ours) → the gate ALLOWS the write and emits one `orchestrator.scope.foreign_session_ignored` event. A foreign manifest is somebody else's wave plan; it never had authority here, and the event keeps the skip counted rather than silent.
 - **`own`** → enforce, unchanged.

package/skills/architecture/SKILL.md

@@ -30,7 +30,9 @@ Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
 - **The interface is the test surface.**
 - **One adapter = hypothetical seam. Two adapters = real seam.**
 
-This skill is _informed_ by the project's domain model — `CONTEXT.md` and any `docs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../domain-model/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../domain-model/ADR-FORMAT.md).
+This skill is _informed_ by the project's domain model — `CONTEXT.md` and any `docs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [references/CONTEXT-FORMAT.md](./references/CONTEXT-FORMAT.md) and [references/ADR-FORMAT.md](./references/ADR-FORMAT.md).
+
+**When to load [references/domain-model.md](./references/domain-model.md):** before this skill's first pass on a repo with no `CONTEXT.md` yet, or one too thin to name the seams below — run its grilling interview to establish the domain vocabulary first. Skip it once `CONTEXT.md` already reflects the domain.
 
 ## Process
 
@@ -45,7 +47,7 @@ If any of these files don't exist, proceed silently — don't flag their absence
 
 **Optional pre-pass — export inventory injection (mapper-supported projects only):**
 
-Before dispatching the Explore subagent, call `extractSemanticSlices(filePath, { type: 'exports' })` from `scripts/lib/language-mappers/index.mjs` on known entry-point files (e.g., `index.ts`, `src/index.ts`, main export barrel). If the mapper returns a non-empty result, format the export list as structured context and inject it into the Explore subagent prompt. This gives the subagent an immediate map of the codebase's public surface without requiring it to grep manually.
+Before dispatching the Explore subagent, read each known entry-point file (e.g. `index.ts`, `src/index.ts`, the main export barrel) and pass its contents to `extractSemanticSlices(filePath, content)` from `scripts/lib/language-mappers/index.mjs`. The signature is `(filePath, content, options?)` — the second argument is the raw file text, **not** an options object, and there is no slice-kind filter parameter. It resolves to an array of `SemanticSlice` records (`{ kind, name, exported, … }`); keep the ones with `exported === true`, format them as structured context, and inject that into the Explore subagent prompt. This gives the subagent an immediate map of the codebase's public surface without requiring it to grep manually.
 
 ```
 ## Export inventory (auto-generated)
@@ -53,7 +55,7 @@ Before dispatching the Explore subagent, call `extractSemanticSlices(filePath, {
 - src/lib/bar.ts: exports `processBar`
 ```
 
-This pre-pass is OPTIONAL — only activate when the entry-point file is mapper-supported (TypeScript/JavaScript). For unsupported file types, `extractSemanticSlices` returns an empty array and the pre-pass is silently skipped. Never block Explore dispatch on a mapper failure.
+This pre-pass is OPTIONAL — only activate when the entry-point file is mapper-supported (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.md`, `.mdx`, `.swift`, `.py` — the `EXT_TO_LANG` map in `index.mjs` is the source of truth). For any other extension `extractSemanticSlices` **throws** rather than returning an empty array, so wrap the call in a try/catch and skip the pre-pass silently on failure. Never block Explore dispatch on a mapper error.
 
 Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
 
@@ -86,7 +88,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
 
 Side effects happen inline as decisions crystallize:
 
-- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/domain-model` (see [CONTEXT-FORMAT.md](../domain-model/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as the domain-model grilling reference (see [references/CONTEXT-FORMAT.md](./references/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
-- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../domain-model/ADR-FORMAT.md).
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [references/ADR-FORMAT.md](./references/ADR-FORMAT.md).
 - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

package/skills/{domain-model/SKILL.md → architecture/references/domain-model.md}

@@ -1,12 +1,12 @@
----
-name: domain-model
-description: Use when the user wants to stress-test a plan against the existing domain model and documented decisions. Grilling session that interviews the user one question at a time, sharpens fuzzy terminology inline, updates CONTEXT.md lazily, and offers ADRs sparingly under a 3-criteria gate. Reads docs/adr/ and CONTEXT.md if present.
-model: inherit
-disable-model-invocation: true
-derived-from: mattpocock/skills@90ea8ee
-license: MIT
-upstream-url: https://github.com/mattpocock/skills/tree/main/domain-model
----
+# Domain-Model Grilling (reference)
+
+> Reference material for the `architecture` skill — **not a skill of its own.**
+> Merged here in v4.0.0 from the former `skills/domain-model/` (retired: zero
+> telemetry, zero fleet invocations, reference-only usage — see
+> `docs/audits/2026-09-06-360-audit.md` § 5A). Invoke it by reading this file
+> from `/architecture`, not via a slash command.
+>
+> Adapted from [`mattpocock/skills@90ea8ee`](https://github.com/mattpocock/skills/tree/main/domain-model), MIT — Copyright (c) 2026 Matt Pocock. See the repo-root `NOTICE`.
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 

package/skills/autopilot/SKILL.md

@@ -377,24 +377,10 @@ identically by readers per the v1 schema additive convention).
 
 ## Configuration
 
-The `autopilot` block in Session Config (`CLAUDE.md` / `AGENTS.md`) accepts the following fields. All fields are optional; omitting a field applies the documented default.
-
-```yaml
-autopilot:
-  bg-isolation: worktree   # worktree | none (default: worktree) — see #431
-```
-
-### bg-isolation
-
-**Type:** `worktree` | `none` — **Default:** `worktree`
-
-Controls whether `autopilot --multi-story` creates a per-story git worktree before spawning sub-sessions.
-
-`worktree` (default): Each story pipeline receives its own isolated git worktree via `EnterWorktree`. Parallel writes are safe because every agent edits a private working copy. Cost: disk space proportional to the number of concurrent stories plus the latency of worktree creation at story-start.
-
-`none` (opt-in): No worktrees are created. Sub-sessions spawn directly in the main working tree. Useful for monorepos where worktree creation is impractical due to large `node_modules`, sparse-checkout setups, or build caches that must be shared. **Requires file-scope discipline:** when `max-stories > 1`, every story must edit a disjoint set of files. If two stories touch the same file simultaneously, edits will collide silently. To enforce acknowledgement of this discipline, `autopilot-multi` requires `--deconflict-paths=<glob>` whenever `bg-isolation: none` AND `max-stories > 1`; omitting the flag is a hard error (exit 1). See `.claude/rules/parallel-sessions.md` PSA-001/002/003.
-
-**Operator-awareness note:** CC 2.1.133 silently flipped `worktree.baseRef` default from `head` to `origin/<default>`, breaking users who relied on unpushed commits being included in their worktree base. The same class of upstream change can affect `bg-isolation` semantics in a future CC release. Treat CC changelog entries related to worktree or `--bg` session behaviour as requiring a re-read of this section before upgrading.
+Single-story `/autopilot` takes no Session Config block. Multi-story
+(`autopilot.bg-isolation`, `--multi-story`, `--deconflict-paths`) was removed in
+4.0.0 — see `docs/migration-v4.md` and `docs/session-config-reference.md` §
+"Autopilot Multi-Story (#431) — removed".
 
 ## References
 

package/skills/claude-md-drift-check/SKILL.md

@@ -39,7 +39,7 @@ PHASE 1 IMPLEMENTED (2026-04-19). Session-end opt-in quality gate. Upstream of `
 | 4 | `session-file-existence` | `50-sessions/YYYY-MM-DD-*.md` references anywhere in scope | `existsSync(vault/50-sessions/<file>)` |
 | 5 | `command-count` | "N commands" / "N /commands" claims in prose | compare to `ls commands/*.md \| wc -l`; skipped if no `commands/` dir |
 | 6 | `session-config-parity` | Top-level keys under `## Session Config` in `CLAUDE.md` / `AGENTS.md` | diff against `docs/session-config-template.md`; a missing MANDATORY (minimal-baseline) key is an error, a missing OPT-IN-baseline-only key is a warning |
-| 7 | `vault-dir-parity` | `vault-integration.vault-dir` in BOTH `CLAUDE.md` AND `AGENTS.md` | reuse `_parseVaultIntegration`; flag when the two files disagree |
+| 7 | `vault-dir-parity` | `vault-integration.vault-dir` in BOTH `CLAUDE.md` AND `AGENTS.md` | reuse `_parseVaultIntegration`; flag when the two files disagree. Short-circuits to PASS when the two are the SAME file by construction (symlink / same inode / byte-identical generated copy) |
 | 8 | `generated-rule-staleness` *(WARN only)* | `.claude/rules/*.md` with `auto-generated: true` frontmatter | extract `learning-key`; WARN when the key is absent from `.orchestrator/metrics/learnings.jsonl` or its learning's `expires_at` is in the past; skipped silently when no auto-generated rules exist |
 | 9 | `rule-scoping` | `.claude/rules/*.md` frontmatter + `## See Also` footers + `.claude/rules/<name>.md` citations in `CLAUDE.md`/`AGENTS.md` | five probes: `paths:` frontmatter (error), cited-but-missing rule citations (error), zero-match `globs:` patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped); skipped silently when `.claude/rules/` is absent |
 | 10 | `docs-parity` | `docs/components.md` count-claims, Session Config key parity (`docs/session-config-template.md` vs `docs/session-config-reference.md`), `.claude/metrics/` stale-path references in `docs/*.md` / `docs/examples/*.md` | three sub-checks (a/b/c) — see below; skipped silently when `docs/components.md` is absent |
@@ -61,6 +61,10 @@ A local CLAUDE.md / AGENTS.md that omits any of these now surfaces a `session-co
 
 Check 7 (issue #600) is the **only** check that intentionally reads BOTH instruction files rather than the single alias-resolved one. The alias rule (CLAUDE.md wins ties, AGENTS.md is the Codex alias) means `resolveInstructionFile()` picks exactly one — so a repo carrying both files can silently let `AGENTS.md` drift out of sync with `CLAUDE.md`. A sibling project ran for weeks with a correct `vault-integration.vault-dir` in `CLAUDE.md` and a dead path in `AGENTS.md`. Check 7 reads `vault-integration.vault-dir` from each file (reusing the `_parseVaultIntegration` parser from `scripts/lib/config/vault-integration.mjs` — no hand-rolled YAML) and flags a `vault-dir-parity` error when the two values diverge (the error is attributed to `AGENTS.md`, the secondary alias, and names both values). The check skips gracefully when only one instruction file is present (nothing to compare), when neither file declares a `vault-integration:` block, or when explicitly disabled via `--skip-vault-dir-parity`. Two files that both omit `vault-dir` (both unset) agree and pass.
 
+**Alias-by-construction short-circuit.** Since this repo's root `AGENTS.md` became a GENERATED byte-identical copy of `CLAUDE.md` (`scripts/generate-agents-skills.mjs`), Check 7 no longer skips here — it RUNS on every invocation. Two files that cannot disagree have nothing to diff, so the check reports parity as satisfied without deriving one: `instructionFilesAreAliased()` recognises a symlink resolving to the same path, the same inode/device (hardlink or already-resolved symlink), and byte-identical content. Branch order is load-bearing: the "neither file has a `vault-integration:` block" skip is evaluated FIRST, because an absent subject is a different (and more informative) outcome than "the files cannot disagree". The error class the check exists for is untouched — two INDEPENDENT files that declare different `vault-dir` values still produce the `vault-dir-parity` error attributed to `AGENTS.md`.
+
+The same predicate guards Check 9's probe 2a, which iterates `['CLAUDE.md', 'AGENTS.md']`: with an aliased `AGENTS.md` it scans `CLAUDE.md` only, because otherwise every dangling `.claude/rules/*.md` citation would be reported TWICE — one defect, two errors, and in `--mode strict` a doubled blocking surface against a file the operator is not allowed to edit.
+
 Check 9 (`rule-scoping`) validates `.claude/rules/*.md` frontmatter against the `scripts/lib/rule-loader.mjs` contract, catching the class of defect where a rule silently drifts out of the activation pipeline the loader actually implements. Four probes: **(1) paths-presence** — a top-level `paths:` frontmatter key is not a key `rule-loader.mjs` recognises (it only reads `globs:`), so a rule with `paths:` silently loads ALWAYS-ON regardless of intended file scope; flagged as an error. **(2) cited-but-missing** — `(a)` `.claude/rules/<name>.md` citations inside `CLAUDE.md`/`AGENTS.md` that don't resolve to a file on disk, and `(b)` bare `<name>.md` tokens in a rule's own `## See Also` footer that don't exist as sibling rule files (tokens carrying a path separator, e.g. `../../skills/_shared/state-ownership.md`, are cross-directory references and explicitly out of scope); both flagged as errors. **(3) zero-match-globs** — a `globs:` pattern matching zero files in `git ls-files` (falls back to a manual directory walk when git is unavailable); flagged as a WARNING, not an error, because library/exemplar repos legitimately carry dead stack rules (this repo alone carries ~37 by design — Swift/Next.js/Supabase rules with no matching files in a pure-Node-ESM codebase). **(4) foreign-glob** — a glob pattern containing a PascalCase product-like token (regex `[A-Z][a-z]+[A-Z]`, e.g. `WalkAITalkieTests`) — a likely copy-paste leftover from another project's rule scope; flagged as a WARNING. Glob matching reuses the same picomatch-with-inline-fallback resolution `scripts/lib/rule-loader.mjs` uses (`parseGlobsFrontmatter` is imported directly; the picomatch resolution itself is duplicated locally since `rule-loader.mjs` does not export a public matcher function). The check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `.claude/rules/` is absent, or explicitly via `--skip-rule-scoping`.
 
 Check 10 (`docs-parity`, issue #780) validates the public docs surface against live repository state via three sub-checks, all reported under the single `docs-parity` check id: **(a) count-claims** — `docs/components.md`'s own heading counts ("## Skills (N user-facing)", "## Commands (N)", "## Agents (N typed sub-agents)", "## Hook event types (N)") are compared against the SAME actual on-disk derivation the surface-count family (Check 5) uses (`countSkills`/the commands-dir listing/`countAgents`/`readHookCounts`) — NOT Check 5's `claimRe` regexes, which are tuned for CLAUDE.md/README prose phrasing and verifiably do not match `components.md`'s own heading convention; a dedicated set of regexes tailored to the doc's actual authored structure is used instead. **(b) config-block-parity** — top-level Session Config keys documented in `docs/session-config-template.md` (opt-in baseline, via the Check 6 'last'-occurrence extractor) are compared against `docs/session-config-reference.md`; a key is considered documented in the reference when it appears in a `yaml` fence (any indent), a `##`/`###`/`####` heading, or the first cell of a markdown table row (`` | `key-name` | ... ``) — the reference's dominant documentation shape is one table row per field, so a naive fence-only extraction under-counts what it actually documents. Missing keys surface as `docs-parity` errors attributed to `docs/session-config-reference.md`. **(c) metrics-path-liveness** — any `.claude/metrics/` path reference (stale; canonical is `.orchestrator/metrics/`) found in root `docs/*.md` or `docs/examples/*.md` surfaces as an error at its exact file/line. The whole check is skipped silently (no `checks_run` entry, no `checks_skipped` entry) when `docs/components.md` is absent, or explicitly via `--skip-docs-parity`.

package/skills/claude-md-drift-check/checker.mjs

@@ -28,7 +28,7 @@
  * rule-loader.mjs uses); otherwise pure Node stdlib.
  */
 
-import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, statSync, lstatSync, realpathSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -294,6 +294,45 @@ function readVaultIntegration(filePath) {
   return { present, vaultDir: parsed['vault-dir'] };
 }
 
+/**
+ * Are the two instruction files the SAME file by construction?
+ *
+ * Since the cross-harness portable surface landed, this repo's root `AGENTS.md`
+ * is GENERATED from `CLAUDE.md` (`scripts/generate-agents-skills.mjs`) as a
+ * byte-identical copy, and a consumer repo may instead symlink it. Three shapes
+ * therefore count as aliased: a symlink resolving to the same path, the same
+ * inode/device (symlink already resolved, or a hardlink), and byte-identical
+ * content.
+ *
+ * This matters because Check 7 exists to catch TWO INDEPENDENT files that
+ * disagree. Files that cannot disagree have nothing to diff — running the
+ * comparison on them would turn a check that skipped for years into a source of
+ * spurious findings the moment AGENTS.md appears. Check 9's probe 2a uses the
+ * same predicate to avoid reporting every CLAUDE.md defect twice.
+ *
+ * @param {string} pathA
+ * @param {string} pathB
+ * @returns {boolean}
+ */
+function instructionFilesAreAliased(pathA, pathB) {
+  if (!existsSync(pathA) || !existsSync(pathB)) return false;
+  try {
+    if (lstatSync(pathA).isSymbolicLink() || lstatSync(pathB).isSymbolicLink()) {
+      if (realpathSync(pathA) === realpathSync(pathB)) return true;
+    }
+    const a = statSync(pathA);
+    const b = statSync(pathB);
+    if (a.ino !== 0 && a.ino === b.ino && a.dev === b.dev) return true;
+  } catch {
+    // stat/realpath failure (race, permissions) — fall back to bytes
+  }
+  try {
+    return readFileSync(pathA).equals(readFileSync(pathB));
+  } catch {
+    return false;
+  }
+}
+
 function classifySection(heading) {
   if (!heading) return null;
   if (BACKWARD_HEADING_RE.test(heading)) return 'backward';
@@ -881,7 +920,19 @@ function main() {
       const claudeVi = readVaultIntegration(claudePath);
       const agentsVi = readVaultIntegration(agentsPath);
       if (!claudeVi.present && !agentsVi.present) {
+        // Nothing to compare — the SUBJECT of the check is absent from both
+        // files. This branch precedes the alias short-circuit on purpose: an
+        // absent vault-integration block is a different (and more informative)
+        // outcome than "the files cannot disagree".
         checksSkipped.push('vault-dir-parity: neither file has a vault-integration: block');
+      } else if (instructionFilesAreAliased(claudePath, agentsPath)) {
+        // Identical by construction (generated copy, symlink, or hardlink) —
+        // parity is SATISFIED, so the check RAN and found nothing. Reporting
+        // this as a skip would be wrong too: the invariant Check 7 guards is
+        // actively held here, it is simply held mechanically rather than by
+        // agreement, and re-deriving a diff between one file and itself can
+        // only manufacture noise.
+        vaultDirParityRan = true;
       } else {
         vaultDirParityRan = true;
         const claudeDir = claudeVi.vaultDir;
@@ -1182,7 +1233,16 @@ function main() {
       }
 
       // --- Probe 2a: cited-but-missing (CLAUDE.md / AGENTS.md citations) → errors[] ---
-      for (const instrName of ['CLAUDE.md', 'AGENTS.md']) {
+      // AGENTS.md is scanned as a SECOND file only when it is genuinely
+      // independent. When it is an alias of CLAUDE.md (this repo generates it
+      // byte-identically), scanning both would report every dangling citation
+      // TWICE — one defect, two errors, and in `--mode strict` a doubled exit
+      // surface for a file the operator cannot edit.
+      const aliasedInstruction = instructionFilesAreAliased(
+        join(vaultDir, 'CLAUDE.md'), join(vaultDir, 'AGENTS.md'),
+      );
+      const instrNames = aliasedInstruction ? ['CLAUDE.md'] : ['CLAUDE.md', 'AGENTS.md'];
+      for (const instrName of instrNames) {
         const filePath = join(vaultDir, instrName);
         if (!existsSync(filePath) || !statSync(filePath).isFile()) continue;
         const fcontent = readFileSync(filePath, 'utf8');

package/skills/convergence-monitoring/SIGNALS.md

@@ -32,6 +32,34 @@ PEAK_DIFF_SIZE=$(jq -s 'map(.diff_size) | max' <<< "$WAVE_HISTORY_JSON")
 SD_VALUE=$(echo "scale=3; $WAVE_DIFF_SIZE / $PEAK_DIFF_SIZE" | bc)
 ```
 
+### Live monitor input (`scripts/lib/convergence-monitor.mjs`)
+
+The `shrinking_diff` NDJSON signal compares `files_changed` across two
+consecutive `orchestrator.wave.completed` records. Until 2026-09-05 **no
+producer wrote that key** — 144 such records in
+`.orchestrator/metrics/events.jsonl`, none carrying a measurement key, so the
+signal was structurally dead. The emitter is now
+`hooks/post-tool-batch-wave-signal.mjs` (#980): at an N→N+1 wave transition its
+`orchestrator.wave.completed` for wave N carries
+
+- `files_changed` — the DEDUPED count of `git diff --name-only <wave_start_sha>`
+  ∪ `git ls-files --others --exclude-standard`, and
+- `files_changed_source: 'worktree-vs-wave-start-sha'` — how it was measured.
+
+`wave_start_sha` is the `git rev-parse HEAD` the same hook persists into
+`.orchestrator/current-session.json` when wave N is opened. The comparison is
+against the WORKING TREE, not `<sha>..HEAD`, because the coordinator commits at
+session close rather than per wave.
+
+**Both keys are optional, and absent is not zero.** Any git failure, a 1.5 s
+timeout, or a missing `wave_start_sha` omits them; the monitor reads the absence
+as `null` and `shrinking_diff` simply does not fire. Two records carry no
+measurement by construction: the final wave's completion from
+`hooks/on-session-end.mjs` (no wave-open transition ran there, so it has no
+start sha) and any completion emitted from an explicit injected `wave_signal`.
+The git/jq recipe above is the SKILL-level computation and is independent of the
+monitor.
+
 ### Thresholds
 
 | SD value  | Interpretation                                         |
@@ -99,6 +127,22 @@ PR_PRIOR=$(echo "$PASS_RATES" | jq '.[length - 2] // 0')
 If `quality.incremental` events are absent (test runner not configured), set
 `PR_confidence = 0.0` and trend = `plateau` (neutral; do not block on missing data).
 
+### Live monitor input (`scripts/lib/convergence-monitor.mjs`)
+
+The `pass_rate_plateau` NDJSON signal reads the **quality-gate envelope**:
+`orchestrator.quality_gate.passed` / `.failed` records carrying BOTH
+`wave_number` and a well-formed `counts` object. It folds `counts.passed` into
+the wave's pass count (and `counts.failed` alongside it), then fires when two
+consecutive waves report the identical pass count. Measured 2026-09-05: 33 such
+records in `.orchestrator/metrics/events.jsonl`; the flat `test.passed` key the
+reader also accepts has **0** producers and is kept only as an alias for a future
+direct emitter.
+
+The `wave_number` + `counts` pair is a type-AND-shape gate, not a prefix
+widening: a session-level gate run (no `wave_number`) must stay invisible to the
+monitor, because admitting it would instantiate a `WaveSummary` per gate run and
+burn the once-per-wave emit keys before the real wave record arrives (#966).
+
 ### Thresholds
 
 | PR value  | Interpretation                                             |
@@ -160,6 +204,17 @@ VEL_LINES=$(git diff --shortstat "$WAVE_START_REF" "$WAVE_END_REF" \
 VEL_LINES_PRIOR=<read from events.jsonl for wave N-1>
 ```
 
+### Live monitor input (`scripts/lib/convergence-monitor.mjs`)
+
+The `velocity_drop` NDJSON signal counts **one `orchestrator.agent.stopped`
+record per dispatched agent** (wave read from `wave` or `wave_number`) and fires
+when the later wave stopped fewer agents than the earlier one. Measured
+2026-09-05 over `.orchestrator/metrics/events.jsonl`: 11,754
+`orchestrator.agent.stopped` records versus **0** for the `agent.dispatched` type
+the reader also accepts — `agent.stopped` is the only per-agent record this repo
+actually emits with a wave number. The git-based `VEL_COMMITS` / `VEL_LINES`
+recipe above is the SKILL-level computation and is independent of the monitor.
+
 ### Thresholds
 
 | Condition                        | Interpretation                                 |

package/skills/discovery/probes/vault-staleness.mjs

@@ -10,12 +10,21 @@
  * Output: {findings[], metrics, duration_ms, [skipped_reason]}. Never throws.
  * Also appends one JSONL summary record to .orchestrator/metrics/vault-staleness.jsonl.
  *
- * Current limitation: we compare lastSync age against probe run time only —
- * not against the upstream repo's most-recent commit. Mapping vault slugs to
- * local repo paths is not reliably available from the probe's inputs. A future
- * iteration should resolve each slug to a repo path and run
- * `git log -1 --format=%aI` to obtain the true lastCommit timestamp, then
- * compute |lastCommit - lastSync| instead.
+ * Denominator (GitLab #1238): staleness is `lastCommit - lastSync` — how far the
+ * upstream repo advanced PAST the last sync — not `now - lastSync`. A mirror of a
+ * repo nobody has committed to in three weeks is CURRENT, not three weeks stale.
+ * `lastCommit` needs no slug→repo-path resolution: the vault sync writer already
+ * stamps it into the same `_overview.md` frontmatter it writes `lastSync` into,
+ * so both sides of the comparison come from one read of one file.
+ *
+ * Measured against the live vault before the fix (2026-09-05): 33 of 48 overviews
+ * reported "stale", 26 of them >7d, with a demonstrably healthy sync chain —
+ * because the clock, not the repo, was the denominator.
+ *
+ * Fallback: an overview WITHOUT `lastCommit` carries no repo-activity signal at
+ * all, so the wall-clock comparison is the only thing left. It is retained for
+ * that case only, marked `basis: 'probe-runtime'` in the evidence and carried at
+ * lower confidence, so a consumer can tell a measured delta from a guessed one.
  */
 
 import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
@@ -173,6 +182,7 @@ export async function runProbe(projectRoot, config) {
       const slug = fm.slug || entry.name;
       const tier = fm.tier || undefined;
       const lastSync = fm.lastSync || undefined;
+      const lastCommit = fm.lastCommit || undefined;
 
       if (!lastSync) {
         metrics.stale_count++;
@@ -202,21 +212,33 @@ export async function runProbe(projectRoot, config) {
         continue;
       }
 
-      const delta = now - lastSyncMs;
+      // #1238 — the denominator. `lastCommit` is the repo's own newest activity,
+      // so `lastCommit - lastSync` measures what the mirror actually MISSED.
+      // A negative or zero delta means the sync ran at or after the newest
+      // commit: current, whatever the wall clock says.
+      const lastCommitMs = lastCommit ? Date.parse(lastCommit) : NaN;
+      const haveCommitBasis = !isNaN(lastCommitMs);
+      const basis = haveCommitBasis ? 'lastCommit' : 'probe-runtime';
+      const delta = haveCommitBasis ? lastCommitMs - lastSyncMs : now - lastSyncMs;
+
       if (delta > HOURS_24) {
         const severity = delta > HOURS_168 ? 'medium' : 'low';
         const dh = deltaHours(delta);
         metrics.stale_count++;
         findings.push({
           severity,
-          confidence: 0.9,
+          // A repo-anchored delta is a measurement; a clock-anchored one is the
+          // best available guess about a repo this probe cannot see.
+          confidence: haveCommitBasis ? 0.9 : 0.6,
           file_path: overviewPath,
           title: `[vault-staleness] ${slug}: ${formatDelta(delta)} since last sync`,
-          description:
-            `lastSync is ${formatDelta(delta)} old (threshold: 24h). ` +
-            `Note: this compares lastSync age against probe run time, not upstream lastCommit — ` +
-            `a future iteration will add repo-path resolution for a more precise delta.`,
-          evidence: { slug, tier, lastSync, delta_hours: dh },
+          description: haveCommitBasis
+            ? `The repo advanced ${formatDelta(delta)} past the last vault sync ` +
+              `(lastCommit ${lastCommit} vs lastSync ${lastSync}, threshold: 24h).`
+            : `lastSync is ${formatDelta(delta)} old (threshold: 24h). ` +
+              `No lastCommit in the frontmatter, so this compares against probe run time — ` +
+              `an idle repo reads as stale here. Add lastCommit to make the delta repo-anchored.`,
+          evidence: { slug, tier, lastSync, lastCommit, basis, delta_hours: dh },
         });
       }
     }
@@ -237,6 +259,8 @@ export async function runProbe(projectRoot, config) {
         slug: f.evidence.slug,
         severity: f.severity,
         last_sync: f.evidence.lastSync,
+        last_commit: f.evidence.lastCommit,
+        basis: f.evidence.basis,
         delta_hours: f.evidence.delta_hours,
         flag: 'stale-yes',
       })),

package/skills/discovery/probes-arch.md

@@ -8,23 +8,16 @@
 
 **Detection Method:**
 
-**Preferred (language-mapper-supported projects):**
-
-Call `extractSemanticSlices(filePath, { type: 'imports' })` from `scripts/lib/language-mappers/index.mjs` for each source file to obtain a typed list of import edges. The mapper handles TypeScript, JavaScript, and Markdown files natively; unsupported file types return an empty array (graceful degradation). Feed the resulting `{source_file -> [imported_file]}` adjacency map directly into the cycle-detection loop below.
-
-```js
-// Pseudocode — wire once per probe run
-import { extractSemanticSlices } from '$PLUGIN_ROOT/scripts/lib/language-mappers/index.mjs';
-
-for (const filePath of sourceFiles) {
-  const imports = await extractSemanticSlices(filePath, { type: 'imports' });
-  for (const { resolved } of imports) {
-    adjacency.get(filePath).push(resolved);
-  }
-}
-```
-
-**Fallback (when language-mapper returns empty or for unsupported file types):**
+> **The language-mapper does NOT produce import edges.** An earlier revision of this
+> file described a "preferred" path calling
+> `extractSemanticSlices(filePath, { type: 'imports' })`. Neither half of that call
+> exists: the real signature is
+> `extractSemanticSlices(filePath, content, options)` — the second parameter is the
+> file's CONTENT, not an options object — and `'imports'` is not a slice kind.
+> `SLICE_KINDS` (`scripts/lib/language-mappers/index.mjs`) is
+> `function | class | interface | type | export | section`; there is no import kind
+> and no `resolved` field, so no adjacency map can be built from it. The grep/madge
+> method below is the only detection method this probe has.
 
 ```bash
 # Build import graph from source files
@@ -39,7 +32,7 @@ Grep pattern: (import\s+.*from\s+["']([^"']+)["']|require\s*\(\s*["']([^"']+)["'
 npx madge --circular --extensions ts,tsx,js,jsx src/ 2>/dev/null
 ```
 
-Algorithm (cycle detection — same for both paths above):
+Algorithm (cycle detection):
 1. Build `{source_file -> [imported_file]}` adjacency map
 2. Resolve relative imports to absolute paths
 3. For each file, BFS through imports with depth limit of 10
@@ -56,6 +49,15 @@ Files Involved:
 
 **Default Severity:** High.
 
+**Related committed artefact (this repo only, and NOT a substitute):**
+`hooks/_lib/hook-import-set.json`, regenerated by
+`node scripts/generate-hook-import-set.mjs` (flags: `--plugin-root`, `--out`,
+`--check`). It records `{file, reachable_from[]}` — which modules are transitively
+reachable from a HOOK entry file — so it is a reachability allowlist scoped to
+`hooks/`, not an edge list over the whole tree, and it cannot detect cycles. Use it
+to answer "does an edit to this module reach a hook?", never as the adjacency map
+above.
+
 ---
 
 ### Probe: complexity-hotspots

package/skills/dispatcher/SKILL.md

@@ -65,7 +65,7 @@ Compute the suitability verdict for **R** via the pure four-gate engine `compute
 | `autonomy` | `resolveDispatcherAutonomy({ committed, env, ownerConfig })` from `scripts/lib/config/dispatcher-autonomy.mjs` | The effective dial. Defaults to `'off'` when unset (fail-closed). |
 | `confidenceFloor` | the `confidence-floor` from the parsed `dispatcher-autonomy:` block (default 0.5) | Same source object as `autonomy`. |
 | `confidence` | mode-selector `selectMode(signals).confidence` (0..1 float) for the recommended session-type | The same mode-selector the Phase-2 heuristic and autopilot use. |
-| `ci` | `checkCiStatus({ repoRoot: R })` → `{ status }` \| `null` | **CRITICAL (NICE-b):** Phase-1 `rank.mjs` exposes only the BARE status string (`readiness.ciStatus`). The engine's G3 gate expects an OBJECT `{ status }` — wrap it as `{ status: ciStatus }` when you HAVE a status; on a CI-fetch FAILURE pass `ci = null` (checkCiStatus already returns `null` on failure — pass it straight through). **Do NOT synthesize `{ status: undefined }`** (or `{}`): that present-but-unusable object hits the engine's MALFORMED branch (`'CI signal malformed — treated as absent'`) instead of the clean ABSENT branch (`'CI signal absent'`). Both pass G3 + warn, but `null` is the honest "no signal" — reserve the malformed branch for a genuinely unexpected shape. A bare string ALSO hits the malformed branch — always wrap or null. |
+| `ci` | `checkCiStatus({ repoRoot: R })` → `{ status }` \| `null` | **CRITICAL (NICE-b):** Phase-1 `rank.mjs` exposes only the BARE status string (`readiness.ciStatus`). The engine's G3 gate expects an OBJECT `{ status }` — wrap it as `{ status: ciStatus }` when you HAVE a status; on a genuine ABSENCE (no CI configured) pass `ci = null`. **Since #1031 `checkCiStatus` no longer returns `null` on failure** — an unreadable state comes back as `{severity:'warn', ok:false, degraded:<reason>}`, and Phase-1 `rank.mjs` surfaces exactly that as `readiness.ciDegraded` with `readiness.ciStatus === 'unknown'`. Wrap that state as `{ status: 'unknown' }` (the engine warns `'CI signal unknown — treated as absent'` and G3 still passes) rather than flattening it to `null` — `null` claims a measured absence the probe never established. **Do NOT synthesize `{ status: undefined }`** (or `{}`): that present-but-unusable object hits the engine's MALFORMED branch (`'CI signal malformed — treated as absent'`) instead of the clean ABSENT branch (`'CI signal absent'`). Both pass G3 + warn, but `null` is the honest "no signal" — reserve the malformed branch for a genuinely unexpected shape. A bare string ALSO hits the malformed branch — always wrap or null. |
 | `resourceVerdict` | the host resource verdict string (`'green'\|'warn'\|'degraded'\|'critical'`) from `rank.mjs` (`readiness.resourceVerdict`) or a fresh `evaluate(probe(), thresholds).verdict` | Host-level — already fetched once in Phase 1. **NICE-b:** on a genuine probe FAILURE (no signal), prefer `resourceVerdict = null` over synthesizing `'green'`. `null` = "no signal" ⇒ G4 passes + warns (`'resource signal absent'`) — honest. Synthesizing `'green'` fabricates a positive signal the host never reported and can let an autonomous launch proceed against an unknown host state. Pass the real verdict string when you have one; `null` when you do not. |
 | `recentRuns` | `readRecentAutopilotRuns({ repoRoot: R })` from `scripts/lib/autopilot/recent-runs.mjs` | NEW reader. Reads `<R>/.orchestrator/metrics/autopilot.jsonl`, returns the most-recent records (newest-last), never throws (`[]` on missing/unreadable). Pass the TRUE count — the engine's G2 gate omits-with-warn below 5 runs and otherwise checks `fired/N < 0.2`. |
 
@@ -167,7 +167,8 @@ Data → stdout, warnings/errors → stderr (never mixed). Exit codes follow `.c
 - **Running this from a subagent** — coordinator-only (AUQ is unavailable in subagents).
 - **Fail-OPEN verdict gate (#682)** — keying the autonomous launch on `verdict.suitable` alone (ignoring `autonomy === 'autonomous-gated'`) auto-launches in `advisory`/`off` mode. ALWAYS gate on BOTH.
 - **Feeding the bare CI string into the engine** — `rank.mjs` exposes `ciStatus` as a bare string; `computeSuitabilityVerdict` wants `{ status }`. Wrap it (`{ status: ciStatus }`) or pass `null` — a bare string silently hits the malformed-absent branch. A red CI fed as a bare string would PASS G3 (masked as malformed) instead of forcing the FORCED-fail branch (NICE-c).
-- **Synthesizing an absent signal instead of passing `null` (NICE-b)** — on a CI-fetch or resource-probe failure, pass `ci = null` / `resourceVerdict = null` (honest "no signal" ⇒ gate passes + warns). Do NOT synthesize `{ status: undefined }` (hits the malformed branch) and do NOT fabricate `'green'` / `{ status: 'green' }` (invents a positive signal the host never reported and can green-light an autonomous launch against an unknown state).
+- **Flattening a DEGRADED CI reading to `null` (#1031)** — `readiness.ciDegraded` set (⇒ `readiness.ciStatus === 'unknown'`) means the state could NOT be read, which is weaker than absence, not equal to it. Pass `{ status: 'unknown' }`; `null` asserts a measured absence nothing established.
+- **Synthesizing an absent signal instead of passing `null` (NICE-b)** — on a resource-probe failure, pass `resourceVerdict = null` (honest "no signal" ⇒ gate passes + warns). Do NOT synthesize `{ status: undefined }` (hits the malformed branch) and do NOT fabricate `'green'` / `{ status: 'green' }` (invents a positive signal the host never reported and can green-light an autonomous launch against an unknown state).
 - **Pre-truncating `recentRuns` below 5** — passing fewer than the true on-disk count when ≥ 5 runs exist falsely triggers the engine's <5-run omission branch and skips the kill-switch gate. Pass the TRUE count; never call `readRecentAutopilotRuns` with `limit < 5` on the launch-gate read (the reader honours a small `limit` literally and will not clamp it upward).
 - **Auto-launching against a non-green verdict** — a CI-red / resource-critical / low-confidence verdict ALWAYS falls to inform + ask, even under `autonomous-gated`. Never proceed straight to claim on a non-suitable verdict.