mandrel 2.64.0 → 2.66.0

package/.agents/workflows/audit-performance.md

@@ -27,18 +27,18 @@ Per the core's Scope interpretation:
 
 ## Execution strategy
 
-This is a **heavyweight lens**: dispatch it as a single `subagent_type: auditor`
-call, or fan its resource dimensions out per-dimension across parallel `auditor`
-subagents (parallel-tooling Rule 3) and merge under the self-cross-check.
-Sequential inline execution is the fallback (see the core's Execution strategy).
+Dispatch this lens as one `subagent_type: auditor` call. Fan its resource
+dimensions out across parallel `auditor` subagents (parallel-tooling Rule 3),
+merging under the self-cross-check, only when the operator explicitly asks for
+per-dimension fan-out. Sequential inline execution is the fallback (see the
+core's Execution strategy).
 
 > **Measurement is non-mutating, not forbidden.** This lens is read-only with
-> respect to source, but it MUST be allowed to *run* measurements. The
-> orchestrated path grants its measurement agents a `Bash` tool restricted to a
-> **non-mutating command allowlist** (profilers, timers, bundle-stat and
-> file-size probes — never a command that writes source, installs, or mutates
-> git/labels). See the allowlist in the harness-generated
-> `.claude/workflows/audit-performance.workflow.js`.
+> respect to source, but the auditor MUST be allowed to *run* measurements. It
+> runs only **non-mutating** commands — profilers, timers, bundle-stat and
+> file-size probes — and never a command that writes source, installs
+> packages, or mutates git state or labels. The one write is the report
+> artifact.
 
 ## Step 0: Measure before you judge (mandatory)
 

package/.agents/workflows/audit-quality.md

@@ -12,7 +12,8 @@ the Story under audit. The shared lens machinery lives in
 `{{auditOutputDir}}/audit-quality-results.md`. Each finding carries a
 **Category:** (`Flakiness | Coverage | Performance | Mocking | Test Plans`); the
 report adds a **Test Strategy Assessment** table (Unit / Integration / E2E /
-Test Plans: Healthy / Needs Work / Missing).
+Test Plans / Property-Based Testing: Healthy / Needs Work / Missing, or `N/A`
+for Property-Based Testing when no module is a candidate).
 
 ## Scope
 
@@ -130,6 +131,36 @@ Evaluate the gathered context against the following test quality dimensions:
    finding here. Route the *architectural* framing of the same defect to
    [`audit-architecture`](audit-architecture.md)'s Shipped-But-Never-Wired
    dimension; this lens owns the **missing-test** framing.
+8. **Property-Based Coverage — Invariants Tested Only by Examples.** Flag a
+   module whose correctness rests on an invariant but whose tests are all
+   hand-picked examples, which structurally cannot reach the inputs nobody
+   thought to pick. A module is a candidate **only** on code evidence: a
+   documented invariant or "never"/"always" claim in a header comment; an
+   explicit state machine or status/label transition table; an
+   encode/decode, parse/serialize or normalise pair (round-trip); a
+   merge/dedup/sort/scheduler function; bounded-concurrency or retry
+   coordination over async I/O; or an idempotency claim. A module with no
+   stated or implied invariant is **never** a finding. Rank candidates by
+   Step 0's churn × coverage gap and cite their `baselines/` coverage/CRAP row
+   where one exists.
+
+   - **Toolchain by ecosystem, never one library.** Detect an existing
+     property-testing library from the consumer's manifests (e.g.
+     `fast-check` for JS/TS, `hypothesis` for Python, `proptest`/`quickcheck`
+     for Rust, `jqwik` for the JVM, `rapid`/`gopter` for Go); recommend the
+     ecosystem-idiomatic one only when none is present.
+   - Severity: an async/concurrency coordinator, or a guard whose
+     invariant protects an irreversible write, tested only by examples →
+     **High**; any other invariant-bearing module with example-only tests →
+     **Medium**; toolchain absent with no High/Medium candidate → **one Low**
+     roll-up finding, not one per module.
+   - Category: file under `Coverage`. A property test whose seed is
+     neither pinned nor printed on failure goes under `Flakiness`: a red that
+     cannot be reproduced breaks the reproducibility the rubric demands.
+   - **Name the property.** Each finding states the invariant as a testable
+     property (e.g. `decode(encode(x)) === x`; "no transition leaves a
+     terminal state") plus its generator shape (the input domain to draw
+     from) — never a bare "add property tests".
 
 ## Constraint (lens-specific carve-out)
 
