mandrel 1.86.0 → 1.88.0

package/.agents/docs/SDLC.md

@@ -891,11 +891,23 @@ watch / auto-merge / cleanup tail that drives the PR to merge:
    fixed on a hotfix branch and re-merged into the Epic.
 2. **Audit (Phase 4).** The change-set audit lenses run against the Epic
    diff; findings flow through as advisory signal to inform the code
-   review that follows.
+   review that follows. Remediation routing is **threshold-aware**
+   (`delivery.epicAudit.autoFixSeverity`, default `medium`): at `medium`
+   the host LLM fixes 🔴/🟠/🟡 findings on-branch (Mediums batched per
+   lens) while 🟢 Suggestions graduate to follow-up issues; `high`
+   reproduces the older Critical/High-only routing. Findings fixed
+   on-branch are recorded under the `audit-results` comment's
+   `## Fixed on-branch` section, which the graduator skips so they never
+   spawn duplicate follow-up issues.
 3. **Code-review (Phase 5).** `lib/orchestration/code-review.js` (extracted
    from the `code-review.md` helper) audits the diff and posts the
-   findings as a `code-review` structured comment on the Epic. 🔴 Critical
-   findings halt the run; 🟠/🟡/🟢 findings flow through as non-blocking.
+   findings as a `code-review` structured comment on the Epic. Focused-fix
+   routing is threshold-aware in the same way
+   (`delivery.codeReview.autoFixSeverity`, default `medium` — fixes
+   🔴/🟠/🟡 on-branch, 🟢 stays on the comment), and fixed findings land
+   under the comment's `## Fixed on-branch` section so the graduator skips
+   them. The severity gate is unchanged: surviving 🔴 Critical findings
+   halt the run; surviving 🟠/🟡/🟢 flow through as non-blocking.
 4. **Retro (Phase 6).** `lib/orchestration/retro-runner.js` (extracted from the old
    retro helper) aggregates perf signals, friction counts, hotfix counts,
    recut counts, parked counts, and HITL count using

package/.agents/docs/configuration.md

@@ -275,12 +275,14 @@ top-level keys are validation errors.
 | `epicAudit` | No | `object` | — | Nested configuration block. |
 | `epicAudit.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3. |
 | `epicAudit.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
+| `epicAudit.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /deliver Phase 4 (epic-audit). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM remediation loop (Mediums batched per lens: one commit per lens, a single validation + overlapping-lens rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
 | `codeReview` | No | `object` | — | Nested configuration block. |
 | `codeReview.provider` | No | `"native"` \| `"codex"` \| `"security-review"` | `"native"` | Legacy single-adapter selection. ReviewProvider that produces the Finding[] consumed by runCodeReview(). Story #2833 registered `native` (in-process maintainability/lint); Story #2830 added `codex` (invokes `/codex:review` plugin); Story #2871 added `security-review` (shells out to `claude --print /security-review`). When `providers` (chain shape) is set this field is ignored with a warning. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. |
 | `codeReview.providers[]` | No | `array<object>` | — | Multi-provider chain (Story #2871). When set and non-empty, takes precedence over the legacy `provider` field. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Each item has: name, scopes, optional, manualPrompt, when. |
 | `codeReview.providerConfig` | No | `object` | — | Optional escape hatch for adapter-specific configuration. No documented keys in Epic #2815; reserved so future adapters can be configured without another schema migration. |
 | `codeReview.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
 | `codeReview.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
+| `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
 | `retro` | No | `object` | — | Story #3042 (Epic #3019). Operator-tunable retro behaviour. Currently exposes `perfThresholds`, the gates the retro perf-signals classifier uses to decide which signals to surface in the `## Performance Signals` / `## Recommended Follow-Ons` retro sections. |
 | `retro.perfThresholds` | No | `object` | — | Gates for `classifyPerfSignals` (lib/orchestration/retro-perf-heuristics.js). Defaults are 0.6 / 0.4 / 2. |
 | `retro.perfThresholds.utilisation` | No | `number` | — | Per-wave utilisation threshold. Waves whose `utilisation` is strictly below this value emit a `low-utilisation` signal. Default 0.6. |

