mandrel 1.86.0 → 1.88.0

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

@@ -1,8 +1,10 @@
 ---
 description: >-
   Run smart change-set audits at Epic finalize. Consumes the epic-audit-prepare
-  envelope, dispatches each selected lens inline via runAuditSuite, and posts
-  an audit-results structured comment back onto the Epic ticket.
+  envelope, dispatches each selected lens (inline, or via a single
+  audit-orchestrator sub-agent that fans the lenses out as parallel level-2
+  agents) through runAuditSuite, and posts an audit-results structured comment
+  back onto the Epic ticket.
 ---
 
 # Epic Audit (helper)
@@ -197,6 +199,62 @@ After the runner returns:
    🟡 Medium / 🟢 Suggestion). Hold the aggregate for Step 3
    (auto-fix) and Step 4 (the `audit-results` structured comment).
 
+### Optional: delegate the roster walk to an audit-orchestrator sub-agent
+
+The Step 2 loop above walks the `selectedAudits` roster **serially in the
+host's own context**. When the roster carries more than one lens, `/deliver`
+Phase 4 MAY instead delegate the whole walk to a **single audit-orchestrator
+sub-agent** — one level-1 `Agent` call (`subagent_type: general-purpose`) — that:
+
+1. Receives the **already-selected** `selectedAudits` roster, the run's
+   `depth`, and the prepare envelope's substitution payload. It does **not**
+   re-run `selectAudits` and does **not** widen the roster — the roster is
+   fixed upstream by Step 1 (see the Constraints below).
+2. Fans the roster out as **parallel level-2 agents, one per lens** (nested
+   `Agent` dispatch — verified depth 2, announced max depth 5, per
+   [#2870](https://github.com/dsj1984/mandrel/issues/2870) and the
+   "Flat Story dispatch by design" note in
+   [`deliver-epic.md`](deliver-epic.md)). Each level-2 agent executes exactly
+   one lens's workflow procedure at the run's `depth`, isolated from the main
+   context.
+3. Collects the per-lens findings, **aggregates them by severity** (🔴 / 🟠 /
+   🟡 / 🟢), and returns **only the aggregated audit-results** to the host —
+   the per-lens reasoning transcripts stay in the level-2 leaves and never
+   enter the main context. The host resumes at Step 3 (remediation routing)
+   with the aggregate exactly as if it had walked the roster itself, and Step 4
+   posts the identical `audit-results` comment.
+
+This delegation is a **cross-lens parallelization of the roster walk only**. It
+is orthogonal to — and MUST NOT be conflated with — the *per-lens execution
+strategy*:
+
+- **The per-lens cost/precision gate is preserved.** Each level-2 lens agent
+  still runs its own lens at whatever strategy that lens's cost/precision gate
+  dictates (`docs/roadmap.md` § "The per-lens cost / precision gate"): an
+  orchestrated lens fans its own analysis dimensions out under
+  `runAuditOrchestration`, a sequential-only lens runs turn-by-turn. Fanning
+  the *roster* out in parallel changes **which context** runs a lens, never
+  **how** that lens runs internally, so no per-lens cost gate is bypassed or
+  altered.
+- **The "do not batch-convert the sequential-only lenses" rule is preserved.**
+  The seven sequential-only lenses (`audit-dependencies`, `audit-devops`,
+  `audit-sre`, `audit-privacy`, `audit-seo`, `audit-ux-ui`,
+  `audit-lighthouse`) stay sequential **inside** their level-2 agent.
+  Dispatching them as parallel level-2 agents is **not** a batch-conversion of
+  their internal execution — a sequential-only lens remains sequential-only
+  (`docs/roadmap.md` § "Remaining orchestration surface"). Generalizing any of
+  those lenses to orchestrated is still a separate, gated, lens-by-lens
+  decision that this roster fan-out neither performs nor pre-empts.
+
+Weigh the whole subtree's token cost before delegating
+([`.agents/instructions.md` § 4](../../instructions.md) — cost compounds with
+nesting depth): the level-1 orchestrator plus one level-2 agent per lens
+re-pays the always-loaded context at each level. For a single-lens roster the
+serial host walk is cheaper; the delegation pays off when several lenses fan
+out at once. Either path produces the identical Step 4 `audit-results` comment,
+so the delegation is a performance/context-isolation choice, never a change to
+what gets audited or reported.
+
 If a future Story lifts per-lens execution out of the host-LLM walk
 into the CLI itself, the runner will populate `findings[]` and this
 section will collapse to a "read the structured findings off the
@@ -205,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:
 
@@ -239,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
@@ -274,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/.agents/workflows/helpers/parallel-tooling.md

@@ -76,8 +76,15 @@ If a unit of work is both long (Rule 2) and independent (Rule 1 or 3),
 prefer the higher-numbered rule — the parallelism gain compounds the
 background-shell gain. Concretely: dispatch the `Agent` calls in one turn
 (Rule 3), and **inside** each sub-agent let it apply Rule 2 to its own
-long-running shells. The host does not need to micromanage the child's
-shell strategy.
+long-running shells — and, within the supported nesting depth budget
+(verified depth 2, announced max depth 5; see
+[#2870](https://github.com/dsj1984/mandrel/issues/2870)), let it apply
+**Rule 3** to its own independent sub-units as well, not only Rule 2
+background shells. A sub-agent is a full orchestrator at its own level:
+recursive `Agent` fan-out is available to it, so the host does not need to
+micromanage the child's shell **or** dispatch strategy. Mind the depth
+budget and the compounding cost — every nesting level re-pays the
+always-loaded context (see [`instructions.md` § 4](../../instructions.md)).
 
 ## Constraints
 

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

@@ -683,26 +683,36 @@ node .agents/scripts/epic-plan-spec-validate.js \
 
 3. **Phase 8.3 — Holistic Consolidation (HITL diff gate)**: After the
    draft `temp/epic-[Epic_ID]/tickets.json` exists and **before** the persist
-   call below, activate the
+   call below, **dispatch a genuine fresh-context sub-agent** (`Agent` tool,
+   `subagent_type: general-purpose`) whose task is to read the
    [`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
-   skill with `[Epic_ID]` as input. This is a **separate critic pass with
-   fresh context** (not a self-review appended to the author skill): it reads
-   the draft array plus the Epic body (which carries the Tech Spec
-   sections), reconciles the draft against
+   skill and execute its procedure with `[Epic_ID]` as input. Dispatching the critic
+   as a sub-agent — **not** activating the skill inline in your authoring
+   turn — is what makes it a **separate critic pass with fresh context**: the
+   sub-agent does not inherit the conversation that authored the draft, so it
+   cannot grade its own homework (the same nested-dispatch mechanic the
+   acceptance self-eval loop uses, now that the sub-agent depth limit is
+   lifted — see [`.agents/instructions.md` § 4](../../instructions.md)). The
+   sub-agent reads the draft array plus the Epic body (which carries the Tech
+   Spec sections), reconciles the draft against
    the Tech Spec `## Delivery Slicing` target, and emits a **consolidated**
    `tickets.json` plus a human-readable
    `temp/epic-[Epic_ID]/consolidation-report.md`. Its operations are
    scope-preserving only — **merge sibling Stories and rewire
    `depends_on`** — and it MUST NOT add scope or invent tickets; it
    consolidates fragmented slices by merging them into a cohesive Story,
-   never by splitting one. It runs **before** the deterministic
+   never by splitting one. The sub-agent **never writes to GitHub**: it emits
+   only the two temp artifacts and returns control to this operator session.
+   It runs **before** the deterministic
    validator (step 7), so the validator re-checks its output and the critic
    cannot emit an invalid plan.
 
    **Show the operator the consolidation report (the before/after diff +
-   rationale) before persisting.** Consolidation is never auto-applied without
-   review: on operator approval, persist the consolidated `tickets.json`; on
-   rejection, persist the draft instead. This is a sub-step of Phase 8 — it
+   rationale) before persisting.** The HITL diff-confirm and the persist call
+   both run here in the **operator session**, never inside the sub-agent —
+   consolidation is never auto-applied without review: on operator approval,
+   persist the consolidated `tickets.json`; on rejection, persist the draft
+   instead. This is a sub-step of Phase 8 — it
    does **not** renumber the top-level lifecycle phases (9–12).
 
 4. **Phase 8.4 — Reachability Completeness Critic (HITL diff gate, F6)**:
@@ -742,11 +752,17 @@ node .agents/scripts/epic-plan-spec-validate.js \
      invalid addition cannot reach GitHub.
 
 5. **Phase 8.5 — Planning Pre-Mortem Critic (code-reading, F9)**: After the
-   reachability critic (8.4) and **before** the persist call below, activate the
+   reachability critic (8.4) and **before** the persist call below, **dispatch a
+   genuine fresh-context sub-agent** (`Agent` tool,
+   `subagent_type: general-purpose`) whose task is to read the
    [`epic-plan-premortem`](../../skills/core/epic-plan-premortem/SKILL.md)
-   skill with `[Epic_ID]` as input. This is a **fresh-context critic** sibling
-   to `epic-plan-consolidate`: it reads the drafted `tickets.json`, the Epic
-   body (with its folded Tech Spec sections), **and the actual cited code
+   skill and execute its procedure with `[Epic_ID]` as input. Like the 8.3
+   consolidate pass, dispatching the critic as a sub-agent — **not** activating
+   the skill inline in your authoring turn — is what makes it a genuine
+   **fresh-context critic** sibling to `epic-plan-consolidate`: the sub-agent
+   does not inherit the authoring conversation, so its code-reading review is
+   independent of the draft it grades. It reads the drafted `tickets.json`, the
+   Epic body (with its folded Tech Spec sections), **and the actual cited code
    surfaces** (the files each Story's
    `changes[]` / `references[]` name), then emits predicted-rework findings —
    unverifiable acceptance criteria, over- or under-specified Stories, and
@@ -756,7 +772,9 @@ node .agents/scripts/epic-plan-spec-validate.js \
    Unlike the consolidate critic it is **not** scope-preserving-only: it may
    recommend splitting an under-specified Story or tightening an AC. But it
    **never writes to GitHub** and never persists `tickets.json` — it only emits
-   the report. Its findings are shown in the **same Phase 8 HITL diff**, and on
+   the report and returns control to this operator session. Its findings are
+   shown in the **same Phase 8 HITL diff** (which stays in the operator
+   session), and on
    operator approval the author re-runs (Step 2) on the findings **before** the
    persist call. The critic runs **before** the deterministic validator (step
    7), so the persist below is the single GitHub write for the whole phase.

package/.agents/workflows/loops/nightly-audit.md

@@ -32,7 +32,15 @@ Each scheduled run:
    (`/audit-security`, `/audit-clean-code`, `/audit-dependencies`,
    `/audit-quality`, and any others the project relies on). Each audit writes a
    structured `temp/audits/audit-*-results.md` report — that is the canonical
-   artifact this loop consumes, not free-form prose.
+   artifact this loop consumes, not free-form prose. Because these audits are
+   **independent** of one another, a scheduled run **may fan them out to
+   parallel sub-agents** (one per audit) rather than walking them serially —
+   the same cross-lens parallelization `/deliver` Phase 4 uses (see
+   [`../helpers/epic-audit.md` § "Optional: delegate the roster walk to an
+   audit-orchestrator sub-agent"](../helpers/epic-audit.md)). Each sub-agent
+   returns only its structured report; the scheduler/host owns the fan-out just
+   as it owns the cadence, and each per-audit strategy (sequential or
+   orchestrated) is unchanged by running under its own sub-agent.
 2. **Diff against the prior night.** Compare the fresh findings against the last
    sweep's reports and against already-open Issues. A finding seen before is
    not new signal; only genuinely fresh or regressed findings warrant a record.

package/docs/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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)
+
+
+### Added
+
+* **boot-sweep:** report content-merged branches and align sweep docs ([#4396](https://github.com/dsj1984/mandrel/issues/4396)) ([#4398](https://github.com/dsj1984/mandrel/issues/4398)) ([8c9c938](https://github.com/dsj1984/mandrel/commit/8c9c938d34c0bcbdaeb607f5a148261925a58622))
+* Epic [#4385](https://github.com/dsj1984/mandrel/issues/4385) ([#4392](https://github.com/dsj1984/mandrel/issues/4392)) ([0999dca](https://github.com/dsj1984/mandrel/commit/0999dcac00a708bca0d1a9664f46d8f79c9ffe11))
+* **git-cleanup:** detect content-merged branches and surface silent skips (refs [#4395](https://github.com/dsj1984/mandrel/issues/4395)) ([#4397](https://github.com/dsj1984/mandrel/issues/4397)) ([a5ddabf](https://github.com/dsj1984/mandrel/commit/a5ddabf41f25a75cb5b63e0f51ed05e8dcfcf81d))
+* **planning:** stamp authoring Mandrel version onto Epic and Story bodies (refs [#4382](https://github.com/dsj1984/mandrel/issues/4382)) ([#4383](https://github.com/dsj1984/mandrel/issues/4383)) ([db3de0a](https://github.com/dsj1984/mandrel/commit/db3de0a9302a8f3aa97b06ad74af04879aaba53a))
+
+
+### Fixed
+
+* branchCleaner false-blocks a successfully-merged Epic when local branches are already reaped ([#4393](https://github.com/dsj1984/mandrel/issues/4393)) ([#4394](https://github.com/dsj1984/mandrel/issues/4394)) ([83a5604](https://github.com/dsj1984/mandrel/commit/83a5604b55aab470d9c4c08ee9d66b4b181af81a))
+
 ## [1.86.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.85.0...mandrel-v1.86.0) (2026-07-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.86.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/",