@@ -150,10 +181,14 @@ table:
 
 ## Test Strategy Assessment
 
-| Layer               | Status                           | Notes          |
-| ------------------- | -------------------------------- | -------------- |
-| Unit Testing        | [Healthy / Needs Work / Missing] | [Brief reason] |
-| Integration Testing | [Healthy / Needs Work / Missing] | [Brief reason] |
-| E2E Testing         | [Healthy / Needs Work / Missing] | [Brief reason] |
-| Test Plans          | [Healthy / Needs Work / Missing] | [Brief reason] |
+| Layer                  | Status                                 | Notes          |
+| ---------------------- | -------------------------------------- | -------------- |
+| Unit Testing           | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| Integration Testing    | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| E2E Testing            | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| Test Plans             | [Healthy / Needs Work / Missing]       | [Brief reason] |
+| Property-Based Testing | [Healthy / Needs Work / Missing / N/A] | [Brief reason] |
 ```
+
+`Property-Based Testing` reads `N/A` when the repo has no candidate module
+(dimension 8), so a repo with no invariant-bearing code is not nagged.

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

@@ -32,8 +32,8 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    authors the Story's verdict, and it covers **every** `acceptance[]` item in
    one file. Which pass is named by the ceremony decision
    (`verdictOwner: 'fresh-critic' | 'inline-self-eval'` from
-   `resolveCeremonyForRisk`), and since Story #5343 that follows the
-   **ceremony profile alone**:
+   `resolveCeremonyForRisk`), which follows the **ceremony profile
+   alone**:
 
    > ```bash
    > node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>
@@ -43,9 +43,8 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    > classes **for review depth**, and resolves the owner (`mode`, `reason`,
    > `verdictOwner`): **`minimal` / `standard` → `inline`** (the default — you
    > author the verdict yourself), **`strict` → `fresh`** (dispatch the
-   > maker-blind critic). The derived level no longer routes this decision;
-   > it escalates `review-depth.js` instead, which still resolves `deep` for
-   > any sensitive path.
+   > maker-blind critic). The derived level feeds `review-depth.js`, not
+   > this decision; review depth resolves `deep` for any sensitive path.
 
    **Never run both**, and never run a preliminary self-assessment before
    dispatching a fresh critic — the redundant pre-pass buys no measurable
@@ -69,12 +68,13 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    > `delivery.routing.roleScopedAgents` is enabled (the **default**), use
    > `subagent_type: acceptance-critic`: it boots on the role-scoped
    > [`acceptance-critic`](../../agents/acceptance-critic.md) context (its own
-   > system prompt, no `CLAUDE.md` @-closure) carrying the maker-blind
+   > system prompt, no entry-doc @-closure) carrying the maker-blind
    > invariant and the verdict schema standalone. With the kill-switch off
    > (`roleScopedAgents: false`), fall back to
-   > `subagent_type: general-purpose`. This loop already runs inside a Story
-   > delivery sub-agent, so the critic sits at nesting depth 2 — supported by
-   > any harness that carries `Agent` into sub-agents (Claude Code ≥ 2.1.202).
+   > `subagent_type: general-purpose`. Under sub-agent dispatch this loop
+   > runs inside a `story-worker`, so the critic sits at nesting depth 2
+   > (depth 1 inline) — supported by any harness that carries `Agent` into
+   > sub-agents (Claude Code ≥ 2.1.202).
 
    Whichever pass owns it, the verdict:
    + Inspects the **change set it was handed** — the one `files` list above —

