session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/rules-sync.mjs

@@ -3,26 +3,37 @@
  * Syncs canonical rules from the plugin's rules/ library into a consumer repo's .claude/rules/.
  *
  * Stdlib-only, cross-platform, no Zod, no third-party parsers. ESM module.
- * Preserves local rules (files without the plugin source header).
+ * Preserves local rules — files carrying the plugin provenance header in
+ * neither accepted position (see `isPluginOwnedContent`).
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, basename, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { validateRuleContent, scanVendoringLeaks } from './validate-vendored-rules.mjs';
+import {
+  validateRuleContent,
+  scanVendoringLeaks,
+  isPluginOwnedContent,
+} from './validate-vendored-rules.mjs';
 import { isMainModule } from './is-main-module.mjs';
 
 // The vendoring sanitizer (issue #1098) lives in validate-vendored-rules.mjs —
 // it has that module's shape ("judge one rule file → findings") and its
 // standalone CLI needs it too. Re-exported here so importers that predate the
 // move (and this file's own tests) keep resolving it from rules-sync.mjs.
-export { scanVendoringLeaks };
+//
+// isPluginOwnedContent (#1449) — the ownership predicate below — lives there
+// for the same reason as PLUGIN_HEADER_PREFIX's copy: this module imports
+// validate-vendored-rules.mjs, so defining it here and importing it back into
+// the validator's provenance probe would make the two modules import each
+// other. Re-exported so the ownership rule is reachable from the sync module.
+export { scanVendoringLeaks, isPluginOwnedContent };
 
 // Exported (issue #722 Epic A Wave 2) for external consumers (e.g. tests).
-// NOT imported by validate-vendored-rules.mjs — that module imports
-// validateRuleContent FROM this file (see the pre-write gate below), so
-// importing this constant back would create a module-load cycle; it keeps
-// its own textually-identical copy instead.
+// NOT imported by validate-vendored-rules.mjs — this module imports
+// validateRuleContent FROM that file (see the pre-write gate below), so
+// importing this constant back there would create a module-load cycle; it
+// keeps its own textually-identical copy instead.
 export const PLUGIN_HEADER_PREFIX = '<!-- source: session-orchestrator plugin';
 
 /**
@@ -170,8 +181,9 @@ function escapeRegex(s) {
  *
  * When `validate` is true (the default — issue #722 Epic A Wave 2),
  * validateRuleContent() runs as a pre-write gate on every source file before
- * it is copied. A file with any error-severity violation (paths-frontmatter,
- * missing provenance header, unfilled placeholder) is recorded in `errors[]`
+ * it is copied. A file with any error-severity violation (frontmatter-not-at-top,
+ * globs-paths-mismatch, missing provenance header, unfilled placeholder) is
+ * recorded in `errors[]`
  * and its write is skipped entirely — it is never added to
  * written/skipped/preserved. Warn-severity violations (zero-match-globs,
  * foreign-glob) do NOT block the write; they are collected into the
@@ -405,9 +417,12 @@ export function syncRules({
         continue;
       }
 
-      const firstLine = targetContent.split('\n')[0] ?? '';
-      if (!firstLine.startsWith(PLUGIN_HEADER_PREFIX)) {
-        // Local file — preserve it
+      // Ownership accepts BOTH header positions (#1449): line 1 (the format
+      // every copy vendored before #1449 carries, frontmatter or not) and the
+      // first non-blank line after a line-1 frontmatter (the current format).
+      // So an old-format copy is rewritten into the new format below, never
+      // preserved; only a file with no header in either position is local.
+      if (!isPluginOwnedContent(targetContent)) {
         preserved.push(fileName);
         continue;
       }

package/scripts/lib/scope-baseline.mjs

@@ -604,10 +604,9 @@ export function computeDrift({ repoRoot, threshold = 2.0 } = {}) {
     ? plannedFilesRaw
     : 0;
 
-  // Mirrors the existing over_delivery_ratio div-by-zero guard in
-  // skills/wave-executor/wave-loop.md (`files_changed / max(planned_files_count, 1)`,
-  // in the per-wave metrics section). Deliberately un-line-pinned: that file is
-  // edited often enough that a pinned number goes stale, as this very comment did.
+  // Division-by-zero guard: a baseline that froze zero planned files (no declared
+  // file scope, or a non-numeric count coerced to 0 above) would otherwise yield
+  // Infinity or NaN; `max(plannedFiles, 1)` keeps the ratio finite and comparable.
   const filesRatio = round2(actualFiles / Math.max(plannedFiles, 1));
   const breached = filesRatio >= threshold;
 

package/scripts/lib/scope-echo.mjs

@@ -21,6 +21,13 @@
  * when the platform exposes a stable prompt-assembly boundary; at that point the
  * digest can be computed against the real assembled prompt instead of echoed.
  *
+ * CALLERS (#1298): the CLI modes run only from prose — `--instruction` in
+ * `skills/wave-executor/references/wave-loop-dispatch.md`, `--emit` and `--verify`
+ * in `wave-loop-review.md`. Ceiling: `check-unwired-features` S4 cannot notice both
+ * dropping that citation — it judges modules, not CLI modes, and reads this one wired
+ * as a CLI entrypoint AND via its hook importer (`scopeDigest`). Revisit on a third
+ * prose caller, or when the census learns to track prose-invoked CLI entrypoints.
+ *
  * Pure + stdlib only. Nothing here throws on malformed input — a broken echo
  * check must never change a wave's outcome.
  *
@@ -34,6 +41,8 @@
  *   node scripts/lib/scope-echo.mjs --scope-file <path> --instruction
  *   node scripts/lib/scope-echo.mjs --scope-file <path> --report-file <path> \
  *        [--wave N --agent-id ID --emit]
+ *   node scripts/lib/scope-echo.mjs --verify --wave <N> --state-dir <dir> \
+ *        [--session <id> --events <path> --json --emit]
  *   node scripts/lib/scope-echo.mjs --help
  */
 
