mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/observability/signals-writer.js

@@ -1,20 +1,21 @@
 /**
- * Append-only signals/trace writer (Epic #1030 Story #1041).
+ * Append-only signals writer (Epic #1030 Story #1041).
  *
  * Centralizes the per-(epic, story) NDJSON streams under
- * `temp/run-<id>/stories/story-<sid>/signals.ndjson` (and a sibling
- * `traces.ndjson` for trace-shaped records). Detector modules and the
- * runtime trace hook all funnel through this writer so the on-disk
- * shape stays under one schema and one set of robustness guarantees.
+ * `temp/run-<id>/stories/story-<sid>/signals.ndjson`. Every live emitter
+ * funnels through this writer so the on-disk shape stays under one schema
+ * and one set of robustness guarantees. The sibling `traces.ndjson` stream
+ * and its `appendTrace` entry point went in Story #5003 with the tool-trace
+ * hook that was its only producer.
  *
  * Robustness contract (Tech Spec #1032 §observability):
  *   - **Best-effort.** Every entry point swallows fs / JSON failures
  *     after logging via `Logger.warn`. Observability MUST NOT take down
  *     the runner — a failed write is a missing signal, not a halted
  *     wave.
- *   - **No buffering.** Each `appendSignal` / `appendTrace` opens the
- *     target file, writes one newline-terminated JSON line, and closes.
- *     The Tech Spec explicitly forbids in-process buffering: detectors
+ *   - **No buffering.** Each `appendSignal` opens the target file, writes
+ *     one newline-terminated JSON line, and closes.
+ *     The Tech Spec explicitly forbids in-process buffering: emitters
  *     fire from inside per-Story sub-agents that may exit abruptly, and
  *     a buffered tail would silently disappear on `process.exit`.
  *   - **Lazy directory creation.** The first write to a fresh Story
@@ -42,23 +43,11 @@ import {
   STANDALONE_DIRNAME,
   STORIES_DIRNAME,
   signalsFile,
-  storyTempDir,
 } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
-import { recordSignalReject, validateSignal } from './signal-validator.js';
+import { validateSignal } from './signal-validator.js';
 import { classifySignalSource } from './source-classifier.js';
 
-const TRACES_BASENAME = 'traces.ndjson';
-
-/**
- * Async traces-file path (kept private — consumers thread through
- * `appendTrace`). Mirrors `signalsFile` but with the `traces.ndjson`
- * sibling so the analyzer can scan signals and traces independently.
- */
-function tracesFile(eid, sid, config) {
-  return path.join(storyTempDir(eid, sid, config), TRACES_BASENAME);
-}
-
 /**
  * Best-effort decoration of a signal record with a `source` field
  * (`"framework"` or `"consumer"`) produced by `classifyPathSource`.
@@ -111,21 +100,23 @@ function tagSignalSource(signal) {
 /**
  * Validate a record against the canonical `signal-event.schema.json`
  * before it is appended. On failure the record is **dropped** (never
- * appended), a `Logger.warn` names the violating field, and the per-Epic
- * reject tally is incremented under the Epic temp tree. Never throws —
+ * appended) and a `Logger.warn` names the violating field. Never throws —
  * the writer's best-effort contract is preserved.
  *
+ * Story #5003 removed the persisted per-Epic reject tally this used to
+ * increment: v2 Stories are standalone (`epicId` is always null), so the
+ * tally was never written and its only reader could never see one.
+ *
  * @param {unknown} record
- * @param {{ epicId?: number|null, config?: object, label: string }} ctx
- * @returns {Promise<boolean>} true when the record is valid (safe to append).
+ * @param {string} label
+ * @returns {boolean} true when the record is valid (safe to append).
  */
-async function validateOrDrop(record, { epicId, config, label }) {
+function validateOrDrop(record, label) {
   const { valid, violatingField, message } = validateSignal(record);
   if (valid) return true;
   Logger.warn(
     `signals-writer: dropping schema-invalid ${label} record — violating field '${violatingField}' (${message}).`,
   );
-  await recordSignalReject({ epicId, config, field: violatingField });
   return false;
 }
 
@@ -189,44 +180,10 @@ export async function appendSignal(args) {
     return false;
   }
   const tagged = tagSignalSource(signal);
-  const ok = await validateOrDrop(tagged, {
-    epicId: Number.isInteger(epicId) ? epicId : null,
-    config,
-    label: 'signal',
-  });
-  if (!ok) return false;
+  if (!validateOrDrop(tagged, 'signal')) return false;
   return appendOne(target, tagged);
 }
 