package/.agents/workflows/helpers/audit-lens-core.md

@@ -118,14 +118,12 @@ dropped finding is indistinguishable from a finding you never wrote.
   Use it instead of inventing a below-`Low` word of your own; a finding that
   cannot clear the evidence bar below is **dropped**, not filed as `Info`.
 
-## Self-cross-check (mandatory — filter false positives before you finalize) {#self-cross-check}
+## Self-cross-check (the false-positive bar) {#self-cross-check}
 
-You are your own adversarial reviewer. After you have drafted the Detailed
-Findings but **before** you write the report artifact, re-open every finding
-and hold it to the bar below. This pass is **read-only** — it filters and
-tightens the findings you already have; it never invents new ones. It gives the
-sequential single-pass path the same false-positive filter the orchestrated
-path's independent adversarial reviewer applies.
+A finding goes in the report only when it clears the bar and the exclusion
+list below. The bar filters and tightens findings; it never invents new ones.
+It is the one false-positive filter every execution path applies — no separate
+adversarial reviewer runs after it.
 
 ### Per-finding evidence bar (keep or drop)
 
@@ -173,23 +171,18 @@ that rests on one of them:
 > delivery shipped and nothing in production ever calls. When a candidate is
 > genuinely one of the exclusions, cite the exclusion and drop it.
 
-### Final re-open-and-drop pass (mandatory)
+### Recording the outcome
 
-1. Walk your Detailed Findings once more, applying the bar and the exclusion
-   list above. Remove every finding that fails.
-2. Count what you kept (`k`) and what you dropped (`d`).
-3. Record the outcome in the report's **Executive Summary** as a single line:
+Record what you kept (`k`) and dropped (`d`) in the report's **Executive
+Summary** as a single line:
 
-   ```text
-   Self-cross-check: kept <k> / dropped <d>.
-   ```
-
-   When `d > 0`, name the dropped findings (title + the bar/exclusion reason)
-   in one short list under that line, so the filtering is auditable and never
-   silent.
+```text
+Self-cross-check: kept <k> / dropped <d>.
+```
 
-A lens that keeps every finding still records `dropped 0` — the line's absence
-is itself a defect (it means the pass did not run).
+When `d > 0`, name the dropped findings (title + the bar/exclusion reason) in
+one short list under that line, so the filtering is auditable and never
+silent. A lens that keeps every finding still records `dropped 0`.
 
 ## Severity tally (mandatory, machine-readable) {#severity-tally}
 
@@ -261,55 +254,35 @@ available; every path emits the **identical** report contract (the finding-block
 skeleton above), so downstream consumers (`audit-to-stories`) are agnostic to
 which path produced it.
 
-1. **Subagent dispatch (first-class).** Dispatch the lens as a single
+1. **One auditor per lens (the default).** Dispatch the lens as exactly one
    `subagent_type: auditor` call — the standalone boot context in
    [`../../agents/auditor.md`](../../agents/auditor.md) carries the read-only
    MUSTs, the finding-block skeleton, the severity scale, and the
    self-cross-check bar, so the child needs only the lens's own dimensions to
    run. The subagent returns the **report path plus the Executive Summary**
    (including the self-cross-check line); the parent never needs the full
-   findings inline. This is the default: the auditor boots without the full
-   project closure, so the spawn is cheap relative to running the lens inline
-   in the parent's context.
-
-   - **Per-dimension fan-out (heavyweight lenses).** `audit-architecture`,
-     `audit-performance`, and `audit-documentation` carry enough independent
-     dimensions to be worth fanning out: dispatch one `subagent_type: auditor`
-     call **per dimension** in a single turn via
-     [`parallel-tooling.md`](parallel-tooling.md) Rule 3, then **merge** the
+   findings inline. One auditor reads the repo once; per-dimension agents each
+   re-read it, so the single dispatch is the cheap path, not a compromise.
+
+   - **Per-dimension fan-out (operator request only).** Fan a lens out only
+     when the operator's invocation explicitly asks for it. Then dispatch one
+     `subagent_type: auditor` call **per dimension** in a single turn via
+     [`parallel-tooling.md`](parallel-tooling.md) Rule 3, and **merge** the
      per-dimension findings under this file's self-cross-check (the merge is
