mandrel 1.87.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/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/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/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.

package/.agents/scripts/lib/feedback-loop/code-review-graduator.js

@@ -104,6 +104,13 @@ export function buildIdempotencyMarker(epicId, index) {
  * filter 🔴 (Critical Blocker — blocking) out; 🟠/🟡/🟢 are non-blocking
  * and graduate to follow-up issues.
  *
+ * Findings the Phase 5 focused-fix routing 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.
+ *
  * @param {string} body
  * @returns {Array<{ severity: 'high'|'medium'|'low', path: string, summary: string, index: number }>}
  */
@@ -112,9 +119,19 @@ export function parseFindings(body) {
   const findings = [];
   const lines = body.split(/\r?\n/);
   let idx = 0;
+  let inFixedSection = false;
   for (const line of lines) {
     const trimmed = line.trim();
     if (trimmed.length === 0) continue;
+    // Any markdown heading resets the Fixed-on-branch guard; a
+    // "Fixed on-branch" heading opens a section whose entries never
+    // graduate (Story #4399).
+    const headingMatch = trimmed.match(/^#{1,6}\s+(.+)$/);
+    if (headingMatch) {
+      inFixedSection = /fixed on-branch/i.test(headingMatch[1]);
+      continue;
+    }
+    if (inFixedSection) continue;
     let severity = null;
     if (trimmed.startsWith('🟠')) severity = 'high';
     else if (trimmed.startsWith('🟡')) severity = 'medium';

package/.agents/workflows/helpers/code-review.md

@@ -293,12 +293,63 @@ For every finding, provide:
   fix worked. Keep it tight (≤ 5 sentences); the sub-agent will read the
   surrounding code itself.
 
+### The `## Fixed on-branch` section (Story #4399)
+
+Findings that Step 4.5 remediated on `[HEAD_REF]` MUST be rendered under a
+dedicated **`## Fixed on-branch`** heading, **not** in the severity groups
+above. This is the contract seam that keeps remediated findings from
+spawning ghost follow-up issues: the
+[`code-review` graduator](../../scripts/lib/feedback-loop/code-review-graduator.js)
+skips every entry inside this section (both because a fixed entry is
+rendered with a **✅ prefix** — so it carries no leading severity emoji the
+parser would match — and because the parser has an explicit
+Fixed-on-branch section guard).
+
+Render each fixed finding as a `✅`-prefixed line naming its original
+severity, the file path in backticks, and the remediating commit SHA, e.g.:
+
+```markdown
+## Fixed on-branch
+
+- ✅ 🟡 Medium: `src/lib/foo.js` — missing edge-case guard added (a1b2c3d)
+- ✅ 🟠 High: `src/api/users.js` — ownership check added (d4e5f6a)
+```
+
+Open (escalated / unfixed) findings stay in their severity group with
+their leading severity emoji so the graduator still files them.
+
 ## Step 4.5 — Focused-fix Routing (host LLM, no automated loop)
 
 There is **no runtime auto-fix function** at this phase. The host LLM is
-the executor: for each 🔴 / 🟠 finding from Step 4, decide between two
-paths and keep the `code-review` structured comment authoritative for
-anything not fixed in-place.
+the executor: it decides, per finding, between a focused fix on
+`[HEAD_REF]` and leaving the finding on the `code-review` structured
+comment for the operator.
+
+### Resolve the remediation threshold (Story #4399)
+
+Read `delivery.codeReview.autoFixSeverity` from the resolved `.agentrc.json`
+(default **`medium`**; the resolver in
+[`config/runners.js`](../../scripts/lib/config/runners.js) supplies the
+default when the key is absent). The threshold governs **which severities
+route into on-branch remediation** — it never changes the halting rule (a
+surviving 🔴 still stops) or the escalation classes:
+
+- **`medium`** (default) — route 🔴 Critical, 🟠 High, **and 🟡 Medium**
+  findings into remediation. 🟢 Suggestions stay on the comment (never
+  auto-fixed).
+- **`high`** — route only 🔴 Critical and 🟠 High findings, reproducing
+  the pre-4399 behavior exactly. 🟡 Medium and 🟢 Suggestion findings stay
+  on the comment.
+
+Hard cutover per
+[`rules/git-conventions.md`](../../rules/git-conventions.md) § Contract
+Cutovers — no back-compat flag; `high` is opt-in to the old routing.
+
+### 🔴 / 🟠 findings — per-finding ceremony (unchanged)
+
+For each 🔴 / 🟠 finding from Step 4, decide between two paths and keep the
+`code-review` structured comment authoritative for anything not fixed
+in-place.
 
 1. **Apply a focused fix on `[HEAD_REF]`.** Permitted only when the
    finding is unambiguously *fixable* (clean remediation, no scope
@@ -328,11 +379,36 @@ anything not fixed in-place.
      attempt (the equivalent of the prior loop's
      `validation-regression` / `thrash-detected` exits).
 
+### 🟡 Medium findings — batched per-lens ceremony (only when `autoFixSeverity: medium`)
+
+When the threshold is `medium`, remediate the fixable 🟡 Medium findings in
+a **batch keyed by owning review lens/pillar** rather than the per-finding
+ceremony above:
+
+1. Group the fixable Mediums by owning lens (the pillar or audit family
+   that produced them). A Medium is fixable on the same terms as a 🟠; a
+   Medium in any escalation class stays on the comment exactly like a 🟠.
+2. For each lens, call `assert-branch.js --expected [HEAD_REF]`, stage
+   explicit paths only, and make **one focused conventional commit per
+   lens** (`fix(<scope>): <description> (review findings batch)`).
+3. Bounded-attempt semantics extend to the batch: each finding gets **at
+   most one** attempt, and a lens's batch commit that would exceed
+   `delivery.codeReview.maxFixScopeFiles` routes that lens's findings to
+   escalation (`scope-exceeded`) instead of committing.
+4. After **all** lens batches are committed, run a **single** validation
+   pass (`npm run lint` plus the relevant `npm test` slice) and a
+   **single** targeted rescan over the touched files. Surviving batched
+   findings stay on the comment for Step 5.
+
+Record every remediated finding (🟠 or 🟡) in the **"Fixed on-branch"**
+section of the `code-review` comment (Step 4) so it does not graduate to a
+follow-up issue.
+
 Do not invent a programmatic retry budget. The host LLM applies *at most
-one* focused-fix attempt per finding before escalating to the operator.
-Escalated findings remain on the `code-review` structured comment with
-their reason recorded, so Step 5 (and downstream consumers) see exactly
-why each one was not auto-remediated.
+one* focused-fix attempt per finding (or per batched finding) before
+escalating to the operator. Escalated findings remain on the `code-review`
+structured comment with their reason recorded, so Step 5 (and downstream
+consumers) see exactly why each one was not auto-remediated.
 
 ## Step 4.6 — Cross-phase re-check trigger
 

package/.agents/workflows/helpers/deliver-epic.md

@@ -489,6 +489,16 @@ therefore auto-runs its mapped lenses (e.g. a `security`-axis Epic runs
 low-risk Epic adds nothing. Findings are persisted as an `audit-results`
 structured comment on the Epic.
 
+The helper's Step 3 remediation is **threshold-aware** (Story #4399): it
+reads `delivery.epicAudit.autoFixSeverity` (default **`medium`**) and, at
+`medium`, routes 🔴/🟠/**🟡** findings into on-branch remediation (Mediums
+batched per lens — one commit per lens, a single validation + overlapping-
+lens rescan at the end) while 🟢 Suggestions still graduate; `high`
+reproduces the pre-4399 Critical/High-only routing. Remediated findings are
+rendered under the comment's `## Fixed on-branch` section so they never
+graduate to follow-up issues. The severity gate below is **unchanged** —
+it keys off the surviving (unfixed) findings.
+
 The helper walks the selected roster **serially in-context by default**; when
 the roster carries more than one lens it **may delegate the walk to a single
 audit-orchestrator sub-agent** that fans the already-selected lenses out as
@@ -500,8 +510,8 @@ per-lens cost gate is preserved, and the seven sequential-only lenses are **not*
 batch-converted — the fan-out parallelizes across lenses only and never changes
 how any single lens runs internally.
 
-- **Any 🔴 Critical Blocker** — STOP. Relay to the operator.
-- **Only 🟠/🟡/🟢** — log as non-blocking and continue.
+- **Any surviving 🔴 Critical Blocker** — STOP. Relay to the operator.
+- **Only 🟠/🟡/🟢 surviving** — log as non-blocking and continue.
 - **Selector reports `degraded: true`** — STOP. Propagate the
   `reason`/`detail`, post a friction comment, do not fall back to a
   full-roster audit.
@@ -533,8 +543,18 @@ emit so a high-risk Epic gets a deeper adversarial pass and a low-risk one a
 lighter one. Depth is **input-only** — it never changes the findings envelope
 or the posted comment shape.
 
-- **Any 🔴 Critical Blocker** — STOP. Relay to the operator.
-- **Only 🟠/🟡/🟢** — log as non-blocking and continue.
+The helper's Step 4.5 focused-fix routing is **threshold-aware**
+(Story #4399): it reads `delivery.codeReview.autoFixSeverity` (default
+**`medium`**) and, at `medium`, routes 🔴/🟠/**🟡** findings into on-branch
+remediation (Mediums batched per lens — one commit per lens, a single
+validation + rescan at the end) while 🟢 Suggestions stay on the comment;
+`high` reproduces the pre-4399 Critical/High-only routing. Remediated
+findings are rendered under the comment's `## Fixed on-branch` section so
+they never graduate to follow-up issues. The severity gate below is
+**unchanged** — it keys off the surviving (unfixed) findings.
+
+- **Any surviving 🔴 Critical Blocker** — STOP. Relay to the operator.
+- **Only 🟠/🟡/🟢 surviving** — log as non-blocking and continue.
 
 ---
 

package/.agents/workflows/helpers/epic-audit.md

@@ -263,9 +263,32 @@ envelope" bullet. Until then, the host LLM is the gate.
 ## Step 3 — Remediation Routing (host LLM, no automated loop)
 
 There is **no runtime auto-fix function** at this phase. The host LLM is
-the executor: it inspects the aggregated 🔴 / 🟠 findings from Step 2 and
-either applies a focused fix on the Epic branch or escalates the finding
-to the operator via the `audit-results` comment in Step 4.
+the executor: it inspects the aggregated findings from Step 2 and either
+applies a focused fix on the Epic branch or escalates the finding to the
+operator via the `audit-results` comment in Step 4.
+
+### Resolve the remediation threshold (Story #4399)
+
+Read `delivery.epicAudit.autoFixSeverity` from the resolved `.agentrc.json`
+(default **`medium`**; the resolver in
+[`config/runners.js`](../../scripts/lib/config/runners.js) supplies the
+default when the key is absent). The threshold governs **which severities
+route into on-branch remediation** — it never changes the halting rule
+(a surviving 🔴 still stops Phase 4 in Step 4) or the escalation classes:
+
+- **`medium`** (default) — route 🔴 Critical, 🟠 High, **and 🟡 Medium**
+  findings into remediation. 🟢 Suggestions still graduate to follow-up
+  issues (never auto-fixed).
+- **`high`** — route only 🔴 Critical and 🟠 High findings into
+  remediation, reproducing the pre-4399 behavior exactly. 🟡 Medium and
+  🟢 Suggestion findings graduate to follow-up issues untouched.
+
+This is a hard cutover per
+[`rules/git-conventions.md`](../../rules/git-conventions.md) § Contract
+Cutovers — there is no back-compat flag; `high` is opt-in to the old
+routing, `medium` is the shipped default.
+
+### 🔴 / 🟠 findings — per-finding ceremony (unchanged)
 
 For each 🔴 / 🟠 finding, the host LLM MUST decide between two paths:
 
@@ -297,10 +320,42 @@ For each 🔴 / 🟠 finding, the host LLM MUST decide between two paths:
      attempt (the equivalent of the prior loop's
      `validation-regression` / `thrash-detected` exits).
 
+### 🟡 Medium findings — batched per-lens ceremony (only when `autoFixSeverity: medium`)
+
+When the threshold is `medium`, remediate the fixable 🟡 Medium findings
+in a **batch keyed by owning lens** rather than the per-finding ceremony
+above — the per-finding rescan is disproportionate for the volume of
+Mediums a wide change set surfaces:
+
+1. Group the fixable Mediums by their owning lens. A Medium is fixable on
+   the same terms as a 🟠 (clean remediation, no escalation class); a
+   Medium that falls into any escalation class (`spec-deviation`,
+   `secrets`, `test-deletion`, `scope-exceeded`) routes to Step 4
+   untouched exactly like a 🟠.
+2. For each lens, call `assert-branch.js --expected [EPIC_BRANCH]`, stage
+   explicit paths only, and make **one focused conventional commit per
+   lens** carrying all that lens's Medium fixes
+   (`fix(<scope>): <description> (audit findings batch)`).
+3. The bounded-attempt semantics extend to the batch: each finding in the
+   batch gets **at most one** attempt, and a lens's batch commit that
+   would exceed `delivery.epicAudit.maxFixScopeFiles` routes that lens's
+   findings to escalation (`scope-exceeded`) instead of committing.
+4. After **all** lens batches are committed, run a **single** validation
+   pass (`npm run lint` plus the relevant `npm test` slice) and a
+   **single** rescan of the **overlapping lenses only** (re-invoke
+   `run-audit-suite.js` for the lenses whose findings were touched).
+   Confirm the batched findings are gone. If a batched finding survives
+   the rescan or validation regresses, route the surviving finding(s) to
+   escalation and record the attempt context in Step 4.
+
+Record every remediated finding (🟠 or 🟡) in the **"Fixed on-branch"**
+section of the `audit-results` comment (Step 4) so it does not graduate to
+a follow-up issue.
+
 Do not invent a programmatic retry budget. The host LLM applies *at most
-one* focused-fix attempt per finding before escalating; any further
-remediation is the operator's call after reading the `audit-results`
-comment.
+one* focused-fix attempt per finding (or per batched finding) before
+escalating; any further remediation is the operator's call after reading
+the `audit-results` comment.
 
 Escalated findings flow through to Step 4 unchanged with their
 escalation reason recorded — the audit pass does not delete them, it
@@ -332,12 +387,40 @@ The body MUST include:
 - a link to the per-lens artifact files under `<auditOutputDir>` so the
   operator (and downstream retro) can re-read the full prompt body.
 
+### The `## Fixed on-branch` section (Story #4399)
+
+Findings that Step 3 remediated on the Epic branch MUST be rendered under a
+dedicated **`## Fixed on-branch`** heading, **not** under their lens's
+open-findings group. This is the contract seam that keeps remediated
+findings from spawning ghost follow-up issues: the
+[`audit-results` graduator](../../scripts/lib/feedback-loop/audit-results-graduator.js)
+skips every entry inside this section (both because a fixed entry is
+rendered with a **✅ prefix** — so it carries no leading severity emoji the
+parser would match — and because the parser has an explicit
+Fixed-on-branch section guard).
+
+Render each fixed finding as a `✅`-prefixed line naming its original
+severity, the file path in backticks, and the remediating commit SHA, e.g.:
+
+```markdown
+## Fixed on-branch
+
+- ✅ 🟡 Medium (audit-clean-code): `.agents/scripts/foo.js` — dead branch removed (a1b2c3d)
+- ✅ 🟠 High (audit-security): `src/api/users.js` — ownership check added (d4e5f6a)
+```
+
+Open (escalated / unfixed) findings stay under their lens heading with
+their leading severity emoji so the graduator still files them.
+
 ### Severity gating
 
-- **Any 🔴 Critical Blocker** → STOP. Relay to the operator and let
-  `/deliver` Phase 4 record a manual intervention.
-- **Only 🟠/🟡/🟢** → log as non-blocking and return to `/deliver`
-  Phase 5 (code-review).
+The gate is unchanged by the threshold — it keys off the **surviving**
+(unfixed) findings after Step 3:
+
+- **Any surviving 🔴 Critical Blocker** → STOP. Relay to the operator and
+  let `/deliver` Phase 4 record a manual intervention.
+- **Only 🟠/🟡/🟢 surviving** → log as non-blocking and return to
+  `/deliver` Phase 5 (code-review).
 
 ## Constraints
 

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.88.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.87.0...mandrel-v1.88.0) (2026-07-08)
+
+
+### Added
+
+* **delivery:** threshold-aware auto-fix remediates Medium findings on-branch (refs [#4399](https://github.com/dsj1984/mandrel/issues/4399)) ([#4400](https://github.com/dsj1984/mandrel/issues/4400)) ([34964b3](https://github.com/dsj1984/mandrel/commit/34964b3665852bf43081f6d893430ff9a0a1f630))
+
 ## [1.87.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.86.0...mandrel-v1.87.0) (2026-07-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.87.0",
+  "version": "1.88.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",