session-orchestrator 3.16.0 → 3.19.0

package/scripts/validate-wave-scope.mjs

@@ -15,6 +15,17 @@
  *                           fileScope file (a JSON array of strings) and assert
  *                           it is a subset of wave-scope.allowedPaths (#796).
  *                           Fails (exit 1) with "missing: [...]" on violation.
+ *   --expand-test-siblings  With --assert-subset: ALSO require allowedPaths to
+ *                           grant the test sibling of every concrete production
+ *                           file in the agent fileScope (#970). Default OFF.
+ *                           Only ever ADDS a requirement — never relaxes the
+ *                           subset assertion above.
+ *                           GATED ON THE MANIFEST'S OWN `role`: the assertion
+ *                           fires only for the roles where expansion fires
+ *                           (scope-gate.mjs TEST_SIBLING_EXPANSION_ROLES), so
+ *                           the caller may pass the flag unconditionally on
+ *                           every pre-dispatch check. A skip is announced on
+ *                           stderr as a WARN.
  *
  * Exit codes:
  *   0 — valid (validated JSON echoed to stdout)
@@ -22,9 +33,15 @@
  *   2 — I/O error (file not found, unreadable stdin, unreadable --assert-subset file)
  */
 
+import path from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { warn } from './lib/common.mjs';
-import { assertFileScopeSubset } from './lib/scope-gate.mjs';
+import {
+  assertFileScopeSubset,
+  assertTestSiblingCoverage,
+  testSiblingExpansionApplies,
+  TEST_SIBLING_EXPANSION_ROLES,
+} from './lib/scope-gate.mjs';
 
 /**
  * Write an error to stderr and exit with the given code.
@@ -40,19 +57,23 @@ function die(msg, code = 1) {
 /**
  * Parse CLI flags out of argv, leaving positional args behind.
  *
- * Recognised: `--assert-subset <path>` (#796). Everything else is treated as a
- * positional argument (the wave-scope.json file path), preserving legacy
- * behaviour where argv[2] is the input file.
+ * Recognised: `--assert-subset <path>` (#796) and `--expand-test-siblings`
+ * (#970). Everything else is treated as a positional argument (the
+ * wave-scope.json file path), preserving legacy behaviour where argv[2] is the
+ * input file.
  *
  * @param {string[]} argv - full process.argv
- * @returns {{ assertSubset: string|null, positionals: string[] }}
+ * @returns {{ assertSubset: string|null, expandTestSiblings: boolean, positionals: string[] }}
  */
 function parseArgs(argv) {
   const positionals = [];
   let assertSubset = null;
+  let expandTestSiblings = false;
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--assert-subset') {
+    if (a === '--expand-test-siblings') {
+      expandTestSiblings = true;
+    } else if (a === '--assert-subset') {
       assertSubset = argv[i + 1];
       if (assertSubset === undefined) {
         die('--assert-subset requires a file-path argument', 1);
@@ -62,7 +83,7 @@ function parseArgs(argv) {
       positionals.push(a);
     }
   }
-  return { assertSubset, positionals };
+  return { assertSubset, expandTestSiblings, positionals };
 }
 
 /**
@@ -139,9 +160,91 @@ function validateRequired(obj, errors) {
   }
 }
 
+/**
+ * Literal filesystem-root forms — POSIX "/" and the Windows equivalents "\"
+ * and a bare drive root ("C:\", "C:\\", ...). Checked independently of
+ * `path.isAbsolute()` because that primitive is platform-native: on a POSIX
+ * host (this repo's dev/CI hosts) it never reports `C:\` as absolute, so a
+ * Windows-literal-root entry would otherwise slip past every check below.
+ * @type {ReadonlySet<string>}
+ */
+const FILESYSTEM_ROOT_LITERALS = new Set(['/', '\\']);
+const WINDOWS_DRIVE_ROOT_RE = /^[A-Za-z]:\\+$/;
+
+/**
+ * @param {string} entry
+ * @returns {boolean}
+ */
+function isFilesystemRootLiteral(entry) {
+  return FILESYSTEM_ROOT_LITERALS.has(entry) || WINDOWS_DRIVE_ROOT_RE.test(entry);
+}
+
+/**
+ * Well-known top-level system/home directories. A FIXED DENYLIST (not a
+ * segment-count threshold): the #792 legitimate grant
+ * (`/private/tmp/<session>/scratchpad/**`) is itself a single-segment-deep
+ * grant under an unusual root ("private"), so any segment-count heuristic
+ * tight enough to catch `/etc/**` risks catching that too, or must be tuned
+ * loosely enough to leave a gap. A fixed list of the directories a
+ * hallucinated/mis-copied wave-scope entry could plausibly land on is
+ * predictable, auditable in a one-line diff, and does not touch legitimate
+ * deep grants under any other root.
+ * @type {ReadonlySet<string>}
+ */
+const DENIED_ABSOLUTE_TOP_SEGMENTS = new Set([
+  'etc',
+  'Users',
+  'home',
+  'root',
+  'bin',
+  'sbin',
+  'usr',
+  'System',
+  'var',
+  'boot',
+  'dev',
+  'proc',
+  'sys',
+  'Library',
+  'Applications',
+  'Windows',
+]);
+
+/**
+ * The top-level path segment of an absolute POSIX-style entry (the segment
+ * immediately after the leading "/"), if it is on the denylist above.
+ * @param {string} entry
+ * @returns {string|null}
+ */
+function deniedTopSegment(entry) {
+  const first = entry.split('/').filter(Boolean)[0];
+  return first && DENIED_ABSOLUTE_TOP_SEGMENTS.has(first) ? first : null;
+}
+
+/**
+ * Does this entry contain a glob wildcard? Mirrors this codebase's own glob
+ * convention (`isGlobScopeEntry` in scripts/lib/scope-gate.mjs / #796): `*`
+ * is the sole wildcard metachar used in allowedPaths/fileScope entries
+ * throughout this repo (no `?`/`[]`/`{}` glob syntax is supported or tested
+ * anywhere else in scope-gate.mjs or enforce-scope.mjs).
+ * @param {string} entry
+ * @returns {boolean}
+ */
+function hasWildcard(entry) {
+  return entry.includes('*');
+}
+
 /**
  * Validate allowedPaths array: must exist, be an array of non-empty strings,
- * with no absolute paths and no path-traversal segments.
+ * with no path-traversal segments. Absolute (out-of-repo) entries are a
+ * SANCTIONED Gate 5b grant (#792) — WARN, not reject; see #870. A narrow
+ * catastrophic subclass of absolute entries is instead a hard ERROR
+ * (#870-followup security review, confidence 0.85): allowedPaths is not
+ * hand-authored — wave-loop.md's Scope Manifest computes it PROGRAMMATICALLY
+ * as the union of LLM-authored per-agent "Files:" scopes — so a
+ * hallucinated/mis-copied/injected entry reaching one of these shapes must
+ * hard-fail rather than rely on a stderr WARN nothing guarantees a human
+ * reads before dispatch.
  * @param {Record<string, unknown>} obj
  * @param {string[]} errors
  * @param {string[]} warnings
@@ -161,11 +264,46 @@ function validateAllowedPaths(obj, errors, warnings) {
       errors.push('allowedPaths contains empty string');
       continue;
     }
-    // Reject absolute paths (must be repo-relative)
-    if (entry.startsWith('/')) {
-      errors.push(`allowedPaths contains absolute path: ${entry}`);
+    // #870: an explicit absolute entry is a SANCTIONED out-of-repo grant — mirrors
+    // hooks/enforce-scope.mjs Gate 5b (matchesAbsoluteAllowlist), which honours ANY
+    // syntactically-absolute allowedPaths entry (path.isAbsolute) against the
+    // realpath-resolved write candidate. Using `path.isAbsolute` (not a hand-rolled
+    // `startsWith('/')`) keeps the same platform-native semantics Gate 5b uses.
+    // WARN, not reject — the validator must not contradict the hook it validates
+    // for (#792 / #870) — EXCEPT for the narrow catastrophic subclass below
+    // (#870-followup), which hard-rejects regardless of what Gate 5b would do
+    // with it: pre-flight validation exists precisely to catch a grant this bad
+    // before the hook is ever consulted.
+    if (path.isAbsolute(entry) || isFilesystemRootLiteral(entry)) {
+      if (isFilesystemRootLiteral(entry)) {
+        errors.push(
+          `allowedPaths grants the entire filesystem root: ${entry} — refused unconditionally, this can never be a valid wave scope`,
+        );
+      } else {
+        const denied = deniedTopSegment(entry);
+        if (denied) {
+          errors.push(
+            `allowedPaths contains a well-known system/home directory grant: ${entry} (top-level segment "${denied}" is denylisted) — refused, scope a narrower path instead`,
+          );
+        } else if (!hasWildcard(entry)) {
+          errors.push(
+            `allowedPaths contains a bare absolute file grant with no wildcard: ${entry} — a single concrete out-of-repo file has no established legitimate use in this codebase; scope a glob instead`,
+          );
+        } else {
+          warnings.push(
+            `allowedPaths contains an absolute (out-of-repo) path: ${entry} — honoured by hooks/enforce-scope.mjs Gate 5b; verify this grant is intentional`,
+          );
+        }
+      }
     }
-    // Reject path traversal: any `../` segment
+    // Reject path traversal: any `../` segment. INDEPENDENT of the absolute checks
+    // above — an absolute entry that ALSO contains `../` must still be rejected
+    // here, unconditionally, even when it was already rejected above for a
+    // different reason. (Such an entry could never actually match Gate 5b's
+    // realpath-canonicalised candidate anyway, since realpath strips `..`
+    // segments before Gate 5b ever compares it — see enforce-scope.mjs REQ-09 —
+    // but validate-time rejection gives the operator immediate, actionable
+    // feedback instead of leaving a silently-dead allowedPaths entry.)
     if (entry.includes('../')) {
       errors.push(`allowedPaths contains path traversal: ${entry}`);
     }
@@ -224,8 +362,9 @@ function validateGates(obj, errors) {
  *
  * @param {Record<string, unknown>} obj - the already schema-validated wave-scope object
  * @param {string} fileScopePath - path to the agent fileScope JSON file
+ * @param {boolean} [expandTestSiblings] - also assert #970 test-sibling coverage
  */
-function assertSubsetOrDie(obj, fileScopePath) {
+function assertSubsetOrDie(obj, fileScopePath, expandTestSiblings = false) {
   if (!existsSync(fileScopePath) || !statSync(fileScopePath).isFile()) {
     die(`Cannot read --assert-subset file: ${fileScopePath}`, 2);
   }
@@ -248,14 +387,40 @@ function assertSubsetOrDie(obj, fileScopePath) {
   if (!ok) {
     die(`agent fileScope not ⊆ allowedPaths — missing: [${missing.join(', ')}]`, 1);
   }
+  // #970 — opt-in, and deliberately AFTER the plain subset assertion so the
+  // pre-existing failure mode keeps its exact message. This only ever adds a
+  // requirement: the union must also grant each production file's test sibling,
+  // or the agent is mechanically unable to update the test it just broke.
+  //
+  // The manifest's OWN `role` (already schema-validated as a non-empty string
+  // above) gates it, through the same predicate the expander uses. That is what
+  // lets the pre-dispatch command carry the flag unconditionally: on a Quality
+  // phase-1 manifest — production files with tests deliberately excluded — an
+  // ungated assertion would block every dispatch of that phase.
+  if (expandTestSiblings) {
+    if (!testSiblingExpansionApplies({ role: obj.role })) {
+      warn(
+        `--expand-test-siblings: skipped for role "${obj.role}" — test-sibling expansion applies only to [${TEST_SIBLING_EXPANSION_ROLES.join(', ')}] (scripts/lib/scope-gate.mjs)`,
+      );
+      return;
+    }
+    const sib = assertTestSiblingCoverage(fileScope, obj.allowedPaths, { role: obj.role });
+    if (!sib.ok) {
+      die(
+        `allowedPaths does not grant the test sibling of every production file in the agent fileScope (#970) — missing: [${sib.missing.join(', ')}]. Re-run the Scope Manifest step: allowedPaths must be expandTestSiblings(union, { role }) — see skills/wave-executor/wave-loop.md § Scope Manifest #3`,
+        1,
+      );
+    }
+  }
 }
 
 /**
  * Main validation entry point. Reads input, validates, exits with appropriate code.
  * @param {string} input - raw JSON string
  * @param {string|null} [assertSubsetPath] - optional agent fileScope file for the #796 subset assertion
+ * @param {boolean} [expandTestSiblings] - opt-in #970 test-sibling coverage assertion
  */
-function validate(input, assertSubsetPath = null) {
+function validate(input, assertSubsetPath = null, expandTestSiblings = false) {
   const obj = parseJson(input);
   const errors = [];
   const warnings = [];
@@ -278,12 +443,12 @@ function validate(input, assertSubsetPath = null) {
 
   // #796 — optional dispatch-time subset assertion (runs only after schema validation passes)
   if (assertSubsetPath) {
-    assertSubsetOrDie(obj, assertSubsetPath);
+    assertSubsetOrDie(obj, assertSubsetPath, expandTestSiblings);
   }
 
   // Echo validated JSON to stdout (trailing newline normalised)
   process.stdout.write(input.endsWith('\n') ? input : input + '\n');
 }
 
-const { assertSubset, positionals } = parseArgs(process.argv);
-validate(readInput(positionals[0]), assertSubset);
+const { assertSubset, expandTestSiblings, positionals } = parseArgs(process.argv);
+validate(readInput(positionals[0]), assertSubset, expandTestSiblings);

package/scripts/vault-integration-watcher.mjs

@@ -9,6 +9,9 @@
  * CLI usage:
  *   node scripts/vault-integration-watcher.mjs [--dry-run] [--issue <id>] [--verbose]
  *     [--glab-bin <path>]        override glab binary (used by tests)
+ *     [--repo <spec>]            override the -R/--repo host-pinning spec (#872;
+ *                                used by tests — default: resolveRepoSpec() against
+ *                                the process cwd, degrading gracefully to no -R)
  *     [--issue <id>]             override tracking issue (default: 305)
  *     [--dep-issues <id,id>]     override dependency issues (default: 303,304)
  *     [--dry-run]                compute + print, no glab posts
@@ -32,6 +35,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
+import { resolveRepoSpec, redactUrlCredentials } from './lib/vcs-repo-spec.mjs';
 
 // ── Argument parsing ──────────────────────────────────────────────────────────
 
@@ -49,6 +53,17 @@ const DEP_ISSUES_RAW = getArg('--dep-issues') ?? '303,304';
 const DEP_ISSUES = DEP_ISSUES_RAW.split(',').map((s) => s.trim());
 const GLAB_BIN = getArg('--glab-bin') ?? process.env.GLAB_BIN ?? 'glab';
 
+// -R/--repo host-pinning spec (#872) — resolved ONCE at module load, reused
+// by every glab call site below (glabJson + postComment cover all 4 call
+// sites: fetchIssues, fetchComments, the tracking-issue view in main(), and
+// the note-add write). `--repo <spec>` is an explicit override (analogous to
+// `--glab-bin`, used by tests); otherwise falls back to the real
+// `resolveRepoSpec` (shells out to `git remote get-url`). Graceful
+// degradation: undefined ⇒ no -R appended anywhere, matching the ambient
+// glab/GITLAB_HOST fallback this watcher always used pre-#872 — never a hard
+// fail, per #839's "never emit -R undefined" contract.
+const REPO_SPEC = getArg('--repo') ?? resolveRepoSpec({ repoRoot: process.cwd(), vcs: 'gitlab' });
+
 // ── Logging ───────────────────────────────────────────────────────────────────
 
 function log(msg) {
@@ -56,7 +71,12 @@ function log(msg) {
 }
 
 function verbose(msg) {
-  if (VERBOSE) log(msg);
+  // Defense-in-depth (#907, CWE-214): the resolved REPO_SPEC is already
+  // credential-stripped at the source (resolveRepoSpec), but a `--repo <spec>`
+  // override bypasses that strip and flows verbatim into the `glab … -R <spec>`
+  // line logged here. Redact any embedded userinfo credential before it reaches
+  // the CI job's stderr.
+  if (VERBOSE) log(redactUrlCredentials(msg));
 }
 
 function emit(action) {
@@ -66,13 +86,17 @@ function emit(action) {
 // ── glab helpers ──────────────────────────────────────────────────────────────
 
 /**
- * Run a glab command and return parsed JSON output.
+ * Run a glab command and return parsed JSON output. Every call is pinned to
+ * -R <REPO_SPEC> (#872) when a spec resolved — appended centrally here so
+ * all glabJson call sites (fetchIssues, fetchComments, main()'s tracking-issue
+ * view) inherit the pin without each needing to build it themselves.
  * @param {string[]} args
  * @returns {unknown}
  */
 function glabJson(args) {
-  verbose(`glab ${args.join(' ')}`);
-  const result = spawnSync(GLAB_BIN, args, { encoding: 'utf8', timeout: 30_000 });
+  const fullArgs = REPO_SPEC ? [...args, '-R', REPO_SPEC] : args;
+  verbose(`glab ${fullArgs.join(' ')}`);
+  const result = spawnSync(GLAB_BIN, fullArgs, { encoding: 'utf8', timeout: 30_000 });
   if (result.error) {
     log(`glab spawn error: ${result.error.message}`);
     process.exit(2);
@@ -90,7 +114,7 @@ function glabJson(args) {
 }
 
 /**
- * Post a comment to an issue.
+ * Post a comment to an issue. Pinned to -R <REPO_SPEC> (#872) — see glabJson.
  * @param {string} issueId
  * @param {string} body
  */
@@ -101,11 +125,9 @@ function postComment(issueId, body) {
     return;
   }
   verbose(`posting comment to #${issueId}`);
-  const result = spawnSync(
-    GLAB_BIN,
-    ['issue', 'note', 'add', issueId, '--message', body],
-    { encoding: 'utf8', timeout: 30_000 }
-  );
+  const args = ['issue', 'note', 'add', issueId, '--message', body];
+  if (REPO_SPEC) args.push('-R', REPO_SPEC);
+  const result = spawnSync(GLAB_BIN, args, { encoding: 'utf8', timeout: 30_000 });
   if (result.error) {
     log(`glab note add spawn error: ${result.error.message}`);
     process.exit(2);

package/skills/_shared/config-reading.md

@@ -195,7 +195,7 @@ Flow-style arrays are also accepted: `globs: ["src/**", "tests/**"]`.
 In the live path the coordinator does NOT call the loader directly — it runs the CLI `scripts/print-applicable-rules.mjs` (which calls the loader) once per wave and captures stdout as the `<APPLICABLE-RULES>` block:
 
 ```sh
-RULES_BLOCK="$(node "$PLUGIN_ROOT/scripts/print-applicable-rules.mjs" 2>/dev/null)"
+RULES_BLOCK="$(node "$PLUGIN_ROOT/scripts/print-applicable-rules.mjs" --context wave 2>/dev/null)"
 # Empty stdout (no .claude/rules/, no matches, or any failure) → inject nothing.
 ```
 
@@ -219,7 +219,7 @@ const rules = loadApplicableRules({
 ### Backward compatibility
 
 - Rule files without any frontmatter continue to load as always-on. No migration required.
-- Files already using the old `paths:` frontmatter key do not match `globs:` — they are treated as always-on until updated.
+- `paths:` is a full alias for `globs:` (issue #795) — files using the old `paths:` frontmatter key load correctly SCOPED, not always-on. When BOTH `globs:` and `paths:` are present on the same rule, `globs:` wins silently (no merge, no warning) and `paths:` is discarded.
 
 ### Failure mode
 

package/skills/bootstrap/fast-template.md

@@ -90,7 +90,7 @@ node "$PLUGIN_ROOT/scripts/lib/claude-md-budget-lint.mjs" --repo-root "$REPO_ROO
 ```
 
 `--mode warn` is deliberate at Anlage-time — the lint informs, the operator decides; it never blocks the scaffold. Interpret the JSON `violations[]`:
-- `max-lines` — the instruction file is already over the lean-root ceiling (150 lines default). Recommend trimming to pointers per the lean-root convention (delegate detail to `README.md` / `.orchestrator/steering/` / `.claude/rules/*.md` — see this plugin's own `CLAUDE.md` for a worked example of the pointer pattern — note it predates the lint and currently exceeds the 150-line ceiling itself).
+- `max-lines` — the instruction file is already over the lean-root ceiling. The ceiling's SSOT is the exported constant `DEFAULT_MAX_LINES` in `scripts/lib/claude-md-budget-lint.mjs` (read it, do not memorise it; `= 80` as of 2026-08-03), overridable per run with `--max-lines`. The budget counts **non-exempt effective lines**, not the raw `wc -l`: the runtime-critical `## Session Config` block is excluded, because it is machine-parsed configuration rather than trimmable prose and applying a raw-line ceiling to it was structurally unreachable (#959 — the ceiling was re-derived in these units at the same time). Recommend trimming to pointers per the lean-root convention (delegate detail to `README.md` / `.orchestrator/steering/` / `.claude/rules/*.md` — see this plugin's own `CLAUDE.md` for a worked example of the pointer pattern; it **passes** this lint, 61 non-exempt of 209 raw lines against the ceiling of 80, measured 2026-08-03 at HEAD `730ee9d` — re-run the command above rather than trusting that number).
 - `max-line-chars` — a single line exceeds the char ceiling (400 default); surface the line number for a quick manual wrap.
 - `provenance-header` — line 1 lacks a `<!-- source: ...` attribution. On the `claude init` path (Public Fast Tier, Claude Code) this is a WARN only, never a hard failure — `claude init` output is not plugin-authored and has no reason to carry the plugin's provenance convention.