-     where cross-dimension duplicates and false positives are dropped). Respect
-     the nesting-depth budget and the concurrency cap that Rule 3 documents.
+     where cross-dimension duplicates and false positives are dropped). Never
+     fan out on your own judgment of a lens's size.
+   - **No nested fan-out.** An auditor never dispatches sub-agents of its own.
+     The fan-out, when requested, happens once, at the caller.
 
 2. **Sequential inline execution (documented fallback).** When subagent
    dispatch is unavailable, run the lens's steps turn-by-turn in the current
    context exactly as written, ending with the self-cross-check. This changes
    nothing about the report contract.
 
-> **Orchestrated dynamic-workflow path (optimization note).** Six lenses ship a
-> saved project workflow at `.claude/workflows/audit-<lens>.workflow.js` that,
-> **when Claude Code dynamic workflows are available** (runtime is Claude Code,
-> `disableWorkflows` unset, version `>= 2.1.154`), fans the dimensions out as
-> parallel read-only subagents and runs an independent adversarial cross-check
-> stage before synthesising the report. It derives its per-dimension prompts
-> from the *lens* markdown at run time — the lens stays the single source of
-> truth. This is a performance optimization over path 1, **not** a separate
-> contract, and it is not covered by the No-Shim / hard-cutover rule in
-> [`../../rules/git-conventions.md`](../../rules/git-conventions.md) because
-> there is one report contract and only the execution strategy varies — the
-> same capability-degradation pattern the protocol endorses for live-docs
-> fallback. **The host owns the choice.** Mandrel ships no in-repo strategy
-> selector and no force-override env var: Claude Code launches the saved
-> workflow when it can, and you get path 1 or 2 above when it cannot.
-> Suppress the orchestrated path with `CLAUDE_CODE_DISABLE_WORKFLOWS=1`
-> or `disableWorkflows: true` in `.claude/settings.json`. On the orchestrated
-> path the analysis subagents are granted only read/search tools (`Read`,
-> `Grep`, `Glob`) — the single write is the final report artifact.
-
 ## Parallel tooling {#parallel-tooling}
 
 When a lens batches independent reads/greps, runs a long shell (a scanner, a
-profiler, a suite time), or fans out per-dimension, apply
-[`parallel-tooling.md`](parallel-tooling.md): batch independent reads in one
-turn (Rule 1), run long shells via `run_in_background` + `Monitor` (Rule 2),
-and dispatch N independent units as N `Agent` calls in one turn (Rule 3).
+profiler, a suite time), apply [`parallel-tooling.md`](parallel-tooling.md):
+batch independent reads in one turn (Rule 1) and run long shells via
+`run_in_background` (Rule 2). Rule 3 applies only to the caller of
+an operator-requested per-dimension fan-out — never inside an auditor.

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

@@ -74,8 +74,8 @@ How each tier changes the review protocol:
   adversarial pass over the diff hunting for integration regressions and
   security-relevant edges before findings are finalized.
 
