mandrel 1.86.0 → 1.87.0

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -35,7 +35,29 @@ per-criterion, mid-delivery, and evaluates the actual work product.
 1. **Eval pass (fresh context, independent of the author).** Run a **separate
    critic pass** — a fresh-context sub-agent (`Agent` tool,
    `subagent_type: general-purpose`), *not* a continuation of your implementing
-   turn — so the evaluator does not grade its own homework. The critic:
+   turn — so the evaluator does not grade its own homework.
+
+   > **Inline-critic fallback (nesting-absent harness).** Dispatching the
+   > critic as a nested `Agent` is the preferred shape — it gives genuine
+   > fresh-context isolation — and works on any harness that carries `Agent`
+   > into sub-agents (Claude Code ≥ 2.1.202; see
+   > [#2870](https://github.com/dsj1984/mandrel/issues/2870)). This eval loop
+   > itself runs inside a Story delivery sub-agent, so the nested critic sits
+   > at nesting depth 2. If the host does **not** support nested `Agent`
+   > dispatch at that depth — the tool is absent, or a spawn attempt returns
+   > an unsupported-capability error — do **not** stall the Story. Fall back
+   > to authoring the verdict **inline**: in a deliberately scoped,
+   > self-critical pass (re-read only the diff, the `acceptance[]` /
+   > `verify[]` arrays, and the `verify[]` command output — treat the
+   > implementation reasoning as untrusted and score against the criteria
+   > afresh), write the same verdict file described below and hand it to the
+   > same `acceptance-eval.js` gate. The fresh-context isolation is weaker in
+   > the inline path, but the gate, the schema, the round cap, and the
+   > proceed / redraft / block decision are identical — a Story is **never**
+   > stranded on a nesting-absent harness. Note in the blocked/friction
+   > comment (if you block) that the inline fallback was used.
+
+   The critic:
    - Inspects the working diff (`git diff origin/<baseBranch>...HEAD`) and the
      Story's inline `acceptance[]` / `verify[]` arrays.
    - **Runs the `verify[]` commands** and consumes their output as **required

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

@@ -89,9 +89,17 @@ Every other runtime modifier is sourced from the Epic's labels or from
 - **Single pause point.** Only `agent::blocked` halts execution. No
   clarifying questions — if stuck, flip to `agent::blocked`, post a
   friction comment, park.
-- **Two-level dispatch.** Host LLM fans out per-Story Agent calls
-  directly with `subagent_type: general-purpose`. Sub-agents do not
-  carry the `Agent` tool, so this stays flat.
+- **Flat Story dispatch by design.** Host LLM fans out per-Story Agent
+  calls directly with `subagent_type: general-purpose`. Keeping Story
+  dispatch flat — the host owns the single fan-out level — is a
+  **design choice**, not a harness constraint: the wave aggregator, idle
+  watchdog, and merge-lock all assume one host-owned dispatch level. As of
+  Claude Code 2.1.202 a level-1 sub-agent **does** 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 a Story
+  worker may itself fan out for its own sub-work within that depth budget —
+  the Epic wave loop nonetheless stays flat by choice, not because nesting
+  is unavailable.
 - **Operator-merges-PR exit.** Phase 7 opens the PR; the workflow
   never merges to `main` itself. Phase 8.5 may fire auto-merge when
   every signal is clean.
@@ -481,6 +489,17 @@ 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 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
+parallel level-2 agents and returns only the aggregated `audit-results` (see
+[`epic-audit.md` § "Optional: delegate the roster walk to an audit-orchestrator
+sub-agent"](epic-audit.md), within the sub-agent depth budget noted under
+"Flat Story dispatch by design" above). The roster stays fixed upstream, every
+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.
 - **Selector reports `degraded: true`** — STOP. Propagate the

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/docs/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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)
 
 

package/package.json

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