mandrel 2.39.0 → 2.41.0

package/.agents/scripts/install-matrix-assert.js

@@ -8,8 +8,8 @@
  * `mandrel doctor` — across {npm, pnpm, yarn} x {ubuntu-latest,
  * windows-latest}. Rather than spread the per-leg invariants across
  * PowerShell-vs-bash shell snippets (which diverge on quoting, `$?`, and
- * separators per `.agents/rules/shell-conventions.md`), every leg shells out
- * to this single Node script so the checks run identically on every OS.
+ * path separators), every leg shells out to this single Node script so the
+ * checks run identically on every OS.
  *
  * It asserts three invariants against a consumer project directory:
  *

package/.agents/scripts/lib/audit-to-stories/epic-grouping-directive.js

@@ -0,0 +1,45 @@
+/**
+ * epic-grouping-directive.js — the container-Epic directive an audit sweep
+ * emits (Story #5139).
+ *
+ * Lives on its own because **both** `/audit-to-stories` output paths carry it:
+ * the `/mandrel-plan` seed one-pager (`seed-from-findings.js`) and the
+ * standalone Story-draft transcript (`audit-to-stories.js`). A sweep is the
+ * clearest case for a container — every Story shares a provenance and the
+ * operator almost always wants them delivered together — so the Epic is the
+ * **default** here, unlike the offer `/mandrel-plan` makes on an ad-hoc plan.
+ *
+ * It stays a directive in the text rather than an automatic write: the
+ * workflow's Phase 4 HITL stop is where an operator declines it.
+ *
+ * Since Story #5155 the directive names adoption first: a repeat sweep over the
+ * same area is the case most likely to already have a container, and opening a
+ * second one beside it is the failure this ordering exists to prevent.
+ *
+ * @module lib/audit-to-stories/epic-grouping-directive
+ */
+
+import { EPIC_SUGGESTION_THRESHOLD } from '../orchestration/plan-persist/epic-ops.js';
+
+/**
+ * Render the grouping directive for a proposed Story set.
+ *
+ * @param {unknown[]} groups The proposed Stories (only the count is read).
+ * @returns {string} Markdown paragraph(s).
+ */
+export function formatEpicGrouping(groups) {
+  const count = Array.isArray(groups) ? groups.length : 0;
+  if (count < EPIC_SUGGESTION_THRESHOLD) {
+    const noun = count === 1 ? 'Story' : 'Stories';
+    return `This sweep proposes ${count} ${noun} — below the ${EPIC_SUGGESTION_THRESHOLD}-Story threshold, so no container Epic is needed.`;
+  }
+  return [
+    `**Group these under a container Epic.** This sweep proposes ${count} Stories from one audit pass, which is exactly the case a container earns: they share a provenance and an operator will want to deliver them as a unit.`,
+    '',
+    '**Check `epicCandidates[]` first.** A repeat sweep over the same area usually belongs under the Epic the previous sweep opened, not beside it — adopt that one with `--epic <id>` (any Story count) rather than opening a second container for one body of work. Only when no open Epic fits does this directive mean *create*.',
+    '',
+    'The Epic is a **pure container** — a title, a one-paragraph goal, and the child checklist. It must carry no finding, no path and no rationale that is not already in a child Story, or that information ends up somewhere no delivering agent reads.',
+    '',
+    'Decline it and file the Stories flat if the operator prefers.',
+  ].join('\n');
+}

package/.agents/scripts/lib/audit-to-stories/ledger-commit.js

