mandrel 2.31.0 → 2.33.0

package/.agents/scripts/check-lifecycle-lint.js

@@ -2,30 +2,37 @@
 /* node:coverage ignore file */
 
 /**
- * check-lifecycle-lint.js — enforce the three Tech Spec lint rules for
- * the lifecycle bus surface that biome's stock ruleset cannot express.
+ * check-lifecycle-lint.js — enforce the lifecycle lint rules that biome's
+ * stock ruleset cannot express.
  *
- * Rule 1 — "No Promise.all over listener arrays".
- *   Files under `.agents/scripts/lib/orchestration/lifecycle/**` (the bus
- *   + listeners surface) MUST NOT contain `Promise.all(`. The bus is a
- *   strictly sequential mediator; parallelizing listeners breaks
- *   repeatability and idempotency by definition. Tests under
- *   `tests/lifecycle/**` are exempt — fixtures that prove the rule
+ * Rule 1 — "No Promise.all over the lifecycle surface".
+ *   Files under `.agents/scripts/lib/orchestration/lifecycle/**` MUST NOT
+ *   contain `Promise.all(`. The surface is the append-only ledger writer, and
+ *   record ordering is the whole point of an append-only trail: a parallel
+ *   write interleaves records and breaks the ordering a reader relies on.
+ *   Tests under `tests/lifecycle/**` are exempt — fixtures that prove the rule
  *   bites need to carry the pattern.
  *
- * Rule 2 — "Wildcard-observer firewall".
- *   Any module under `.agents/scripts/lib/orchestration/lifecycle/listeners/**`
- *   that calls `bus.on('*', …)` MUST NOT import a side-effecting module.
- *   The static blocklist is small (the modules that mutate GitHub state,
- *   the worktree, or write outside `temp/run-<id>/`); we match by module
- *   specifier suffix to keep the rule simple and stable.
+ *   (Story #5024 narrowed the rationale. It was "the bus is a strictly
+ *   sequential mediator; parallelizing listeners breaks repeatability", which
+ *   stopped being the reason when the bus was deleted. The rule still guards a
+ *   real property of what remains.)
+ *
+ *   The old Rule 2 — "wildcard-observer firewall", gating any module under
+ *   `lifecycle/listeners/**` that called `bus.on('*', …)` — was deleted by
+ *   Story #5024 along with the bus. Both halves of its predicate became
+ *   unsatisfiable in the same commit (the directory is gone and there is no
+ *   `bus` to call `.on` on), so it returned zero violations by construction
+ *   rather than by verification: a gate that cannot fire, of exactly the class
+ *   Story #5004 retired `check-gherkin-placeholders.js` for.
  *
  * Rule 3 — "Auto-merge lockout" (Story #2253 / Task #2255, Epic #2172
  *   review High-1).
  *   String literals containing the substring `gh pr merge` MUST NOT
  *   appear in any file under `.agents/scripts/**` EXCEPT
- *   `.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-armer.js`
- *   (Wave 7, Story #2256). The original safety hole was an
+ *   `lib/orchestration/single-story-close/phases/auto-merge.js` — the v2
+ *   close path that replaced the Epic-era `AutomergeArmer` listener the rule
+ *   was originally written against. The original safety hole was an
  *   unconditional `gh pr merge <pr> --auto --squash --delete-branch`
  *   call in `epic-deliver-finalize.js` that armed GitHub's native
  *   auto-merge BEFORE the framework's automerge predicate evaluated
@@ -39,6 +46,23 @@
  *   The exempt path is matched by suffix so it bites even before the
  *   armer file lands (Wave 7); pre-existence is not required.
  *
+ * Scan root:
+ *   --root <dir>  Scan <dir> instead of this checkout. Both surfaces are
+ *                 derived from it, so one flag moves the whole scan.
+ *                 Defaults to the repository this script ships in, which is
+ *                 what `npm run lint` gets by passing nothing.
+ *
+ *   The seam exists for tests (Story #5052). The CLI test that proves a
+ *   violation is *caught* has to plant one, and it used to plant into the
+ *   live `.agents/` tree — which `tests/e2e/sync-prune.integration.test.js`
+ *   copies with the real binary, so the two raced: the sync either lost the
+ *   file between enumeration and `copyfile` (ENOENT) or copied it once and
+ *   pruned it on the second pass, tripping an idempotence assertion. Pointing
+ *   the planting test at a temp root keeps what that test was written for —
+ *   discovery is still the CLI's own walk, not an injected file list — while
+ *   leaving the shared tree untouched. Mirrors the `--root` seam
+ *   `check-test-temp-hygiene.js` already ships for the same reason.
+ *
  * Exit codes:
  *   0 — clean.
  *   1 — at least one violation; offending file + line printed to stderr.
@@ -48,25 +72,32 @@
  * biome + markdownlint; a custom rule fits cleanly alongside.
  */
 
