mandrel 1.85.0 → 1.87.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

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/.agents/workflows/plan.md

@@ -124,6 +124,30 @@ are operator-input waits, not validators. The two *named* HITL STOP gates the
 Story tracks (gate #1, gate #2) are the load-bearing pair; these additional
 waits are auto-proceeded for the same headless reason.
 
+## Boot sweep
+
+Before anything else — ahead of the first-run preflight — run the **protected
+boot sweep** so `/plan` opens against a tidy local checkout instead of one
+still carrying the merged refs of the last delivered Epic or Story:
+
+```bash
+node .agents/scripts/boot-sweep.js \
+  --include 'story-*' --include 'epic/*' \
+  --include 'feat/*' --include 'fix/*' --include 'chore/*'
+```
+
+This is the **safe subset** of the `/git-cleanup` phases: it fast-forwards the
+base branch (`main`), prunes stale remote-tracking refs, and reaps every local
+branch whose PR is **merged** and whose HEAD matches the merged `headRefOid`.
+It **never** touches the stash stack, and its `evaluateProtection` partition
+skips (never reaps) any candidate with unpushed work, a dirty worktree, or a
+still-open parent Story ticket — so it is safe to run unattended at the top of
+a planning session. The sweep is **silent on a no-op**: with nothing to reap
+and `main` already current it prints a single summary line
+(`[boot-sweep] reaped 0 local + 0 remote; protected 0.`) and moves on. Its exit
+code is always `0` — a failed sweep is swallowed and reported in the summary,
+never allowed to fail the planning run.
+
 ## First-run preflight
 
 Before routing to a path helper, run a **first-run preflight** to catch
@@ -169,18 +193,22 @@ stubbed docs, or an unready doctor verdict).
 1. **Parse args.** Exactly one of `<epicId>`, `--idea`, `--from-notes`, or
    `--body` must be present; anything else is a usage error naming the four
    forms. A `--body` invocation routes to the story path (no triage).
-2. **First-run preflight.** Run the preflight above. Skip when all signals
+2. **Boot sweep.** Run the protected boot sweep above
+   (`node .agents/scripts/boot-sweep.js …`) to fast-forward `main`, prune
+   stale remotes, and reap merged-PR branches. Silent on a no-op; never fails
+   the run.
+3. **First-run preflight.** Run the preflight above. Skip when all signals
    are clear (healthy project).
-3. **Triage (idea path only).** Run the
+4. **Triage (idea path only).** Run the
    [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
    seed. Record the verdict in chat (one line).
-4. **Delegate.** Read the selected path helper **in full** and execute it
+5. **Delegate.** Read the selected path helper **in full** and execute it
    from its entry phase, forwarding the absorbed flags (including `--yes`).
    The helper's phase numbering, HITL gates, and scripts are unchanged — this
    router adds no phase content. When `--yes` is present, the two HITL STOP
    gates auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
    above; every deterministic gate still runs.
-5. **Internal returns.** When a path helper would historically have handed
+6. **Internal returns.** When a path helper would historically have handed
    off to the other planning command, switch helpers in-place and continue;
    surface the switch to the operator as a one-line note.
 

package/docs/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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)
+
+
+### Added
+
+* Epic [#4372](https://github.com/dsj1984/mandrel/issues/4372) ([#4376](https://github.com/dsj1984/mandrel/issues/4376)) ([98a82a4](https://github.com/dsj1984/mandrel/commit/98a82a4c27e5eafdfa2f1c54cfb42ed537a69a2e))
+
+
+### Fixed
+
+* **baselines:** repair check-baselines auto-refresh + dedupe FF probes ([#4380](https://github.com/dsj1984/mandrel/issues/4380)) ([20a4ecd](https://github.com/dsj1984/mandrel/commit/20a4ecd97f92cb6a88be474c321b139fed95db56)), closes [#4379](https://github.com/dsj1984/mandrel/issues/4379)
+
 ## [1.85.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.84.0...mandrel-v1.85.0) (2026-07-06)
 
 

package/package.json

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