package/.agents/instructions.md

@@ -334,6 +334,13 @@ budget grounds.
   spawns (search, doc regeneration, lint, log triage) and keep
   **implementation and design** work on the default capability; name no
   specific model — let the host and operator own the concrete mapping.
+  **Depth compounds the cost.** Sub-agents now carry the `Agent` tool and
+  can nest further (verified depth 2, announced max depth 5; see
+  [#2870](https://github.com/dsj1984/mandrel/issues/2870)), so this
+  spend-per-spawn caution is not one-level — **every** nesting level
+  re-pays the full always-loaded context. Weigh the whole subtree's cost,
+  not just the immediate spawn, before opening a deeper orchestration
+  level, and stay within the supported depth envelope.
 - **Anti-Laziness:** NEVER use placeholder comments like
   `// ... existing code ...`, `/* rest of file */`, or
   `// implementation here`. You MUST output the ENTIRE file or the ENTIRE

package/.agents/rules/git-conventions.md

@@ -142,7 +142,19 @@ operator intervention:
   candidate with unpushed work, a dirty worktree, or a still-open parent
   ticket. A branch a flow leaves behind (e.g. a `/git-deliver` feature branch
   whose PR merges out of band) is therefore reaped automatically at the next
-  workflow boot, not left for the operator to sweep by hand.
+  workflow boot, not left for the operator to sweep by hand. `boot-sweep.js`
+  defaults its `--include` glob to `story-*` — a bare invocation only sweeps
+  Story branches; `/plan` and `/git-deliver` widen the scope to their own
+  branch namespaces (`epic/*`, `feat/*`, `fix/*`, `chore/*`, `docs/*`,
+  `refactor/*`) by passing `--include` explicitly at their boot call site.
+  A branch the planner detects only via the weaker content-equivalence
+  signal (`detectedBy: 'content-merged'`, Story #4395's
+  `git merge-tree --write-tree` probe — content already landed in the base
+  branch by another route, such as a squash-merged Epic PR, with no merged
+  PR or git ancestry of its own) is **never** reaped by the boot sweep: it
+  is report-only, surfaced under `contentMerged` in the result envelope and
+  a routing hint in the summary line (Story #4396), so the operator can
+  send it to `/git-cleanup` for a confirmed, eyeballed reap.
 - **`/git-cleanup` is recovery, not routine.** Run it by hand only to recover
   an unusual state the automated hygiene does not cover — triaging stashes,
   reaping across non-standard branch namespaces, or `--remote` pruning after a

package/.agents/schemas/agentrc.schema.json

@@ -542,6 +542,12 @@
           "type": "integer",
           "minimum": 1,
           "description": "Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5."
+        },
+        "autoFixSeverity": {
+          "type": "string",
+          "enum": ["high", "medium"],
+          "default": "medium",
+          "description": "Severity threshold for on-branch remediation in /deliver Phase 4 (epic-audit). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM remediation loop (Mediums batched per lens: one commit per lens, a single validation + overlapping-lens rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag."
         }
       },
       "additionalProperties": false
@@ -624,6 +630,12 @@
           "type": "integer",
           "minimum": 1,
           "description": "Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5."
+        },
+        "autoFixSeverity": {
+          "type": "string",
+          "enum": ["high", "medium"],
+          "default": "medium",
+          "description": "Severity threshold for on-branch remediation in /deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag."
         }
       },
       "additionalProperties": false

package/.agents/scripts/boot-sweep.js

@@ -17,6 +17,17 @@
  * is swallowed and reported in the result envelope, never thrown, so a
  * caller can wire it into a boot path without risking the host run.
  *