-import { readdirSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { runAsCli } from './lib/cli-utils.js';
+import { walkFilesByExtension } from './lib/fs-walk.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
-const LIFECYCLE_DIR = path.join(
-  REPO_ROOT,
-  '.agents',
-  'scripts',
-  'lib',
-  'orchestration',
-  'lifecycle',
-);
-const LISTENERS_SUBDIR = path.join(LIFECYCLE_DIR, 'listeners');
-const SCRIPTS_DIR = path.join(REPO_ROOT, '.agents', 'scripts');
+/** Rule 1's scan surface for a given repository root. */
+function lifecycleDirFor(root) {
+  return path.join(
+    root,
+    '.agents',
+    'scripts',
+    'lib',
+    'orchestration',
+    'lifecycle',
+  );
+}
+
+/** Rule 3's scan surface for a given repository root. */
+function scriptsDirFor(root) {
+  return path.join(root, '.agents', 'scripts');
+}
 
 /**
  * Files exempt from the merge-lockout rule. The path is matched by
@@ -102,52 +133,6 @@ const MERGE_LOCKOUT_INFRASTRUCTURE_SUFFIXES = Object.freeze([
   path.join('.agents', 'scripts', 'check-lifecycle-lint.js'),
 ]);
 
-/**
- * Static blocklist of modules that mutate state under orchestration.
- * Matched by `import … from '<spec>'` specifier suffix so both
- * relative and package imports are caught. The list is small by
- * intent — wildcard observers should not need ANY of these.
- *
- * Maintainers: when a future module joins the "mutates real state"
- * club, add it here. The lint rule is the wildcard-firewall contract;
- * the listeners SHOULD NOT bypass it.
- */
-const STATE_MUTATING_MODULES = Object.freeze([
-  // GitHub state writers
-  'update-ticket-state.js',
-  'post-structured-comment.js',
-  'lib/orchestration/ticketing/state.js',
-  'lib/orchestration/ticketing/bulk.js',
-  // git / worktree mutators
-  'lib/git-utils.js',
-  'lib/orchestration/worktree-manager.js',
-  // notification writers
-  'notify.js',
-]);
-
-/**
- * Walk a directory tree synchronously, yielding absolute paths of files
- * matching `.js`. The lifecycle surface is small (< 50 files in the
- * worst case); a streaming walker is unnecessary.
- */
-function* walkJs(dir) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === 'ENOENT') return;
-    throw err;
-  }
-  for (const entry of entries) {
-    const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      yield* walkJs(p);
-    } else if (entry.isFile() && entry.name.endsWith('.js')) {
-      yield p;
-    }
-  }
-}
-
 /**
  * Rule 1 enforcement. Returns an array of `{ file, line, hint }`
  * violations. Inline disable comments (`// lint-lifecycle-disable`) on
@@ -158,7 +143,7 @@ export function findPromiseAllViolations(
   { read = readFileSync } = {},
 ) {
   const violations = [];
-  for (const file of walkJs(rootDir)) {
+  for (const file of walkFilesByExtension(rootDir, '.js')) {
     const text = read(file, 'utf8');
     const lines = text.split('\n');
     for (let i = 0; i < lines.length; i += 1) {
@@ -169,7 +154,7 @@ export function findPromiseAllViolations(
         violations.push({
           file,
           line: i + 1,
-          hint: 'Promise.all over listener arrays breaks bus repeatability. Listeners must run sequentially with await.',
+          hint: 'Promise.all on the lifecycle surface interleaves ledger writes. The ledger is append-only; writes must stay sequential.',
         });
       }
     }
@@ -177,45 +162,6 @@ export function findPromiseAllViolations(
   return violations;
 }
 
-/**
- * Rule 2 enforcement. Returns violations for any file under
- * `listenersDir` that BOTH (a) registers a wildcard observer
- * (`bus.on('*', …)`) AND (b) imports a state-mutating module.
- *
- * Files that don't register a wildcard observer are not gated; files
- * that wildcard-observe but only import safe modules are not gated.
- */
-export function findWildcardObserverFirewallViolations(
-  listenersDir,
-  { read = readFileSync, blocklist = STATE_MUTATING_MODULES } = {},
-) {
-  const violations = [];
-  for (const file of walkJs(listenersDir)) {
-    const text = read(file, 'utf8');
-    const hasWildcard = /\bbus\s*\.\s*on\s*\(\s*['"`]\*['"`]/.test(text);
-    if (!hasWildcard) continue;
-    // Extract imported module specifiers — robust enough for ES module
-    // imports without parsing the full AST.
-    // `matchAll` returns an iterator of regex match arrays; using it
-    // sidesteps the assignment-in-`while` pattern biome flags as
-    // confusing.
-    for (const match of text.matchAll(/\bfrom\s+['"]([^'"]+)['"]/g)) {
-      const spec = match[1];
-      for (const banned of blocklist) {
-        if (spec === banned || spec.endsWith(`/${banned}`)) {
-          violations.push({
-            file,
-            spec,
-            hint: `Wildcard observers must not import state-mutating modules. Saw '${spec}'.`,
-          });
-          break;
-        }
-      }
-    }
-  }
-  return violations;
-}
-
 /**
  * Strip block (`/* … *​/`) and line (`// …`) comments from a source
  * string. Pure — exported for tests so the comment-stripping contract
@@ -310,7 +256,7 @@ export function findMergeLockoutViolations(
   // CLI, only the space-delimited form is.
   const FORBIDDEN = 'gh pr merge';
   const lineRe = /(['"`])((?:\\.|(?!\1).)*)\1/g;
-  for (const file of walkJs(rootDir)) {
+  for (const file of walkFilesByExtension(rootDir, '.js')) {
     // Skip the armer (intentional carrier) and the lint infrastructure.
     const allExempt = [...allowSuffixes, ...infrastructureSuffixes];
     if (allExempt.some((suffix) => file.endsWith(suffix))) continue;
@@ -347,25 +293,48 @@ export function findMergeLockoutViolations(
   return violations;
 }
 
+/**
+ * Parse the argument vector. The only option is the scan root; anything
+ * else is ignored so an extra flag can never silently narrow the scan.
+ *
+ * @param {string[]} argv Arguments without the node/script entries.
+ * @returns {{ root: string }}
+ */
+function parseArgv(argv) {
+  let root = REPO_ROOT;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--root') {
+      i += 1;
+      root = path.resolve(String(argv[i] ?? '.'));
+    }
+  }
+  return { root };
+}
+
 async function main() {
-  // Per-rule discovery.
-  const v1 = findPromiseAllViolations(LIFECYCLE_DIR);
-  const v2 = findWildcardObserverFirewallViolations(LISTENERS_SUBDIR);
-  const v3 = findMergeLockoutViolations(SCRIPTS_DIR);
+  const { root } = parseArgv(process.argv.slice(2));
+  // Per-rule discovery. Both rules' exemptions match by absolute-path
+  // SUFFIX, which is what lets an injected root keep the same allow-list
+  // semantics as the live tree — do not re-anchor them to `root`.
+  const v1 = findPromiseAllViolations(lifecycleDirFor(root));
+  const v3 = findMergeLockoutViolations(scriptsDirFor(root));
   const all = [
-    ...v1.map((v) => ({ rule: 'no-promise-all-listeners', ...v })),
-    ...v2.map((v) => ({ rule: 'wildcard-observer-firewall', ...v })),
+    ...v1.map((v) => ({ rule: 'no-promise-all-lifecycle', ...v })),
     ...v3.map((v) => ({ rule: 'merge-lockout', ...v })),
   ];
   if (all.length === 0) {
     process.stdout.write(
-      '[lifecycle-lint] clean: no Promise.all over listeners; no wildcard-firewall breaches; no merge-lockout violations.\n',
+      '[lifecycle-lint] clean: no Promise.all on the lifecycle surface; no merge-lockout violations.\n',
     );
     return 0;
   }
   for (const v of all) {
-    const loc = v.line ? `${v.file}:${v.line}` : v.file;
-    process.stderr.write(`[lifecycle-lint][${v.rule}] ${loc}\n  ${v.hint}\n`);
+    // Both finders always stamp a 1-based `line`, so there is no file-only
+    // fallback to render — the ternary that used to guard this was an
+    // unreachable branch (Story #5024).
+    process.stderr.write(
+      `[lifecycle-lint][${v.rule}] ${v.file}:${v.line}\n  ${v.hint}\n`,
+    );
   }
   return 1;
 }
