mandrel 1.87.0 → 1.89.0

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

@@ -16,11 +16,21 @@ You are the master orchestrator for the v5 Epic-Centric ticketing pipeline. Your
 goal is to transform a high-level Epic into a fully decomposed, ready-to-execute
 backlog of Stories.
 
-`/plan` is the unified planning entry point. It delegates to the two
-phase helpers — [`helpers/epic-plan-spec.md`](epic-plan-spec.md) and
-[`helpers/epic-plan-decompose.md`](epic-plan-decompose.md) — and runs
-both phases sequentially with a human confirmation gate between them. The Epic
-ID is the single positional argument.
+`/plan` is the unified planning entry point. This file (`helpers/plan-epic.md`)
+is the single authoritative home for Phase 7 (spec) and Phase 8 (decompose) —
+it carries the full step-by-step procedure for both and delegates only the
+authoring middle of each to the
+[`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md) /
+[`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
+skills. It runs both phases sequentially with a human confirmation gate
+between them. The Epic ID is the single positional argument.
+
+> **Thin pointers, not duplicate procedures.** [`helpers/epic-plan-spec.md`](epic-plan-spec.md)
+> and [`helpers/epic-plan-decompose.md`](epic-plan-decompose.md) used to
+> restate Phase 7/8 as their own inline step lists — a drifted, pre-skill
+> pattern now that authoring is delegated to the two skills above. Both files
+> are now thin pointers back to this one; do not resurrect inline step lists
+> in either.
 
 As of v5.6, planning artifacts (Tech Spec, ticket decomposition) are
 authored **directly by you, the host LLM** — no external Gemini / Anthropic /
@@ -37,12 +47,13 @@ artifacts you author.
   See [SDLC § Adaptive planning risk routing](../../docs/SDLC.md#adaptive-planning-risk-routing)
   for the full envelope shape and the planner-selected
   `acceptance::n-a` route.
-- Delegate Phase 7 and Phase 8 to the
-  [`helpers/epic-plan-spec.md`](epic-plan-spec.md) and
-  [`helpers/epic-plan-decompose.md`](epic-plan-decompose.md)
-  procedures respectively — they own the Epic lifecycle label transitions and
-  the `epic-plan-state` checkpoint. This wrapper must not apply those labels
-  directly.
+- Delegate Phase 7 and Phase 8 authoring to the
+  [`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
+  and [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
+  skills respectively — the deterministic `epic-plan-spec.js` /
+  `epic-plan-decompose.js` CLIs (invoked by this file's own Phase 7 / Phase 8
+  steps) own the Epic lifecycle label transitions and the `epic-plan-state`
+  checkpoint. This wrapper must not apply those labels directly.
 
 ## Prerequisites
 
@@ -448,6 +459,18 @@ for the scoring logic.
    `--emit-context` envelope is a backstop for legacy callers; the
    skill body wins when the two surfaces diverge.
 
+   > **One-pass refinement contract (amend, don't regenerate).** When step 3's
+   > persist call rejects the authored artifacts (missing `## Delivery
+   > Slicing`, a schema-invalid risk verdict), re-entering this step applies
+   > **targeted edits** to the existing `temp/epic-[Epic_ID]/{techspec.md,
+   > risk-verdict.json,acceptance-spec.md}` files — fix only what the
+   > rejection named — per the `epic-plan-spec-author` skill's re-emit rule.
+   > This refinement is bounded to **one pass**: fix the named gap and
+   > re-run step 3 once: do not loop wholesale re-authoring across multiple
+   > rejections. The same one-pass shape already governs the Phase 6 Epic
+   > Clarity Gate's refinement loop above ("Do not loop — one refinement
+   > pass per invocation").
+
 3. **Persist to GitHub**: Run the spec-phase CLI's persist half. It
    schema-validates the planner-authored risk verdict (`--risk-verdict`,
    required — a missing or malformed verdict fails closed before any
@@ -564,65 +587,35 @@ for the scoring logic.
    temp files automatically on success — no operator action required. The
    cleanup contract lives in
    [`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js).
-   **Run the Phase 7.5 spec-validate gate (below) on
-   `temp/epic-[Epic_ID]/techspec.md` *before* this cleanup deletes the file** —
-   the gate reads the authored spec from temp.
-
-## Phase 7.5: Tech Spec Section Gate (`epic-plan-spec-validate.js`)
-
-> **Hard gate (blocks Phase 8).** This step runs **after** the Tech Spec is
-> authored (Phase 7) and **before** decomposition (Phase 8). Unlike the
-> advisory spec-freshness and BDD cross-reference checks in Phase 7, this gate
-> is **blocking**: a missing required section exits non-zero and Phase 8 MUST
-> NOT proceed until it is resolved. It is the Phase 8-side counterpart to the
-> Phase 6 Epic Clarity Gate — same detect-then-prompt pattern, one phase later.
-
-**Why this gate exists.** Phase 8.3 (Holistic Consolidation) reconciles the
-draft ticket array against the Tech Spec's `## Delivery Slicing` section, which
-the [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-skill uses as the capability-boundary anchor (see Phase 8 step 2 below). When
-the authored Tech Spec omits that section, the consolidation pass runs against a
-void and produces groupings that reflect **technical shape** (e.g. cron jobs
-together) rather than **capability boundaries** — reproduced on Epic #18 in
-`dsj1984/athportal` (planned with v1.54.0), whose spec carried a detailed
-`## Core Components` table but no `## Delivery Slicing` section.
-
-**Run the gate** against the authored Tech Spec before the Phase 7 cleanup
-deletes `temp/epic-[Epic_ID]/techspec.md`:
-
-```bash
-node .agents/scripts/epic-plan-spec-validate.js \
-  --techspec temp/epic-[Epic_ID]/techspec.md
-```
 
-- **Exit 0** — the spec contains a `## Delivery Slicing` heading (case-
-  insensitive; the gate also accepts the variant `## Delivery slicing` and the
-  shorthand `## Slicing`). Continue to Phase 8.
-- **Exit non-zero** — the required section is missing. The gate is implemented
-  by [`lib/orchestration/spec-section-validator.js`](../../scripts/lib/orchestration/spec-section-validator.js)
-  and prints an operator-visible message naming the missing section and the two
-  recovery paths:
-
-  ```text
-  [epic-plan-spec-validate] Tech Spec is missing required section(s): ## Delivery Slicing
-    Spec file: temp/epic-18/techspec.md
-
-    Phase 8 (decomposition) reconciles the draft ticket array against the
-    Tech Spec's "## Delivery Slicing" section — without it, the Phase 8.3
-    consolidation pass has no capability-boundary anchor and groups by
-    technical shape instead.
-
-    To continue, do ONE of the following before re-running Phase 8:
-      1. Re-author the Tech Spec (re-run the Phase 7 spec-author step) so it
-         emits a "## Delivery Slicing" section, OR
-      2. Add a "## Delivery Slicing" section to the Tech Spec by hand,
-         describing the capability boundaries the work should be sliced along.
-  ```
-
-  **STOP** on a non-zero exit: do not advance to Phase 8. Re-author the Tech
-  Spec (re-run the Phase 7 spec-author step) or add a `## Delivery Slicing`
-  section by hand (to the temp spec file and the Epic body's tech-spec
-  section), then re-run the gate until it exits 0.
+> **Tech Spec section gate (folded into Step 3 persist).** The persist call
+> in Step 3 above validates the authored Tech Spec for the required
+> `## Delivery Slicing` heading (case-insensitive; also accepts the variant
+> `## Delivery slicing` and the shorthand `## Slicing`) via
+> [`lib/orchestration/spec-section-validator.js`](../../scripts/lib/orchestration/spec-section-validator.js#validateSpecSections)
+> **before** acquiring the Epic-lease or making any GitHub mutation — a
+> Tech Spec missing the section fails the persist call closed with a message
+> naming the gap and the two recovery paths (re-author, or add the section by
+> hand). This used to run as a separate, standalone
+> `epic-plan-spec-validate.js` CLI invoked as its own Phase 7.5 workflow
+> step; that ordering ran the check *after* the persist had already written
+> to GitHub and *after* `cleanupPhaseTempFiles` had deleted the temp spec
+> file the check read, so the "blocking gate" could never actually block.
+> Folding the check into the persist path's input validation makes it a
+> real hard gate. **Why this gate exists**: Phase 8.3 (Holistic
+> Consolidation) reconciles the draft ticket array against the Tech Spec's
+> `## Delivery Slicing` section, which the
+> [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
+> skill uses as the capability-boundary anchor (see Phase 8 step 2 below).
+> Without it, the consolidation pass runs against a void and produces
+> groupings that reflect **technical shape** (e.g. cron jobs together)
+> rather than **capability boundaries** — reproduced on Epic #18 in
+> `dsj1984/athportal` (planned with v1.54.0), whose spec carried a detailed
+> `## Core Components` table but no `## Delivery Slicing` section. On a
+> persist failure, re-enter the Step 2 spec-author step and apply a
+> **targeted edit** adding the missing `## Delivery Slicing` section to the
+> existing `techspec.md` (amend, don't regenerate — the one-pass refinement
+> contract above) — or add the section by hand — then re-run Step 3 once.
 
 ## Phase 8: Work Breakdown Decomposition
 
@@ -681,38 +674,78 @@ node .agents/scripts/epic-plan-spec-validate.js \
    toward the Architect's proposed shippable-Story clusters; it degrades
    gracefully when the section is absent.
 
-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, **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 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. 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.** 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
+   > **One-pass refinement contract (amend, don't regenerate).** When the
+   > deterministic validator (`validateAndNormalizeTickets`) rejects the
+   > draft, or the 8.3 / 8.4 / 8.5 critics below flag specific Stories,
+   > re-entering this step applies
+   > **targeted edits** to the existing `temp/epic-[Epic_ID]/tickets.json` —
+   > fix only the rejected or flagged Stories — per the
+   > `epic-plan-decompose-author` skill's re-emit rule, rather than
+   > re-authoring the whole array from scratch. Each critic's feedback gets
+   > **one refinement pass**: apply the targeted edit and re-run the
+   > relevant downstream step (validator or persist) once, matching the
+   > Phase 7 spec-author contract above; do not loop wholesale re-authoring
+   > across repeated rejections.
+
+3. **Phase 8.3 — Holistic Consolidation (HITL diff gate, precondition-gated
+   dispatch)**: After the draft `temp/epic-[Epic_ID]/tickets.json` exists and
+   **before** the persist call below, first consult the deterministic
+   dispatch precondition — [`evaluateConsolidationPrecondition`](../../scripts/lib/orchestration/consolidation-precondition.js),
+   called with the draft Story array and the Epic body (which carries the
+   folded Tech Spec `## Delivery Slicing` section). The precondition compares
+   the draft against the Delivery Slicing table **1:1** — same shippable-Story
+   count (excluding the wave-0 `bdd-scaffold` Story) and a `depends_on` shape
+   that agrees with each slice's `Independent?` answer — and returns
+   `{ dispatch, reasons }`. It **fails open** (`dispatch: true`) on every
+   ambiguous input: a missing or unparseable Delivery Slicing section, or an
+   unparseable `Independent?` cell.
+
+   - **`dispatch: false`** — the draft already matches the Delivery Slicing
+     target, so the consolidation critic has nothing to reconcile. **Skip the
+     sub-agent dispatch** and surface the skip as a **one-line progress
+     note** naming the precondition's `reasons` — quoting verbatim the
+     string `evaluateConsolidationPrecondition` actually emits: "Draft
+     matches Delivery Slicing 1:1 in count and dependency shape (N
+     slice(s)) — skipping the 8.3 consolidation dispatch." (`N` is the
+     interpolated `slicing.length`). Proceed straight to Phase 8.4 with the
+     draft `tickets.json` unchanged (no `consolidation-report.md` is
+     produced when the dispatch is skipped).
+   - **`dispatch: true`** — **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 and execute its procedure with `[Epic_ID]` as input, including the
+     precondition's `reasons` in the HITL diff context so the operator sees
+     *why* the critic ran. 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. 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
+     (`validateAndNormalizeTickets`), 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.** 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.
+
+   Phase 8.4 (Reachability Completeness Critic), Phase 8.5 (Planning
+   Pre-Mortem Critic), and the deterministic ticket validator
+   (`validateAndNormalizeTickets`) are
+   **unconditional** — the precondition governs only the 8.3 sub-agent
+   dispatch, never any other Phase 8 gate. 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)**:
@@ -748,8 +781,8 @@ node .agents/scripts/epic-plan-spec-validate.js \
    - **HITL.** The added Story is surfaced in the **same Phase 8 HITL diff** as
      consolidation, **before** any GitHub write — never auto-persisted. On
      operator rejection, drop the added Story and persist without it. The
-     deterministic validator (step 7) re-checks the critic's output, so an
-     invalid addition cannot reach GitHub.
+     deterministic validator (`validateAndNormalizeTickets`) re-checks the
+     critic's output, so an 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, **dispatch a
@@ -776,8 +809,11 @@ node .agents/scripts/epic-plan-spec-validate.js \
    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.
+   persist call — applying **targeted edits** to the flagged Stories in the
+   existing `tickets.json` (amend, don't regenerate; **one refinement pass**
+   per the contract above), not a wholesale re-author. The critic runs
+   **before** the deterministic validator (`validateAndNormalizeTickets`),
+   so the persist below is the single GitHub write for the whole phase.
 
 6. **Persist to GitHub**: Run the decompose CLI's persist half. It
    validates the ticket array (`validateAndNormalizeTickets`), creates

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

@@ -98,8 +98,18 @@ Envelope fields (`kind: "story-plan-context"`, `version: 1`):
 | `requiredSections`     | `["Context", "Acceptance Criteria", "Out of Scope", "Notes"]`. |
 | `duplicateCandidates`  | Ranked open Stories whose titles fuzzy-match the seed.    |
 | `techStack`            | The project's Tech Stack inventory, resolved in order: `docs/tech-stack.md` (full body) when present, else the `## Tech Stack` section of `docs/architecture.md` (numbered/decorated and final-section headings tolerated). |
+| `corpusContext`        | Corpus-aware inherited context (Story #4432): `{ docsDigest, relevantSections }` — see below. |
 | `deliverContract`      | Workflow path + required/forbidden labels and references. |
 
+`corpusContext.docsDigest` is the same per-project docs digest
+`orchestration/docs-digest.js` builds for `/deliver` Story children (`null`
+when `project.docsContextFiles` is not configured). `corpusContext.relevantSections`
+is a ranked list of `{ epicId, epicTitle, section, score, excerpt }` —
+existing-Epic Tech Spec (or ideation-lede) excerpts that overlap with the
+seed, fetched via a bounded explicit per-candidate body fetch
+(`planning-corpus.js`). Both fields degrade to `null` / `[]` respectively
+when there is nothing to surface.
+
 ### Refine heuristic
 
 `refine.refine` is `true` when the seed is shorter than 200 characters
@@ -121,6 +131,28 @@ Using the envelope above, draft a Story body that:
 - Does **NOT** contain any `Epic: #N` reference — that breaks the
   standalone contract enforced by `single-story-init.js`.
 
+### Drafting against `corpusContext`
+
+Check `corpusContext` before authoring the `## Context` section:
+
+- **When `corpusContext.relevantSections` is non-empty** (the seed is a
+  change-request-shaped delta against a surface an existing Epic already
+  covers — see the
+  [`core/scope-triage`](../../skills/core/scope-triage/SKILL.md) change-request
+  rubric), draft `## Context` **against that inherited context** rather than
+  re-deriving it from scratch: reference the matching Epic's Tech Spec
+  excerpt(s) by number (`Epic #<epicId>`) and build the acceptance criteria on
+  top of the architecture / conventions they already establish. Pull
+  `corpusContext.docsDigest` the same way the digest-first delivery path does
+  (§ 3 of [`.agents/instructions.md`](../../instructions.md)) — read the
+  relevant doc section on demand when the digest outline names one that bears
+  on the change.
+- **When `corpusContext.relevantSections` is `[]` and `docsDigest` is
+  `null`** — no configured docs and no overlapping prior art — draft exactly
+  as today: from the seed, the body template, and the duplicate-candidates
+  scan alone. This is the common case for a genuinely new standalone Story
+  and is not a degraded path; it is simply that there is nothing to inherit.
+
 Write the draft to `temp/single-story-draft.md`.
 
 ### Scope-triage escalation gate (symmetric counterpart to `/plan` Phase 1.5)

package/.agents/workflows/helpers/single-story-deliver.md

@@ -135,6 +135,19 @@ Operator/agent responsibilities while in the worktree:
    only when the Story's own context points you at one — do not ingest the
    whole docs set up front. See
    [`.agents/instructions.md` § 3](../../instructions.md).
+
+   **Write-time audit checklists.** The write-time local-lens checklist
+   threading (Story #4410) is wired on the Epic delivery path via
+   `epic-deliver-prepare.js`, which threads a per-Story `checklistPath` into
+   the maker prompt. When a standalone caller provides a `checklistPath`
+   (the repo-relative path to this Story's footprint-matched **local**-lens
+   authoring checklists, matched via `resolveLensTier(lens) === 'local'` +
+   `matchesAnyFilePattern` against the Story's predicted footprint — never
+   `selectAudits`, so no provider or git diff runs), read it before you
+   write and self-check your change against each listed concern as you
+   author it. When no `checklistPath` is provided, there is nothing extra to
+   read — the lens-aware coverage still runs maker-blind at Story-scope
+   review inside the close subprocess.
 2. Implement the changes.
 3. Commit on the Story branch. Conventional-commit format is encouraged
    but not enforced — the PR title carries the canonical summary.
@@ -249,6 +262,28 @@ Flags:
 - `--no-auto-merge` — disable auto-merge. Use when the PR materially changes
   behaviour and warrants a pre-merge eyeball; the operator then merges via
   the GitHub UI.
+- `--wait-merge` — **headless must-land** (Story #4428, Epic #4425). Pass
+  this flag when driving `single-story-close.js` from an unattended /
+  headless context (no operator available to run Step 5 by hand — a CI
+  job, a scheduled `/loop`, or any wrapper that cannot rely on a human to
+  invoke `single-story-confirm-merge.js` later). Instead of resting at
+  `agent::closing` after arming, close polls the armed PR to merge
+  confirmation on the `delivery.mergeWatch.*` cadence (reusing the same
+  `confirmStoryMerged` flip logic Step 5 calls) and flips `agent::done`
+  itself. If the arm fails, the PR closes without merging, or the poll
+  budget is exhausted first, close classifies the block
+  (`checks-pending-timeout` \| `branch-protection-human-required` \|
+  `arm-failure` \| `api-race-other`), emits a `merge.unlanded` lifecycle
+  event, posts a `friction` comment, transitions the Story to
+  `agent::blocked`, and exits non-zero — never a silent `agent::closing`
+  rest. **Attended runs must not pass this flag** — the default (no flag)
+  preserves the exit-at-`agent::closing` behaviour documented in Step 3
+  and Step 5 below.
+- `--no-wait-merge` — explicit opt-out that always wins over `--wait-merge`
+  (including for a caller that otherwise defaults to headless mode). Use
+  when a headless wrapper still wants to manage merge confirmation itself
+  (e.g. via its own `single-story-confirm-merge.js` invocation) rather than
+  have close block the turn.
 
 > **Full close pipeline (base-sync outcomes, `agent::closing` rationale,
 > lease release).** For the numbered close pipeline, the base-sync outcome
@@ -260,6 +295,14 @@ Flags:
 
 ## Step 4 — CI watch + fix loop (**required, not optional**)
 
+> **Headless (`--wait-merge`) runs skip Steps 4 and 5.** When Step 3 passed
+> `--wait-merge`, `single-story-close.js` already polled the PR to a
+> confirmed merge (flipping `agent::done` itself) or exited non-zero after
+> transitioning the Story to `agent::blocked` with a `merge.unlanded`
+> event — there is no separate CI-watch turn or manual confirm step to run.
+> Proceed straight to Step 5.5. Attended runs (the default) still own
+> Steps 4 and 5 as documented below.
+
 The Story is **not done** when `single-story-close.js` returns. Auto-merge
 only fires when every required CI check turns green. Local close-validation
 gates pass on the dev host's environment; CI runs on a different OS and

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

@@ -34,13 +34,15 @@ Each scheduled run:
    structured `temp/audits/audit-*-results.md` report — that is the canonical
    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.
+   parallel sub-agents** (one per audit) rather than walking them serially:
+   dispatch one general-purpose sub-agent per lens, each instructed to read
+   its `/audit-<lens>` workflow and write the structured report. 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. (The former `/deliver` Phase 4 audit-orchestrator pattern this
+   note used to cite was retired by Story #4412, which folded the Epic-close
+   lens walk into the Phase 5 code-review pass.)
 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,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.89.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.88.0...mandrel-v1.89.0) (2026-07-11)
+
+
+### Added
+
+* add cross-epic guard to story-close.js shared-checkout merge phase ([#4462](https://github.com/dsj1984/mandrel/issues/4462)) ([78c5263](https://github.com/dsj1984/mandrel/commit/78c526309a65f71fbfe14f4ef51c1e8ae706e454))
+* Epic [#4405](https://github.com/dsj1984/mandrel/issues/4405) ([#4463](https://github.com/dsj1984/mandrel/issues/4463)) ([99737f1](https://github.com/dsj1984/mandrel/commit/99737f171d0cb0b4b28b40ea4c160b92c59428d6))
+* Epic [#4406](https://github.com/dsj1984/mandrel/issues/4406) ([#4440](https://github.com/dsj1984/mandrel/issues/4440)) ([63cc5c3](https://github.com/dsj1984/mandrel/commit/63cc5c35483e9ec1138be2880127fad3b6244eb4))
+* Epic [#4425](https://github.com/dsj1984/mandrel/issues/4425) ([#4458](https://github.com/dsj1984/mandrel/issues/4458)) ([6da35a6](https://github.com/dsj1984/mandrel/commit/6da35a6f740cabc620b7b286dc87a710af237a30))
+* Epic [#4429](https://github.com/dsj1984/mandrel/issues/4429) ([#4443](https://github.com/dsj1984/mandrel/issues/4443)) ([0a8122f](https://github.com/dsj1984/mandrel/commit/0a8122fb406092ff2212346b546276727d04f974))
+* Epic [#4430](https://github.com/dsj1984/mandrel/issues/4430) ([#4470](https://github.com/dsj1984/mandrel/issues/4470)) ([8cfcd28](https://github.com/dsj1984/mandrel/commit/8cfcd28099664763d34231121ebea9f2187c437f))
+* Epic [#4454](https://github.com/dsj1984/mandrel/issues/4454) ([#4459](https://github.com/dsj1984/mandrel/issues/4459)) ([bd57246](https://github.com/dsj1984/mandrel/commit/bd57246cdb867e62e7e2eae662c93658a54766e2))
+
+
+### Fixed
+
+* **deliver:** add missing fs import in epic-deliver-prepare ([#4465](https://github.com/dsj1984/mandrel/issues/4465)) ([7b24da8](https://github.com/dsj1984/mandrel/commit/7b24da806c9859dcb75d4f5232670c2d3547d126))
+* **delivery:** smoke-cover the prepare checklist branch + undeclared-var guard + docs-freshness hygiene ([#4471](https://github.com/dsj1984/mandrel/issues/4471)) ([d9ead77](https://github.com/dsj1984/mandrel/commit/d9ead770263bc49d210ed65038de6e454602c684)), closes [#4466](https://github.com/dsj1984/mandrel/issues/4466) [#4469](https://github.com/dsj1984/mandrel/issues/4469)
+* **lifecycle:** restore the Epic agent::done flip + remediate post-1.88.0 robustness findings ([#4468](https://github.com/dsj1984/mandrel/issues/4468)) ([0cf9d5b](https://github.com/dsj1984/mandrel/commit/0cf9d5b499127a26c57cade13d753bd7aa6b3082))
+* **single-story-close:** intersect wrong-tree stray paths with the Story diff (refs [#4424](https://github.com/dsj1984/mandrel/issues/4424)) ([#4434](https://github.com/dsj1984/mandrel/issues/4434)) ([a3b05a5](https://github.com/dsj1984/mandrel/commit/a3b05a5afe3175e58ad9b7e1a76bdf69637a1f0f)), closes [#4420](https://github.com/dsj1984/mandrel/issues/4420)
+* **story-close:** make re-run against an already-closed Story a safe no-op ([#4461](https://github.com/dsj1984/mandrel/issues/4461)) ([7e6859d](https://github.com/dsj1984/mandrel/commit/7e6859d6e5a7d42b06f5781684defb88830ea16a))
+
+## [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/lib/cli/doctor.js

@@ -26,6 +26,10 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
+import {
+  resolveAlwaysLoadedClosure,
+  tierTotalBytes,
+} from '../../.agents/scripts/lib/doc-tiers.js';
 import { registry } from './registry.js';
 
 // ---------------------------------------------------------------------------
@@ -78,6 +82,40 @@ function formatSummary(passed, total) {
   return `❌  Not ready (${failed}/${total} checks failed)\n`;
 }
 
+/**
+ * Build the one report-only line describing the always-loaded documentation
+ * closure (the `CLAUDE.md` `@`-import graph) — its file count and total size in
+ * KB. This is **informational only**: it is never counted toward the pass/fail
+ * tally and therefore never changes the doctor exit code (Story #4438). Any
+ * failure to resolve the closure degrades to a neutral line rather than
+ * throwing, so an unreadable tree never breaks the doctor run.
+ *
+ * Security (security-baseline § 5 — Data Leakage & Logging): emits only a file
+ * count and byte total, never file contents.
+ *
+ * Exported for testing.
+ *
+ * @param {{ cwd?: () => string, resolveClosure?: (root: string) => Array<{ path: string, bytes: number }> }} [opts]
+ * @returns {string} a single line terminated by `\n`
+ */
+export function formatClosureReport({
+  cwd = process.cwd,
+  resolveClosure = (root) => resolveAlwaysLoadedClosure(root),
+} = {}) {
+  const label = padName('context-closure', NAME_COL);
+  let files = [];
+  try {
+    files = resolveClosure(cwd()) ?? [];
+  } catch {
+    return `ℹ  ${label}  always-loaded closure unavailable\n`;
+  }
+  if (files.length === 0) {
+    return `ℹ  ${label}  no CLAUDE.md closure found\n`;
+  }
+  const kb = (tierTotalBytes(files) / 1024).toFixed(1);
+  return `ℹ  ${label}  ${files.length} file(s), ${kb} KB always-loaded\n`;
+}
+
 // ---------------------------------------------------------------------------
 // Result cache
 // ---------------------------------------------------------------------------
@@ -124,6 +162,7 @@ export function writeDoctorResultCache(
  *   write?: (s: string) => void,
  *   exit?: (code: number) => void,
  *   writeResultCache?: (verdict: 'ready'|'unready') => void,
+ *   closureReport?: () => string,
  * }} [opts]
  * @returns {void}
  */
@@ -132,6 +171,7 @@ export async function runDoctor({
   write = (s) => process.stdout.write(s),
   exit = (code) => process.exit(code),
   writeResultCache = writeDoctorResultCache,
+  closureReport = () => formatClosureReport(),
 } = {}) {
   let passed = 0;
 
@@ -141,6 +181,10 @@ export async function runDoctor({
     write(formatResult({ name: check.name, ...result }));
   }
 
+  // Report-only informational line — NOT counted toward passed/total, so it
+  // never affects the doctor verdict or exit code (Story #4438).
+  write(closureReport());
+
   const total = checks.length;
   write(formatSummary(passed, total));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.87.0",
+  "version": "1.89.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -30,8 +30,8 @@
     "coverage:update": "node .agents/scripts/update-coverage-baseline.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
     "lint": "node .agents/scripts/run-lint.js && npm run docs:check",
-    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-lifecycle-docs.js && node .agents/scripts/generate-workflows-doc.js",
-    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/check-lifecycle-doc-drift.js && node .agents/scripts/check-doc-links.js && node .agents/scripts/check-gherkin-placeholders.js && npm run skills:check",
+    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-lifecycle-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
+    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-lifecycle-doc-drift.js && node .agents/scripts/check-doc-links.js && node .agents/scripts/check-gherkin-placeholders.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
     "skills:check": "node .agents/scripts/generate-skills-index.js --check",
     "format": "biome format --write .",
@@ -39,6 +39,7 @@
     "maintainability:check": "node .agents/scripts/check-baselines.js --gate maintainability",
     "maintainability:update": "node .agents/scripts/update-maintainability-baseline.js",
     "check:arch": "node .agents/scripts/check-arch-cycles.js",
+    "check:context-budget": "node .agents/scripts/check-context-budget.js",
     "crap:check": "node .agents/scripts/check-baselines.js --gate crap",
     "crap:update": "node .agents/scripts/update-crap-baseline.js",
     "duplication:check": "node .agents/scripts/check-baselines.js --gate duplication",