+ * **Content-merged branches are report-only (Story #4396).** The planner
+ * also surfaces branches whose content already landed in the base branch
+ * by another route (a squash-merged Epic PR, a renamed head, a manual
+ * squash merge) via `detectedBy: 'content-merged'` (Story #4395's
+ * `git merge-tree --write-tree` probe) — a weaker signal than a merged PR
+ * or git ancestry, since no CI/GitHub merge check ever validated that
+ * branch's exact diff. This sweep never reaps on that signal alone; it
+ * surfaces the branches under `contentMerged` in the result envelope (and
+ * a routing hint in the human summary) so the operator can send them to
+ * `/git-cleanup` for a confirmed, eyeballed reap.
+ *
  * Usage:
  *   node .agents/scripts/boot-sweep.js [--include <glob>...] \
  *     [--exclude <glob>...] [--current <branch>] [--base <branch>] \
@@ -42,6 +53,10 @@ Runs the protected merged-branch boot sweep non-interactively: reaps every
 local branch whose PR is MERGED and whose HEAD matches the merged headRefOid,
 skipping any candidate the protection partition flags (unpushed work, dirty
 worktree, still-open parent Story), then fast-forwards the base branch.
+Branches detected only via the weaker content-equivalence signal
+(detectedBy: 'content-merged') are never reaped here — they are reported
+under "contentMerged" (and a routing hint in the summary line) for the
+operator to send to /git-cleanup.
 
 Options:
   --include <glob>     Branch glob to sweep (repeatable). Default: story-*
@@ -136,11 +151,31 @@ export async function runBootSweep({
       localDeleted: 0,
       remoteDeleted: 0,
       protected: [],
+      contentMerged: [],
       failures: [],
     };
   }
 }
 
