session-orchestrator 4.1.0 → 4.2.0

package/scripts/lib/validate/check-skill-script-paths.mjs

@@ -3,11 +3,13 @@
  * Check: every `scripts/**.mjs` path cited in `skills/`, `commands/`,
  * `agents/` and `docs/` either EXISTS or is annotated as deliberately absent
  * (#1176). Extended (#1187) to also cite `scripts/**.sh` and `hooks/**.sh` —
- * see "## Mode: BLOCKING for `.mjs`, ADVISORY for `.sh`" below for why that
+ * see "## Mode" below for why that
  * half is advisory, not blocking. `docs/` joined `SCAN_DIRS` in #1208, after
  * the 22 dead paths it carried at the time (9 `.mjs`, all ADR/reference
  * prose) were annotated — see that section below for the census and why
  * widening the scan root had to wait for the annotation pass, not precede it.
+ * #1241 adds blocking repo-rooted `.md` paths quoted as complete inline-code
+ * spans, with the same annotations and fence handling. Scan roots stay fixed.
  *
  * ## Why
  *
@@ -50,7 +52,7 @@
  * looking misplaced. A malformed marker (unknown class, or `planned` without a
  * `#<iid>`) is itself a finding for the same reason — it must never fail silent.
  *
- * ## Mode: BLOCKING for `.mjs`, ADVISORY for `.sh` (#1187)
+ * ## Mode: BLOCKING for `.mjs` / `.md`, ADVISORY for `.sh` (#1187)
  *
  * Unlike `check-doc-cli-commands.mjs`, the oracle here is the repository's own
  * filesystem, not a locally installed third-party binary — there is no version
@@ -115,6 +117,22 @@ export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs'])
  */
 const CITATION_RE = /scripts\/[a-zA-Z0-9_/-]*\.(?:mjs|sh)|hooks\/[a-zA-Z0-9_/-]*\.sh/g;
 
+/**
+ * A complete inline-code span, including spans delimited by multiple backticks.
+ * Consume the outer span before judging its content, so a quoted command that
+ * contains backticks cannot donate a nested path-looking substring.
+ */
+const INLINE_CODE_RE = /(?<!`)(`+)(.+?)(?<!`)\1(?!`)/g;
+
+/**
+ * #1241's bounded grammar: a literal repo-rooted .md path, optionally followed
+ * by :line, :line:end / :line-end, and #anchor. Only the file is checked.
+ * URLs, commands, absolute paths, skill-relative references/, variables and
+ * globs are outside this grammar. Matching is line-local; revisit if the
+ * instruction corpus adopts multiline path spans or another target root.
+ */
+const MARKDOWN_CITATION_RE = /^((?:docs|skills|commands|agents|templates|rules|scripts|hooks|tests|\.(?:claude|codex|cursor|pi|orchestrator|gitlab|github))\/[a-zA-Z0-9_./-]+\.md)(?::\d+(?:[:-]\d+)?)?(?:#[^\s`]+)?$/;
+
 /**
  * Filename fragments that mark a citation as an ILLUSTRATIVE placeholder —
  * `scripts/example.sh`, `hooks/my-hook.sh`, `scripts/<name>.sh` — rather than
@@ -211,6 +229,10 @@ export function extractCitations(lines) {
     for (const hit of raw.matchAll(CITATION_RE)) {
       citations.push({ line: lineNumber, path: hit[0] });
     }
+    for (const span of raw.matchAll(INLINE_CODE_RE)) {
+      const hit = span[2].match(MARKDOWN_CITATION_RE);
+      if (hit) citations.push({ line: lineNumber, path: hit[1] });
+    }
   };
 
   // A blockquoted fence is still a fence — the shared tracker strips the `>`
@@ -234,12 +256,12 @@ export function extractCitations(lines) {
 
 /**
  * Census the documentation corpus for dead `scripts/**.mjs`/`.sh` and
- * `hooks/**.sh` citations.
+ * `hooks/**.sh` citations, plus repo-rooted `.md` inline-code paths.
  *
  * @param {{pluginRoot: string, dirs?: string[], strictSh?: boolean}} options
  *   `strictSh` (default `false`) promotes a dead `.sh` citation from
  *   `severity: 'warn'` to `severity: 'fail'` — see the module docblock
- *   "Mode: BLOCKING for `.mjs`, ADVISORY for `.sh`" for why the default stays
+ *   "Mode" for why the default stays
  *   advisory in this release.
  * @returns {{ok: boolean, summary: object, findings: {kind: string, file: string, line: number, path: string, annotation: string | null, message: string, severity: 'fail' | 'warn'}[], toolError: boolean}}
  */
@@ -344,10 +366,11 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
         summary.existing += 1;
         continue;
       }
-      // An illustrative placeholder name needs no marker — see
+      // A script placeholder name needs no marker — see
       // `isPlaceholderCitation`'s docblock for the closed fragment list and
-      // its named ceiling.
-      if (isPlaceholderCitation(citation.path)) {
+      // its named ceiling. Markdown examples require explicit annotations:
+      // a real missing docs/foobar.md must not disappear because of its name.
+      if (path.extname(citation.path) !== '.md' && isPlaceholderCitation(citation.path)) {
         summary.placeholders += 1;
         continue;
       }
@@ -366,7 +389,7 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
       }
       if (marker && !marker.ok) continue; // already reported as bad-annotation
 
-      // `.mjs` is blocking exactly as before this module grew a `.sh` half.
+      // `.mjs` and `.md` are blocking.
       // `.sh` is advisory (`warn`) unless the caller opted into `strictSh`.
       const isSh = path.extname(citation.path) === '.sh';
       const severity = isSh && !strictSh ? 'warn' : 'fail';
@@ -405,7 +428,7 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
  * @returns {number} 0 = clean, 1 = findings, 2 = tool error
  */
 export function runCheckSkillScriptPaths(pluginRoot, { strictSh = false } = {}) {
-  console.log('--- Check: scripts/*.mjs (+ *.sh) paths cited in skills/commands/agents exist ---');
+  console.log('--- Check: script and Markdown paths cited in skills/commands/agents/docs exist ---');
   const inspection = scanSkillScriptPaths({ pluginRoot, strictSh });
 
   for (const item of inspection.findings) {
@@ -427,7 +450,7 @@ export function runCheckSkillScriptPaths(pluginRoot, { strictSh = false } = {})
   const blockingCount = inspection.findings.filter((f) => f.severity !== 'warn').length;
   if (inspection.ok) {
     console.log(
-      `  PASS: ${s.citations} script citation(s) in ${s.filesScanned} doc file(s) — ` +
+      `  PASS: ${s.citations} file citation(s) in ${s.filesScanned} doc file(s) — ` +
         `${s.existing} exist, ${s.annotated} annotated as deliberately absent, ` +
         `${s.placeholders} placeholder(s)` +
         (s.warnings > 0 ? `, ${s.warnings} advisory .sh warning(s) (see --strict-sh)` : ''),

package/scripts/lib/validate/check-unwired-features.mjs

@@ -114,8 +114,9 @@
  * `CHANGELOG.md` is excluded from the prose corpus for the same reason: it is an
  * append-only record of what a PAST release shipped, so it names the symbols of
  * code that may since have died. Counting it silenced a true positive
- * (`soul-resolve.mjs`, whose only live claim is in `.claude/rules/owner-persona.md`
- * but whose symbols appear in a 2026-06 changelog entry).
+ * (`soul-resolve.mjs` — since DELETED as dead: its only live claim was in
+ * `.claude/rules/owner-persona.md`, while its symbols appeared in a 2026-06
+ * changelog entry).
  *
  * ## S4 `unreachable-library-module` — the question the machine can answer
  *
@@ -777,11 +778,11 @@ function mentionedModuleTokens(lines) {
  * ## Cluster roots — one defect, one line
  *
  * Only the ROOT of each unreachable cluster is reported: a module no OTHER
- * unreachable module references. `scripts/lib/owner-config.mjs` has no importer
- * and drags its whole 7-file `owner-config/` subtree down with it; reporting the
- * six interior files would multiply one deletion into seven findings that all
- * disappear together. Measured on the live tree: 71 unreachable modules collapse
- * to 50 roots. This is category separation in the sense of
+ * unreachable module references. A drag-cluster looks like this: an unimported
+ * top-level module whose own subtree of interior files goes down with it —
+ * reporting the interior files too would multiply one deletion into N findings
+ * that all disappear together. Measured on the live tree: 71 unreachable modules
+ * collapse to 50 roots. This is category separation in the sense of
  * `.claude/rules/development.md` § Guard & Threshold Design — a structural split,
  * never a raised threshold.
  *

package/scripts/lib/vault-mirror/process.mjs

@@ -879,7 +879,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // This is deliberately REDUNDANT with the renderer's status mapping (#909,
   // render-sessions.mjs) — see that module's header. The filter removes one
   // status from the vault; the mapping keeps every OTHER status honest, and
-  // guards the generators' other entry point (the render.mjs barrel).
+  // guards the generators' other entry point (this module imports
+  // render-learnings.mjs and render-sessions.mjs directly — no barrel).
   if (!isRealSession(entry)) {
     return emitEntryAction(_lineNum, ctx, {
       action: 'skipped-abandoned',

package/scripts/lib/vault-status/narrative-mirror.mjs

@@ -1,7 +1,7 @@
 /**
  * narrative-mirror.mjs — Durable per-repo narrative mirror (Epic #673 Phase 1, #675).
  *
- * At session-end, extract from a repo's `.claude/STATE.md` the DURABLE narrative —
+ * At session-end, extract from a repo's active `STATE.md` the DURABLE narrative —
  * `## Wave History`, `## Deviations`, `## What Not To Retry`, plus the mission-status
  * rollup — and idempotently mirror it into a generator-owned per-repo vault file, so a
  * reviewer or stand-in can read PER REPO what was done, what failed, and what not to
@@ -31,7 +31,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
-import { parseStateMd, parseMissionStatus } from '../state-md.mjs';
+import { parseStateMd, parseMissionStatus, resolveStateMdPath } from '../state-md.mjs';
 import {
   parseFrontmatter,
   toDate,
@@ -328,7 +328,7 @@ export function renderNarrative(opts) {
   lines.push(`# ${repo ?? 'unknown'} — Session Narrative`);
   lines.push('');
   lines.push(
-    '> Durable per-repo narrative mirrored from `.claude/STATE.md` (Epic #673). ' +
+    '> Durable per-repo narrative mirrored from the repo\'s active `STATE.md` (Epic #673). ' +
       'What was done, what failed, and what not to retry — readable without opening the repo.',
   );
   lines.push('');
@@ -909,7 +909,7 @@ async function runNarrativeMirror(opts) {
   }
 
   // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
-  const stateMdPath = path.join(repoRoot, '.claude', 'STATE.md');
+  const stateMdPath = resolveStateMdPath(repoRoot);
   let stateContents;
   try {
     stateContents = await readFile(stateMdPath, 'utf8');

package/scripts/lib/wave-resource-gate.mjs

@@ -8,6 +8,7 @@
  */
 
 import { probe, evaluate } from './resource-probe.mjs';
+import { resolveAgentCap } from './session-shape.mjs';
 
 /**
  * Wave roles that may run on a declared remote host, mapped to the
@@ -194,7 +195,10 @@ async function applyOffloadDecision(result, opts) {
   // ceiling, which is a property of the REPO and holds wherever the wave runs.
   // Restoring plannedAgents unconditionally here would let a heavy repo exceed
   // its own cap by way of a remote host.
-  const cap = config?.['heavy-repo'] === true ? resolveApwCap(config['agents-per-wave']) : null;
+  const cap =
+    config?.['heavy-repo'] === true
+      ? resolveAgentCap(config['agents-per-wave'], MODE_BLIND_SESSION_TYPE)
+      : null;
   const agents = cap === null ? plannedAgents : Math.min(plannedAgents, cap);
 
   return {
@@ -210,42 +214,34 @@ async function applyOffloadDecision(result, opts) {
 }
 
 /**
- * Resolve an `agents-per-wave` config value into a plain numeric cap, or
- * `null` when no cap should apply.
+ * The session type this module resolves `agents-per-wave` FOR: none.
  *
  * `_coerceInteger()` (scripts/lib/config/coercers.mjs) parses the documented
  * HR-003 parenthetical-override syntax — `agents-per-wave: 4 (deep: 18)` —
- * into an OBJECT `{ default: 4, deep: 18 }`, not a plain number. Feeding that
- * object straight into a `typeof cap !== 'number'` guard makes the heavy-repo
- * cap silently no-op for every repo using the override syntax, which defeats
- * HR-004 exactly where it matters most (a heavy repo that also runs deep
- * sessions).
+ * into an OBJECT `{ default: 4, deep: 18 }`, not a plain number, so the cap
+ * must be resolved rather than type-guarded (a bare `typeof cap !== 'number'`
+ * check no-ops HR-004 for every repo using the override syntax).
  *
- * `evaluateWaveResourceGate()` has no session-mode input in scope — `waveRole`
- * is a wave role (e.g. "Impl-Core"), not a session mode (e.g. "deep") — so the
- * object shape resolves to `cap.default` here. That is the conservative
- * choice: the documented HR-003 convention writes the override as
- * `<default> (mode: <higher-ceiling>)`, i.e. `default` is the MORE
- * restrictive of the pair. Falling back to it can only under-apply a looser
- * mode-specific ceiling; it never lets a heavy repo exceed its base cap.
+ * This gate has NO session mode in scope — `waveRole` is a wave role (e.g.
+ * "Impl-Core"), never a session mode (e.g. "deep") — so it deliberately asks
+ * `resolveAgentCap` for no type and takes the `.default` fallback. That is the
+ * conservative reading: the HR-003 convention writes the override as
+ * `<default> (mode: <higher-ceiling>)`, i.e. `default` is the MORE restrictive
+ * of the pair. Under-applying a looser mode-specific ceiling is safe; passing a
+ * guessed `'deep'` here would silently RAISE a heavy repo's ceiling to the deep
+ * override, which is the bug this named constant exists to make un-writable.
  *
- * @param {number|{default: number, [mode: string]: number}|*} cap
- * @returns {number|null}
+ * @type {undefined}
  */
-function resolveApwCap(cap) {
-  if (typeof cap === 'number') return Number.isFinite(cap) ? cap : null;
-  if (cap !== null && typeof cap === 'object' && !Array.isArray(cap)) {
-    const def = cap.default;
-    return typeof def === 'number' && Number.isFinite(def) ? def : null;
-  }
-  return null;
-}
+const MODE_BLIND_SESSION_TYPE = undefined;
 
 /**
  * HR-003/HR-004 heavy-repo preflight ceiling (baseline #60). A STATIC cap
  * independent of the live resource-probe verdict: when `config['heavy-repo']`
  * is `true`, `agents` is clamped to at most `config['agents-per-wave']`
- * (resolved via {@link resolveApwCap} to handle the object-override shape).
+ * (resolved via `resolveAgentCap` from `./session-shape.mjs` — the ONE exported
+ * copy of that resolver — to handle the object-override shape; see
+ * {@link MODE_BLIND_SESSION_TYPE} for why no session type is passed).
  * More-restrictive-wins — this only ever LOWERS `agents`, never raises it
  * above what the resource-driven rules already decided (e.g. a
  * coordinator-direct 0 stays 0).
@@ -257,7 +253,7 @@ function resolveApwCap(cap) {
 function applyHeavyRepoCap(result, opts) {
   const { config } = opts;
   if (!config || config['heavy-repo'] !== true) return result;
-  const cap = resolveApwCap(config['agents-per-wave']);
+  const cap = resolveAgentCap(config['agents-per-wave'], MODE_BLIND_SESSION_TYPE);
   if (cap === null) return result;
   if (result.agents <= cap) return result; // already within the ceiling — never raise
   return {

package/scripts/lib/wave-sizing.mjs

@@ -3,10 +3,17 @@
  * Learning: coordinator-over-worktree-on-shared-files caused back-to-back regressions.
  */
 
-// 'unknown' is accepted because scripts/lib/session-close-backfill.mjs writes it for records whose
+// SSOT for the session-type enum. It used to be RE-DECLARED here while this very comment named
+// constants.mjs as the source of truth — two literals that agreed only by luck (and already
+// differed in member order). The direction of the dependency is forced: constants.mjs declares
+// itself a leaf ("no imports from siblings or parent") and mentions wave-sizing.mjs only in prose,
+// so this module imports, never the reverse; no cycle exists in either direction.
+//
+// 'unknown' is a member because scripts/lib/session-close-backfill.mjs writes it for records whose
 // type it could not measure (4.0.0). It is NOT a mode anyone selects — isolation resolves as for
-// 'deep' (the conservative end). SSOT for the ledger enum: scripts/lib/session-schema/constants.mjs.
-const VALID_SESSION_TYPES = ['housekeeping', 'feature', 'deep', 'unknown'];
+// 'deep' (the conservative end).
+import { VALID_SESSION_TYPES } from './session-schema/constants.mjs';
+
 const VALID_COLLISION_RISKS = ['low', 'medium', 'high'];
 const VALID_CONFIG_ISOLATIONS = ['auto', 'worktree', 'none'];
 const VALID_ENFORCEMENTS = ['strict', 'warn', 'off'];

package/scripts/materialize-wave-scope.mjs

@@ -22,7 +22,7 @@
  * `allowedPaths` never grants a peer's territory to this wave's agents.
  */
 
-import { readdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeJsonAtomicSync } from './lib/io.mjs';
@@ -49,6 +49,12 @@ Options:
                       it, orphans are reported and RETAINED, never deleted.
   --json              Emit {ok, aggregatePath, perAgentPaths, removedOrphans,
                       retainedOrphans} to stdout.
+  --warn-missing      Warn on stderr about absent concrete scope paths, resolved
+                      from the project working directory (not --state-dir).
+                      Glob/prefix grants containing * or ending / are skipped.
+  --new-file <path>   Suppress a missing-path warning for an intended new file.
+                      Repeatable; each path must exactly match a declared scope
+                      path and pass scope validation, even without --warn-missing.
   -h, --help          Show this help and exit 0.
 
 Output:
@@ -85,13 +91,16 @@ class WriteError extends Error {}
 
 /**
  * @param {string[]} argv
- * @returns {{ stateDir: string, wave: number, session: string|null, json: boolean, help: boolean }}
+ * @returns {{ stateDir: string, wave: number, session: string|null, json: boolean,
+ *             warnMissing: boolean, newFiles: string[], help: boolean }}
  */
 export function parseCliArgs(argv) {
   let stateDir;
   let waveRaw;
   let session = null;
   let json = false;
+  let warnMissing = false;
+  const newFiles = [];
   let help = false;
 
   for (let index = 0; index < argv.length; index++) {
@@ -100,16 +109,22 @@ export function parseCliArgs(argv) {
       json = true;
       continue;
     }
+    if (arg === '--warn-missing') {
+      warnMissing = true;
+      continue;
+    }
     if (arg === '--help' || arg === '-h') {
       help = true;
       continue;
     }
-    if (arg === '--state-dir' || arg === '--wave' || arg === '--session') {
+    if (arg === '--state-dir' || arg === '--wave' || arg === '--session' || arg === '--new-file') {
       const value = argv[index + 1];
       if (value === undefined || value.startsWith('--')) {
         throw new InputError(`${arg} requires a value`);
       }
-      if (arg === '--state-dir') {
+      if (arg === '--new-file') {
+        newFiles.push(value);
+      } else if (arg === '--state-dir') {
         if (stateDir !== undefined) throw new InputError('--state-dir may be specified only once');
         stateDir = value;
       } else if (arg === '--session') {
@@ -128,7 +143,7 @@ export function parseCliArgs(argv) {
     throw new InputError(`unknown argument: ${arg}`);
   }
 
-  if (help) return { stateDir: '', wave: 0, session, json, help: true };
+  if (help) return { stateDir: '', wave: 0, session, json, warnMissing, newFiles, help: true };
   if (stateDir === undefined) throw new InputError('--state-dir is required');
   if (waveRaw === undefined) throw new InputError('--wave is required');
   if (stateDir.length === 0 || /[\0\r\n]/.test(stateDir)) {
@@ -140,7 +155,7 @@ export function parseCliArgs(argv) {
 
   const wave = Number(waveRaw);
   if (!Number.isSafeInteger(wave)) throw new InputError('--wave must be a safe positive integer');
-  return { stateDir, wave, session, json, help: false };
+  return { stateDir, wave, session, json, warnMissing, newFiles, help: false };
 }
 
 /**
@@ -157,18 +172,17 @@ function isRecord(value) {
  * are rejected because no scope consumer can safely interpret them verbatim.
  *
  * @param {unknown} value
- * @param {number} recordIndex
- * @param {number} fileIndex
+ * @param {string} description
  */
-function validateScopePath(value, recordIndex, fileIndex) {
+function validateScopePath(value, description) {
   if (typeof value !== 'string' || value.length === 0 || value.trim().length === 0) {
-    throw new InputError(`record #${recordIndex} files[${fileIndex}] must be a non-empty string`);
+    throw new InputError(`${description} must be a non-empty string`);
   }
   if (/[\0\r\n]/.test(value)) {
-    throw new InputError(`record #${recordIndex} files[${fileIndex}] must not contain NUL or newline characters`);
+    throw new InputError(`${description} must not contain NUL or newline characters`);
   }
   if (value.split(/[\\/]+/).includes('..')) {
-    throw new InputError(`record #${recordIndex} files[${fileIndex}] must not contain path traversal`);
+    throw new InputError(`${description} must not contain path traversal`);
   }
 }
 
@@ -210,7 +224,7 @@ export function validateScopeRecords(value) {
       throw new InputError(`record #${recordIndex} (${record.id}) must have a files string array`);
     }
     for (let fileIndex = 0; fileIndex < record.files.length; fileIndex++) {
-      validateScopePath(record.files[fileIndex], recordIndex, fileIndex);
+      validateScopePath(record.files[fileIndex], `record #${recordIndex} files[${fileIndex}]`);
     }
   }
 
@@ -220,6 +234,42 @@ export function validateScopeRecords(value) {
   return value;
 }
 
+/**
+ * Validate exceptions before any published declarations can be invalidated.
+ * Keep exact spelling: these are diagnostic exceptions, never scope rewrites.
+ *
+ * @param {string[]} newFiles
+ * @param {Array<{id: string, files: string[]}>} records
+ * @returns {Set<string>}
+ */
+function validateNewFiles(newFiles, records) {
+  const declared = new Set(records.flatMap(({ files }) => files));
+  for (const file of newFiles) {
+    validateScopePath(file, '--new-file');
+    if (!declared.has(file)) throw new InputError(`--new-file path is not declared in scope records: ${file}`);
+  }
+  return new Set(newFiles);
+}
+
+/**
+ * Missing-file diagnostics are opt-in and never change scope grants or stdout.
+ * `*` and trailing `/` are the scope consumer's glob/prefix grammar; `?` and
+ * braces are literal names (scripts/lib/scope-gate.mjs isGlobScopeEntry).
+ *
+ * @param {Array<{id: string, files: string[]}>} records
+ * @param {Set<string>} newFiles
+ */
+function warnMissingPaths(records, newFiles) {
+  for (const { id, files } of records) {
+    for (const file of files) {
+      if (newFiles.has(file) || file.includes('*') || file.endsWith('/')) continue;
+      if (!existsSync(resolve(file))) {
+        process.stderr.write(`materialize-wave-scope: WARN ${id}: declared path not found: ${file}\n`);
+      }
+    }
+  }
+}
+
 
 /**
  * Read the session ids the sibling manifest `<state-dir>/wave-scope.json`
@@ -462,14 +512,18 @@ export function main() {
       return;
     }
     const records = validateScopeRecords(readStdinJson());
+    const newFiles = validateNewFiles(args.newFiles, records);
     const { aggregatePath, perAgentPaths, removedOrphans, retainedOrphans } =
       materializeWaveScope(records, args);
 
+    if (args.warnMissing) warnMissingPaths(records, newFiles);
+
     // stderr carries ONLY the anomalous cases. Measured constraint, not taste:
     // the corpus pins byte-empty stderr on this command's success path
     // (tests/scripts/materialize-wave-scope.test.mjs and
     // tests/integration/wave-scope-producer.test.mjs), and a wave with no
-    // orphans IS the success path. Both lists always reach --json.
+    // orphans IS the success path unless missing-path diagnostics are explicitly
+    // requested above. Both orphan lists always reach --json.
     for (const file of removedOrphans) {
       process.stderr.write(`materialize-wave-scope: removed orphaned declaration ${file} (id absent from this wave's records)\n`);
     }

package/scripts/print-applicable-rules.mjs

@@ -11,9 +11,9 @@
  * it to each dispatched agent's prompt.
  *
  * Resolution:
- *   - scopePaths ← `allowedPaths` from `.claude/wave-scope.json`
+ *   - scopePaths ← `allowedPaths` from the active harness wave-scope.json
  *                  (override: --wave-scope <path>)
- *   - mode       ← `session-type:` frontmatter in `.claude/STATE.md`
+ *   - mode       ← `session-type:` frontmatter in the active harness STATE.md
  *                  (override: --mode <m>; unreadable → null = no mode gating)
  *   - hostClass  ← `host_class` from `.orchestrator/host.json` via readHostClass
  *                  (override: --host-class <c>; unreadable → null = no gating)
@@ -103,6 +103,7 @@ import { createHash } from 'node:crypto';
 import { findProjectRoot } from './lib/common.mjs';
 import { loadApplicableRules } from './lib/rule-loader.mjs';
 import { readHostClass } from './lib/autopilot/telemetry.mjs';
+import { resolveStateArtifactPath, resolveStateMdPath } from './lib/state-md.mjs';
 
 // ---------------------------------------------------------------------------
 // EPIPE hardening (regression follow-up on #876)
@@ -136,10 +137,10 @@ as an injectable Markdown block, for the wave-executor to prepend to each
 dispatched agent's prompt (#336 / #694).
 
 Options:
-  --wave-scope <path>   Path to wave-scope.json (default: .claude/wave-scope.json).
+  --wave-scope <path>   Path to wave-scope.json (default: active harness, then legacy).
                         Its "allowedPaths" array is used as scopePaths.
   --mode <m>            Override session mode (default: session-type: from
-                        .claude/STATE.md; unreadable -> no mode gating).
+                        active harness STATE.md; unreadable -> no mode gating).
   --host-class <c>      Override host class (default: host_class from
                         .orchestrator/host.json; unreadable -> no gating).
   --context <c>         Caller context for tier gating: 'wave' | 'coordinator'.
@@ -322,8 +323,8 @@ const repoRoot = findProjectRoot(process.cwd());
 const rulesDir = join(repoRoot, '.claude', 'rules');
 const waveScopePath = opts['wave-scope']
   ? opts['wave-scope']
-  : join(repoRoot, '.claude', 'wave-scope.json');
-const stateMdPath = join(repoRoot, '.claude', 'STATE.md');
+  : resolveStateArtifactPath(repoRoot, 'wave-scope.json');
+const stateMdPath = resolveStateMdPath(repoRoot);
 const hostJsonPath = join(repoRoot, '.orchestrator', 'host.json');
 
 // ---------------------------------------------------------------------------

package/scripts/print-learnings-index.mjs

@@ -101,6 +101,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { findProjectRoot } from './lib/common.mjs';
+import { resolveStateArtifactPath } from './lib/state-md.mjs';
 import {
   CANDIDATE_POOL_SIZE,
   DEFAULT_MAX_GLOBAL,
@@ -141,7 +142,7 @@ Options:
                         agent's declared "Files:" scope. Preferred input.
                         Unreadable or malformed -> exit 1.
   --wave-scope <path>   Fallback scope source; reads "allowedPaths" (default:
-                        .claude/wave-scope.json). An EXPLICIT path that is
+                        active harness, then legacy). An EXPLICIT path that is
                         unreadable/malformed -> exit 1; the DEFAULT path being
                         absent -> stderr diagnostic + empty scope, exit 0.
   --task-text <text>    Optional agent task title/description. Feeds the token
@@ -314,7 +315,7 @@ if (scopePaths.length === 0) {
   const waveScopeExplicit = Boolean(opts['wave-scope']);
   const waveScopePath = waveScopeExplicit
     ? opts['wave-scope']
-    : join(repoRoot, '.claude', 'wave-scope.json');
+    : resolveStateArtifactPath(repoRoot, 'wave-scope.json');
   const doc = readJsonOrNull(waveScopePath, waveScopeExplicit, '--wave-scope');
   if (doc === null) {
     note(`wave-scope not found at ${waveScopePath} — using empty scope`);