@@ -312,13 +321,22 @@ function parseJsonl(raw) {
  * Digest every per-agent scope file of one wave — shape (a) of the two scope
  * shapes (CLAUDE.md / AGENTS.md § allowedPaths).
  *
+ * A file that cannot be read or parsed is the FILE-side counterpart of a
+ * truncated ledger line: skipping it silently makes a wave whose scope files are
+ * corrupt indistinguishable from one that was never injected (`digest-unknown` /
+ * `injection-missing`). The count therefore rides back on the returned Map as
+ * `malformedFiles` — an additive own property, so every existing consumer that
+ * only iterates the entries is unaffected. (A file that parses to a non-array or
+ * to an empty scope stays a silent skip: an empty scope is legitimate.)
+ *
  * @param {string} stateDir
  * @param {number} wave
  * @param {{readDir?: typeof readdirSync, readFile?: typeof readFileSync}} [io]
- * @returns {Map<string, string[]>} digest → agent ids (file basenames)
+ * @returns {Map<string, string[]> & {malformedFiles: number}} digest → agent ids (file basenames)
  */
 export function digestScopeFiles(stateDir, wave, { readDir = readdirSync, readFile = readFileSync } = {}) {
   const out = new Map();
+  out.malformedFiles = 0;
   const dir = resolve(String(stateDir), 'filescopes', `wave-${wave}`);
   let names;
   try {
@@ -332,7 +350,10 @@ export function digestScopeFiles(stateDir, wave, { readDir = readdirSync, readFi
     let parsed;
     try {
       parsed = JSON.parse(readFile(join(dir, file), 'utf8'));
-    } catch { continue; }
+    } catch {
+      out.malformedFiles += 1; // unreadable or unparseable — not nothing
+      continue;
+    }
     if (!Array.isArray(parsed) || normalizeScopePaths(parsed).length === 0) continue;
     const digest = scopeDigest(parsed);
     const ids = out.get(digest) ?? [];
@@ -372,6 +393,12 @@ export function digestScopeFiles(stateDir, wave, { readDir = readdirSync, readFi
  * evidence — the counts and verdicts below are a floor, not a census — and the
  * human table says so beside them.
  *
+ * `malformed_scope_files` is the same measurement on the FILE side (#1379 P2):
+ * a scope file that cannot be read or parsed was silently skipped, which made a
+ * corrupt wave yield `digest-unknown` / `injection-missing` verdicts
+ * indistinguishable from a genuinely missing injection. Always present,
+ * including as `0`.
+ *
  * ## Transport degradation
  *
  * On a platform with no `PreToolUse` `Agent` matcher (Codex, Cursor, Pi) the
@@ -491,6 +518,7 @@ export function verifyWaveScope({
     injected,
     echoed,
     malformed_lines: malformedLines,
+    malformed_scope_files: fileIds.malformedFiles ?? 0,
     by_verdict: byVerdict,
     agents,
   };
@@ -506,6 +534,8 @@ export function verifyWaveScope({
  * including as `0` — it is the denominator's honesty check: without it a join
  * that silently dropped half the ledger is indistinguishable in the record from
  * a wave where nothing went wrong (`.claude/rules/host-resources.md` § HR-105).
+ * `malformed_scope_files` carries the same guarantee for the scope files the
+ * join reads (#1379 P2).
  *
  * @param {ReturnType<typeof verifyWaveScope>} report
  * @returns {Record<string, unknown>}
@@ -518,6 +548,7 @@ export function scopeVerifiedPayload(report) {
     injected: report.injected,
     echoed: report.echoed,
     malformed_lines: report.malformed_lines ?? 0,
+    malformed_scope_files: report.malformed_scope_files ?? 0,
     by_verdict: report.by_verdict,
     digests: report.agents.map((a) => a.digest),
   };
@@ -636,6 +667,12 @@ async function mainVerify(args) {
       ? [`  WARNING: ${report.malformed_lines} malformed ledger line(s) skipped — `
         + 'counts and verdicts below are a floor, not a census']
       : []),
+    // Same honesty check on the FILE side: an unparseable scope file makes a
+    // corrupt wave look exactly like one that was never injected.
+    ...(report.malformed_scope_files > 0
+      ? [`  WARNING: ${report.malformed_scope_files} malformed scope file(s) skipped — `
+        + 'digest-unknown / injection-missing below may be corruption, not a missing injection']
+      : []),
     ...report.agents.map((a) => `  ${a.digest}  ${a.verdict.padEnd(20)}  ${a.agent_id}`),
   ];
   process.stdout.write(`${lines.join('\n')}\n`);