mandrel 2.8.0 → 2.10.0

package/.agents/scripts/lib/audit-suite/selector.js

@@ -702,7 +702,7 @@ const SOURCE_CODE_EXTENSIONS = Object.freeze([
 const TEST_FILE_RE = new RegExp(String.raw`\.(test|spec)\.[cm]?[jt]sx?$`);
 // biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
 const TEST_DIR_RE = new RegExp(
-  String.raw`(^|/)(tests?|__tests__|spec|e2e|__mocks__)(/|$)`,
+  '(^|/)(tests?|__tests__|spec|e2e|__mocks__)(/|$)',
 );
 // biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
 const CODE_EXT_RE = new RegExp(String.raw`\.[cm]?[jt]sx?$`);

package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js

@@ -36,6 +36,92 @@ import { toCanonicalFinding } from './finding-adapter.js';
  * @property {string[]} matchedFingerprints — full sha1 list that triggered the match.
  */
 
+/**
+ * Render a short, operator-legible reason from a dedup-lookup failure. Pure —
+ * no imports, no I/O — so the module stays pure orchestration (Story #4678).
+ * @param {unknown} err
+ * @returns {string}
+ */
+function describeDegradeReason(err) {
+  const status = err?.status;
+  const message = err?.message ?? String(err);
+  if (status === 422 || /\b422\b/.test(message)) {
+    return 'search query rejected (HTTP 422)';
+  }
+  if (/rate limit/i.test(message)) {
+    return 'rate limit still exhausted after cooldown';
+  }
+  return `dedup lookup failed: ${message}`;
+}
+
+/**
+ * Stable operator-facing label for a group in a degrade report.
+ * @param {object} group
+ * @returns {string}
+ */
+function groupLabel(group) {
+  return group?.groupKey ?? group?.title ?? '(unlabelled group)';
+}
+
+/**
+ * Route every finding in one group and fold the per-finding decisions up to a
+ * group action. Extracted so the top-level loop can wrap it in one try/catch:
+ * a search failure that survives the endpoint budget (an HTTP 422, or a rate
+ * limit still exhausted after the cooldown) throws out of here and is caught
+ * once per group rather than aborting the whole scan (Story #4678).
+ *
+ * @param {object} group
+ * @param {object} routing — `{ searchIssues, semanticPort, routeOptions }`.
+ * @returns {Promise<{ action: string, matchedIssues: Array, matchedFingerprints: string[] }>}
+ */
+async function classifyOneGroup(
+  group,
+  { searchIssues, semanticPort, routeOptions },
+) {
+  const findings = group.findings ?? [];
+  const matchedIssues = [];
+  const matchedFingerprints = [];
+  let sawOpen = false;
+  let sawClosed = false;
+
+  for (const finding of findings) {
+    const sha = finding?.fingerprint?.full;
+    if (typeof sha !== 'string' || sha.length !== 40) continue;
+
+    const canonical = toCanonicalFinding(finding);
+    const { decision, matchedIssue, fingerprint } = await routeFinding(
+      canonical,
+      semanticPort
+        ? { searchIssues, searchCandidates: () => semanticPort(canonical) }
+        : { searchIssues },
+      routeOptions,
+    );
+
+    if (decision === 'new') continue;
+
+    if (matchedIssue) {
+      matchedIssues.push({
+        number: matchedIssue.number,
+        state: matchedIssue.state,
+      });
+    }
+    if (!matchedFingerprints.includes(fingerprint)) {
+      matchedFingerprints.push(fingerprint);
+    }
+    if (decision === 'update-existing' || decision === 'duplicate') {
+      sawOpen = true;
+    } else if (decision === 'regression-of-closed') {
+      sawClosed = true;
+    }
+  }
+
+  let action = 'create';
+  if (sawOpen) action = 'skip-open';
+  else if (sawClosed) action = 'skip-reoccurring';
+
+  return { action, matchedIssues, matchedFingerprints };
+}
+
 /**
  * @param {object} params
  * @param {Array<object>} params.groups — output of `groupFindings`.
@@ -44,12 +130,18 @@ import { toCanonicalFinding } from './finding-adapter.js';
  *   Optional meaning-first candidate search (production: `semantic-issue-search.js`).
  *   When supplied, routing runs the Stage-1 semantic pass and opts into
  *   location-based semantic-key confirmation.
- * @returns {Promise<{ classifications: GroupClassification[], summary: { create: number, skipOpen: number, skipReoccurring: number } }>}
+ * @param {(entry: { group: object, reason: string }) => void} [params.onDegraded]
+ *   Optional sink notified once per group whose dedup lookup could not complete
+ *   (Story #4678). The group is then classified `create` — a soft-fail, never
+ *   fatal. Pure orchestration: this module performs no network I/O and swallows
+ *   no failure silently.
+ * @returns {Promise<{ classifications: GroupClassification[], summary: { create: number, skipOpen: number, skipReoccurring: number, dedupDegraded: { count: number, groups: Array<{ group: string, reason: string }> } } }>}
  */
 export async function classifyGroupsAgainstGitHub({
   groups,
   provider,
   searchCandidates,
+  onDegraded,
 }) {
   if (!Array.isArray(groups)) {
     throw new Error('classifyGroupsAgainstGitHub: groups must be an array');
@@ -67,67 +159,40 @@ export async function classifyGroupsAgainstGitHub({
   const searchIssues = (sha) => provider.findIssuesByFingerprint(sha);
   const semanticPort =
     typeof searchCandidates === 'function' ? searchCandidates : undefined;
-  const routeOptions = { semanticKeyConfirm: Boolean(semanticPort) };
+  const routing = {
+    searchIssues,
+    semanticPort,
+    routeOptions: { semanticKeyConfirm: Boolean(semanticPort) },
+  };
 
   const classifications = [];
-  const summary = { create: 0, skipOpen: 0, skipReoccurring: 0 };
+  const summary = {
+    create: 0,
+    skipOpen: 0,
+    skipReoccurring: 0,
+    dedupDegraded: { count: 0, groups: [] },
+  };
 
   for (const group of groups) {
-    const findings = group.findings ?? [];
-
-    const matchedIssues = [];
-    const matchedFingerprints = [];
-    let sawOpen = false;
-    let sawClosed = false;
-
-    for (const finding of findings) {
-      const sha = finding?.fingerprint?.full;
-      if (typeof sha !== 'string' || sha.length !== 40) continue;
-
-      const canonical = toCanonicalFinding(finding);
-      const { decision, matchedIssue, fingerprint } = await routeFinding(
-        canonical,
-        semanticPort
-          ? { searchIssues, searchCandidates: () => semanticPort(canonical) }
-          : { searchIssues },
-        routeOptions,
-      );
-
-      if (decision === 'new') continue;
-
-      if (matchedIssue) {
-        matchedIssues.push({
-          number: matchedIssue.number,
-          state: matchedIssue.state,
-        });
-      }
-      if (!matchedFingerprints.includes(fingerprint)) {
-        matchedFingerprints.push(fingerprint);
-      }
-      if (decision === 'update-existing' || decision === 'duplicate') {
-        sawOpen = true;
-      } else if (decision === 'regression-of-closed') {
-        sawClosed = true;
-      }
+    let result;
+    try {
+      result = await classifyOneGroup(group, routing);
+    } catch (err) {
+      // A dedup lookup that cannot complete degrades this group to `create`
+      // with a recorded reason — never aborts the whole scan.
+      const reason = describeDegradeReason(err);
+      const entry = { group: groupLabel(group), reason };
+      summary.dedupDegraded.count += 1;
+      summary.dedupDegraded.groups.push(entry);
+      if (typeof onDegraded === 'function') onDegraded({ group, reason });
+      result = { action: 'create', matchedIssues: [], matchedFingerprints: [] };
     }
 
-    let action = 'create';
-    if (sawOpen) {
-      action = 'skip-open';
-      summary.skipOpen += 1;
-    } else if (sawClosed) {
-      action = 'skip-reoccurring';
-      summary.skipReoccurring += 1;
-    } else {
-      summary.create += 1;
-    }
+    if (result.action === 'skip-open') summary.skipOpen += 1;
+    else if (result.action === 'skip-reoccurring') summary.skipReoccurring += 1;
+    else summary.create += 1;
 
-    classifications.push({
-      group,
-      action,
-      matchedIssues,
-      matchedFingerprints,
-    });
+    classifications.push({ group, ...result });
   }
 
   return { classifications, summary };

package/.agents/scripts/lib/config/temp-paths.js

@@ -52,6 +52,8 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { mkdtempSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 /**
@@ -114,6 +116,81 @@ export function _clearMainCheckoutRootCache() {
   _mainCheckoutRootCache.clear();
 }
 
+/**
+ * Environment variable naming an absolute per-process scratch tempRoot that
+ * every stream writer must land in during a test run (Story #4696).
+ *
+ * The shared test bootstrap (`lib/test-env.js`) sets this to a fresh
+ * `os.tmpdir()` directory before spawning the test runner, so any test that
+ * reaches a writer (`signals-writer`, the lifecycle `LedgerWriter`, etc.)
+ * *without* explicitly injecting an absolute tempRoot still resolves under
+ * scratch instead of the repo's real `temp/` tree. This is the single
+ * injection seam: because every path helper funnels a relative root through
+ * `anchorTempRoot`, one redirect here covers all writers regardless of how
+ * each one resolved its root.
+ */
+export const TEST_TEMP_ROOT_ENV = 'MANDREL_TEST_TEMP_ROOT';
+
+/**
+ * Resolve the absolute scratch tempRoot override, or `null` when none is
+ * configured. Only an **absolute** value is honoured — a relative override
+ * would re-anchor against the repo tree and defeat the isolation, so it is
+ * ignored (treated as unset). Module-internal: the behaviour is exercised
+ * through `anchorTempRoot`, so it is deliberately not exported (keeps the
+ * public seam to `anchorTempRoot` + `TEST_TEMP_ROOT_ENV`).
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string|null}
+ */
+function testScratchTempRoot(env = process.env) {
+  const override = env?.[TEST_TEMP_ROOT_ENV];
+  return typeof override === 'string' &&
+    override.length > 0 &&
+    path.isAbsolute(override)
+    ? override
+    : null;
+}
+
+/**
+ * Environment variable that opts a test-context process back into the real
+ * `temp/` tree (Story #4711). The `anchorTempRoot` test-context fallback
+ * refuses to anchor a relative root into the repo's telemetry tree when the
+ * process is a node:test context; a test that genuinely needs the real tree
+ * sets this to `'1'` on its own spawn — an explicit, greppable opt-out
+ * instead of a silent bypass.
+ */
+export const TEST_ALLOW_REAL_TEMP_ENV = 'MANDREL_TEST_ALLOW_REAL_TEMP';
+
+/**
+ * Per-process memo for the lazily-created test-context scratch dir, so every
+ * relative-root resolution in one test process converges on a single scratch
+ * tree (mirrors the `_mainCheckoutRootCache` pattern above).
+ */
+let _testContextScratchDir = null;
+
+/**
+ * Test-only: clear the test-context scratch memo so a suite can exercise the
+ * lazy-arming branch repeatedly in one process.
+ */
+export function _clearTestContextScratchCache() {
+  _testContextScratchDir = null;
+}
+
+/**
+ * Is this process a node:test context? True when the env carries
+ * `NODE_TEST_CONTEXT` (set by the node:test runner on every spawned test
+ * child, regardless of how the runner itself was launched) or when the
+ * process was started with the `--test` flag (a direct `node --test <file>`
+ * runner process, or in-process isolation modes).
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string[]} execArgv
+ * @returns {boolean}
+ */
+function inNodeTestContext(env, execArgv) {
+  return Boolean(env?.NODE_TEST_CONTEXT) || execArgv.includes('--test');
+}
+
 /**
  * Anchor a resolved `tempRoot` to the main checkout root when it is a
  * relative path (Story #3900). Absolute roots are returned verbatim; a
@@ -123,11 +200,54 @@ export function _clearMainCheckoutRootCache() {
  * root is returned unchanged so behaviour degrades to the prior
  * cwd-relative semantics rather than throwing.
  *
+ * Test isolation (Story #4696): when the scratch override
+ * (`MANDREL_TEST_TEMP_ROOT`) is set, a relative root is joined onto the
+ * scratch dir instead of the main checkout root, so a writer that reaches
+ * the default (or any relative) root under the test bootstrap lands in
+ * scratch and never pollutes the repo's real `temp/` telemetry tree. An
+ * absolute root injected by a well-behaved test still bypasses the redirect
+ * verbatim.
+ *
+ * Process-level arming (Story #4711): the wrapper-armed override above only
+ * covers processes spawned by `run-tests.js` — a direct `node --test <file>`
+ * run used to bypass it and append fixture records to the real tree. When no
+ * override is armed but the process *is* a node:test context (see
+ * `inNodeTestContext`), a per-process scratch dir is created lazily and the
+ * relative root anchors there instead. The scratch dir is memoized and — for
+ * the real `process.env` — written back to `MANDREL_TEST_TEMP_ROOT` so child
+ * processes the test spawns inherit the same scratch tree. Escape hatch: a
+ * test that genuinely needs the real tree sets
+ * `MANDREL_TEST_ALLOW_REAL_TEMP=1` (`TEST_ALLOW_REAL_TEMP_ENV`) to restore
+ * main-checkout anchoring; the `check-test-temp-hygiene` guard remains the
+ * backstop either way.
+ *
  * @param {string} tempRoot
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @param {{ mkdtemp?: typeof mkdtempSync, execArgv?: string[] }} [deps]
+ *   Injectable for tests.
  * @returns {string}
  */
-export function anchorTempRoot(tempRoot) {
+export function anchorTempRoot(tempRoot, env = process.env, deps = {}) {
   if (path.isAbsolute(tempRoot)) return tempRoot;
+  const scratch = testScratchTempRoot(env);
+  if (scratch) return path.join(scratch, tempRoot);
+  const execArgv = deps.execArgv ?? process.execArgv;
+  if (
+    inNodeTestContext(env, execArgv) &&
+    env?.[TEST_ALLOW_REAL_TEMP_ENV] !== '1'
+  ) {
+    if (_testContextScratchDir === null) {
+      const mkdtemp = deps.mkdtemp ?? mkdtempSync;
+      _testContextScratchDir = mkdtemp(
+        path.join(os.tmpdir(), 'mandrel-test-temp-'),
+      );
+      if (env === process.env) {
+        // Children spawned by this test process inherit the same scratch.
+        process.env[TEST_TEMP_ROOT_ENV] = _testContextScratchDir;
+      }
+    }
+    return path.join(_testContextScratchDir, tempRoot);
+  }
   const root = mainCheckoutRoot();
   return root ? path.join(root, tempRoot) : tempRoot;
 }

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -160,10 +160,19 @@ const SIGNALS_SCHEMA = {
  * behind-the-base PR up to date before giving the branch up as unwinnable,
  * rather than waiting out the budget behind a base it could have merged.
  * All keys default in the consumer when omitted (30s / 300s / 3600s / 3).
+ *
+ * `mode` selects the close-time merge posture (Story #4698). Default `sync`
+ * keeps the in-close foreground wait unchanged. `async` caps the per-invocation
+ * wait to a short probe window (~60s: catches instant merges and instantly-red
+ * required checks) and then returns the resumable `pending` terminal, so a
+ * slow-CI consumer no longer burns ~5 minutes of the host tool slot on a merge
+ * that lands after the wait would have expired anyway — the worker launches the
+ * `pending` envelope's `nextCommand` in the background instead.
  */
 const MERGE_WATCH_SCHEMA = {
   type: 'object',
   properties: {
+    mode: { type: 'string', enum: ['sync', 'async'] },
     intervalSeconds: { type: 'integer', minimum: 1 },
     maxWaitSeconds: { type: 'integer', minimum: 1 },
     maxBudgetSeconds: { type: 'integer', minimum: 1 },
@@ -280,6 +289,26 @@ const ACCEPTANCE_EVAL_SCHEMA = {
   additionalProperties: false,
 };
 
+/**
+ * `delivery.review` — close-scope review tuning (Story #4699). `lensDiffFloor`
+ * is the changed-line floor below which the Story-scope local-lens pass skips
+ * lens materialization for a diff with zero sensitive-path hits (default 40
+ * via `lib/audit-suite/lens-diff-floor.js`; `0` disables the skip). The
+ * maker-blind code-review pass and all hard gates are untouched by the floor.
+ */
+const REVIEW_SCHEMA = {
+  type: 'object',
+  properties: {
+    lensDiffFloor: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'Changed-line floor for the close-scope lens walk (Story #4699). A diff strictly below this many changed lines (additions + deletions) with zero sensitive-path hits skips lens materialization and records the skip in the findings-yield ledger. Default 40; 0 disables the skip. Hard gates and the maker-blind code-review pass are unaffected.',
+    },
+  },
+  additionalProperties: false,
+};
+
 /**
  * `delivery.feedbackLoop` — opt-out toggles consumed by the Epic finalize
  * listener's auto-file graduators (`lib/feedback-loop/*-graduator.js`, read
@@ -335,6 +364,7 @@ export const DELIVERY_SCHEMA = {
     quality: QUALITY_SCHEMA,
     mergeWatch: MERGE_WATCH_SCHEMA,
     codeReview: CODE_REVIEW_SCHEMA,
+    review: REVIEW_SCHEMA,
     refactorStage: REFACTOR_STAGE_SCHEMA,
     acceptanceEval: ACCEPTANCE_EVAL_SCHEMA,
     feedbackLoop: FEEDBACK_LOOP_SCHEMA,

package/.agents/scripts/lib/config-settings-schema.js

@@ -278,6 +278,38 @@ const PLANNING_SCHEMA = {
   properties: {
     riskHeuristics: LIST_OR_EXTENDER_OF_STRINGS,
     codebaseSnapshot: CODEBASE_SNAPSHOT_SCHEMA,
+    // Story #4683 — plan-time ceremony-lite complexity gate. Routes a trivial
+    // single-artifact seed onto a collapsed plan/deliver path while a
+    // multi-capability seed keeps the full ceremony. Deterministic and
+    // conservative (full on any doubt); the lite path never relaxes a
+    // non-negotiable (Story ticket, PR-to-main, repo gates, security baseline).
+    // Defaults live on DEFAULT_COMPLEXITY_GATE in
+    // `lib/orchestration/complexity-gate.js`.
+    complexityGate: {
+      type: 'object',
+      description:
+        'Plan-time ceremony-lite complexity gate. Routes trivial single-artifact seeds onto a collapsed plan/deliver path; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.',
+      properties: {
+        enabled: {
+          type: 'boolean',
+          description:
+            'Master switch. When false, every seed takes the full plan/deliver ceremony. Default true.',
+        },
+        maxSeedWords: {
+          type: 'integer',
+          minimum: 0,
+          description:
+            'Seed prose word ceiling for the lite path. A seed above this many words is not trivial and takes the full path. Default 150.',
+        },
+        maxArtifacts: {
+          type: 'integer',
+          minimum: 0,
+          description:
+            'Enumerated-artifact ceiling for the lite path. A seed enumerating more than this many candidate artifacts is multi-capability and takes the full path. Default 1.',
+        },
+      },
+      additionalProperties: false,
+    },
     // Cross-Story conflict-finding severity gates. Off by default so
     // existing repos keep advisory-only behaviour; flipping either to
     // `true` upgrades the matching finding class to `'hard'`, which routes

package/.agents/scripts/lib/findings/semantic-issue-search.js

@@ -23,6 +23,13 @@
 
 const DEFAULT_LIMIT = 25;
 
+/**
+ * Character budget for the query {@link buildQuery} emits. Default 200 leaves
+ * headroom under GitHub Search's 256-char limit for the `repo:` / `type:`
+ * qualifiers `searchIssues` appends (Story #4678).
+ */
+const DEFAULT_QUERY_BUDGET = 200;
+
 /**
  * Normalise a free-text string for token comparison: lowercased, trimmed,
  * punctuation collapsed to spaces.
@@ -68,18 +75,49 @@ function jaccard(a, b) {
   return union === 0 ? 0 : intersection / union;
 }
 
+/**
+ * The trailing path segment of a slash-or-backslash-delimited path. A deep
+ * `primaryFile` like `src/very/deep/module.js` contributes only `module.js`
+ * to the query — the basename carries the discriminating signal while the
+ * mangled path spends the character budget for nothing (Story #4678).
+ * @param {unknown} value
+ * @returns {string}
+ */
+function basename(value) {
+  const str = String(value ?? '');
+  const cut = str.split(/[\\/]/).filter(Boolean);
+  return cut.length > 0 ? cut[cut.length - 1] : '';
+}
+
 /**
  * Build the search query text for a finding. The title carries the strongest
- * signal; area and primaryFile sharpen it. This is the text both the
- * (production) full-text search port and the local relevance scorer key on.
+ * signal; area and the primaryFile **basename** sharpen it. This is the text
+ * both the (production) full-text search port and the local relevance scorer
+ * key on. The result is filled highest-signal-first (title, then area, then
+ * basename) up to `budget` characters on a whole-token boundary so a long title
+ * over a deep path never blows GitHub Search's length limit (Story #4678).
  * @param {object} finding
+ * @param {object} [options]
+ * @param {number} [options.budget] — max query length in characters.
  * @returns {string}
  */
-export function buildQuery(finding) {
-  return [finding?.title, finding?.area, finding?.primaryFile]
+export function buildQuery(finding, { budget = DEFAULT_QUERY_BUDGET } = {}) {
+  const tokens = [finding?.title, finding?.area, basename(finding?.primaryFile)]
     .map((v) => normaliseText(v))
     .filter((v) => v.length > 0)
-    .join(' ');
+    .join(' ')
+    .split(' ')
+    .filter(Boolean);
+
+  const kept = [];
+  let length = 0;
+  for (const token of tokens) {
+    const cost = kept.length === 0 ? token.length : token.length + 1;
+    if (length + cost > budget) break;
+    kept.push(token);
+    length += cost;
+  }
+  return kept.join(' ');
 }
 
 /**