@@ -373,4 +342,19 @@ async function main() {
 await runAsCli(import.meta.url, main, {
   source: 'check-lifecycle-lint',
   propagateExitCode: true,
+  usage: {
+    invocation: 'node .agents/scripts/check-lifecycle-lint.js [--root <dir>]',
+    summary:
+      'Enforce the two lifecycle lint rules biome cannot express: no Promise.all on the append-only lifecycle surface, and the auto-merge lockout on string literals under .agents/scripts/.',
+    flags: [
+      [
+        '--root <dir>',
+        'Repository root to scan (default: the checkout this script ships in). Both rule surfaces derive from it; used by tests so a planted violation never touches the shared tree.',
+      ],
+    ],
+    notes: [
+      'Ships as part of `npm run lint`, which invokes it with no arguments.',
+      'Exit codes:\n  0  clean\n  1  at least one violation; offending file and line printed to stderr',
+    ],
+  },
 });

package/.agents/scripts/check-schema-references.js

@@ -36,7 +36,7 @@
  *                      `` `${key}.schema.json` `` template), AND the
  *                      schema's stem appears literally in a JS source as the
  *                      key that would produce it. `lifecycle/` is loaded this
- *                      way by `lib/orchestration/lifecycle/bus.js`, and
+ *                      way by `lifecycle/emit-ledger-event.js`, and
  *                      `baselines/` by `lib/baselines/envelope.js`.
  *
  *                      BOTH halves are required. The directory evidence alone

