session-orchestrator 3.24.0 → 4.0.0

package/scripts/wave-scope-binding.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * wave-scope-binding.mjs — print the session binding for a `wave-scope.json`
+ * manifest, and record the fail-closed case as an event (#1153 P4).
+ *
+ * Usage:
+ *   node scripts/wave-scope-binding.mjs [--merge] [--wave N] [--role R] [--repo-root DIR]
+ *
+ * Prints ONE JSON object on stdout:
+ *
+ *   {"session_id":"<raw session_id>","semantic_session_id":"<semantic id>"}
+ *
+ * Those key names are the canonical ones since #1153 P2 — the same spelling
+ * `.orchestrator/session.lock` and `current-session.json` already use. Readers
+ * additionally accept the pre-#1153 `session` / `semantic_session` spellings
+ * until the next minor release (`MANIFEST_SESSION_KEYS` in
+ * `scripts/lib/session-identity/own-session.mjs`); this writer never emits them.
+ *
+ * Keys whose value is unavailable are OMITTED, never written as `""` — an empty
+ * id is present-but-equal-to-nobody, which every reader classifies as FOREIGN
+ * (the one disposition that skips enforcement entirely), and
+ * `validate-wave-scope.mjs` rejects it outright.
+ *
+ * WHY A COMMAND AND NOT PROSE: this binding used to be an inline
+ * `node --input-type=module -e` block in `skills/wave-executor/wave-loop.md`,
+ * retyped by the coordinator once per wave. An unbound manifest (`{}`) is the
+ * fail-closed direction and therefore SILENT — indistinguishable from a
+ * coordinator that skipped the step. `orchestrator.scope.unbound_manifest` is
+ * what makes the silent case countable; 0 hits repo-wide before this file.
+ *
+ * The binding itself is NOT recomputed here. It is exactly one
+ * `attributionForRecord()` call, which reads `.orchestrator/session.lock` and
+ * confirms the raw `session_id` against this process's own identity before
+ * returning anything — under a peer-owned lock it returns `{}` rather than the
+ * peer's ids. Duplicating that logic would be the one-fact-two-copies class this
+ * repo keeps paying for.
+ */
+
+import { parseArgs } from 'node:util';
+import { resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { attributionForRecord, emitEvent } from './lib/events.mjs';
+import { MANIFEST_SESSION_KEYS } from './lib/session-identity/own-session.mjs';
+
+const HELP = `Usage: node scripts/wave-scope-binding.mjs [--merge] [--wave N] [--role R] [--repo-root DIR]
+
+Print the session-binding keys for a wave-scope.json manifest as one JSON object.
+Empty values are OMITTED; an unbound binding prints {} and emits exactly one
+orchestrator.scope.unbound_manifest event.
+
+With --merge, read the DRAFT manifest as one JSON object on stdin and print that
+same manifest with the binding keys merged in (or with them omitted, plus the
+unbound event, when the binding is {}). Every other field is passed through.
+
+Options:
+  --merge             Read the draft manifest on stdin, print it bound.
+  --wave <n>          Wave number, recorded in the unbound event payload.
+  --role <role>       Wave role, recorded in the unbound event payload.
+  --repo-root <dir>   Repo root to resolve the lock and the events log against
+                      (default: process.cwd()).
+  -h, --help          Show this help and exit 0.
+
+Output:
+  stdout — exactly one JSON object. Diagnostics go to stderr.
+`;
+
+/**
+ * Resolve the manifest binding for `repoRoot`.
+ *
+ * @param {string} repoRoot
+ * @returns {{ session_id?: string, semantic_session_id?: string }} binding with
+ *   empty values omitted
+ */
+export function resolveBinding(repoRoot) {
+  const attribution = attributionForRecord(repoRoot) ?? {};
+  /** @type {{ session_id?: string, semantic_session_id?: string }} */
+  const out = {};
+  const session = typeof attribution.session_id === 'string' ? attribution.session_id.trim() : '';
+  const semantic = typeof attribution.semantic_session_id === 'string'
+    ? attribution.semantic_session_id.trim()
+    : '';
+  if (session) out.session_id = session;
+  if (semantic) out.semantic_session_id = semantic;
+  return out;
+}
+
+async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        wave: { type: 'string' },
+        role: { type: 'string' },
+        'repo-root': { type: 'string' },
+        merge: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+      },
+      allowPositionals: false,
+    });
+  } catch (error) {
+    process.stderr.write(`wave-scope-binding: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.stderr.write(HELP);
+    process.exitCode = 2;
+    return;
+  }
+
+  if (parsed.values.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const repoRoot = parsed.values['repo-root'] ?? process.cwd();
+  const binding = resolveBinding(repoRoot);
+
+  if (Object.keys(binding).length === 0) {
+    // The fail-closed case, and the whole reason this is a command: an unbound
+    // manifest enforces against EVERY session in the checkout, and until now it
+    // left no trace at all. Best-effort — the binding is still printed if the
+    // append fails, because a broken events log must not stall a wave.
+    try {
+      await emitEvent(
+        'orchestrator.scope.unbound_manifest',
+        {
+          // Numeric when it parses as one, so the field matches every other
+          // `wave` in the stream; `null` (never `undefined`) when absent, since
+          // an undefined `wave` lets emitEvent's correlation envelope fill it
+          // from the live manifest — the very artefact this event says is
+          // unbound.
+          wave: Number.isFinite(Number(parsed.values.wave)) && parsed.values.wave !== undefined
+            ? Number(parsed.values.wave)
+            : (parsed.values.wave ?? null),
+          role: parsed.values.role ?? null,
+          reason: 'no-confirmed-session-attribution',
+        },
+        { repoRoot },
+      );
+    } catch (error) {
+      process.stderr.write(
+        `wave-scope-binding: could not record unbound_manifest event: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+    }
+  }
+
+  if (!parsed.values.merge) {
+    process.stdout.write(`${JSON.stringify(binding)}\n`);
+    return;
+  }
+
+  // --merge: the coordinator pipes the draft manifest in and gets the SAME
+  // manifest back with the binding merged, instead of hand-copying two keys
+  // out of the printed object into the JSON it is about to write (#1207).
+  let draftRaw;
+  try {
+    draftRaw = await readStdin();
+  } catch (error) {
+    process.stderr.write(
+      `wave-scope-binding: could not read the draft manifest from stdin: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let draft;
+  try {
+    draft = JSON.parse(draftRaw);
+  } catch {
+    process.stderr.write('wave-scope-binding: --merge expects ONE JSON object on stdin\n');
+    process.exitCode = 1;
+    return;
+  }
+  if (!draft || typeof draft !== 'object' || Array.isArray(draft)) {
+    process.stderr.write('wave-scope-binding: --merge expects ONE JSON object on stdin\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Any binding key already in the draft is dropped first: under an unbound or
+  // peer-owned lock the merged manifest must name NOBODY, and a stale key
+  // surviving the merge would name somebody. Omitted, never `""` — see above.
+  // BOTH spellings are dropped (close-review 2026-09-04, HIGH): a legacy
+  // `session`/`semantic_session` pair surviving the merge is still READ by every
+  // consumer and would name a foreign session — `foreign` = gates stand down.
+  const merged = { ...draft };
+  for (const key of [...MANIFEST_SESSION_KEYS.current, ...MANIFEST_SESSION_KEYS.legacy]) delete merged[key];
+  // Explicit per-key copy, never Object.assign: `merged` derives from a
+  // JSON.parse'd draft, and a `__proto__` payload key would reach the
+  // Object.prototype setter through [[Set]] semantics (CWE-1321, semgrep
+  // prototype-pollution-object-assign — CI-red on ce6a28aa).
+  for (const key of MANIFEST_SESSION_KEYS.current) {
+    if (typeof binding[key] === 'string' && binding[key]) merged[key] = binding[key];
+  }
+  process.stdout.write(`${JSON.stringify(merged)}\n`);
+}
+
+/**
+ * Read all of stdin as UTF-8. Resolves to `''` when stdin is closed/empty.
+ * @returns {Promise<string>}
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => resolve(buf));
+    process.stdin.on('error', reject);
+  });
+}
+
+// `import.meta.main` is not available on every supported Node — compare argv[1]
+// instead, so importing this module from a test never runs the CLI.
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
+  await main(process.argv.slice(2));
+}

package/skills/_shared/instruction-file-resolution.md

@@ -28,6 +28,16 @@ Apply these steps in order against the repo root. Stop at the first hit. Never m
 - Never read both files. Never concatenate, diff, or cross-validate them — the SSOT is whichever the rule selects.
 - The resolved kind (`claude` | `agents`) is part of the contract. Consumers that report paths in JSON output (e.g., `skills/claude-md-drift-check/checker.mjs`) must surface the resolved path so users on either platform can audit the result.
 
+## Interaction with the root `AGENTS.md` this repo now ships
+
+Since the cross-harness portable surface landed, this repo carries BOTH files at its root. That does not weaken the rule above — it is what makes the rule safe to hold while still serving foreign readers:
+
+- **Our own readers still never read both.** `resolveInstructionFile()` picks exactly one (`CLAUDE.md` wins ties), and every consumer listed below goes through it. Nothing merges, diffs, or cross-validates the two as sources.
+- **The root `AGENTS.md` exists for FOREIGN readers**, not for ours. 7 of 8 surveyed harnesses (Codex CLI, Cursor, Copilot CLI, OpenCode, Amp, Kiro, …) read `AGENTS.md`; only Claude Code reads `CLAUDE.md`, and only Copilot CLI reads both. Without a root `AGENTS.md` this repo's `## Session Config` was unreachable from six of them.
+- **It is byte-identical by construction, and generated.** `scripts/generate-agents-skills.mjs` copies `CLAUDE.md` verbatim; `--check` (wired into `scripts/validate-plugin.mjs`) fails CI on any divergence. **Never edit `AGENTS.md`** — edit `CLAUDE.md` and regenerate. A consumer repo may instead symlink it; both shapes are accepted by the drift gate.
+- **Why a copy and not a symlink here:** `package.json` `files[]` does not publish `CLAUDE.md`, so a symlink would be DANGLING in the npm tarball; and `core.symlinks` defaults to false on Windows without Developer Mode, where git materialises the link as a 10-byte regular file containing the literal text `CLAUDE.md` — a pointer with no Session Config, which is precisely the failure this file guards against.
+- **The invariant is "the two cannot disagree", not "exactly one file exists."** `claude-md-drift-check` Check 7 (`vault-dir-parity`) enforces it: alias-by-construction → parity satisfied; two independent files that diverge → error. Check 9's probe 2a uses the same predicate so a defect in `CLAUDE.md` is never reported twice.
+
 ## Reference implementations
 
 ### Bash one-liner (matches `skills/_shared/bootstrap-gate.md` style)

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                                 |