mandrel 1.57.0

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

@@ -0,0 +1,199 @@
+---
+description: >-
+  Phase 8 of sprint planning — decompose an Epic's PRD and Tech Spec into a
+  Feature/Story hierarchy, persist the backlog, and flip the Epic to
+  `agent::ready`. Host-LLM authored; no external API calls.
+---
+
+# Sprint Plan — Decompose Phase (helper)
+
+> **Helper module.** Not a slash command. Invoked by `/epic-plan` (Phase 8).
+> To run the decompose phase interactively, use `/epic-plan [Epic_ID]` — it
+> delegates here after the spec phase.
+
+## Role
+
+Director / Architect
+
+## Context
+
+This helper is the **decompose phase** of the split planning pipeline. It
+reads the PRD and Tech Spec previously produced by the spec phase helper
+([`epic-plan-spec.md`](epic-plan-spec.md)), generates the Feature /
+Story ticket hierarchy, persists it to GitHub, and flips the Epic to
+`agent::ready` (parking) so a human can run `/epic-deliver` when
+execution should begin.
+
+The ticket array is authored **directly by you, the host LLM**.
+`epic-plan-decompose.js` is a deterministic wrapper that (a) emits the
+authoring context you need and (b) validates, persists, and transitions the
+Epic lifecycle state.
+
+The ticket array contains `type::feature` and `type::story` tickets
+only — no `type::task` children. Acceptance criteria and verification
+steps are inlined on each Story body via the `acceptance[]` and
+`verify[]` fields. The decomposer system prompt lives in the
+[`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
+skill.
+
+## Constraint
+
+- **Do not** run this skill until the spec phase is complete. The Epic must
+  have linked `context::prd` and `context::tech-spec` issues; the script will
+  refuse to proceed otherwise.
+- **Do not** reassign Story parents across Features after the
+  decomposition writes — the `epic-plan-state` checkpoint records the
+  structure as committed. Use `--force` to rebuild from scratch.
+- **Every** temp file must include the Epic ID in its name. Multiple Epics
+  may be decomposed concurrently; bare names will collide.
+- **Do not** flip the Epic past `agent::ready` from this helper. Execution
+  begins when an operator runs `/epic-deliver [Epic_ID]`.
+
+## Prerequisites
+
+1. **Epic is on `agent::review-spec`** — i.e. the spec phase has already run
+   and the PRD / Tech Spec exist.
+2. **API keys** — `GITHUB_TOKEN` set in `.env`.
+
+## Step 1 — Gather decomposition context
+
+```bash
+node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] --emit-context \
+  > temp/epic-[Epic_ID]/decomposer-context.json
+```
+
+The emitted JSON contains the PRD body, Tech Spec body, risk heuristics, the
+decomposer system prompt, and the `maxTickets` **reviewability budget**
+(Story #2798 — not a hard cap; over-budget plans require an explicit
+`--allow-over-budget` override at persist time).
+
+## Step 2 — Author the ticket array
+
+Read `temp/epic-[Epic_ID]/decomposer-context.json`. Produce a JSON array of
+Feature / Story objects that conforms to the schema in the system prompt
+and write it to `temp/epic-[Epic_ID]/tickets.json`.
+
+When the Tech Spec carries a `## Delivery Slicing` section, author toward the
+Architect's proposed shippable-Story clusters rather than mapping PRD
+capabilities 1:1; degrade gracefully (current behaviour) when it is absent.
+
+## Step 2.5 — Phase 8.3: Holistic Consolidation (HITL diff gate)
+
+The decompose phase runs in the sequence **emit-context → author →
+consolidate → validate+persist**. Step 2 is the *author* half; this step is
+the *consolidate* half, a separate critic pass run **before** the
+deterministic validator and **before** the GitHub write.
+
+Activate the
+[`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
+skill with `[Epic_ID]` as input. It reads the draft
+`temp/epic-[Epic_ID]/tickets.json` plus the PRD / Tech Spec from
+`decomposer-context.json`, reconciles the draft against the Tech Spec
+`## Delivery Slicing` target (degrading gracefully when absent), and emits:
+
+- a **consolidated** `temp/epic-[Epic_ID]/tickets.json` (overwriting the draft),
+- a human-readable `temp/epic-[Epic_ID]/consolidation-report.md` (rationale +
+  before/after diff).
+
+The pass is constrained to scope-preserving operations only — **merge Stories,
+collapse single-Story Features into siblings, re-parent, rewire `depends_on`**.
+It MUST NOT add scope or invent tickets. It resolves single-Story Features by
+**collapsing** them (rec #2), never by splitting a lone Story into two; the
+`assertNoSingleStoryFeature` validator stays as the post-consolidation
+backstop.
+
+> **HITL diff gate.** Show the operator
+> `temp/epic-[Epic_ID]/consolidation-report.md` (the before/after diff +
+> rationale) **before** running the persist call in Step 3. Consolidation is
+> never auto-applied without operator review — the operator approves the
+> consolidated plan (or rejects it and the draft is persisted instead). Only
+> after approval proceed to Step 3.
+
+This sub-step does **not** renumber the top-level lifecycle phases (9–12); it
+is a sub-step of Phase 8.
+
+## Step 3 — Persist and transition
+
+```bash
+# Normal decomposition
+node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
+  --tickets temp/epic-[Epic_ID]/tickets.json
+
+# Re-decompose (closes existing child Features/Stories first)
+node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
+  --tickets temp/epic-[Epic_ID]/tickets.json --force
+
+# Persist an over-budget plan (Story #2798 — only after the operator
+# has confirmed the over_budget_rationale on the Epic)
+node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
+  --tickets temp/epic-[Epic_ID]/tickets.json --allow-over-budget
+```
+
+On success the script:
+
+- Creates the Feature / Story hierarchy under the Epic.
+- Updates the `epic-plan-state` structured comment with the ticket count
+  and decompose timestamp.
+- Flips the Epic to `agent::ready`.
+
+## Step 4 — Cross-validation
+
+Delegate the structural invariants (hierarchy completeness, dependency DAG
+acyclicity, missing complexity labels) to `epic-plan-healthcheck.js`. It is
+the single source of truth for post-decompose validation — the Phase 10 run
+inside `/epic-plan` calls the same script, so local and remote flows agree.
+
+```bash
+node .agents/scripts/epic-plan-healthcheck.js --epic [Epic_ID] --paranoid
+```
+
+`--paranoid` is the flag that runs the richer hierarchy and dependency
+checks; pair it with `--epic [Epic_ID]` so the script can fetch the
+ticket tree. `--dry-run` exists as well but only emits the planned
+checks without performing any I/O — it is not a substitute for
+`--paranoid` when you need the hierarchy invariants validated.
+
+The script exits 0 regardless of findings (non-blocking), but lists any
+`ERR`-level findings that must be addressed before execution:
+
+- Missing `type::feature` / `type::story` tickets.
+- Stories without `complexity::` labels.
+- Dependency cycles across Stories.
+
+For the semantic checks the healthcheck cannot automate, do these by eye:
+
+- **Scope-overlap check**: Stories whose scope is "docs / runbook / README"
+  downstream of a "config + runbook" Story in the same Epic should carry a
+  scope-verification note pointing at
+  `git diff main -- <path>` against the upstream Story branch.
+- **Risk flagging**: Confirm `risk::high` Stories match the heuristics in
+  the decomposer context.
+
+Fix any gaps by creating additional issues or updating existing ones.
+
+## Step 5 — Cleanup
+
+The wrapper script deletes the phase-scoped temp files automatically when
+Step 3 succeeds — no operator action required. The cleanup contract lives in
+[`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js), which
+is the single source of truth for which temp paths this phase owns.
+
+## Handoff
+
+- Surface the backlog summary and the Wave 0 candidates to the operator:
+
+  > "Decomposition complete. Epic #[ID] is on `agent::ready` with NN ticket(s)
+  > across MM Stories. Run `/epic-deliver [Epic_ID]` to begin execution."
+
+## Troubleshooting
+
+- "Epic #N is missing a linked PRD or Tech Spec" — run `/epic-plan [Epic_ID]`
+  first (it will run the spec phase if the PRD / Tech Spec are missing).
+- Validator rejects the tickets file — the most common causes are a
+  Story whose `parent_slug` does not point at a Feature, a missing
+  `acceptance[]` / `verify[]` array on a Story body, or a Story
+  `depends_on` slug that does not resolve to another Story in the same
+  Epic.
+- If `--force` is required but the script refuses, confirm the Epic has the
+  linked artifacts first — `--force` only re-decomposes; it does not bypass
+  the spec-phase prerequisite.

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

@@ -0,0 +1,184 @@
+---
+description: >-
+  Phase 7 of sprint planning — generate the PRD and Tech Spec for an Epic,
+  persist them as linked GitHub issues, and flip the Epic to
+  `agent::review-spec`. Host-LLM authored; no external API calls.
+---
+
+# Sprint Plan — Spec Phase (helper)
+
+> **Helper module.** Not a slash command. Invoked by `/epic-plan` (Phase 7).
+> To run the spec phase interactively, use `/epic-plan [Epic_ID]` — it
+> delegates here.
+
+## Role
+
+Director / Architect
+
+## Context
+
+This helper is the **spec phase** of the split planning pipeline. It produces
+**three** planning artifacts for an Epic — a Product Requirements Document, a
+Technical Specification, and an Acceptance Spec — persists them as
+`context::prd`, `context::tech-spec`, and `context::acceptance-spec` issues
+under the Epic, and flips the Epic to `agent::review-spec` (parking) so a human
+reviewer can read the artifacts on GitHub before decomposition.
+
+> **Single prose home.** The canonical, full-detail spec-phase contract
+> (idempotent context tickets, the three-ticket rationale, the
+> `acceptance::n-a` waiver, the Epic-lease preflight) lives in
+> [`epic-plan.md` § Phase 7](../epic-plan.md). This helper carries only the
+> operational step list; when the two disagree, `epic-plan.md` wins.
+
+The PRD and Tech Spec are authored **directly by you, the host LLM**.
+`epic-plan-spec.js` is a deterministic wrapper that (a) emits the authoring
+context you need and (b) persists the artifacts and transitions the Epic
+lifecycle state.
+
+The complementary Phase 8 helper is
+[`epic-plan-decompose.md`](epic-plan-decompose.md). The `/epic-plan`
+wrapper chains both helpers with a confirmation gate in between.
+
+## Constraint
+
+- **Do not** create or modify tickets outside the `context::prd` /
+  `context::tech-spec` / `context::acceptance-spec` contract —
+  decomposition belongs to
+  [`epic-plan-decompose.md`](epic-plan-decompose.md).
+- **Do not** flip the Epic to `agent::ready` from this skill. The terminal
+  label for the spec phase is `agent::review-spec`.
+- **Every** temp file must include the Epic ID in its name. Multiple Epics may
+  be planned concurrently; bare names like `temp/prd.md` will collide.
+- **Stop and hand back to the operator** after Step 4 when
+  `planningRisk.requiresReview` is true or the operator passed
+  `--force-review` — do not chain into decomposition. Low-risk Epics
+  auto-proceed to Phase 8 after the persist stdout confirms
+  `reviewRouting.decision === 'auto-proceed'`.
+
+## Prerequisites
+
+1. **GitHub Epic** — an open issue with the `type::epic` label. The Epic's
+   body should contain enough narrative context to seed the PRD.
+2. **API keys** — `GITHUB_TOKEN` set in `.env`.
+
+## Step 1 — Gather authoring context
+
+Run the spec-phase CLI in context-emission mode to collect the Epic body, the
+scraped project docs, and the recommended system prompts.
+
+```bash
+node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] --emit-context \
+  > temp/epic-[Epic_ID]/planner-context.json
+```
+
+## Step 2 — Author the PRD
+
+Read `temp/epic-[Epic_ID]/planner-context.json`. Using `systemPrompts.prd`
+combined with the Epic title/body, write the PRD markdown to
+`temp/epic-[Epic_ID]/prd.md`. Use the four-section structure (Context & Goals,
+User Stories, Acceptance Criteria, Out of Scope) and start the document with
+`## Overview` (no `<h1>`).
+
+## Step 3 — Author the Tech Spec
+
+Using `systemPrompts.techSpec`, the PRD you just wrote, and `docsContext`,
+write the Tech Spec to `temp/epic-[Epic_ID]/techspec.md`. Start with
+`## Technical Overview` (no `<h1>`).
+
+## Step 3.5 — Author the risk verdict
+
+Judge the change described by the PRD and Tech Spec you just wrote and
+write `temp/epic-[Epic_ID]/risk-verdict.json` conforming to
+[`risk-verdict.schema.json`](../../schemas/risk-verdict.schema.json):
+`{ axes: [{ axis, level, rationale }], summary }`. The authoritative
+authoring rules (axis vocabulary, judgment-not-keywords, derivation
+preview) live in the
+[`epic-plan-spec-author` Skill, Step 4](../../skills/core/epic-plan-spec-author/SKILL.md).
+
+## Step 3.6 — Author the Acceptance Spec
+
+Using `systemPrompts.acceptanceSpec`, the PRD, and the Tech Spec, write the
+Acceptance Spec to `temp/epic-[Epic_ID]/acceptance-spec.md`. It captures the
+stable-ID acceptance criteria table
+(`| AC ID | Outcome | Feature File | Scenario | Disposition |`) that drives
+close-time reconciliation in `/epic-deliver` Phase 6.
+
+**Skip this step only** when the Epic carries the `acceptance::n-a` waiver
+label (refactor-only or docs-only Epics); in that case omit `--acceptance-spec`
+from Step 4.
+
+## Step 4 — Persist and transition
+
+```bash
+# Normal flow (three context tickets)
+node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
+  --prd temp/epic-[Epic_ID]/prd.md \
+  --techspec temp/epic-[Epic_ID]/techspec.md \
+  --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json \
+  --acceptance-spec temp/epic-[Epic_ID]/acceptance-spec.md
+
+# Re-plan (--force overwrites the three context tickets in place)
+node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
+  --prd temp/epic-[Epic_ID]/prd.md \
+  --techspec temp/epic-[Epic_ID]/techspec.md \
+  --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json \
+  --acceptance-spec temp/epic-[Epic_ID]/acceptance-spec.md --force
+
+# Waived (acceptance::n-a label on Epic — no Acceptance Spec authored)
+node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
+  --prd temp/epic-[Epic_ID]/prd.md \
+  --techspec temp/epic-[Epic_ID]/techspec.md \
+  --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json
+```
+
+On success the script:
+
+- Validates the risk verdict against `risk-verdict.schema.json` (a
+  malformed verdict fails closed before any GitHub mutation) and derives
+  the `planningRisk` envelope from it.
+- Creates `[PRD]`, `[Tech Spec]`, and `[Acceptance Spec]` child issues
+  (`context::prd` / `context::tech-spec` / `context::acceptance-spec`
+  labels). The Acceptance Spec is skipped when `--acceptance-spec` is
+  omitted under the `acceptance::n-a` waiver.
+- Appends a `## Planning Artifacts` section to the Epic body.
+- Upserts the `risk-verdict` structured comment recording the verdict and
+  the derived envelope.
+- Upserts the `epic-plan-state` structured comment with the current phase,
+  PRD / Tech Spec / Acceptance Spec IDs, the `riskVerdict` field, and
+  timestamps.
+- Flips the Epic to `agent::review-spec`.
+
+## Step 5 — Cleanup
+
+The wrapper script deletes the phase-scoped temp files automatically when
+Step 4 succeeds — no operator action required. The cleanup contract lives in
+[`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js), which
+is the single source of truth for which temp paths this phase owns. If you
+need to inspect the temp artefacts after the fact, re-run
+`epic-plan-spec.js --emit-context` to regenerate the planner context.
+
+## Handoff
+
+Branch on the shared planning risk decision surfaced in the persist stdout
+JSON (`planningRisk`, `reviewRouting`):
+
+- **High risk or `--force-review` — STOP.** Surface the PRD and Tech Spec
+  URLs to the operator:
+
+  > "Spec phase complete for Epic #[ID]. Review PRD (#XX) and Tech Spec (#YY)
+  > on GitHub. When you're ready, re-run `/epic-plan [Epic_ID]` — the wrapper
+  > will pick up where it left off and run the decompose phase."
+
+- **Low risk — auto-proceed.** Relay `reviewRouting.operatorMessage` and
+  continue directly to Phase 8 decomposition without waiting for verbal
+  approval in this session.
+
+## Troubleshooting
+
+- If `--emit-context` fails with "Epic not found", confirm the ID matches the
+  GitHub issue number and the token has `issues:read`.
+- If the persist call fails after creating the PRD but before the Tech Spec,
+  re-run with `--force` (the script reuses the existing PRD when appropriate).
+- If the Epic does not flip to `agent::review-spec` after the script claims
+  success, the label write likely races with a concurrent mutation — re-run the
+  persist step; it's idempotent against the existing PRD/Tech Spec.

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

@@ -0,0 +1,125 @@
+---
+description: QA Epic-testing workflow — ingest the agent-driven QA harness sweep as Epic evidence
+---
+
+# Epic Testing (helper)
+
+> **Helper module.** Not a slash command. Invoked from the QA gate during
+> `/epic-deliver` or directly by an operator when the Epic-testing ticket
+> needs refreshed evidence. For ad-hoc acceptance runs use `/qa-run-harness` —
+> this helper owns the Epic-evidence ticket lifecycle on top of it.
+
+Gather and attach the acceptance-suite evidence that gates Epic closure. The
+evidence artifact is the **agent-driven QA harness sweep report** produced by
+`/qa-run-harness` (scenario pass/fail/blocked totals plus structured
+findings), **not** a hand-ticked markdown checklist.
+
+> **When to run**: During the QA phase of an Epic, after all Story merges
+> have landed on the Epic branch and before `/epic-deliver`. Also run ad-hoc
+> when a regression is suspected mid-Epic.
+>
+> **Persona**: `qa-engineer` · **Skills**:
+> `stack/qa/gherkin-authoring`, `stack/qa/playwright-bdd`
+
+## Step 0 — Resolve Context
+
+1. Identify the Epic-testing ticket for the current Epic (the QA evidence
+   ticket produced by Epic planning).
+2. Confirm the Epic branch is green: all child Story branches merged, CI
+   passing.
+3. Decide the tag slice to run:
+   - Epic-wide regression gate → `@smoke and @risk-high` (or the project's
+     equivalent release gate expression).
+   - Targeted domain pass → `@domain-<area>`.
+   - Full acceptance sweep → omit the tag expression.
+
+   The canonical taxonomy lives in `.agents/rules/gherkin-standards.md`. Do
+   not invent new tags here.
+
+## Step 1 — Execute the QA Harness Sweep
+
+Invoke `/qa-run-harness` with the chosen selector:
+
+```text
+/qa-run-harness "tag:@smoke and @risk-high"
+```
+
+The `/qa-run-harness` workflow (`.agents/workflows/qa-run-harness.md`) owns the
+execution mechanics — `qa` contract resolution, scenario selection, browser
+navigation, and finding capture. This workflow consumes its output.
+
+If the consuming project runs the suite through its own CI invocation rather
+than the slash command, treat the CI run as equivalent provided it produces
+the same scenario totals and structured findings.
+
+## Step 2 — Collect the Evidence Artifact
+
+The evidence package for the Epic-testing ticket is:
+
+- **Sweep summary** — selector applied, scenario totals (passed / failed /
+  blocked), and the commit SHA the sweep ran against. Required.
+- **Structured findings** — the `F#` findings bundle the harness emits
+  (console / network / visual problems by surface). Required.
+- **Accessibility snapshots / traces** — for every failed or blocked scenario.
+  Required on failure.
+- **Drafted follow-up bundle** — the proposed follow-up tickets awaiting
+  operator sign-off, when the sweep surfaced findings.
+
+Store the artifacts where your project's evidence convention dictates (CI
+artifact store, object storage, or attached to the ticket directly). Link —
+do not paste — large artifacts.
+
+## Step 3 — Attach and Transition
+
+1. Comment on the Epic-testing ticket with:
+   - The sweep summary from Step 2.
+   - Links (or attachments) to the structured findings, accessibility
+     snapshots, and any traces.
+   - The commit SHA the sweep executed against.
+2. If every scenario passed (no `failed`, no `blocked`), transition the
+   Epic-testing ticket to `agent::done`.
+3. If any scenario failed or is blocked, leave the ticket in its current
+   state and open a follow-up ticket per failure with:
+   - Scenario name and `.feature` file path.
+   - One-line symptom.
+   - Link to the failing scenario's snapshot or trace.
+
+Do not close the Epic-testing ticket on a failed run. `/epic-deliver`
+depends on green evidence.
+
+## Deprecated — Markdown Checklist Flow
+
+Earlier revisions of this workflow asked the QA reviewer to tick items in a
+hand-maintained markdown checklist (`epic-<id>/test-plan.md`) and attach
+that file as evidence. **That flow is deprecated.** Reasons:
+
+- Hand-ticked checklists drift from the code and cannot be re-executed.
+- They do not capture scenario-level pass/fail state, traces, or the SHA the
+  run targeted.
+- They are not machine-readable, so downstream aggregation and trend
+  reporting are impossible.
+
+The QA harness sweep replaces the checklist as the single evidence artifact.
+Projects still maintaining a checklist should migrate by authoring the
+equivalent scenarios in Gherkin (see the `stack/qa/gherkin-authoring` skill)
+and deleting the checklist in the same change.
+
+## Constraints
+
+- **Never** substitute a hand-authored checklist or prose summary for the
+  harness sweep. The evidence must be the output of an actual run.
+- **Never** close the Epic-testing ticket while any scenario is `failed` or
+  `blocked`.
+- **Always** record the commit SHA the sweep ran against, so the evidence is
+  pinned to a verifiable tree state.
+- **Always** link a snapshot or trace for failed scenarios; a failure without
+  evidence is not actionable.
+
+## Cross-References
+
+- Execution mechanics: `.agents/workflows/qa-run-harness.md`.
+- Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
+- Runner / fixture / trace conventions:
+  `.agents/skills/stack/qa/playwright-bdd/SKILL.md`.
+- Tier responsibilities (unit / contract / acceptance):
+  `.agents/rules/testing-standards.md`.

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

@@ -0,0 +1,88 @@
+# Parallel Tooling — Inline Helper
+
+Procedural module read **inline** by workflows that perform context-gathering,
+long-running shell work, or independent unit fan-out. This is **not** a slash
+command — it is not projected into the flat `.claude/commands/` tree, so there
+is no `/parallel-tooling`. Callers reference this file at the top of their first
+scan / read instruction so the parallelism conventions land before the work
+does.
+
+The three rules below are the canonical dispatch shape for this codebase.
+Apply them in order: a workflow that observes Rule 1 but ignores Rule 3
+serialises its fan-out unnecessarily; a workflow that reaches for Rule 3
+before exhausting Rule 1 spawns sub-agents to do work the host could have
+batched in a single turn.
+
+## Rule 1 — Batch independent reads in a single turn
+
+When the next N tool calls do **not** depend on each other's results, issue
+them in one assistant turn rather than serially. The host runtime executes
+the batch in parallel; serial calls cost N round-trips for no gain.
+
+- **Tool primitives:** `Read`, `Grep`, `Glob`, MCP `list_*` / `get_*` calls.
+- **When:** reading the PRD, Tech Spec, and Story body up front; grepping
+  for multiple unrelated patterns; globbing several directory trees;
+  fetching independent GitHub tickets.
+- **Anti-pattern:** sequential `Read` → wait → `Read` → wait → `Grep` chains
+  when none of the later calls reference earlier output.
+- **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
+
+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.
+
+- **Tool primitives:** `Bash(run_in_background: true)` + `Monitor`.
+- **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
+  blocker — that pattern is reserved for scripts whose exit is the
+  signal-to-proceed (e.g., `story-init.js`'s per-tree install, which the
+  parent skill calls out explicitly).
+- **Don't poll with `sleep`:** `Monitor` returns on each stdout line. Loop
+  on `until <condition>; do sleep 2; done` only when no event stream is
+  available — never as a substitute for the event channel.
+
+## Rule 3 — N parallel `Agent` calls in one turn for N independent units
+
+When a workflow fans out across N independent units of work — N Stories in
+a wave, N audit dimensions, N decomposition slices — dispatch all N
+sub-agents in a **single assistant turn** by issuing N `Agent` tool calls
+together. The host executes the calls concurrently; one turn per unit is
+the same shape as Rule 1 but at the sub-agent layer.
+
+- **Tool primitives:** `Agent` (one call per independent unit, all in one
+  turn).
+- **When:** wave-level Story fan-out from `/epic-deliver`, per-dimension
+  audit dispatch, any "for each X in Xs run /Y X" loop where the Xs do not
+  share write paths.
+- **Anti-pattern:** serial `Agent` calls (`Agent` → wait → `Agent` → wait)
+  for units that have no dependency edge between them. The wave aggregator
+  is designed for the parallel shape — the serial shape is strictly slower
+  and offers no isolation benefit.
+- **Concurrency cap:** respect `delivery.deliverRunner.concurrencyCap` (or the
+  caller's wave-slot budget) — beyond that cap you starve other waves, not
+  speed up your own. When N exceeds the cap, slice into batches of `cap`
+  and dispatch each batch in its own turn.
+
+## 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. The host does not need to micromanage the child's
+shell strategy.
+
+## Constraints
+
+- **Never** chain serial calls when the host can batch them — the rules
+  above are about correctness of dispatch shape, not optimisation.
+- **Never** use `run_in_background` for short commands (< 5 s). The
+  notification overhead exceeds the wall-clock savings.
+- **Always** keep dependent calls sequential — Rule 1 is "batch
+  independent reads," not "batch everything."