package/.agents/scripts/diagnose-friction.js

@@ -36,6 +36,7 @@
 import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import { constants as osConstants } from 'node:os';
+import { INTERCEPTOR_MAX_BUFFER_BYTES } from './lib/child-exec.js';
 import { getLimits, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { appendSignal } from './lib/observability/signals-writer.js';
@@ -291,10 +292,12 @@ export async function main(args = process.argv.slice(2)) {
   const config = resolveConfig();
   const limits = getLimits(config);
   const executionTimeoutMs = limits.executionTimeoutMs;
-  // Hardcoded post-reshape (Epic #1720 Story #1739). Node `spawnSync`
-  // buffer ceiling — 10 MiB is the framework-wide value used by every
-  // child-process spawn site. An OOM symptom, not a domain knob.
-  const executionMaxBuffer = 10485760;
+  // The interceptor's bound is deliberately *below* the framework-wide
+  // `MAX_BUFFER_BYTES` ceiling: it is a reported policy bound whose value the
+  // emitted friction row carries (`details.executionMaxBuffer`), not an
+  // overflow guard. Story #5009 moved its definition to the shared
+  // child-process surface so it is no longer a hand-copied literal here.
+  const executionMaxBuffer = INTERCEPTOR_MAX_BUFFER_BYTES;
 
   const commandStr = cmdArgs.join(' ');
   Logger.error(`[Diagnostic Interceptor] Executing: ${commandStr}`);