-The LLM-backed review providers (codex, security-review, ultrareview) render
-the resolved `depth` into the prompt/instructions they emit so the underlying
+The LLM-backed review providers (code-review, codex, security-review,
+ultrareview) render the resolved `depth` into the prompt/instructions they emit so the underlying
 model actually changes thoroughness. The native provider deliberately ignores
 `depth` — its mechanical lint + maintainability sweep already scales with diff
 size, and there is no "review harder" knob a deterministic scorer can turn (its
@@ -110,44 +110,21 @@ The pipeline will:
 - Run a focused lint check on the change set.
 - Post a structured summary report to the `[TICKET_ID]` issue.
 
-### Step 1a — Story-scope local-lens pass (`scope: story` only)
-
-When `scope === 'story'`, the shared review spine
-[`runStoryReviewCore`](../../scripts/lib/orchestration/story-close/phases/review-core.js)
-runs a **shift-left local-lens pass** in the same close subprocess, *before*
-returning the review envelope. It:
-
-1. Enumerates the actual Story diff (`baseRef...headRef` via
-   `git diff --name-only`).
-2. Selects the **local-tier** lenses that own a concern decidable from a single
-   Story's diff — `resolveLensTier(lens) === 'local'` **plus** the pure
-   `matchesAnyFilePattern` matcher against the diff (the audit-suite SDK's
-   [`selectLocalLenses`](../../scripts/lib/audit-suite/selector.js)). This is
-   deliberately **not** `selectAudits`: `selectAudits` unions in keyword and
-   gate matches and has no per-tier gate, so it would widen the roster past the
-   footprint-matched local set this tier owns.
-3. Materializes the matched roster at **`light`** depth
-   (`STORY_SCOPE_LENS_DEPTH`) via `runAuditSuite`, surfacing the outcome on the
-   review envelope's `localLensReview` field.
-
-A diff that matches no local lens adds **no** lens work (the roster is empty and
-`runAuditSuite` is never invoked). The pass is advisory and best-effort: a git
-or materialization failure degrades to a skipped envelope and never blocks the
-close.
-
-The live close entry point —
-[`runStoryScopeReview`](../../scripts/lib/orchestration/single-story-close/phases/code-review.js)
-— reaches this pass through the shared `runStoryReviewCore` spine. Because
-the pass lives inside the close subprocess (invoked after the delivering
-child exits), it honors the maker-blind invariant above: a maker never runs
-its own local-lens review.
+### Story scope runs no lens pass
+
+Close runs **no** audit-lens pass of its own (Story #5416 retired it: it
+materialized prompt files no workflow read, then armed auto-merge without
+waiting). The Story-scope review is this pipeline plus CI. Local-tier lens
+concerns are covered shift-left by the write-time authoring checklists
+threaded into the Story prompt; the on-demand `/audit-*` workflows remain the
+way to run a full lens over a change.
 
 ## Step 2 — Review Pillars
 
 For each changed file, execute a strict review against four pillars. The
 second pillar (**Integration Review**) deliberately defers the security /
 performance / quality / coverage sweeps to the change-set-scoped lenses —
-those ran shift-left in the Story-scope local-lens pass (Step 1a).
+those are covered shift-left by the write-time lens checklists.
 Re-walking those sweeps a second time in this pillar is duplication, not
 defense-in-depth.
 
@@ -173,9 +150,9 @@ Does the implementation match the Story's acceptance criteria and folded Spec?
 
 The diff under review is `baseRef..headRef`
 (`main..story-<storyId>`, or the configured base branch to the Story
-branch). The Story-scope local-lens pass (Step 1a) has already covered the
-local-tier concerns. Lens findings and pillar findings share the single
-`verification-results` comment this pass posts. The
+branch). The write-time lens checklists have already covered the local-tier
+concerns. Pillar findings land in the single `verification-results` comment
+this pass posts. The
 integration view here focuses on cross-cutting ripple within the Story and
 contract drift against the base branch. Look for:
 
@@ -260,7 +237,7 @@ prior baseline before merging.
 
 Findings are **persisted as a `verification-results` structured comment on
 the `[TICKET_ID]` issue** by `runCodeReview` (the unified findings contract —
-this single comment carries the Story-scope lens findings). The target
+this single comment carries the Story-scope review findings). The target
 ticket is the Story. The comment
 is idempotent — re-runs replace the prior one — and its body includes
 severity-tier counts plus the full findings list so downstream workflows

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

@@ -68,8 +68,8 @@ same derived level, so the two cannot disagree. A sensitive footprint
 therefore buys a **deep review**, not a fresh acceptance critic.
 
 > **The ceremony rule, stated once.** The **profile alone** names the verdict
