mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/checks/loop-health.js

@@ -0,0 +1,340 @@
+/**
+ * loop-health.js — read-only retro-scope check for the feedback-loop
+ * substrate (Epic #4406 / Story #4419, the terminal slice).
+ *
+ * The original feedback-loop drift shipped silently because an empty
+ * feedback report is indistinguishable from a healthy one. This standing
+ * self-check closes that gap: at retro time it samples the on-disk signal
+ * substrate the sibling Stories established and surfaces the three ways the
+ * repaired loop can regress without anyone noticing:
+ *
+ *   1. **Schema-invalid signal lines.** It tails the most recent
+ *      {@link MAX_SAMPLE_LINES} lines of every `signals.ndjson` stream under
+ *      the Epic temp tree and validates each against the canonical
+ *      `signal-event.schema.json` (via `validateSignal`, the same validator
+ *      the writer uses — no hand-rolled drift).
+ *   2. **Persisted write-time rejects.** It reads the per-Epic reject tally
+ *      (`temp/epic-<id>/signal-rejects.json`, written by Story #4413's
+ *      signals-writer) so records that were dropped at write time — and thus
+ *      never appear in the stream — are still counted.
+ *   3. **Un-actioned retro proposals.** It reads the retro mirror
+ *      (`temp/epic-<id>/retro.md`, Story #4418) and flags any actionable
+ *      "Proposed issues" item that carries neither a filed-issue reference
+ *      (`Filed: [#N](url)`) nor lives under the explicit "One-off /
+ *      discarded" record.
+ *
+ * Contract:
+ *   - Scope `retro`, `autoCorrect: 'refuse-and-print'` — read-only by
+ *     construction; the runner refuses `autoFix` under the retro scope.
+ *   - A clean substrate (valid lines, zero rejects, every proposal filed or
+ *     discarded) yields **zero findings**, preserving the compact retro
+ *     shape. Only when a concern is non-zero does `detect` return a single
+ *     combined finding naming every non-clean dimension.
+ *   - No new provider plumbing: `detect(state)` reads `state.cwd` from the
+ *     existing cwd-scoped checks-registry state, anchors it to the main
+ *     checkout root, and reads the temp tree directly.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { mainCheckoutRoot, tempRootFrom } from '../config/temp-paths.js';
+import { validateSignal } from '../observability/signal-validator.js';
+
+/**
+ * Lines sampled from the tail of each `signals.ndjson` stream. The check is
+ * a health probe, not an exhaustive audit — the most recent window is a
+ * representative sample that keeps the read bounded on long streams.
+ */
+export const MAX_SAMPLE_LINES = 200;
+
+/**
+ * Locate the most-recently-touched `epic-<id>` temp tree under
+ * `<baseDir>/<tempRoot>`. Returns `{ epicId, epicDir }` or `null` when no
+ * Epic temp tree exists (a fresh checkout, or a non-Epic context).
+ *
+ * @param {string} baseDir  The main checkout root.
+ * @param {{ tempRoot?: string, fsImpl?: { readdirSync: typeof readdirSync, statSync: typeof statSync } }} [opts]
+ * @returns {{ epicId: number, epicDir: string } | null}
+ */
+export function resolveEpicTempTree(
+  baseDir,
+  { tempRoot = 'temp', fsImpl } = {},
+) {
+  const readdir = fsImpl?.readdirSync ?? readdirSync;
+  const stat = fsImpl?.statSync ?? statSync;
+  const tempDir = path.join(baseDir, tempRoot);
+  let entries;
+  try {
+    entries = readdir(tempDir);
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const entry of entries) {
+    const match = /^epic-(\d+)$/.exec(entry);
+    if (!match) continue;
+    const full = path.join(tempDir, entry);
+    let st;
+    try {
+      st = stat(full);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+    if (!best || st.mtimeMs > best.mtimeMs) {
+      best = { epicId: Number(match[1]), epicDir: full, mtimeMs: st.mtimeMs };
+    }
+  }
+  return best ? { epicId: best.epicId, epicDir: best.epicDir } : null;
+}
+
+/**
+ * Enumerate every `signals.ndjson` stream under an Epic temp tree: the
+ * Epic-level wave-lifecycle stream plus each per-Story stream.
+ *
+ * @param {string} epicDir
+ * @param {{ fsImpl?: { readdirSync: typeof readdirSync, statSync: typeof statSync } }} [opts]
+ * @returns {string[]}
+ */
+export function findSignalStreams(epicDir, { fsImpl } = {}) {
+  const readdir = fsImpl?.readdirSync ?? readdirSync;
+  const stat = fsImpl?.statSync ?? statSync;
+  const streams = [];
+  const isFile = (p) => {
+    try {
+      return stat(p).isFile();
+    } catch {
+      return false;
+    }
+  };
+  const epicSignals = path.join(epicDir, 'signals.ndjson');
+  if (isFile(epicSignals)) streams.push(epicSignals);
+  const storiesDir = path.join(epicDir, 'stories');
+  let storyEntries;
+  try {
+    storyEntries = readdir(storiesDir);
+  } catch {
+    storyEntries = [];
+  }
+  for (const entry of storyEntries) {
+    if (!/^story-\d+$/.test(entry)) continue;
+    const storySignals = path.join(storiesDir, entry, 'signals.ndjson');
+    if (isFile(storySignals)) streams.push(storySignals);
+  }
+  return streams;
+}
+
+/**
+ * Tail `maxLines` of a single stream and count how many sampled lines fail
+ * the canonical schema (a JSON parse failure counts as invalid). A missing
+ * or unreadable stream contributes zero — absence is not invalidity.
+ *
+ * @param {string} streamPath
+ * @param {{ validate?: typeof validateSignal, maxLines?: number, readImpl?: typeof readFileSync }} [opts]
+ * @returns {{ sampled: number, invalid: number }}
+ */
+export function sampleStreamInvalidCount(
+  streamPath,
+  {
+    validate = validateSignal,
+    maxLines = MAX_SAMPLE_LINES,
+    readImpl = readFileSync,
+  } = {},
+) {
+  let raw;
+  try {
+    raw = readImpl(streamPath, 'utf8');
+  } catch {
+    return { sampled: 0, invalid: 0 };
+  }
+  const lines = raw
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const tail = lines.slice(-maxLines);
+  let invalid = 0;
+  for (const line of tail) {
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      invalid += 1;
+      continue;
+    }
+    if (!validate(parsed).valid) invalid += 1;
+  }
+  return { sampled: tail.length, invalid };
+}
+
+/**
+ * Read the per-Epic persisted reject count from `signal-rejects.json`.
+ * Returns 0 when the tally is absent or unreadable.
+ *
+ * @param {string} epicDir
+ * @param {{ readImpl?: typeof readFileSync }} [opts]
+ * @returns {number}
+ */
+export function readRejectTally(epicDir, { readImpl = readFileSync } = {}) {
+  try {
+    const parsed = JSON.parse(
+      readImpl(path.join(epicDir, 'signal-rejects.json'), 'utf8'),
+    );
+    return parsed && Number.isFinite(parsed.count) ? parsed.count : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Scan a retro mirror body for actionable proposals that were neither filed
+ * nor discarded. An actionable proposal is a `- **Title**` item under a
+ * `### Proposed issues` heading whose body carries a paste-ready
+ * `gh issue create` stanza (the un-filed fallback) instead of a
+ * `Filed: [#N](url)` reference. Discarded proposals live under the separate
+ * "### One-off / discarded" heading and are never scanned here.
+ *
+ * @param {string} retroText
+ * @returns {string[]}  Titles of unfiled actionable proposals.
+ */
+export function scanRetroMirror(retroText) {
+  if (typeof retroText !== 'string' || retroText.length === 0) return [];
+  const ACTION_HEADING = /^###\s+Proposed issues\b/;
+  const ANY_HEADING = /^#{1,6}\s+/;
+  const ITEM = /^-\s+\*\*(.+?)\*\*\s*$/;
+  const unfiled = [];
+  let inSection = false;
+  let current = null;
+  const flush = () => {
+    if (current && current.actionable && !current.filed) {
+      unfiled.push(current.title);
+    }
+    current = null;
+  };
+  for (const line of retroText.split('\n')) {
+    if (ANY_HEADING.test(line)) {
+      flush();
+      inSection = ACTION_HEADING.test(line);
+      continue;
+    }
+    if (!inSection) continue;
+    const itemMatch = ITEM.exec(line);
+    if (itemMatch) {
+      flush();
+      current = { title: itemMatch[1].trim(), filed: false, actionable: false };
+      continue;
+    }
+    if (!current) continue;
+    if (/^\s*Filed:/.test(line)) current.filed = true;
+    if (/gh issue create/.test(line)) current.actionable = true;
+  }
+  flush();
+  return unfiled;
+}
+
+/**
+ * Core detection: locate the Epic temp tree under `baseDir`, sample its
+ * signal streams, read its reject tally, and scan its retro mirror. Returns
+ * a single combined finding when any dimension is non-clean, else `null`.
+ *
+ * @param {string} baseDir
+ * @param {{
+ *   tempRoot?: string,
+ *   validate?: typeof validateSignal,
+ *   maxLines?: number,
+ *   scope?: string,
+ *   fsImpl?: object,
+ *   readImpl?: typeof readFileSync,
+ * }} [opts]
+ * @returns {import('./index.js').Finding | null}
+ */
+export function detectLoopHealth(
+  baseDir,
+  {
+    tempRoot = 'temp',
+    validate = validateSignal,
+    maxLines = MAX_SAMPLE_LINES,
+    scope = 'retro',
+    fsImpl,
+    readImpl = readFileSync,
+  } = {},
+) {
+  const tree = resolveEpicTempTree(baseDir, { tempRoot, fsImpl });
+  if (!tree) return null;
+  const { epicId, epicDir } = tree;
+
+  const streams = findSignalStreams(epicDir, { fsImpl });
+  let invalidCount = 0;
+  let sampled = 0;
+  for (const stream of streams) {
+    const r = sampleStreamInvalidCount(stream, {
+      validate,
+      maxLines,
+      readImpl,
+    });
+    invalidCount += r.invalid;
+    sampled += r.sampled;
+  }
+
+  const rejectCount = readRejectTally(epicDir, { readImpl });
+
+  let retroText = '';
+  try {
+    retroText = readImpl(path.join(epicDir, 'retro.md'), 'utf8');
+  } catch {
+    retroText = '';
+  }
+  const unfiledProposals = scanRetroMirror(retroText);
+
+  const signalConcern = invalidCount > 0 || rejectCount > 0;
+  const proposalConcern = unfiledProposals.length > 0;
+  if (!signalConcern && !proposalConcern) return null;
+
+  const summaryParts = [];
+  const detailLines = [];
+  if (signalConcern) {
+    summaryParts.push(
+      `${invalidCount} schema-invalid signal sample(s), ${rejectCount} persisted reject(s)`,
+    );
+    detailLines.push(
+      `Sampled ${sampled} line(s) across ${streams.length} signals.ndjson stream(s) (last ${maxLines} per stream):`,
+      `  schema-invalid samples: ${invalidCount}`,
+      `  persisted reject tally (signal-rejects.json): ${rejectCount}`,
+    );
+  }
+  if (proposalConcern) {
+    summaryParts.push(
+      `${unfiledProposals.length} unfiled actionable proposal(s)`,
+    );
+    detailLines.push(
+      'Retro proposals with neither a filed-issue reference nor a discard record:',
+      ...unfiledProposals.map((title) => `  - ${title}`),
+    );
+  }
+
+  return {
+    id: 'loop-health',
+    severity: 'warning',
+    scope,
+    summary: `Loop-health (epic-${epicId}): ${summaryParts.join('; ')}.`,
+    detail: detailLines.join('\n'),
+    fixCommand:
+      'Inspect temp/epic-<id>/{signals.ndjson,signal-rejects.json,retro.md}; fix the signal producer or file/discard the surfaced proposals.',
+    autoCorrectable: false,
+  };
+}
+
+export default {
+  id: 'loop-health',
+  severity: 'warning',
+  scope: ['retro'],
+  autoCorrect: 'refuse-and-print',
+  detect(state) {
+    const cwd = state?.cwd ?? process.cwd();
+    const baseDir = mainCheckoutRoot(cwd) ?? cwd;
+    return detectLoopHealth(baseDir, {
+      tempRoot: tempRootFrom(state?.config),
+      scope: state?.scope ?? 'retro',
+    });
+  },
+};

package/.agents/scripts/lib/cli-args.js

@@ -58,6 +58,8 @@ export function parseSprintArgs(args = process.argv) {
       'skip-sync': { type: 'boolean', default: false },
       'no-auto-merge': { type: 'boolean', default: false },
       'no-full-scope-crap': { type: 'boolean', default: false },
+      'wait-merge': { type: 'boolean', default: false },
+      'no-wait-merge': { type: 'boolean', default: false },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -79,6 +81,12 @@ export function parseSprintArgs(args = process.argv) {
     skipSync: coerceBooleanFlag(values['skip-sync']),
     noAutoMerge: coerceBooleanFlag(values['no-auto-merge']),
     noFullScopeCrap: coerceBooleanFlag(values['no-full-scope-crap']),
+    // Story #4428 — headless must-land signal for `single-story-close.js`:
+    // `--wait-merge` opts a headless run into polling to merge confirmation
+    // instead of resting at `agent::closing`; `--no-wait-merge` is the
+    // explicit opt-out (see `single-story-close/phases/options.js`).
+    waitForMerge: coerceBooleanFlag(values['wait-merge']),
+    noWaitForMerge: coerceBooleanFlag(values['no-wait-merge']),
     executor: values.executor ?? null,
     // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
     cwd:

package/.agents/scripts/lib/config/explain.js

@@ -196,6 +196,10 @@ const KEY_MEANINGS = Object.freeze({
     'Maximum auto-fix attempts the code-review phase makes.',
   'delivery.codeReview.maxFixScopeFiles':
     'Maximum files an auto-fix may touch in one attempt.',
+  'delivery.codeReview.autoFixSeverity':
+    'Severity threshold for on-branch code-review remediation (medium fixes 🔴/🟠/🟡, high fixes 🔴/🟠 only; default medium).',
+  'delivery.epicAudit.autoFixSeverity':
+    'Severity threshold for on-branch epic-audit remediation (medium fixes 🔴/🟠/🟡, high fixes 🔴/🟠 only; default medium).',
   'delivery.refactorStage.enabled':
     'Whether a dedicated refactor stage runs during delivery.',
   'delivery.acceptanceEval.maxRounds':

package/.agents/scripts/lib/config/runners.js

@@ -48,15 +48,30 @@ const DEFAULT_DELIVER_RUNNER = Object.freeze({
  * and Phase 5 (code-review). Operators override via
  * `delivery.epicAudit.*` and `delivery.codeReview.*` in `.agentrc.json`
  * (Story #2611, Epic #2586).
+ *
+ * `autoFixSeverity` is **tier-aware** (Story #4412, Epic #4405). The
+ * Epic-close audit tier (`DEFAULT_EPIC_AUDIT`) defaults to `'high'` —
+ * remediating only 🔴 Critical + 🟠 High findings on-branch while 🟡 Medium
+ * and 🟢 Suggestion findings graduate to follow-up issues. This is the
+ * three-tier model's slim outermost tier: 🟡 Medium code-quality concerns are
+ * already routed into on-branch remediation shift-left (the write-time
+ * checklist threading of Story #4410 and the Story-scope local-lens pass of
+ * Story #4409), so the Epic-close tier stops paying to re-remediate them where
+ * a fix is most expensive. The code-review tier (`DEFAULT_CODE_REVIEW`) keeps
+ * the `'medium'` default introduced by Story #4399. Both are hard cutovers per
+ * `rules/git-conventions.md` — no back-compat flag; an operator opts back into
+ * the wider routing by setting `delivery.epicAudit.autoFixSeverity: 'medium'`.
  */
 export const DEFAULT_EPIC_AUDIT = Object.freeze({
   maxFixAttempts: 3,
   maxFixScopeFiles: 5,
+  autoFixSeverity: 'high',
 });
 
 export const DEFAULT_CODE_REVIEW = Object.freeze({
   maxFixAttempts: 3,
   maxFixScopeFiles: 5,
+  autoFixSeverity: 'medium',
 });
 
 /**
@@ -65,8 +80,8 @@ export const DEFAULT_CODE_REVIEW = Object.freeze({
  * @param {object | null | undefined} config
  * @returns {{
  *   deliverRunner: { concurrencyCap: number, progressReportIntervalSec: number, verifyConcurrencyCap: number },
- *   epicAudit: { maxFixAttempts: number, maxFixScopeFiles: number },
- *   codeReview: { maxFixAttempts: number, maxFixScopeFiles: number },
+ *   epicAudit: { maxFixAttempts: number, maxFixScopeFiles: number, autoFixSeverity: 'high'|'medium' },
+ *   codeReview: { maxFixAttempts: number, maxFixScopeFiles: number, autoFixSeverity: 'high'|'medium' },
  *   storyMergeRetry: { maxAttempts: number, backoffMs: readonly number[] },
  *   decomposer: { concurrencyCap: number },
  * }}
@@ -92,12 +107,16 @@ export function getRunners(config) {
         epicAuditUser.maxFixAttempts ?? DEFAULT_EPIC_AUDIT.maxFixAttempts,
       maxFixScopeFiles:
         epicAuditUser.maxFixScopeFiles ?? DEFAULT_EPIC_AUDIT.maxFixScopeFiles,
+      autoFixSeverity:
+        epicAuditUser.autoFixSeverity ?? DEFAULT_EPIC_AUDIT.autoFixSeverity,
     },
     codeReview: {
       maxFixAttempts:
         codeReviewUser.maxFixAttempts ?? DEFAULT_CODE_REVIEW.maxFixAttempts,
       maxFixScopeFiles:
         codeReviewUser.maxFixScopeFiles ?? DEFAULT_CODE_REVIEW.maxFixScopeFiles,
+      autoFixSeverity:
+        codeReviewUser.autoFixSeverity ?? DEFAULT_CODE_REVIEW.autoFixSeverity,
     },
     storyMergeRetry: DEFAULT_STORY_MERGE_RETRY,
     decomposer: DEFAULT_DECOMPOSER,

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

@@ -258,6 +258,30 @@ export function signalsFile(eid, sid, config) {
   return path.join(storyTempDir(eid, sid, config), 'signals.ndjson');
 }
 
+/**
+ * `temp/epic-<eid>/stories/story-<sid>/lifecycle.ndjson` — the story-scope
+ * ledger destination for lifecycle events emitted directly by a Story
+ * (rather than routed through the Epic-scoped bus ledger). Story #4426
+ * (Epic #4425) introduces the first consumer: a standalone
+ * `single-story-close` run (no parent Epic) emitting `merge.unlanded`
+ * needs an on-disk home even though there is no `epic-<id>/` directory to
+ * anchor the event to.
+ *
+ * Mirrors `epicLedgerPath` exactly, one level down: `eid === null` routes
+ * through `storyTempDir`'s standalone branch to
+ * `<tempRoot>/standalone/stories/story-<sid>/lifecycle.ndjson`; a real
+ * `eid` routes to `<tempRoot>/epic-<eid>/stories/story-<sid>/lifecycle.ndjson`,
+ * so an Epic-attached Story's story-scope ledger sits alongside its
+ * `signals.ndjson` sibling.
+ *
+ * @param {number|null} eid
+ * @param {number} sid
+ * @param {object} [config]
+ * @returns {string}
+ */
+export const storyLedgerPath = (eid, sid, config) =>
+  storyArtifactPath(eid, sid, 'lifecycle.ndjson', config);
+
 /**
  * Escape hatch for an Epic-level artifact whose name isn't part of the
  * canonical layout (one of the per-Epic perf surfaces, retro mirror, etc.).

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

@@ -210,12 +210,25 @@ const MERGE_WATCH_SCHEMA = {
  * `agent::blocked` (default 5) — a deliberately narrow bound for
  * unattended auto-fixes, independent of the Story-sizing thresholds in
  * `ticket-validator-sizing.js`.
+ *
+ * `autoFixSeverity` (Story #4399) is the threshold that governs which findings
+ * the Epic-close host-LLM remediation loop fixes on-branch. It is **tier-aware**
+ * (Story #4412, Epic #4405): the Epic-close audit tier defaults to `high`
+ * (route only 🔴 Critical + 🟠 High into remediation; 🟡 Medium + 🟢 Suggestion
+ * graduate to follow-up issues) because 🟡 Medium code-quality concerns are
+ * already remediated shift-left at the write-time and Story-scope tiers — the
+ * slim outermost tier stops re-paying to fix them where a fix is most
+ * expensive. Setting `medium` opts back into routing 🔴/🟠/🟡 on-branch. The
+ * enum is the single validation seam: a configured value round-trips through
+ * the resolver, and any value outside `['high', 'medium']` is rejected at load.
+ * Hard cutover per `rules/git-conventions.md` — there is no back-compat flag.
  */
 const EPIC_AUDIT_SCHEMA = {
   type: 'object',
   properties: {
     maxFixAttempts: { type: 'integer', minimum: 0 },
     maxFixScopeFiles: { type: 'integer', minimum: 1 },
+    autoFixSeverity: { type: 'string', enum: ['high', 'medium'] },
   },
   additionalProperties: false,
 };
@@ -324,15 +337,22 @@ const ACCEPTANCE_EVAL_SCHEMA = {
 /**
  * `delivery.feedbackLoop` — opt-out toggles consumed by the Epic finalize
  * listener's auto-file graduators (`lib/feedback-loop/*-graduator.js`, read
- * via `graduator-core.js#makeIsAutoFileEnabled`). Both default to `true`
- * (auto-file on); set either to `false` to suppress auto-filing the
+ * via `graduator-core.js#makeIsAutoFileEnabled`). All default to `true`
+ * (auto-file on); set any to `false` to suppress auto-filing the
  * corresponding non-blocking findings as follow-up issues.
+ *
+ * `retroProposals` (Story #4418) governs the retro auto-filer: when true
+ * (default) the retro's actionable routed proposals are filed as
+ * `meta::<framework-gap|consumer-improvement>` + `friction::<category>`
+ * issues via the graduator pre-parsed-findings seam, and the rendered retro
+ * sections list the filed issue numbers instead of paste-ready `gh` command
+ * stanzas; set it to `false` to fall back to the command stanzas.
  */
 const FEEDBACK_LOOP_SCHEMA = {
   type: 'object',
   properties: {
-    codeReviewAutoFile: { type: 'boolean' },
     auditResultsAutoFile: { type: 'boolean' },
+    retroProposals: { type: 'boolean' },
   },
   additionalProperties: false,
 };

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

@@ -116,6 +116,12 @@ export const QUALITY_SCHEMA = {
 /**
  * `delivery.codeReview` — sibling to `delivery.epicAudit`. Same bounded
  * retry + scope cap, applied to /deliver Phase 5 (code-review).
+ *
+ * `autoFixSeverity` (Story #4399) is the sibling of
+ * `delivery.epicAudit.autoFixSeverity`: the threshold that governs which
+ * Phase 5 findings the host-LLM focused-fix routing remediates on-branch —
+ * `medium` (default) routes 🔴/🟠/🟡 while 🟢 still graduates, `high`
+ * reproduces the pre-4399 Critical/High-only routing.
  */
 export const CODE_REVIEW_SCHEMA = {
   type: 'object',
@@ -173,6 +179,7 @@ export const CODE_REVIEW_SCHEMA = {
     providerConfig: { type: 'object', additionalProperties: true },
     maxFixAttempts: { type: 'integer', minimum: 0 },
     maxFixScopeFiles: { type: 'integer', minimum: 1 },
+    autoFixSeverity: { type: 'string', enum: ['high', 'medium'] },
   },
   additionalProperties: false,
 };