session-orchestrator 3.22.0 → 3.23.0

package/scripts/lib/state-md/yaml-parser.mjs

@@ -6,8 +6,15 @@
  *   - Flow-style integer arrays (`[1, 2, 3]`)
  *   - Block-style sequences of mappings (issue #244), e.g. `docs-tasks:` with
  *     indented `- key: value` entries. Only one nesting level supported.
+ *   - Single-line FLOW MAPPINGS as list items (`- { k: v, … }`) — hand-written
+ *     but valid YAML, parsed into the same plain object a block item yields and
+ *     re-emitted in block notation on the next serialize (#1111).
  *
  * That is the full grammar permitted by skills/_shared/state-ownership.md.
+ * A list item this grammar cannot represent (a flow SEQUENCE `- [a, b]`, or a
+ * flow mapping whose interior is malformed) is dropped from ITS OWN LIST and
+ * reported on `parseStateMd(...).warnings` — never escalated to a null
+ * document. See `parseBlockValue` for why that scoping is load-bearing.
  *
  * Never throws. Returns null for unparseable input rather than raising.
  *
@@ -35,17 +42,28 @@ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 /**
  * Parses a STATE.md file into frontmatter + body.
  *
+ * `warnings` is OMITTED (not `null`, not `[]`) when the parse was clean, so a
+ * caller pinning the whole return with `toEqual({ frontmatter, body })` still
+ * matches and no consumer has to learn about it to keep working. When present
+ * it is a non-empty array of `{ key, index, reason }` records naming list items
+ * that were dropped from `frontmatter[key]` — `index` addresses the RAW source
+ * item position (dropped items included), so it stays quotable against the file
+ * even though the surviving array is shorter.
+ *
  * @param {string} contents
- * @returns {{frontmatter: object, body: string}|null}
+ * @returns {{frontmatter: object, body: string, warnings?: Array<{key: string, index: number, reason: string}>}|null}
  */
 export function parseStateMd(contents) {
   if (typeof contents !== 'string') return null;
   const match = FRONTMATTER_RE.exec(contents);
   if (!match) return null;
   const [, fmText, body] = match;
-  const frontmatter = parseFrontmatter(fmText);
+  const warnings = [];
+  const frontmatter = parseFrontmatter(fmText, warnings);
   if (frontmatter === null) return null;
-  return { frontmatter, body: body.startsWith('\n') ? body.slice(1) : body };
+  const parsed = { frontmatter, body: body.startsWith('\n') ? body.slice(1) : body };
+  if (warnings.length > 0) parsed.warnings = warnings;
+  return parsed;
 }
 
 /**
@@ -70,7 +88,7 @@ export function serializeStateMd({ frontmatter, body }) {
   return `---\n${fmLines.join('\n')}\n---\n${bodyOut}`;
 }
 
-function parseFrontmatter(text) {
+function parseFrontmatter(text, warnings) {
   const out = {};
   const lines = text.split(/\r?\n/);
   let i = 0;
@@ -87,7 +105,7 @@ function parseFrontmatter(text) {
     if (key === '') return null;
     const valuePart = rstripped.slice(idx + 1).trim();
     if (valuePart === '') {
-      const result = parseBlockValue(lines, i + 1);
+      const result = parseBlockValue(lines, i + 1, key, warnings);
       if (result === null) return null;
       out[key] = result.value;
       i = result.nextIndex;
@@ -106,8 +124,27 @@ function parseFrontmatter(text) {
  *     no body) and `nextIndex === start` so the caller resumes at `start`.
  *   - `value === [...]` means a block sequence was consumed.
  * Returns `null` on malformed block syntax.
+ *
+ * A list item that opens a YAML FLOW collection is resolved PER ITEM, never per
+ * document:
+ *   - `- { id: m-1, task: "x", wave: 1, status: b }` parses into exactly the
+ *     object the equivalent block item yields (and serializes back as block
+ *     notation). Splitting it at the first colon — the #1111 bug, measured
+ *     2026-08-24 @ f0766e1 as `keys: ["{ id"] · status: undefined` — is what
+ *     this must never do again.
+ *   - Anything else flow-shaped (`- [a, b]`, or a `{ … }` whose interior is
+ *     malformed) is dropped from THIS list with a `warnings` record. It cannot
+ *     be kept: a non-mapping item makes `isBlockSeqOfMappings` false for the
+ *     whole array, and the serializer would then emit the entire list through
+ *     `serializeScalar` as `[object Object]`.
+ *
+ * Escalating either case to `null` for the WHOLE document — the first #1111 fix
+ * — is the failure this scoping exists to prevent: every mutator in this family
+ * opens with `parseStateMd(contents); if (parsed === null) return contents;`, so
+ * one hand-written item silently turned every STATE.md write into a no-op that
+ * reported success. Silent-wrong must not be traded for silent-absent.
  */
-function parseBlockValue(lines, start) {
+function parseBlockValue(lines, start, key, warnings) {
   let i = start;
   while (i < lines.length) {
     const rstripped = lines[i].replace(/\s+$/, '');
@@ -124,6 +161,7 @@ function parseBlockValue(lines, start) {
   const indent = bulletMatch[1];
   const contIndent = indent + '  ';
   const entries = [];
+  let itemIndex = 0;
   while (i < lines.length) {
     const rstripped = lines[i].replace(/\s+$/, '');
     if (rstripped === '' || /^\s*#/.test(rstripped)) {
@@ -132,12 +170,26 @@ function parseBlockValue(lines, start) {
     }
     if (!rstripped.startsWith(indent + '- ')) break;
     const firstBody = rstripped.slice(indent.length + 2);
-    const firstColon = firstBody.indexOf(':');
-    if (firstColon === -1) return null;
-    const firstKey = firstBody.slice(0, firstColon).trim();
-    if (firstKey === '') return null;
-    const entry = {};
-    entry[firstKey] = parseScalar(firstBody.slice(firstColon + 1).trim());
+    // `entry === null` marks an item this grammar cannot represent: its
+    // continuation lines are still consumed below (so the walk stays aligned),
+    // but nothing is pushed onto `entries`.
+    let entry;
+    if (firstBody.startsWith('{')) {
+      entry = parseFlowMapping(firstBody);
+      if (entry === null) {
+        warnings.push({ key, index: itemIndex, reason: 'malformed-flow-mapping' });
+      }
+    } else if (firstBody.startsWith('[')) {
+      entry = null;
+      warnings.push({ key, index: itemIndex, reason: 'flow-sequence-item' });
+    } else {
+      const firstColon = firstBody.indexOf(':');
+      if (firstColon === -1) return null;
+      const firstKey = firstBody.slice(0, firstColon).trim();
+      if (firstKey === '') return null;
+      entry = {};
+      entry[firstKey] = parseScalar(firstBody.slice(firstColon + 1).trim());
+    }
     i++;
     while (i < lines.length) {
       const inner = lines[i].replace(/\s+$/, '');
@@ -150,16 +202,93 @@ function parseBlockValue(lines, start) {
       if (/^\s/.test(body)) return null;
       const colon = body.indexOf(':');
       if (colon === -1) return null;
-      const key = body.slice(0, colon).trim();
-      if (key === '') return null;
-      entry[key] = parseScalar(body.slice(colon + 1).trim());
+      const contKey = body.slice(0, colon).trim();
+      if (contKey === '') return null;
+      if (entry !== null) entry[contKey] = parseScalar(body.slice(colon + 1).trim());
       i++;
     }
-    entries.push(entry);
+    if (entry !== null) entries.push(entry);
+    itemIndex++;
   }
   return { value: entries, nextIndex: i };
 }
 
+/**
+ * Splits a flow-collection interior on its TOP-LEVEL commas — the ones outside
+ * quotes and outside any nested `{}`/`[]`. A naive `split(',')` would cut
+ * `task: "a, b"` in half, which is the same class of first-separator mistake
+ * that produced the `{ id` key in the first place.
+ *
+ * @param {string} inner
+ * @returns {string[]}
+ */
+function splitFlowSegments(inner) {
+  const segments = [];
+  let depth = 0;
+  let quote = null;
+  let current = '';
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (quote !== null) {
+      current += ch;
+      if (ch === '\\' && quote === '"') {
+        current += inner[++i] ?? '';
+      } else if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === '{' || ch === '[') depth++;
+    else if (ch === '}' || ch === ']') depth--;
+    else if (ch === ',' && depth === 0) {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  segments.push(current);
+  return segments;
+}
+
+/**
+ * Parses a SINGLE-LINE YAML flow mapping (`{ k: v, k2: "v, 2" }`) into a plain
+ * object, reusing `parseScalar` for each value so a flow item and the equivalent
+ * block item yield byte-identical results.
+ *
+ * Returns `null` when `raw` is not a well-formed single-line flow mapping —
+ * unterminated, an empty segment, or a segment with no `:`. Callers report that
+ * as a dropped item; nothing here throws.
+ *
+ * KNOWN CEILING: a NESTED flow mapping value (`{ id: m-1, meta: { a: 1 } }`)
+ * keeps `{ a: 1 }` as a STRING rather than an object — this subset has no
+ * nested-mapping representation and the serializer has no way to emit one. Flat
+ * flow mappings are the whole observed population (hand-written `mission-status`
+ * / `docs-tasks` items). Revisit if a nested flow value ever appears in a real
+ * STATE.md.
+ *
+ * @param {string} raw
+ * @returns {object|null}
+ */
+function parseFlowMapping(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return null;
+  const inner = trimmed.slice(1, -1).trim();
+  const out = {};
+  if (inner === '') return out;
+  for (const segment of splitFlowSegments(inner)) {
+    const part = segment.trim();
+    if (part === '') return null;
+    const colon = part.indexOf(':');
+    if (colon === -1) return null;
+    const key = part.slice(0, colon).trim();
+    if (key === '') return null;
+    out[key] = parseScalar(part.slice(colon + 1).trim());
+  }
+  return out;
+}
+
 function parseScalar(raw) {
   if (raw === '' || raw === 'null' || raw === '~') return null;
   if (raw === 'true') return true;

package/scripts/lib/state-md.mjs

@@ -1,13 +1,13 @@
 /**
  * STATE.md helpers (issue #184).
  *
- * Thin barrel — re-exports all 25 public symbols from the split submodules.
+ * Thin barrel — re-exports every public symbol of the split submodules.
  * Implementation lives in scripts/lib/state-md/*.mjs.
  *
  * @see scripts/lib/state-md/yaml-parser.mjs        parseStateMd, serializeStateMd
  * @see scripts/lib/state-md/frontmatter-mutators.mjs touchUpdatedField, updateFrontmatterFields
  * @see scripts/lib/state-md/body-sections.mjs       readCurrentTask, appendDeviation, markExpressPathComplete, appendWhatNotToRetry, readWhatNotToRetry, readOpenQuestions, appendOpenQuestion, markOpenQuestionAnswered
- * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, writeMissionStatus, setMissionStatus, readMissionStatus
+ * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, parseMissionStatusStrict, MISSION_STATUS_VALUES, writeMissionStatus, setMissionStatus, setMissionStatusDetailed, readMissionStatus, recoverFrontmatterMissionStatusDetailed, writeMissionStatusOnDisk, setMissionStatusOnDisk
  * @see scripts/lib/state-md/recommendations.mjs     parseRecommendations
  */
 
@@ -43,11 +43,21 @@ export {
 
 export {
   parseMissionStatus,
+  // The strict reader and the status vocabulary are part of the same public
+  // surface as `parseMissionStatus` (#1111) — a consumer that imports from this
+  // barrel (the documented entry point) reached neither until this re-export
+  // landed: a static `import { parseMissionStatusStrict } from '.../state-md.mjs'`
+  // failed at link time, and the `await import()` form — the one hooks and
+  // lazy loaders use — yielded `undefined` and failed only at the call.
+  parseMissionStatusStrict,
+  MISSION_STATUS_VALUES,
   writeMissionStatus,
   setMissionStatus,
   readMissionStatus,
   writeMissionStatusOnDisk,
   setMissionStatusOnDisk,
+  recoverFrontmatterMissionStatusDetailed,
+  setMissionStatusDetailed,
 } from './state-md/mission-status.mjs';
 
 export { parseRecommendations } from './state-md/recommendations.mjs';

package/scripts/lib/telemetry/sync.mjs

@@ -287,25 +287,63 @@ export async function flush({
 // ---------------------------------------------------------------------------
 
 /**
- * Whether a daily-fallback flush is due: the queue is non-empty AND more than 24h
- * have passed since the last successful flush (a never-flushed queue with items
- * counts as due). Cheap — a single telemetry.json read + a queue stat. Never throws.
+ * Whether a daily-fallback flush is due. Two independent ways to be due, both
+ * requiring that more than 24h have passed since the last successful flush
+ * (never-flushed counts as infinitely stale):
+ *
+ *   (a) RETRY — the offline queue is non-empty: earlier sends failed and the
+ *       backlog deserves another attempt.
+ *   (b) CATCH-UP — the queue is empty, but `<metricsDir>/sessions.jsonl` ends on
+ *       a record whose `completed_at` is NEWER than `last_flush_at`: a session
+ *       closed since the last successful send and produced no ping.
+ *
+ * (b) is the reason this predicate exists at all. While it was queue-only, the
+ * "daily fallback" could ONLY re-send what had already failed to send — it could
+ * never originate a ping. Measured 2026-08-23 (#1138): 588 session closes across
+ * 13 repos produced 82 ingest records (~14%), because the ONE writer of the
+ * queue is a failed `flush()`, and a `flush()` that never runs never fails.
+ *
+ * Cheap in the common case: the staleness gate is checked FIRST (one small
+ * telemetry.json read), so a host that flushed within the last 24h returns
+ * before touching either the queue or the session ledger.
+ *
+ * Never throws.
  *
  * @param {object} [opts]
  * @param {string} [opts.statePath]  telemetry.json path override.
  * @param {string} [opts.queuePath]  queue path override.
+ * @param {string} [opts.metricsDir] Metrics dir for the (b) catch-up probe
+ *                                   (default `<cwd>/.orchestrator/metrics`).
  * @param {number} [opts.now]        Reference time in epoch-ms (default Date.now()).
  * @returns {boolean}
  */
-export function shouldDailyFlush({ statePath, queuePath, now = Date.now() } = {}) {
+export function shouldDailyFlush({ statePath, queuePath, metricsDir, now = Date.now() } = {}) {
   try {
-    const { count } = queueStats({ path: queuePath });
-    if (count <= 0) return false;
-
+    // Staleness gate — shared by BOTH disjuncts, so it runs first and short-
+    // circuits the two file probes below on every fresh host.
     const { record } = readTelemetryState({ path: statePath });
     const raw = record?.last_flush_at;
     const lastMs = typeof raw === 'string' && !Number.isNaN(Date.parse(raw)) ? Date.parse(raw) : 0;
-    return now - lastMs > DAILY_FLUSH_MS;
+    if (now - lastMs <= DAILY_FLUSH_MS) return false;
+
+    // (a) Retry an existing backlog.
+    const { count } = queueStats({ path: queuePath });
+    if (count > 0) return true;
+
+    // (b) Catch-up: a session completed after the last successful flush.
+    //     Reuses buildBatch's reader — same file, same skipInvalid tolerance,
+    //     no second parser.
+    //
+    //     Deliberate simplification (named ceiling): this parses the WHOLE
+    //     sessions.jsonl to look at its last record. At the observed ledger size
+    //     (271 records / 292 KB in this repo, 2026-08-23) that is sub-millisecond
+    //     and it only runs once the 24h gate above has already passed. Revisit
+    //     with a tail-read if any repo's sessions.jsonl passes ~10 MB.
+    const dir = metricsDir || path.join(process.cwd(), '.orchestrator', 'metrics');
+    const sessions = readJsonlFile(path.join(dir, 'sessions.jsonl'), { skipInvalid: true });
+    const last = sessions.length > 0 ? sessions[sessions.length - 1] : null;
+    const completedMs = Date.parse(last?.completed_at);
+    return !Number.isNaN(completedMs) && completedMs > lastMs;
   } catch {
     return false;
   }

package/scripts/lib/validate/check-agents.mjs

@@ -10,6 +10,7 @@ import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
 import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE } from '../agent-frontmatter.mjs';
 import { extractInitialFrontmatter } from './frontmatter-block.mjs';
+import { parseFrontmatterDescription } from '../description-surface.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -136,6 +137,57 @@ function parseToolsValue(toolsVal) {
   return v.split(',').map((t) => t.trim()).filter(Boolean);
 }
 
+/**
+ * Detect a `description:` whose YAML-PARSED value is a silently truncated
+ * PREFIX of what the file actually says (#1029).
+ *
+ * An unquoted (plain) YAML scalar ends at the first ` #`: everything from there
+ * on is a comment. The block still parses, so every other rule in this gate
+ * stays green while the agent picker receives a stub — `agents/eval-judge.md`
+ * shipped 51 of 1,180 characters (96% dropped, measured 2026-08-24) and nothing
+ * complained. This is the concrete case the Check-6 preamble describes in prose.
+ *
+ * Detected by COMPARISON, never by pattern: the parsed value must be a strict
+ * prefix of the raw scalar AND the dropped tail must open a comment. A
+ * legitimately quoted description whose text merely contains `#` parses in full
+ * (parsed === raw, no length gap) and is never flagged; a quoted description
+ * carrying YAML escapes diverges from its raw form and fails the prefix test.
+ *
+ * Raw extraction is delegated to `parseFrontmatterDescription` (the sibling
+ * measurement probe already owns it, block scalars and quote-stripping included)
+ * rather than re-derived from a fourth regex here.
+ *
+ * @param {string} content - the agent file's raw content
+ * @param {Record<string, unknown>} data - the parsed frontmatter mapping
+ * @param {string} frontmatter - the frontmatter block's inner text
+ * @returns {{ parsedLength: number, rawLength: number } | null} null when intact
+ */
+function detectDescriptionTruncation(content, data, frontmatter) {
+  if (!hasField(frontmatter, 'description')) return null;
+
+  // A `description:` key whose WHOLE value is a comment (`description: #803 …`)
+  // parses to null — a 0-character description, the same defect at 100% loss.
+  const parsedValue =
+    typeof data?.description === 'string'
+      ? data.description
+      : data?.description === null || data?.description === undefined
+        ? ''
+        : null;
+  if (parsedValue === null) return null;
+
+  const rawField = parseFrontmatterDescription(content);
+  // Block scalars carry no comment semantics and are rejected outright by the
+  // inline-string rule below — not this rule's business.
+  if (!rawField || rawField.isBlockScalar) return null;
+
+  const raw = rawField.raw;
+  if (raw.length <= parsedValue.length) return null;
+  if (!raw.startsWith(parsedValue)) return null;
+  if (!/(^|\s)#/.test(raw.slice(parsedValue.length))) return null;
+
+  return { parsedLength: parsedValue.length, rawLength: raw.length };
+}
+
 // ============================================================================
 // Check 6: Agent .md files have valid YAML frontmatter
 // ============================================================================
@@ -226,6 +278,20 @@ if (mdFiles.length === 0) {
     }
     parseable++;
 
+    // ------------------------------------------------------------------
+    // Prefix-truncation rule (#1029) — the ` #` case the preamble above names.
+    // Runs BEFORE the field rules: a description truncated to a stub still
+    // satisfies every one of them, so this is the only place the loss shows up.
+    // ------------------------------------------------------------------
+    const truncated = detectDescriptionTruncation(content, parsedFm.data, frontmatter);
+    if (truncated) {
+      fail(
+        `${agentName}: description is silently truncated by an unquoted ' #' — YAML parses ` +
+          `${truncated.parsedLength} of ${truncated.rawLength} chars and reads the rest as a comment; ` +
+          `quote the description (double-quoted, escaping any " inside) so the full text parses`,
+      );
+    }
+
     // ------------------------------------------------------------------
     // Required fields check
     // ------------------------------------------------------------------

package/scripts/lib/validate/check-cursor-adapter.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// check-cursor-adapter.mjs — Ensure Cursor-native commands, skills, and hooks stay wired.
+// Usage: check-cursor-adapter.mjs <plugin-root>
+// Exit 0 = all checks passed, 1 = at least one failure.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CURSOR_TO_CANONICAL_EVENT } from '../cursor-hook-bridge.mjs';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-cursor-adapter.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+console.log('--- Check 1: generated Cursor command and skill wrappers ---');
+
+const generator = join(pluginRoot, 'scripts', 'generate-cursor-adapter.mjs');
+if (!existsSync(generator)) {
+  fail('scripts/generate-cursor-adapter.mjs exists');
+} else {
+  const result = spawnSync(process.execPath, [generator, '--check'], {
+    cwd: pluginRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status === 0) {
+    pass('.cursor/commands and .cursor/skills are up to date with commands/ and skills/');
+  } else {
+    const detail = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+    fail(`Cursor adapter wrappers are stale${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+console.log('');
+console.log('--- Check 2: .cursor/hooks.json native manifest ---');
+
+const hooksPath = join(pluginRoot, '.cursor', 'hooks.json');
+if (!existsSync(hooksPath)) {
+  fail('.cursor/hooks.json exists');
+} else {
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(readFileSync(hooksPath, 'utf8'));
+    pass('.cursor/hooks.json is valid JSON');
+  } catch (err) {
+    fail(`.cursor/hooks.json is not valid JSON: ${err.message}`);
+    hooksJson = null;
+  }
+
+  if (hooksJson) {
+    if (hooksJson.version === 1) {
+      pass('.cursor/hooks.json version is 1');
+    } else {
+      fail('.cursor/hooks.json version must be 1');
+    }
+
+    const declared = Object.keys(hooksJson.hooks || {});
+    const expected = Object.keys(CURSOR_TO_CANONICAL_EVENT);
+    const missing = expected.filter((event) => !declared.includes(event));
+    const extra = declared.filter((event) => !expected.includes(event));
+    if (missing.length === 0 && extra.length === 0) {
+      pass(`.cursor/hooks.json events match CURSOR_TO_CANONICAL_EVENT (${expected.length})`);
+    } else {
+      if (missing.length > 0) fail(`.cursor/hooks.json missing events: ${missing.join(', ')}`);
+      if (extra.length > 0) fail(`.cursor/hooks.json extra events: ${extra.join(', ')}`);
+    }
+
+    const bridgeRef = 'scripts/lib/cursor-hook-bridge.mjs';
+    const allPointAtBridge = declared.every((event) => {
+      const entries = Array.isArray(hooksJson.hooks[event]) ? hooksJson.hooks[event] : [];
+      return entries.some((entry) => typeof entry.command === 'string' && entry.command.includes(bridgeRef) && entry.command.includes(`--event ${event}`));
+    });
+    if (allPointAtBridge) {
+      pass('.cursor/hooks.json commands invoke cursor-hook-bridge.mjs with --event');
+    } else {
+      fail('.cursor/hooks.json commands must invoke scripts/lib/cursor-hook-bridge.mjs --event <name>');
+    }
+  }
+}
+
+console.log('');
+console.log('--- Check 3: Cursor hook bridge module ---');
+
+const bridgePath = join(pluginRoot, 'scripts', 'lib', 'cursor-hook-bridge.mjs');
+if (existsSync(bridgePath)) {
+  pass('scripts/lib/cursor-hook-bridge.mjs exists');
+} else {
+  fail('scripts/lib/cursor-hook-bridge.mjs exists');
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-dead-bridge.mjs

@@ -27,6 +27,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { DETECTORS } from './dead-bridge-detectors.mjs';
 import * as corpus from './dead-bridge-corpus.mjs';
+import { listRepoFiles } from './repo-files.mjs';
 
 const DEFAULT_EXTS = ['.mjs', '.md'];
 
@@ -90,10 +91,31 @@ function walk(absDir, exts) {
  * }}
  */
 export function buildRepoContext(pluginRoot) {
+  /**
+   * Enumerate `absDir` from the git INDEX when it lies inside the plugin
+   * root, falling back to the raw walk otherwise (#1143). The walk cannot see
+   * `.gitignore`, so a worktree created under this repo's own
+   * `.claude/worktrees/` convention — or any vendored/generated tree, since
+   * this walk carries no exclusion set at all — enters the detector corpus as
+   * repository content. A detector then reads a PEER checkout's copy of a
+   * skill or rule file and counts it as an independent bridge.
+   *
+   * The containment guard matters: a corpus entry outside the root has no
+   * index to consult, and an `ls-files` pathspec of `../..` is an error, not
+   * an empty answer.
+   * @param {string} absDir
+   * @param {string[] | null} exts
+   * @returns {string[]}
+   */
+  const listUnder = (absDir, exts) => {
+    const rel = path.relative(pluginRoot, absDir);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return walk(absDir, exts);
+    return listRepoFiles(pluginRoot, { dirs: [rel], exts });
+  };
   return {
     pluginRoot,
-    listMdFiles: (absDir) => walk(absDir, ['.md']),
-    listFiles: (absDir, exts = DEFAULT_EXTS) => walk(absDir, exts),
+    listMdFiles: (absDir) => listUnder(absDir, ['.md']),
+    listFiles: (absDir, exts = DEFAULT_EXTS) => listUnder(absDir, exts),
     readText: (absPath) => readFileSync(absPath, 'utf8'),
     exists: (absPath) => existsSync(absPath),
   };

package/scripts/lib/validate/check-doc-cli-commands.mjs

@@ -62,10 +62,11 @@
  * Verified against glab 1.91.0 / gh 2.86.0 (2026-08-15).
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
+import { listRepoFiles } from './repo-files.mjs';
 
 /** Directories walked for documentation. Mirrors check-vcs-repo-flag.mjs. */
 const SCAN_DIRS = Object.freeze([
@@ -80,8 +81,6 @@ const SCAN_DIRS = Object.freeze([
 ]);
 
 /** Never descend into these. */
-const EXCLUDED_DIRS = Object.freeze(['node_modules', '.git', 'dist', 'build', 'coverage']);
-
 /** Fence languages whose body is shell. Anything else is prose. */
 const SHELL_LANGS = Object.freeze(new Set(['bash', 'sh', 'shell', 'console', 'zsh']));
 
@@ -296,28 +295,6 @@ function probeHelp(bin, group, cache) {
   return entry;
 }
 
-/**
- * Recursively collect `.md` files.
- *
- * @param {string} directory
- * @param {string[]} acc
- * @returns {string[]}
- */
-function walk(directory, acc = []) {
-  if (!existsSync(directory)) return acc;
-  for (const entry of readdirSync(directory, { withFileTypes: true })) {
-    if (entry.isSymbolicLink()) continue;
-    if (EXCLUDED_DIRS.includes(entry.name)) continue;
-    const fullPath = path.join(directory, entry.name);
-    if (entry.isDirectory()) {
-      walk(fullPath, acc);
-      continue;
-    }
-    if (entry.isFile() && path.extname(entry.name) === '.md') acc.push(fullPath);
-  }
-  return acc;
-}
-
 /** @param {string} text @returns {string} */
 function clampSnippet(text) {
   const flat = text.replace(/\s+/g, ' ').trim();
@@ -358,13 +335,20 @@ export function inspectDocCliCommands(pluginRoot) {
   /** @type {string[]} */
   let files;
   try {
-    files = SCAN_DIRS.flatMap((dir) => walk(path.join(pluginRoot, dir)));
-    for (const entry of readdirSync(pluginRoot, { withFileTypes: true })) {
-      if (entry.isFile() && path.extname(entry.name) === '.md') {
-        files.push(path.join(pluginRoot, entry.name));
-      }
-    }
-    files.sort();
+    // The index, not the filesystem (#1143). A `readdirSync` walk cannot see
+    // `.gitignore`, so every ignored artefact under a scan root entered this
+    // census as if it were documentation: measured 2026-08-26 on a clean
+    // checkout with NO worktree present, 4 such files —  `.claude/STATE.md`
+    // (per-session mutable state) and three gitignored `docs/specs/*.md`. A
+    // worktree under this repo's own `.claude/worktrees/` convention would
+    // add a complete second copy of every scanned doc on top of that.
+    // One enumeration covers both populations this check has always scanned:
+    // the SCAN_DIRS subtrees, and the repo-root `.md` files at depth 0.
+    const scanDirs = new Set(SCAN_DIRS);
+    files = listRepoFiles(pluginRoot, { exts: ['.md'] }).filter((absolute) => {
+      const segments = path.relative(pluginRoot, absolute).split(path.sep);
+      return segments.length === 1 || scanDirs.has(segments[0]);
+    });
   } catch (error) {
     findings.push({
       kind: 'tool-error',