-> owner (Story #5343, narrowed to that one input by #5366): `minimal` /
-> `standard` → `inline`, `strict` → `fresh`. Nothing else moves it — not the
+> owner: `minimal` / `standard` → `inline`, `strict` → `fresh`. Nothing else
+> moves it — not the
 > derived change level, not the footprint's sensitivity, and **not the
 > dispatch mode**: an `inline` Story under `strict` still spawns the fresh
 > maker-blind critic, one nesting level shallower than a dispatched one. The

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

@@ -78,7 +78,9 @@ but not a cycle.
 unblocked it:
 `node .agents/scripts/update-ticket-state.js --ticket <id> --state agent::ready`.
 Do not poll the label yourself while waiting — the HITL pause is the operator's
-turn, not a slow beat.
+turn, not a slow beat. Before resuming, the operator raises session effort one
+step, and raises effort before switching models
+([effort escalation](../../docs/execution-reference.md#session-effort-and-model)).
 
 Each beat re-probes live state: it re-resolves the graph, classifies **done**
 (`agent::done` or a closed issue — including foreign blockers that landed in
@@ -175,7 +177,7 @@ into batches of `cap` and dispatch each batch in its own turn.
 exposes agent dispatch, spawn each ready Story as its own
 `subagent_type: story-worker` sub-agent — it boots on the role-scoped
 [`story-worker`](../../agents/story-worker.md) context (its own system prompt, no
-`CLAUDE.md` @-closure) carrying the load-bearing delivery MUSTs standalone. The
+entry-doc @-closure) carrying the load-bearing delivery MUSTs standalone. The
 sub-agent executes [`deliver-story.md`](deliver-story.md) Steps 0–2.5
 (init → implement → acceptance self-eval → **push**) and stops there; **you**
 own Step 3, serialized — see `/mandrel-deliver` § Closing what the workers hand back.
@@ -291,7 +293,9 @@ confirm instead (`captureStoryFollowUps`).
   reopen the issue.
 - The parent lookup resolves the native parent edge in **one** call
   (`getParentIssue`), falling back to a `type::epic` scan for a child linked by
-  checklist alone. Children are the body checklist **union** the native
+  checklist alone. An authoritative "no parent" narrows that scan to Epics
+  whose body checklist names the Story (no per-Epic native read); only a
+  degraded lookup reads every scanned Epic's native children. Children are the body checklist **union** the native
   sub-issue edges — the same reader `/mandrel-deliver`'s expansion uses.
 - A checklist row citing an id that resolves to nothing is **dropped with a
   warning** when the native read succeeded; an unresolvable *native* edge

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

@@ -72,6 +72,9 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
 1. Read the Story body; its acceptance criteria are the contract. Docs are
    digest-first; read a caller-provided `checklistPath` first, and walk any
    `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
+   After a context summary, re-derive progress from `git log` on
+   `story-<id>` against the `## Slicing` rows (each checkpoint is a commit
+   boundary) before continuing.
 2. Implement and commit on the Story branch, iterating with quick advisory
    gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3,
    and the **one** full-suite run at Step 2.5.
@@ -111,9 +114,14 @@ Do not open the PR or compose a terminal envelope.
 serialized against sibling Stories:
 
 ```bash
-node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo>
+node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo> \
+  [--worker-tokens <n>]
 ```
 
+When the host reported a total-token figure for the story-worker's Agent
+dispatch, pass it as `--worker-tokens <n>` — close records it in its
+result's local `telemetry`; omit it when the host reports none.
+
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
 post-land tail in one process. Never background it, never delegate it to a
 child, and never end your turn while it is still running: "close is running"

package/.agents/workflows/helpers/parallel-tooling.md

@@ -29,15 +29,17 @@ the batch in parallel; serial calls cost N round-trips for no gain.
 - **Bounded fan-out:** keep the batch ≤ 10 calls per turn. Larger batches
   blow the context budget and obscure the failure surface if one call errors.
 
-## Rule 2 — `run_in_background` + `Monitor` for long shells
+## Rule 2 — `run_in_background` for long shells
 
-Shell commands that exceed roughly 30 seconds (test suites, installs,
-multi-file lints, `git fetch --all`, container builds) **must** use the
-`Bash` tool's `run_in_background: true` flag and stream events via the
-`Monitor` tool. A synchronous `Bash` call holds the assistant turn open for
-the full duration and blocks every other parallel opportunity.
+A shell command that can outrun the host's synchronous Bash ceiling, or that
+would idle the turn while independent work waits (test suites, installs,
+multi-file lints, `git fetch --all`, container builds), runs with the `Bash`
+tool's `run_in_background: true` flag; its completion notification is the
+signal to proceed. Attach `Monitor` only when you must act on output before
+the command exits.
 
-- **Tool primitives:** `Bash(run_in_background: true)` + `Monitor`.
+- **Tool primitives:** `Bash(run_in_background: true)`; `Monitor` only when
+  mid-run output matters.
 - **When:** `npm test`, `npm ci`, full-repo `eslint`/`biome` runs, long
   fetches, anything you would have prefixed with `nohup` in a terminal.
 - **Anti-pattern:** synchronous `Bash` with a 600 000 ms timeout used as a
@@ -90,17 +92,13 @@ the same shape as Rule 1 but at the sub-agent layer.
 ## When the rules conflict
 
 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 — and, within the supported nesting depth budget
-(verified depth 2, announced max depth 5), 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)).
+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. A sub-agent does **not** fan out again on its own
+initiative: every nesting level re-pays the always-loaded context (see
+[`instructions.md` § 4](../../instructions.md)), and the cost compounds with
+depth. The one exception is a dispatch the sub-agent's own workflow names
+explicitly — for example the maker-blind acceptance critic a `strict`-profile
+Story worker spawns — which stays legal at that depth.
 
 ## Constraints
 

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