-/**
- * Append one trace record to `temp/run-<id>/stories/story-<sid>/traces.ndjson`.
- * Same robustness contract as `appendSignal` — never throws.
- *
- * @param {{ epicId: number, storyId: number, trace: unknown, config?: object }} args
- * @returns {Promise<boolean>}
- */
-export async function appendTrace(args) {
-  const { epicId, storyId, trace, config } = args ?? {};
-  let target;
-  try {
-    target = tracesFile(epicId, storyId, config);
-  } catch (err) {
-    Logger.warn(
-      `signals-writer: invalid epicId/storyId for appendTrace: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return false;
-  }
-  const ok = await validateOrDrop(trace, {
-    epicId: Number.isInteger(epicId) ? epicId : null,
-    config,
-    label: 'trace',
-  });
-  if (!ok) return false;
-  return appendOne(target, trace);
-}
-
 /**
  * Stream any NDJSON `target` file line by line, invoking
  * `cb(parsed, lineNumber)` for each successfully parsed JSON line.

package/.agents/scripts/lib/observability/source-classifier.js

@@ -88,13 +88,14 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-action-pinning.js',
   'check-arch-cycles.js',
   'check-baseline-drift.js',
+  'check-baseline-scope.js',
   'check-baselines.js',
   'check-context-budget.js',
   'check-cyclomatic.js',
   'check-dead-exports.js',
   'check-doc-links.js',
-  'check-gherkin-placeholders.js',
-  'check-lifecycle-doc-drift.js',
+  'check-gherkin-corpus.js',
+  'check-knip-entries.js',
   'check-lifecycle-lint.js',
   'check-schema-references.js',
   'check-test-temp-hygiene.js',
@@ -117,7 +118,6 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'generate-workflows-doc.js',
   'git-cleanup.js',
   'install-matrix-assert.js',
-  'lint-baseline.js',
   'lint-issue-body.js',
   'lint-label-vocabulary.js',
   'mandrel-update-preflight.js',
@@ -130,6 +130,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'post-structured-comment.js',
   'pr-watch-with-update.js',
   'provision-git-hooks.js',
+  'prune-baseline-orphans.js',
   'quality-preview.js',
   'quality-watch.js',
   'resolve-doc-tiers.js',
@@ -140,24 +141,21 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'run-test-profile.js',
   'run-tests.js',
   'run-verify.js',
-  'signals-view.js',
   'single-story-close.js',
   'single-story-confirm-merge.js',
   'single-story-init.js',
   'stories-wave-tick.js',
-  'story-plan.js',
   'sync-agentrc.js',
-  'sync-branch-from-base.js',
   'sync-claude-agents.js',
   'sync-claude-commands.js',
   'test-isolate.js',
   'test-wrapper.js',
   'update-coverage-baseline.js',
   'update-crap-baseline.js',
+  'update-dead-exports-baseline.js',
   'update-duplication-baseline.js',
   'update-maintainability-baseline.js',
   'update-ticket-state.js',
-  'validate-docs-freshness.js',
   'validate-skills.js',
 ]);
 

package/.agents/scripts/lib/observability/terse-result.js

@@ -8,9 +8,9 @@ import { Logger } from '../Logger.js';
  * Terse hot-path result emission (Story #4685).
  *
  * The orchestration CLIs an agent invokes on every delivery turn
- * (`single-story-init`, `single-story-close`, `single-story-confirm-merge`,
- * `sync-branch-from-base`, the close `emit-blocked` path) historically dumped
- * their whole result object to stdout as pretty-printed JSON:
+ * (`single-story-init`, `single-story-close`, `single-story-confirm-merge`)
+ * historically dumped their whole result object to stdout as pretty-printed
+ * JSON:
  *
  *   --- STORY CLOSE RESULT ---
  *   { ... every field, 2-space indented ... }

package/.agents/scripts/lib/orchestration/behind-recovery.js

@@ -0,0 +1,114 @@
+/**
+ * behind-recovery.js — the one bounded `BEHIND` → `gh pr update-branch`
+ * recovery decision (Story #5006).
+ *
+ * Two loops watch an open PR and both must fast-forward it when GitHub
+ * reports `mergeStateStatus: BEHIND`:
+ *
+ *   - the CI-watch loop (`pr-watch.js#watchPrToTerminal`),
+ *     which probes with a synchronous `gh pr view` spawn and re-enters its
+ *     poll loop after each update; and
+ *   - the merge wait (`single-story-close/phases/confirm-merge.js`), which
+ *     probes with an async `gh` facade and simply re-reads on the next tick.
+ *
+ * They had two copies of the same three-way decision — *is it BEHIND, is
+ * there update budget left, did the update land* — differing only in
+ * incidental ordering, which is exactly the shape that drifts. This module
+ * owns the decision; the callers keep their own probe source, their own
+ * timing model, and their own operator-facing wording (supplied as the
+ * `on*` callbacks).
+ *
+ * Deliberately NOT owned here: probing `mergeStateStatus`, counting the
+ * budget across iterations, and deciding what a caller does next with the
+ * verdict. The helper is a single bounded step, not a loop.
+ */
+
+/**
+ * The `gh pr view --json mergeStateStatus` value that licenses a recovery.
+ * Module-private: both call sites reach it through {@link applyBehindUpdate},
+ * so exporting it would only add a symbol the reachability ratchet scores
+ * dead.
+ */
+const BEHIND_MERGE_STATE = 'BEHIND';
+
+/**
+ * Normalise an `updateBranch()` settlement into `{ ok, detail }`.
+ *
+ * Both callers' invokers signal failure differently — the merge wait's `gh`
+ * facade **throws**, the watcher's `spawnSync` port **resolves** a non-zero
+ * status — so both shapes are accepted: a throw is a failure, and so is a
+ * resolved object carrying `ok === false`. Anything else resolved (including
+ * `undefined`) is a success, which is what a facade that only throws on
+ * failure returns.
+ *
+ * @param {() => Promise<unknown>} updateBranch
+ * @returns {Promise<{ ok: boolean, detail: string }>}
+ */
+async function settleUpdate(updateBranch) {
+  try {
+    const result = await updateBranch();
+    if (result && typeof result === 'object' && result.ok === false) {
+      return { ok: false, detail: String(result.detail ?? 'update-failed') };
+    }
+    return { ok: true, detail: '' };
+  } catch (err) {
+    return { ok: false, detail: String(err?.message ?? err) };
+  }
+}
+
+/**
+ * Apply at most one bounded `gh pr update-branch` to a PR that is BEHIND its
+ * base.
+ *
+ * The order of the two guards is load-bearing: **not-BEHIND is checked
+ * first**, so the budget-spent callback fires only for a PR that actually
+ * wanted an update. Reversing them would announce an exhausted budget on
+ * every poll of a perfectly up-to-date PR.
+ *
+ * @param {object} args
+ * @param {string|undefined|null} args.mergeStateStatus  As probed by the
+ *   caller. Anything other than `BEHIND` (including a degraded/unknown probe)
+ *   is a no-op — an unreadable merge state must never license a write.
+ * @param {number} [args.updatesUsed=0]   Updates already applied this wait.
+ * @param {number} [args.maxUpdates=0]    Hard cap on updates per wait.
+ * @param {() => Promise<unknown>} args.updateBranch  Invoker that issues the
+ *   fast-forward. See {@link settleUpdate} for the accepted settlements.
+ * @param {(args: { maxUpdates: number }) => void} [args.onBudgetSpent]
+ * @param {(args: { updatesUsed: number, maxUpdates: number }) => void} [args.onUpdated]
+ * @param {(detail: string) => void} [args.onUpdateFailed]
+ * @returns {Promise<{
+ *   attempted: boolean,
+ *   updated: boolean,
+ *   outcome: 'not-behind'|'budget-spent'|'updated'|'update-failed',
+ * }>}
+ *   `attempted` is true whenever the invoker ran — a failed update still
+ *   counts as an attempt (the merge wait treats it as a consumed tick and
+ *   re-reads the real state next poll). `updated` is true only when the
+ *   fast-forward actually landed, which is the signal a caller needs before
+ *   invalidating a terminal check outcome and re-polling.
+ */
+export async function applyBehindUpdate({
+  mergeStateStatus,
+  updatesUsed = 0,
+  maxUpdates = 0,
+  updateBranch,
+  onBudgetSpent,
+  onUpdated,
+  onUpdateFailed,
+}) {
+  if (mergeStateStatus !== BEHIND_MERGE_STATE) {
+    return { attempted: false, updated: false, outcome: 'not-behind' };
+  }
+  if (updatesUsed >= maxUpdates) {
+    onBudgetSpent?.({ maxUpdates });
+    return { attempted: false, updated: false, outcome: 'budget-spent' };
+  }
+
+  const settled = await settleUpdate(updateBranch);
+  if (!settled.ok) {
+    onUpdateFailed?.(settled.detail);
+    return { attempted: true, updated: false, outcome: 'update-failed' };
+  }
+  onUpdated?.({ updatesUsed, maxUpdates });
+  return { attempted: true, updated: true, outcome: 'updated' };
+}

package/.agents/scripts/lib/orchestration/ceremony-routing.js

@@ -28,12 +28,11 @@
  * ## The load-bearing invariant (M4-B acceptance floor — DO NOT VIOLATE)
  *
  * Risk-routing chooses fresh-vs-inline **PER CLUSTER**. It NEVER changes the
- * cluster COUNT. The cluster count is `ceil(totalACs / clusterCeiling)` with
- * the non-disableable `[1, 8]` clamp, owned entirely by
- * `acceptance-clusters.js` and untouched here. A low-risk Story still gets one
- * verdict per cluster — just possibly authored inline instead of by a fresh
- * sub-agent. This module takes the cluster index as an INPUT and returns a
- * decision for that one cluster; it has no way to add or remove clusters.
+ * cluster COUNT — the caller owns clustering and hands this module a cluster
+ * index. A low-risk Story still gets one verdict per cluster — just possibly
+ * authored inline instead of by a fresh sub-agent. This module takes the
+ * cluster index as an INPUT and returns a decision for that one cluster; it
+ * has no way to add or remove clusters.
  *
  * ## One verdict-owner per cluster (Story #4723)
  *
@@ -127,8 +126,8 @@ function normalizeCeremonyProfile(value) {
  * 2·stride, …) is forced fresh, yielding ≈`r` of clusters fresh. `r <= 0`
  * disables the floor (no cluster forced); `r >= 1` forces every cluster.
  *
- * @param {number} clusterIndex  Zero-based cluster position (from the fixed
- *   `ceil(totalACs / clusterCeiling)` fan-out — an INPUT, never mutated here).
+ * @param {number} clusterIndex  Zero-based cluster position (from the
+ *   caller-owned fan-out — an INPUT, never mutated here).
  * @param {number} rate          Sampling rate, already clamped into [0, 1] by
  *   `getDeliveryRouting`.
  * @returns {boolean} `true` when the floor forces this cluster fresh.

package/.agents/scripts/lib/orchestration/ci-rerun-guard.js

@@ -32,7 +32,6 @@
  * an unrecognized check state.
  */
 
-import { spawnSync } from 'node:child_process';
 import {
   existsSync,
   mkdirSync,
@@ -41,6 +40,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import path from 'node:path';
+import { spawnChild } from '../child-exec.js';
 import { resolveConfig } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
 import { createProvider } from '../provider-factory.js';
@@ -119,14 +119,13 @@ function ciDigestPaths({ storyId = null, tempRoot, cwd }) {
  * returns an empty tail when the run id is unknown or `gh` errors.
  * Injected into `writeCiDigest` so tests never shell out.
  */
-function ghRunLogTail({ runId, cwd, spawnFn = spawnSync, maxLines = 40 }) {
+function ghRunLogTail({ runId, cwd, spawnFn, maxLines = 40 }) {
   if (!runId) return '';
-  const result = spawnFn('gh', ['run', 'view', String(runId), '--log-failed'], {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-    maxBuffer: 10 * 1024 * 1024,
-  });
+  const result = spawnChild(
+    'gh',
+    ['run', 'view', String(runId), '--log-failed'],
+    { run: spawnFn, cwd },
+  );
   const out = (result.stdout ?? '').trim();
   if (out.length === 0) return '';
   const lines = out.split('\n');
@@ -142,17 +141,12 @@ function ghRunLogTail({ runId, cwd, spawnFn = spawnSync, maxLines = 40 }) {
  *
  * @returns {{ runId: string|null, url: string|null }}
  */
-function resolveFailingCheckRun({
-  prRef,
-  checkName,
-  cwd,
-  spawnFn = spawnSync,
-}) {
-  const result = spawnFn('gh', ['pr', 'checks', prRef, '--json', 'name,link'], {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-  });
+function resolveFailingCheckRun({ prRef, checkName, cwd, spawnFn }) {
+  const result = spawnChild(
+    'gh',
+    ['pr', 'checks', prRef, '--json', 'name,link'],
+    { run: spawnFn, cwd },
+  );
   try {
     const parsed = JSON.parse((result.stdout ?? '').trim() || '[]');
     const entry = Array.isArray(parsed)
@@ -172,15 +166,18 @@ function resolveFailingCheckRun({
  * `null` when `gh` fails or the payload is unparseable; callers treat an
  * unresolvable head as unverifiable, never as "changed".
  *
- * @param {{ prRef: string, cwd: string, spawnFn?: typeof spawnSync }} opts
+ * @param {{ prRef: string, cwd: string, spawnFn?: Function }} opts
  * @returns {string|null}
  */
-export function resolvePrHeadSha({ prRef, cwd, spawnFn = spawnSync }) {
-  const result = spawnFn('gh', ['pr', 'view', prRef, '--json', 'headRefOid'], {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-  });
+export function resolvePrHeadSha({ prRef, cwd, spawnFn }) {
+  const result = spawnChild(
+    'gh',
+    ['pr', 'view', prRef, '--json', 'headRefOid'],
+    {
+      run: spawnFn,
+      cwd,
+    },
+  );
   if ((result?.status ?? 1) !== 0) return null;
   try {
     const parsed = JSON.parse((result.stdout ?? '').trim() || '{}');
@@ -204,18 +201,17 @@ const NOT_ARMED = /not enabled|isn't enabled|is not set|no auto-?merge/i;
  * Disarm GitHub native auto-merge for the PR — the race-free response to the
  * first red. Never throws.
  *
- * @param {{ prRef: string, cwd: string, spawnFn?: typeof spawnSync }} opts
+ * @param {{ prRef: string, cwd: string, spawnFn?: Function }} opts
  * @returns {{ disarmed: boolean, alreadyUnarmed: boolean, detail: string }}
  *   `disarmed` is true when the PR is (now) un-armed; `alreadyUnarmed`
  *   distinguishes "there was nothing armed" from an executed disarm.
  */
-export function disarmAutoMerge({ prRef, cwd, spawnFn = spawnSync }) {
+export function disarmAutoMerge({ prRef, cwd, spawnFn }) {
   let result;
   try {
-    result = spawnFn('gh', ['pr', 'merge', prRef, '--disable-auto'], {
+    result = spawnChild('gh', ['pr', 'merge', prRef, '--disable-auto'], {
+      run: spawnFn,
       cwd,
-      encoding: 'utf-8',
-      shell: false,
     });
   } catch (err) {
     return {
@@ -362,6 +358,9 @@ function renderDigestMarkdown(digest, failures) {
  * @param {string} opts.prRef
  * @param {Function} [opts.checkRunFn]
  * @param {Function} [opts.logTailFn]
+ * @param {Function} [opts.spawnFn] Child runner handed to the two default
+ *   `gh` probes, so their real bodies can be exercised without shelling out.
+ *   Ignored when `checkRunFn` / `logTailFn` are replaced outright.
  * @returns {{ jsonPath: string, mdPath: string } | null}
  */
 export function writeCiDigest({
@@ -374,12 +373,14 @@ export function writeCiDigest({
   prRef,
   checkRunFn = resolveFailingCheckRun,
   logTailFn = ghRunLogTail,
+  spawnFn,
 }) {
   const paths = ciDigestPaths({ storyId, tempRoot, cwd });
   if (!paths) return null;
   const primary = failures[0] ?? { name: 'unknown', outcome: 'failure' };
-  const checkRun = checkRunFn({ prRef, checkName: primary.name, cwd }) ?? {};
-  const logTail = logTailFn({ runId: checkRun.runId, cwd });
+  const checkRun =
+    checkRunFn({ prRef, checkName: primary.name, cwd, spawnFn }) ?? {};
+  const logTail = logTailFn({ runId: checkRun.runId, cwd, spawnFn });
   const previous = readCiDigest({ storyId, tempRoot, cwd });
   const digest = {
     storyId: paths.scope.id,

package/.agents/scripts/lib/orchestration/code-review.js

@@ -15,8 +15,8 @@
  *
  * v2.0.0 removed the Epic tier. The Epic-scope envelope and the
  * Epic-scoped `code-review.start` / `.end` lifecycle emits (whose schema
- * requires `epicId`) went with it; Story scope is the only scope and the
- * module no longer touches the lifecycle bus.
+ * requires `epicId`) went with it; Story scope is the only scope. Story #5024
+ * deleted those schemas along with the bus that was their only publish path.
  *
  * Public API:
  *   - `runCodeReview({ ticketId, headRef, provider, logger, ... })` →