+/**
+ * Build the human-readable one-line summary for a sweep result envelope.
+ * Exported for unit tests (Story #4396). A zero `contentMerged` count keeps
+ * the pre-Story #4396 line byte-identical (silent no-op summary); a nonzero
+ * count appends a routing hint pointing the operator at `/git-cleanup`.
+ *
+ * @param {{ localDeleted: number, remoteDeleted: number, protected?: Array, contentMerged?: Array }} result
+ * @returns {string}
+ */
+export function buildSummaryLine(result) {
+  const protectedCount = result.protected?.length ?? 0;
+  const contentMergedCount = result.contentMerged?.length ?? 0;
+  const contentMergedSuffix =
+    contentMergedCount > 0
+      ? `; ${contentMergedCount} content-merged branch(es) left for /git-cleanup`
+      : '';
+  return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${contentMergedSuffix}.`;
+}
+
 async function main() {
   const { values } = parseArgs({
     options: {
@@ -173,10 +208,7 @@ async function main() {
   if (values.json) {
     Logger.info(JSON.stringify(result, null, 2));
   } else {
-    const protectedCount = result.protected?.length ?? 0;
-    Logger.info(
-      `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}.`,
-    );
+    Logger.info(buildSummaryLine(result));
   }
 }
 

package/.agents/scripts/git-cleanup.js

@@ -55,11 +55,14 @@ import {
   computeProtectedSet,
 } from './lib/orchestration/git-cleanup/phases/filters.js';
 import {
+  branchLastCommitAt,
   branchTipSha,
   classifyLatestPr,
   probeAllPrs,
+  probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,
+  refExists,
 } from './lib/orchestration/git-cleanup/phases/git-probes.js';
 import { parseCleanupArgs } from './lib/orchestration/git-cleanup/phases/parse-args.js';
 import {
@@ -74,6 +77,7 @@ import {
   renderExecutionLine,
   renderExecutionSummary,
   renderLatestPrSkipLine,
+  renderNotMergedSkipLine,
   renderPruneLine,
 } from './lib/orchestration/git-cleanup/phases/render.js';
 import {
@@ -86,6 +90,7 @@ import {
 
 // Public surface preserved for tests + `single-story-sweep.js`.
 export {
+  branchLastCommitAt,
   branchTipSha,
   buildAllowlistDecider,
   buildGlobFilter,
@@ -105,13 +110,16 @@ export {
   planFastForward,
   planStashes,
   probeAllPrs,
+  probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,
+  refExists,
   renderDeferredLine,
   renderDryRun,
   renderExecutionLine,
   renderExecutionSummary,
   renderLatestPrSkipLine,
+  renderNotMergedSkipLine,
   renderPruneLine,
   stashRefIndex,
 };

package/.agents/scripts/lib/checks/subagent-agent-tool-required.js

@@ -1,30 +1,44 @@
 /**
- * subagent-agent-tool-required — refuse-and-print check.
+ * subagent-agent-tool-required — supported-depth guard (refuse-and-print).
  *
- * Detects sub-agent workflow definitions that declare access to the
- * `Agent` tool (or otherwise document nested Agent dispatch). Nested
- * Agent dispatch is not supported in this Claude Code, so any
- * wave-runner-as-sub-agent or cascading fan-out design that declares
- * `Agent` in its tool list will silently fail at runtime. The remediation
- * is to flatten the fan-out back to the host agent and run sub-agents at
- * one level only.
+ * Nested `Agent` dispatch from a sub-agent is **supported** on this Claude
+ * Code build (verified depth 2, announced max depth 5 — Claude Code
+ * 2.1.202, re-spiked 2026-07-08; see Epic #4385 / watch #2870). A level-1
+ * sub-agent carries `Agent` in its primary toolset and can spawn a working
+ * level-2 sub-agent. Declaring `Agent` in a sub-agent workflow is therefore
+ * a legitimate design choice, **not** an automatic runtime failure.
+ *
+ * What this check guards is the one case that still fails: a fan-out whose
+ * declared nesting depth exceeds the announced/supported ceiling. A dispatch
+ * chain deeper than the harness supports will silently fail at runtime, so a
+ * workflow that declares `Agent` together with a `nesting-depth` beyond the
+ * ceiling is flagged as a blocker. A sub-agent that declares `Agent` at a
+ * supported depth (the common case — an undeclared depth is treated as the
+ * shallow level-1 fan-out) produces no finding.
+ *
+ * This inverts the historical guard (Story #4387): the check used to refuse
+ * `Agent` in *any* sub-agent workflow on the now-false rationale that
+ * sub-agents cannot dispatch. It no longer strips a real capability; it only
+ * catches an over-deep fan-out. The self-healing surface is preserved — it is
+ * re-scoped, not removed.
  *
  * Scope: 'epic-deliver', 'retro'. Surfaces as a blocker at preflight for
  * `epic-deliver` (the fan-out site) and as audit signal at retro.
  *
- * The check is `refuse-and-print` — auto-rewriting a workflow's tool
- * list would silently change runtime behavior in ways the operator may
- * not have intended (the workflow's logic may depend on the missing
- * tool). The fixCommand cites the flatten-fan-out remediation pattern.
+ * The check is `refuse-and-print` — auto-rewriting a workflow's declared
+ * depth or tool list would silently change runtime behavior in ways the
+ * operator may not have intended. The fixCommand explains how to bring the
+ * fan-out back under the ceiling (reduce the declared depth or split the
+ * deepest level out), and is explicit that stripping `Agent` is NOT the fix.
  *
- * Implementation note: we scan `.agents/workflows/*.md` for workflow
- * files whose frontmatter or body identifies them as a sub-agent role
- * AND whose `tools:` declaration includes `Agent`. The marker for
- * "sub-agent" is the phrase `sub-agent` appearing in the description /
- * overview region. This keeps the check stable while the workflow
- * surface evolves — the project doesn't yet have a structured
- * `role: sub-agent` frontmatter field, and the textual marker is what
- * the human contributors actually grep for.
+ * Implementation note: we scan `.agents/workflows/*.md` for workflow files
+ * whose frontmatter or body identifies them as a sub-agent role AND whose
+ * `tools:` declaration includes `Agent`, then read the workflow's declared
+ * `nesting-depth`. The marker for "sub-agent" is the phrase `sub-agent`
+ * appearing in the description / overview region. The depth is read from a
+ * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
+ * `<!-- nesting-depth: N -->` body marker; an absent declaration is treated
+ * as depth 1 (a single, shallow fan-out level).
  */
 
 import { readdirSync, readFileSync } from 'node:fs';