@@ -0,0 +1,290 @@
+/**
+ * lib/audit-to-stories/ledger-commit.js — persist the cross-run audit ledger.
+ *
+ * The `--auto` sweep's whole value is memory: `baselines/audit-ledger.json`
+ * is what lets the next run tell a re-detection from a fresh finding and an
+ * accepted risk from an unseen one. A scheduled sweep, though, typically runs
+ * on an ephemeral checkout — a fresh clone that is deleted when the job ends —
+ * so the ledger `--auto` writes is discarded and every later sweep starts from
+ * an empty memory. The sweep is then permanently amnesiac, and the ledger's
+ * suppression and regression signals never fire.
+ *
+ * This module closes that hole from both ends:
+ *
+ *   - {@link runLedgerCommit} (`--auto --ledger-commit`) commits the changed
+ *     ledger onto a dated `chore/audit-ledger-<YYYY-MM-DD>` branch, pushes it,
+ *     and opens a PR against `project.baseBranch` through the `gh` wrapper.
+ *     Auto-merge is never requested: a ledger PR records machine-derived state
+ *     a human should glance at, so landing it stays an operator decision.
+ *   - {@link resolveLedgerSummary} answers the question the *unflagged* sweep
+ *     needs — "would this ledger survive?" — so a run that cannot persist (no
+ *     `origin`, or HEAD parked off the base branch) says so in its summary,
+ *     and on stderr, instead of silently discarding the state.
+ *
+ * Both take injectable `git` / `gh` seams (`.agents/rules/test-seams.md`) so
+ * the branch/commit/push/PR argv shape is assertable without a live remote.
+ * The logic lives here rather than in `audit-to-stories.js` so the CLI file's
+ * complexity budget does not absorb a git driver.
+ */
+
+import { gh as defaultGh } from '../gh-exec.js';
+import { gitSync } from '../git-utils.js';
+import { DEFAULT_LEDGER_PATH } from './ledger.js';
+
+/** Fallback base branch when config carries no `project.baseBranch`. */
+const DEFAULT_BASE_BRANCH = 'main';
+
+/**
+ * Render the `YYYY-MM-DD` stamp both the branch name and the commit subject
+ * carry, so one sweep produces one identifiable ledger branch per day.
+ * @param {Date|string|number} [now]
+ * @returns {string}
+ */
+function isoDate(now) {
+  const date = now instanceof Date ? now : new Date(now ?? Date.now());
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * Resolve `project.baseBranch` defensively: an explicit value wins, then
+ * config, then `main`. A failed config resolve must never break a sweep that
+ * has already done its real work.
+ * @param {string} [explicit]
+ * @returns {Promise<string>}
+ */
+async function resolveBaseBranch(explicit) {
+  if (typeof explicit === 'string' && explicit.length > 0) return explicit;
+  try {
+    const { resolveConfig } = await import('../config-resolver.js');
+    const branch = resolveConfig()?.project?.baseBranch;
+    if (typeof branch === 'string' && branch.length > 0) return branch;
+  } catch (_) {
+    // fall through to the default
+  }
+  return DEFAULT_BASE_BRANCH;
+}
+
+/**
+ * Run a read-only git probe that must never throw: a checkout with no commits
+ * (or no repository at all) is a legitimate answer of "nothing to report",
+ * not a crash. The write path below uses {@link runStep} instead, where a
+ * failure IS fatal.
+ * @param {(cwd: string, ...args: string[]) => string} git
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {string} trimmed stdout, or `''` when git failed.
+ */
+function probeGit(git, cwd, args) {
+  try {
+    const out = git(cwd, ...args);
+    return typeof out === 'string' ? out.trim() : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+/**
+ * Wrap one write step so a git or `gh` failure surfaces as a fatal error that
+ * names the step that broke. Accepts sync and async steps alike.
+ * @param {string} name
+ * @param {() => unknown} fn
+ * @returns {Promise<unknown>}
+ */
+async function runStep(name, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw new Error(
+      `--ledger-commit failed at step "${name}": ${error?.message ?? error}`,
+      { cause: error },
+    );
+  }
+}
+
+/**
+ * Inspect whether the ledger changed and whether this checkout could persist
+ * it at all. Module-local: the two exported entry points below are the whole
+ * public surface, so a probe helper never becomes a second way in.
+ *
+ * `unpersisted` is the signal the unflagged `--auto` summary carries: the
+ * sweep produced new memory, and this checkout has nowhere to put it — either
+ * there is no `origin` to push to or HEAD is not on the base branch, so a
+ * commit here would not reach the repository's shared state.
+ *
+ * @param {object} [params]
+ * @param {string} [params.ledgerPath] — defaults to `baselines/audit-ledger.json`.
+ * @param {string} [params.baseBranch] — defaults to resolved `project.baseBranch`.
+ * @param {string} [params.cwd]
+ * @param {(cwd: string, ...args: string[]) => string} [params.git]
+ * @returns {Promise<{ ledgerPath: string, baseBranch: string, changed: boolean,
+ *   hasOrigin: boolean, headBranch: string, onBaseBranch: boolean,
+ *   unpersisted: boolean }>}
+ */
+async function assessLedgerPersistence({
+  ledgerPath = DEFAULT_LEDGER_PATH,
+  baseBranch,
+  cwd = process.cwd(),
+  git = gitSync,
+} = {}) {
+  const base = await resolveBaseBranch(baseBranch);
+  const changed =
+    probeGit(git, cwd, ['status', '--porcelain', '--', ledgerPath]).length > 0;
+  const hasOrigin = probeGit(git, cwd, ['remote'])
+    .split('\n')
+    .map((line) => line.trim())
+    .includes('origin');
+  const headBranch = probeGit(git, cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const onBaseBranch = headBranch === base;
+
+  return {
+    ledgerPath,
+    baseBranch: base,
+    changed,
+    hasOrigin,
+    headBranch,
+    onBaseBranch,
+    unpersisted: changed && (!hasOrigin || !onBaseBranch),
+  };
+}
+
+/**
+ * Warn that the reconciled ledger has nowhere to go. Names the file, because
+ * "state will be lost" is unactionable without knowing which state.
+ * @param {{ ledgerPath: string, baseBranch: string, hasOrigin: boolean, headBranch: string }} state
+ * @returns {string}
+ */
+function unpersistedWarning(state) {
+  const cause = state.hasOrigin
+    ? `HEAD is on "${state.headBranch || '(detached)'}", not the base branch "${state.baseBranch}"`
+    : 'this checkout has no "origin" remote';
+  return `ledger not persisted: ${state.ledgerPath} changed but ${cause}, so this sweep's memory will be lost when the checkout goes away. Re-run with --ledger-commit to open a PR for it, or commit ${state.ledgerPath} by hand.`;
+}
+
+/**
+ * Resolve the `--auto` summary's `ledger` field, annotating it with
+ * `unpersisted: true` (and warning on stderr) when the sweep produced memory
+ * this checkout cannot keep.
+ *
+ * The whole decision lives here rather than in the CLI so `runAuto` stays a
+ * straight-line assembly of its summary: `dryRun` and `ledgerCommit` are
+ * passed through raw and branched on once, in one place.
+ *
+ * @param {object} [params]
+ * @param {object|null} [params.ledger] — the plan's ledger summary, or null.
+ * @param {string} [params.ledgerPath]
+ * @param {boolean} [params.dryRun] — nothing was written, so nothing is at risk.
+ * @param {boolean} [params.ledgerCommit] — a PR is about to persist it.
+ * @param {string} [params.cwd]
+ * @param {(cwd: string, ...args: string[]) => string} [params.git]
+ * @param {{ warn: Function }} [params.logger]
+ * @returns {Promise<object|null>} the (possibly annotated) ledger summary.
+ */
+export async function resolveLedgerSummary({
+  ledger = null,
+  ledgerPath = DEFAULT_LEDGER_PATH,
+  dryRun,
+  ledgerCommit,
+  cwd,
+  git,
+  logger,
+} = {}) {
+  if (dryRun || ledgerCommit) return ledger;
+  const state = await assessLedgerPersistence({ ledgerPath, cwd, git });
+  if (!state.unpersisted) return ledger;
+  logger?.warn?.(unpersistedWarning(state));
+  return { ...(ledger ?? { path: ledgerPath }), unpersisted: true };
+}
+
+/**
+ * Compose the ledger PR body. Kept separate so the step sequence below reads
+ * as a sequence and not as a string-building exercise.
+ * @param {string} ledgerPath
+ * @param {string} date
+ * @returns {string}
+ */
+function pullRequestBody(ledgerPath, date) {
+  return [
+    `Reconciles the cross-run audit ledger (\`${ledgerPath}\`) written by the`,
+    `unattended \`audit-to-stories --auto\` sweep on ${date}.`,
+    '',
+    'Ledger-only change — no source, workflow or documentation file is touched.',
+    'Merging it is what gives the next sweep a memory: without it the ledger',
+    'dies with the checkout and every later run re-proposes findings this one',
+    'already filed, and re-surfaces findings a human already rejected.',
+    '',
+    'Auto-merge is deliberately not requested: the ledger records machine-derived',
+    'lifecycle state, and a human glance before it lands is the point.',
+  ].join('\n');
+}
+
+/**
+ * Commit the changed ledger onto a dated branch and open a PR for it.
+ *
+ * Skipped — returning `{ committed: false }` with a `reason` — when the ledger
+ * did not change. Every git/`gh` failure is fatal and names its step; the
+ * caller runs this *after* printing the run summary, so a broken remote never
+ * costs the operator the sweep's findings.
+ *
+ * @param {object} [params]
+ * @param {string} [params.ledgerPath]
+ * @param {string} [params.baseBranch]
+ * @param {string} [params.cwd]
+ * @param {(cwd: string, ...args: string[]) => string} [params.git]
+ * @param {{ pr: { create: (flags: string[]) => Promise<unknown> } }} [params.gh]
+ * @param {Date|string|number} [params.now]
+ * @returns {Promise<{ committed: boolean, reason?: string, branch?: string,
+ *   subject?: string, baseBranch?: string, ledgerPath: string }>}
+ */
+export async function runLedgerCommit({
+  ledgerPath = DEFAULT_LEDGER_PATH,
+  baseBranch,
+  cwd = process.cwd(),
+  git = gitSync,
+  gh = defaultGh,
+  now,
+} = {}) {
+  const state = await assessLedgerPersistence({
+    ledgerPath,
+    baseBranch,
+    cwd,
+    git,
+  });
+  if (!state.changed) {
+    return { committed: false, reason: 'ledger-unchanged', ledgerPath };
+  }
+
+  const date = isoDate(now);
+  const branch = `chore/audit-ledger-${date}`;
+  const subject = `chore(audit): reconcile audit ledger ${date}`;
+
+  await runStep('create-branch', () => git(cwd, 'checkout', '-b', branch));
+  await runStep('stage-ledger', () => git(cwd, 'add', '--', ledgerPath));
+  // The `-- <path>` pathspec is what keeps the commit ledger-only even when
+  // the sweep's checkout carries unrelated dirt.
+  await runStep('commit-ledger', () =>
+    git(cwd, 'commit', '-m', subject, '--', ledgerPath),
+  );
+  await runStep('push-branch', () =>
+    git(cwd, 'push', '--set-upstream', 'origin', branch),
+  );
+  await runStep('open-pull-request', () =>
+    gh.pr.create([
+      '--base',
+      state.baseBranch,
+      '--head',
+      branch,
+      '--title',
+      subject,
+      '--body',
+      pullRequestBody(ledgerPath, date),
+    ]),
+  );
+
+  return {
+    committed: true,
+    branch,
+    subject,
+    baseBranch: state.baseBranch,
+    ledgerPath,
+  };
+}

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -20,7 +20,10 @@ import path from 'node:path';
 import { normalizeSeverity } from '../findings/severity.js';
 
 const KEY_LINE = /^\s*-\s*\*\*([^:*]+):\*\*\s*(.*)$/;
-const HEADING_FINDING = /^###\s+(.+?)\s*$/;
+const HEADING_FINDING = /^(#{3,4})\s+(.+?)\s*$/;
+const SEVERITY_KEY_LINE = /^\s*-\s*\*\*(?:severity|impact)\s*:\*\*/i;
+const TALLY_LINE =
+  /severity\s+tally\s*:?\**\s*critical\s+(\d+)\s*\/\s*high\s+(\d+)\s*\/\s*medium\s+(\d+)\s*\/\s*low\s+(\d+)/i;
 const HEADING_SECTION = /^##\s+(.+?)\s*$/;
 const PATH_HINT =
   /(?<![\w/])([A-Za-z0-9_./\\@-]+\.(?:js|ts|tsx|jsx|mjs|cjs|md|json|yaml|yml|css|scss|html|py|go|rs|java|kt|rb|sh|ps1|tf|env))(?![\w])/g;
@@ -238,7 +241,11 @@ function splitFindingBlocks(reportText) {
     const findingMatch = HEADING_FINDING.exec(line);
     if (findingMatch) {
       if (current) blocks.push(current);
-      current = { title: findingMatch[1].trim(), bodyLines: [] };
+      current = {
+        level: findingMatch[1].length,
+        title: findingMatch[2].trim(),
+        bodyLines: [],
+      };
       continue;
     }
 
@@ -249,6 +256,88 @@ function splitFindingBlocks(reportText) {
   return blocks;
 }
 
+/**
+ * Does this block carry the axis line that makes it a finding rather than a
+ * section header? The skeleton mandates `Severity` (or its `Impact` alias), so
+ * its absence is the signal that a heading is organisational.
+ *
+ * @param {{ bodyLines: string[] }} block
+ * @returns {boolean}
+ */
+function carriesSeverity(block) {
+  return block.bodyLines.some((line) => SEVERITY_KEY_LINE.test(line));
+}
+
+/**
+ * Resolve `###` headings that are **grouping headers** rather than findings.
+ *
+ * Several lenses nest their findings one level deeper — a `###` per dimension
+ * (`### Perceivable`), each holding `####` finding blocks. Read flat, that
+ * report parsed as one severity-less finding per dimension with no files and
+ * no recommendation, and `--auto` filed those empties (Story #5144). The rule
+ * this applies: a `###` heading that carries no `Severity:`/`Impact:` line and
+ * is followed by `####` headings is a grouping header — its `####` children
+ * are emitted as findings and the header itself never is.
+ *
+ * A `###` heading that DOES carry the axis line keeps the previous behaviour:
+ * its `####` sub-sections fold back into its own body rather than splitting
+ * into phantom findings, so existing flat reports parse exactly as before.
+ *
+ * @param {Array<{ level: number, title: string, bodyLines: string[] }>} blocks
+ * @returns {Array<{ level: number, title: string, bodyLines: string[] }>}
+ */
+function foldGroupingHeaders(blocks) {
+  const out = [];
+  let parent = null;
+  for (const block of blocks) {
+    if (block.level <= 3) {
+      parent = block;
+      out.push(block);
+      continue;
+    }
+    if (!parent) {
+      out.push(block);
+      continue;
+    }
+    if (carriesSeverity(parent)) {
+      parent.bodyLines.push(`#### ${block.title}`, ...block.bodyLines);
+      continue;
+    }
+    parent.isGroupingHeader = true;
+    out.push(block);
+  }
+  return out.filter((block) => !block.isGroupingHeader);
+}
+
+/**
+ * Read the machine-readable severity tally the report envelope mandates in its
+ * `## Executive Summary`:
+ *
+ * ```text
+ * Severity tally: Critical 0 / High 2 / Medium 1 / Low 0
+ * ```
+ *
+ * The line is what lets a consumer cross-check what the lens says it found
+ * against what the parser actually extracted — a parse that silently drops
+ * findings is otherwise indistinguishable from a clean report. `Info` is never
+ * counted (the severity scale already excludes it from scheduled work).
+ *
+ * @param {string} markdown — full report text.
+ * @returns {{ critical: number, high: number, medium: number, low: number }|null}
+ *   `null` when the report declares no tally at all.
+ */
+export function parseSeverityTally(markdown) {
+  if (typeof markdown !== 'string') return null;
+  const match = TALLY_LINE.exec(markdown);
+  if (!match) return null;
+  return {
+    critical: Number(match[1]),
+    high: Number(match[2]),
+    medium: Number(match[3]),
+    low: Number(match[4]),
+  };
+}
+
 function parseBlockFields(bodyLines) {
   const fields = {};
   let activeKey = null;
@@ -302,7 +391,7 @@ export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
   }
 
   const fallbackDimension = inferDimensionFromReportName(sourceReport);
-  const blocks = splitFindingBlocks(markdown);
+  const blocks = foldGroupingHeaders(splitFindingBlocks(markdown));
 
   return blocks.map((block) => {
     const fields = parseBlockFields(block.bodyLines);
@@ -357,6 +446,8 @@ export function parseAuditReports(reports, { repoRoot } = {}) {
 }
 
 export const __testing = {
+  carriesSeverity,
+  foldGroupingHeaders,
   normaliseSeverity,
   extractFilePaths,
   normaliseTitle,

package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js

@@ -18,6 +18,7 @@
  */
 
 import { SEVERITIES } from '../findings/severity.js';
+import { formatEpicGrouping } from './epic-grouping-directive.js';
 import {
   renderFingerprintFooter,
   renderSemanticKeyFooter,
@@ -137,6 +138,10 @@ function formatKeyAssumptions(sourceReports) {
  * @param {string[]} params.sourceReports — list of source report paths.
  * @returns {string}
  */
+/**
+ * @param {{ groups: object[], findings: object[], sourceReports: object[] }} opts
+ * @returns {string} The `/mandrel-plan` seed one-pager.
+ */
 export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
   if (
     !Array.isArray(groups) ||
@@ -152,6 +157,7 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
   const scope = formatMVPScope(groups);
   const files = formatKeyFiles(groups);
   const assumptions = formatKeyAssumptions(sourceReports);
+  const grouping = formatEpicGrouping(groups);
 
   return [
     '# Idea Seed: Audit Remediation',
@@ -176,6 +182,10 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
     '',
     files,
     '',
+    '## Grouping',
+    '',
+    grouping,
+    '',
     '## Not Doing',
     '',
     '- Findings with severity below the operator-selected threshold.',

package/.agents/scripts/lib/label-constants.js

@@ -74,8 +74,26 @@ export function isValidTransition(fromState, toState) {
   return allowed.includes(toState);
 }
 
+/**
+ * Ticket-type axis.
+ *
+ * `STORY` is the only type carrying an execution payload — it is what
+ * `/mandrel-deliver` branches, implements and lands.
+ *
+ * `EPIC` (Story #5139) is a **pure container**: a grouping ticket that holds
+ * a `## Goal` paragraph and a child checklist and nothing else. It is never
+ * branched, never implemented, and never carries an `agent::*` label — that
+ * absence is what keeps it out of the bare `/mandrel-deliver` ready list and
+ * outside `lint-issue-body.js`, which is `type::story`-scoped.
+ *
+ * This is deliberately NOT a revival of the v1 Epic tier. Linkage runs
+ * parent→child only (the Epic body's checklist plus native sub-issue edges),
+ * so Story bodies stay untouched and the `Epic: #N` footer stays retired and
+ * refused. See ADR `20260905-container-epic` in `docs/decisions.md`.
+ */
 export const TYPE_LABELS = {
   STORY: 'type::story',
+  EPIC: 'type::epic',
 };
 
 export const STATUS_LABELS = {

package/.agents/scripts/lib/label-taxonomy.js

@@ -20,14 +20,27 @@ import {
   TYPE_LABELS,
 } from './label-constants.js';
 
+/**
+ * The ticket-type axis. Both rows share one colour, so they are derived from
+ * `[name, description]` pairs rather than restated as full literals — Story
+ * #5139 added `type::epic` here, and the derived form absorbs it without
+ * growing the file's structural weight.
+ *
+ * @type {Array<{ name: string, color: string, description: string }>}
+ */
+const TYPE_LABEL_ROWS = [
+  [TYPE_LABELS.STORY, 'Story work item'],
+  [TYPE_LABELS.EPIC, 'Container-only grouping ticket for child Stories'],
+].map(([name, description]) => ({
+  name,
+  color: LABEL_COLORS.TYPE,
+  description,
+}));
+
 /** @type {Array<{ name: string, color: string, description: string }>} */
 export const LABEL_TAXONOMY = [
   // Type
-  {
-    name: TYPE_LABELS.STORY,
-    color: LABEL_COLORS.TYPE,
-    description: 'Story work item',
-  },
+  ...TYPE_LABEL_ROWS,
 
   // Agent State
   {