@@ -100,19 +100,20 @@ not re-deriving which assumptions were really the agent's to make.
 
 ## Gate #1 → the one advisory line
 
-Gate #1 stops for exactly two things — the sharpened plan intent and any HITL
-unknown — and everything else the envelope surfaced collapses to **one
-advisory line** beneath it. Nothing on that line stops the run,
-reroutes it, or is invoked by `/mandrel-plan`; each item names something the
-operator may prefer to do instead, and the run proceeds either way. Under
+Gate #1 stops only when there is at least one HITL unknown or
+`duplicates[]` is non-empty; otherwise the run announces the sharpened plan
+intent plus the advisory line and continues to authoring. Everything else the
+envelope surfaced collapses to **one advisory line** beneath the gate.
+Nothing on that line reroutes the run or is invoked by `/mandrel-plan`; each
+item names something the operator may prefer to do instead. Under
 `--yes` the line is recorded and planning continues — an unattended run has
 nobody to take an offer.
 
 The line names, in order, whichever of these the envelope carries:
 
 - **`duplicates[]`** — open Stories the seed resembles (never Epics). Name
-  the top one or two by id and title; a plan that duplicates open work is
-  still the operator's call.
+  the top one or two by id and title. A plan that duplicates open work is
+  still the operator's call, so a non-empty list also stops Gate #1.
 - **Open `intake` rows** (`priorFeedback`) — CI-gap intake filings written by
   [`file-ci-gap.js`](../../scripts/file-ci-gap.js) when a delivery reached an
   Option-2 verdict in [`ci-remediation.md`](../../rules/ci-remediation.md).
@@ -339,7 +340,7 @@ On `dispatch: true`, dispatch **one fresh-context, maker-blind sub-agent**.
 When `delivery.routing.roleScopedAgents` is enabled (the **default**), use
 `subagent_type: plan-critic` — it boots on the role-scoped
 [`plan-critic`](../../agents/plan-critic.md) context (its own system prompt,
-no `CLAUDE.md` @-closure) that carries the maker-blind invariant, the
+no entry-doc @-closure) that carries the maker-blind invariant, the
 `pre-mortem` charter, and the output shape standalone. When the kill-switch
 is off (`roleScopedAgents: false`) or the host cannot spawn at this depth,
 fall back to a generic sub-agent and hand it the same charter. Either way the