@@ -32,6 +46,17 @@ import path from 'node:path';
 
 const WORKFLOWS_DIR_DEFAULT = path.join('.agents', 'workflows');
 
+/**
+ * Announced maximum nesting depth the Claude Code harness supports for
+ * sub-agent fan-out. Depth 2 is independently verified; depths 3–5 are
+ * announced but not yet re-spiked (Epic #4385 / watch #2870). A workflow
+ * declaring a fan-out deeper than this ceiling is flagged. Operators can pin
+ * a stricter (or, once verified, looser) ceiling via `state.supportedDepth`.
+ *
+ * @type {number}
+ */
+export const ANNOUNCED_MAX_DEPTH = 5;
+
 /**
  * Walk a workflow directory and return absolute `.md` file paths
  * (non-recursive — the workflows surface is one level deep; helpers/
@@ -127,17 +152,57 @@ function findAgentToolDeclaration(parts) {
   return null;
 }
 
+/**
+ * Parse the workflow's declared nesting depth. A sub-agent that declares
+ * `Agent` may also declare how deep its fan-out reaches via a
+ * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
+ * `<!-- nesting-depth: N -->` marker in the body. Returns the integer
+ * depth, or `null` when no depth is declared (the caller treats an absent
+ * declaration as the shallow level-1 fan-out).
+ *
+ * @param {{ frontmatter: string, body: string }} parts
+ * @returns {number | null}
+ */
+function parseDeclaredDepth(parts) {
+  const { frontmatter, body } = parts;
+  const fmMatch = frontmatter.match(
+    /^[ \t]*(?:nesting-depth|agent-depth)\s*:\s*(\d+)\s*$/m,
+  );
+  if (fmMatch) return Number.parseInt(fmMatch[1], 10);
+  const bodyMatch = body.match(
+    /<!--\s*(?:nesting-depth|agent-depth)\s*:\s*(\d+)\s*-->/,
+  );
+  if (bodyMatch) return Number.parseInt(bodyMatch[1], 10);
+  return null;
+}
+
+/**
+ * Resolve the supported depth ceiling for a detect run. Operators may pin a
+ * stricter (or, once verified, looser) ceiling via `state.supportedDepth`;
+ * an unset or non-positive-integer override falls back to the announced max.
+ *
+ * @param {{ supportedDepth?: unknown } | null | undefined} state
+ * @returns {number}
+ */
+function resolveCeiling(state) {
+  const override = state?.supportedDepth;
+  if (Number.isInteger(override) && override > 0) return override;
+  return ANNOUNCED_MAX_DEPTH;
+}
+
 const FIX_COMMAND = [
-  '# Flatten fan-out to the host. Sub-agents cannot dispatch other agents.',
-  "# Remove the `Agent` entry from this workflow's `tools:` declaration,",
-  '# move any fan-out logic up to the parent / host invocation, and have',
-  '# the parent dispatch the leaf sub-agents directly.',
+  '# Nested Agent dispatch IS supported (verified depth 2, announced max 5 —',
+  '# Claude Code 2.1.202). This workflow declares a fan-out deeper than the',
+  '# supported ceiling, so the deepest dispatch chain will fail at runtime.',
   '#',
-  '# Pattern (host workflow):',
-  '#   for each child: Agent(prompt=<child workflow>, args=<id>)',
+  '# Bring the fan-out back under the ceiling — either:',
+  '#   1. Lower the declared `nesting-depth` to <= the supported ceiling, or',
+  '#   2. Split the deepest level out to a shallower sibling fan-out so no',
+  '#      single dispatch chain exceeds the supported depth.',
   '#',
-  '# Pattern (sub-agent workflow):',
-  '#   tools: [Bash, Read, Edit, Grep, Glob, Write]   # NO Agent',
+  '# Do NOT strip `Agent` from the tool list to silence this. Sub-agents CAN',
+  '# dispatch nested agents at a supported depth; removing the tool would',
+  '# disable a legitimate capability, not fix the depth overflow.',
 ].join('\n');
 
 export default {
@@ -149,6 +214,7 @@ export default {
   detect(state) {
     const cwd = state?.cwd ?? process.cwd();
     const root = state?.scanRoot ?? path.join(cwd, WORKFLOWS_DIR_DEFAULT);
+    const ceiling = resolveCeiling(state);
     const files = listWorkflowFiles(root);
     const offences = [];
     for (const file of files) {
@@ -162,18 +228,29 @@ export default {
       const parts = splitFrontmatter(src);
       const where = findAgentToolDeclaration(parts);
       if (!where) continue;
+      // Declaring `Agent` is legitimate. Only a fan-out deeper than the
+      // supported ceiling is a runtime hazard; an undeclared depth is the
+      // shallow level-1 fan-out and always within the ceiling.
+      const depth = parseDeclaredDepth(parts) ?? 1;
+      if (depth <= ceiling) continue;
       offences.push({
         file: path.relative(root, file).replace(/\\/g, '/'),
         where,
+        depth,
       });
     }
     if (offences.length === 0) return null;
-    const detail = offences.map((o) => `${o.file} — ${o.where}`).join('\n');
+    const detail = offences
+      .map(
+        (o) =>
+          `${o.file} — declares Agent at nesting-depth ${o.depth} (exceeds supported ceiling ${ceiling}); ${o.where}`,
+      )
+      .join('\n');
     return {
       id: 'subagent-agent-tool-required',
       severity: 'blocker',
       scope: state?.scope ?? 'epic-deliver',
-      summary: `${offences.length} sub-agent workflow(s) declare Agent in their tool list — nested Agent dispatch is unsupported`,
+      summary: `${offences.length} sub-agent workflow(s) declare an Agent fan-out deeper than the supported nesting ceiling (${ceiling})`,
       detail,
       fixCommand: FIX_COMMAND,
       autoCorrectable: false,

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,22 @@ 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` (Story #4399) defaults to `'medium'` — the phase
+ * remediates 🔴/🟠/🟡 findings on-branch while 🟢 suggestions graduate to
+ * follow-up issues. `'high'` reproduces the pre-4399 Critical/High-only
+ * routing. Hard cutover per `rules/git-conventions.md` — no back-compat flag.
  */
 export const DEFAULT_EPIC_AUDIT = Object.freeze({
   maxFixAttempts: 3,
   maxFixScopeFiles: 5,
+  autoFixSeverity: 'medium',
 });
 
 export const DEFAULT_CODE_REVIEW = Object.freeze({
   maxFixAttempts: 3,
   maxFixScopeFiles: 5,
+  autoFixSeverity: 'medium',
 });
 
 /**
@@ -65,8 +72,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 +99,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-settings-schema-delivery.js

@@ -210,12 +210,19 @@ 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 Phase 4 host-LLM remediation loop fixes on-branch: `medium`
+ * (the default) routes 🔴/🟠/🟡 into remediation while 🟢 still graduates;
+ * `high` reproduces the pre-4399 Critical/High-only routing. It is a 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,
 };

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,
 };

package/.agents/scripts/lib/epic-plan-ideation.js

@@ -13,6 +13,10 @@
  * mock the provider call without touching the GitHub HTTP client.
  */
 
+import {
+  extractFrameworkStamp,
+  stampFrameworkVersion,
+} from './framework-version.js';
 import { TYPE_LABELS } from './label-constants.js';
 
 // Canonical section keys match the rendered template at
@@ -113,24 +117,33 @@ export function parseOnePager(onePager) {
  * sections are rendered as `_(not specified)_` so the operator can spot
  * gaps during the HITL review (Phase 3).
  *
+ * Story #4382 — the rendered body is stamped with the Mandrel framework
+ * version + authoring date (hidden `mandrel_version` / `authored_at` meta
+ * field + a visible `> 🏷️ Authored with Mandrel …` marker) via
+ * {@link stampFrameworkVersion}. Pass `stamp` to preserve a
+ * previously-authored version on re-render (the Epic edit path does this);
+ * omit it to stamp the running version and today's date.
+ *
  * @param {{
  *   onePager: string,
  *   template: string,
+ *   stamp?: { version?: string, authoredAt?: string },
  * }} args
  * @returns {{ title: string, body: string }}
  */
-export function renderEpicBody({ onePager, template }) {
+export function renderEpicBody({ onePager, template, stamp }) {
   if (!template || typeof template !== 'string') {
     throw new Error('renderEpicBody: template must be a non-empty string');
   }
   const parsed = parseOnePager(onePager);
 
-  const body = template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+  const rendered = template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
     if (key === 'title') return parsed.title;
     const value = parsed[key];
     return value && value.length > 0 ? value : '_(not specified)_';
   });
 
+  const body = stampFrameworkVersion(rendered, stamp ?? {});
   return { title: parsed.title, body };
 }
 
@@ -226,7 +239,15 @@ export async function updateEpicFromOnePager({
     );
   }
 
-  const { title, body } = renderEpicBody({ onePager, template });
+  // Story #4382 — preserve the originally-authored version stamp on edit
+  // rather than bumping it to whatever version is running now. When the
+  // current body carries no stamp (legacy Epic), a fresh stamp is applied.
+  const priorStamp = extractFrameworkStamp(currentBody ?? '');
+  const stamp = priorStamp
+    ? { version: priorStamp.version, authoredAt: priorStamp.authoredAt }
+    : undefined;
+
+  const { title, body } = renderEpicBody({ onePager, template, stamp });
 
   if (typeof currentBody === 'string' && currentBody === body) {
     return { epicId, title, body, changed: false };

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -98,6 +98,13 @@ export function buildIdempotencyMarker(epicId, index) {
  * emoji and embeds the cited path inside backticks. 🔴 critical findings
  * are filtered out (they're blocking — the Epic stops on those).
  *
+ * Findings the Phase 4 remediation loop already fixed on-branch are
+ * rendered under a **"Fixed on-branch"** heading (Story #4399) with a ✅
+ * prefix so they no longer parse as open findings. As a belt-and-suspenders
+ * guard the parser also skips every line inside a Fixed-on-branch section
+ * outright, so a remediated 🟡 Medium never spawns a ghost follow-up issue
+ * even if its line retains its original severity emoji.
+ *
  * Pure. Exported so the parser can be unit-tested in isolation.
  *
  * @param {string} body
@@ -109,18 +116,25 @@ export function parseFindings(body) {
   const lines = body.split(/\r?\n/);
   let idx = 0;
   let lens = 'unknown';
+  let inFixedSection = false;
   for (const rawLine of lines) {
     const trimmed = rawLine.trim();
     if (trimmed.length === 0) continue;
 
-    // Detect a lens heading. We accept any heading-prefixed line that
-    // names a known audit family (`audit-*`).
-    const lensMatch = trimmed.match(/^#{2,6}\s+(audit-[a-z0-9-]+)/i);
-    if (lensMatch) {
-      lens = lensMatch[1];
+    // Any markdown heading resets the Fixed-on-branch guard and, when it
+    // names a known audit family (`audit-*`), sets the active lens. A
+    // "Fixed on-branch" heading opens a section whose entries never
+    // graduate (Story #4399).
+    const headingMatch = trimmed.match(/^#{2,6}\s+(.+)$/);
+    if (headingMatch) {
+      inFixedSection = /fixed on-branch/i.test(headingMatch[1]);
+      const lensMatch = headingMatch[1].match(/^(audit-[a-z0-9-]+)/i);
+      if (lensMatch) lens = lensMatch[1];
       continue;
     }
 
+    if (inFixedSection) continue;
+
     let severity = null;
     if (trimmed.startsWith('🔴')) {
       // Critical Blocker — skip; never graduates.