package/.agents/workflows/mandrel-deliver.md

@@ -76,7 +76,8 @@ to an attended run.
    it cannot read — a missing gate would co-dispatch against an unlanded
    blocker.
 
-2. **Confirm (N>1).** Present the order; wait unless `--yes`.
+2. **Announce (N>1).** Present the resolved order and proceed — do not wait
+   for confirmation; the operator can interject mid-run to change it.
 
 3. **Run the beat.** One command per beat, repeated until the envelope reports
    the run `done`:
@@ -143,7 +144,7 @@ resume what it names.
 
 **Reading the outcome.** Each close ends the Story in one schema-validated
 envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
-fields are digest § 5. `pending` is **not** a failure — run its `nextCommand`.
+fields are digest § 6. `pending` is **not** a failure — run its `nextCommand`.
 
 **Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
 required checks), per digest § 2; dependent Stories land sequentially. The

package/.agents/workflows/mandrel-plan.md

@@ -71,13 +71,17 @@ assumed; a **HITL** unknown goes to Gate #1. Under `--yes` do not ask free-form
 operator questions — AFK unknowns are still researched; only HITL unknowns land
 in Key Assumptions, each a decision-made-by-default.
 
-**Gate #1** — STOP for exactly two things: confirm the sharpened plan intent,
-and settle any HITL unknown the operator owns. Everything else the envelope
-surfaced — `duplicates[]`, open `intake` rows, a truthy
-`memoryPoolAdvisory.recommend`, a truthy `complexitySignals.uiSurface` naming
-[`/prototype`](prototype.md) (never invoke it here) — collapses to
-**one advisory line** under the gate; none of it stops the run or reroutes
-it ([ref](helpers/plan-reference.md)). Under `--yes`, auto-proceed.
+**Gate #1** — STOP only when a HITL unknown the operator owns exists or
+`duplicates[]` is non-empty (planning a duplicate of open work stays the
+operator's call): confirm the sharpened plan intent and settle it. Otherwise
+announce the sharpened intent and the advisory line, and continue to
+authoring. The advisory line names what the envelope surfaced — any
+`duplicates[]` (the stop above), open `intake` rows, a truthy
+`memoryPoolAdvisory.recommend`, a truthy `complexitySignals.uiSurface`
+naming [`/prototype`](prototype.md) (never invoke it here) — as
+**one advisory line** under the gate; the line itself never reroutes the run
+([ref](helpers/plan-reference.md)).
+Under `--yes`, auto-proceed.
 
 ### 2. Author
 

package/.agents/workflows/mandrel-update.md

@@ -200,13 +200,15 @@ non-optional.
 
 ## Step 4 — Review the surfaced changelog and update consumer-side guidance
 
-Framework upgrades change behaviour the consumer's own `AGENTS.md` /
-`CLAUDE.md` and runbooks often encode. Step 1 already printed the changelog
+Framework upgrades change behaviour the consumer's own `AGENTS.md` and
+runbooks often encode. Step 1 already printed the changelog
 for the applied range — that output is your source of truth (re-read the
 transcript or the GitHub Releases page if it scrolled past). For each entry
 between the installed and target versions:
 
-1. **Consumer `AGENTS.md` / `CLAUDE.md`.** Update instructions so a fresh
+1. **Consumer `AGENTS.md`.** It is the entry doc — `mandrel update` folds a
+   root `CLAUDE.md` into it and deletes `CLAUDE.md`, so reconcile the folded
+   content here. Update instructions so a fresh
    agent reading them in isolation produces output that passes the
    framework's new validators; remove or rewrite instructions that
    contradict a tightened rule.