mandrel 2.40.0 → 2.41.0

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

@@ -1,8 +1,7 @@
 ---
 description:
   Unified planning entry point. Interrogate → author → persist. Emits one
-  Story by default; splits into N>1 only under the default-single split
-  policy.
+  Story by default; splits into N>1 only under the default-single split policy.
 ---
 
 # /mandrel-plan
@@ -19,20 +18,20 @@ mode from what the operator typed, announce it, act**:
 | Invocation | Mode | Behavior |
 | --- | --- | --- |
 | `/mandrel-plan` | ask | Ask what to plan; nothing runs first. |
-| `/mandrel-plan add a --json flag to doctor` | seed | Ideation from prose: interrogate → author **one Story by default** → persist. |
+| `/mandrel-plan add a --json flag to doctor` | seed | Ideation from prose → **one Story by default** → persist. |
 | `/mandrel-plan temp/notes/idea.md` | seed-file | Same, from notes. An existing file is a path, not prose. |
 | `/mandrel-plan 4712[,4713…]` | tickets | Fetch issue(s), analyze into proper Stories (prefer N=1 rewrite). |
-| `/mandrel-plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**, not a re-interrogation. |
+| `/mandrel-plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**. |
 
 **Resolving a bare id.** Read live state rather than asking: `agent::done` can
-only be amended, an open unplanned issue only planned. **Announce the derivation** —
-"4712 is `agent::done` → amending". Ask **only** for an open Story already at
-`agent::ready`.
+only be amended, an open unplanned issue only planned. **Announce the
+derivation** — "4712 is `agent::done` → amending". Ask **only** for an open
+Story already at `agent::ready`.
 
 ## Saying what you want
 
 No flags to remember — state intent; the workflow fills in the CLI
-([reference](helpers/plan-reference.md)). Run scripts with `--help`.
+([ref](helpers/plan-reference.md)). Run scripts with `--help`.
 
 `--yes` is **runner-set, never operator-typed** — cron, `/loop`, and headless
 dispatch set it to mean *nobody is at the keyboard*, which auto-proceeds the
@@ -42,8 +41,7 @@ gates below (#1 and #2) and skips #3. Never offer it to an operator.
 
 Author **one Story** unless the pieces have **near-zero overlap** or sit across
 an **architectural seam**. Coupled work stays one Story — `## Slicing`
-checkpoints, not sibling tickets
-([detail](helpers/plan-reference.md)). **N=1 is lean.**
+checkpoints, not sibling tickets ([ref](helpers/plan-reference.md)).
 
 ## Procedure
 
@@ -52,19 +50,21 @@ checkpoints, not sibling tickets
 ```bash
 node .agents/scripts/plan-context.js --seed "<seed>" \
   --out temp/plan-<slug>/plan-context.json
-# or: --seed-file <path>  |  --tickets 123,456  |  --amends #<id>
+# or: --seed-file <path> | --tickets 123,456 | --amends #<id>
 ```
 
 **Always pass `--out`.** Persist auto-discovers the envelope from `--plan-dir`
-and derives source ids from its `sourceTickets[]`; the CLI also writes
+and derives source ids from its `sourceTickets[]`; it also writes
 **`stories.template.json`**, step 2's skeleton.
 
 The envelope carries docs context, the story-author prompt, `sourceTickets[]`,
-`duplicates[]` (open **Stories**, never Epics) and advisory `complexitySignals`
-(**no routing authority**). A trivial scope can claim the lite route at
-persist — shape-validated, failing closed to `full` ([detail](helpers/plan-reference.md)).
+`duplicates[]` (open **Stories**, never Epics), `epicCandidates[]` +
+`dependencyCandidates[]` (Gate #3; path collisions) and advisory
+`complexitySignals` (**no routing authority**). A trivial scope can claim the
+lite route at persist — shape-validated, failing closed to `full`
+([ref](helpers/plan-reference.md)).
 
-**Triage each unknown by resolver** ([detail](helpers/plan-reference.md)): an
+**Triage each unknown by resolver** ([ref](helpers/plan-reference.md)): an
 **AFK** unknown (research settles it) is resolved before authoring, never
 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
@@ -74,26 +74,26 @@ in Key Assumptions, each a decision-made-by-default.
 duplicate-candidate review. Under `--yes`, auto-proceed.
 
 On a truthy `memoryPoolAdvisory.recommend`, name
-[`/memory-consolidate`](memory-consolidate.md) quoting its `reasons[]` —
-advisory, never invoked here.
+[`/memory-consolidate`](memory-consolidate.md) quoting its `reasons[]`;
+advisory.
 
 On a truthy `deliverLightSuggestion.suggested`, offer — advisory, never an
 automatic reroute — to deliver the seed instead; on confirm route **in this
 session** into [`helpers/deliver-light.md`](helpers/deliver-light.md), its gate
 filled from this envelope. A truthy `complexitySignals.uiSurface` names
-[`/prototype`](prototype.md) as an option; never invoke it here.
-[Both offers](helpers/plan-reference.md).
+[`/prototype`](prototype.md); never invoke it here.
+[Both](helpers/plan-reference.md).
 
 ### 2. Author
 
-**One-shot authoring.** Start from `stories.template.json`; author
-`stories.json` in one pass. `body` is markdown **or** a structured object;
+**One-shot authoring.** From `stories.template.json`, author `stories.json`
+in one pass. `body` is markdown **or** a structured object;
 persist parses either, serializes canonical markdown and syncs top-level
-`acceptance[]` / `verify[]` in — never dual-author those lists.
+`acceptance[]` / `verify[]` in — never dual-author them.
 
 **Grounding = your reads + Phase 8.** Nothing inventories the repo: read each
-file you cite; persist hard-errors on any `{path, assumption}` absent from
-the tree. Fields: [reference](helpers/plan-reference.md).
+file you cite; persist hard-errors on any `{path, assumption}` absent from the
+tree. Fields: [ref](helpers/plan-reference.md).
 
 Artifacts under `temp/plan-<slug>/`: `stories.json` (**length 1 by default**;
 over-budget Specs fail closed — split or tighten, never under `docs/`); optional
@@ -112,10 +112,10 @@ node .agents/scripts/plan-critics.js \
   [--tech-spec temp/plan-<slug>/techspec.md]
 ```
 
-Run **before** persist — the last point a finding folds into a re-author.
-It exits 0 on **any** verdict (verdicts route work, they do not gate) and
-exits **1** only on a usage/IO error — no critic ran: **do not proceed to
-Persist**, fix and re-run.
+Run **before** persist — the last point a finding folds into a re-author. It
+exits 0 on **any** verdict (verdicts route work, they do not gate) and exits
+**1** only on a usage/IO error — no critic ran: **do not proceed to Persist**,
+fix and re-run.
 
 - **Both `dispatch: false`** — proceed to Persist (each skip is ledgered).
 - **Either `dispatch: true`** — dispatch **one fresh-context, maker-blind
@@ -130,12 +130,12 @@ Persist**, fix and re-run.
 **Gate #2** — STOP for approval before persist **only** when the operator asked
 to review (`--force-review`). Under `--yes`, auto-proceed.
 
-**Gate #3 (N>2 only)** — offer a **container Epic**; on a yes add
-`--epic-title` / `--epic-goal` below. It carries nothing a child does not
-([shape](helpers/plan-reference.md)). Never below 3 Stories, never unasked.
+**Gate #3 — adopt, else create.** Offer the top `epicCandidates[]` Epic at
+**any N** (`--epic <id>`); else, at **N>2**, a new container (`--epic-title` /
+`--epic-goal`). Never unasked ([ref](helpers/plan-reference.md)).
 
-Run persist with `--dry-run` **first** — same command, writes suppressed; every
-gate runs before the first `createIssue` ([list](helpers/plan-reference.md)):
+Run persist `--dry-run` **first** — same command, writes suppressed; every gate
+runs before the first `createIssue` ([list](helpers/plan-reference.md)):
 
 ```bash
 node .agents/scripts/plan-persist.js \
@@ -144,28 +144,28 @@ node .agents/scripts/plan-persist.js \
   [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
   [--tech-spec temp/plan-<slug>/techspec.md] \
   [--source-tickets 123,456] \
-  [--epic-title "<name>" --epic-goal "<one paragraph>"]
+  [--epic <id> | --epic-title "<name>" --epic-goal "<one paragraph>"]
 ```
 
-At lite shape `--chain-on-clean` folds a clean dry-run into the real persist;
-a full plan keeps its review trip.
+At lite shape `--chain-on-clean` folds a clean dry-run into the persist; a full
+plan keeps its review trip.
 
 Persist creates `type::story` issue(s), a **metadata-only** `plan-run::<id>`
-label, `blocked by #<id>` footers for N>1 `depends_on` edges, and on a confirmed
-Gate #3 a `type::epic` container linking every created Story.
-`agent::ready` is the **terminal** flip after receipts land; stdout is pure
-JSON. Tickets mode also comments on and closes each source id
-([detail](helpers/plan-reference.md)).
+label, `blocked by #<id>` footers for every `depends_on` edge, and on a Gate #3
+yes links them under a `type::epic` container (adopted or new). `agent::ready`
+is the **terminal** flip after receipts land; stdout is pure JSON. Tickets mode
+also comments on and closes each source id ([ref](helpers/plan-reference.md)).
 
 ## Constraints
 
 - `/mandrel-plan` starts delivery **only** through a confirmed Gate #1 light
-  route — never off its own authored Stories, which land via
+  route — never off its Stories, which land via
   [`/mandrel-deliver`](mandrel-deliver.md).
 - Duplicate search targets open Stories (`type::story`), not Epics; and
   deterministic gates still fail closed under `--yes`.
-- A container Epic is never a work item, and no Story body gains an `Epic: #N`
-  footer: linkage is parent→child only.
+- A container Epic is never a work item and only an **open** one is adoptable;
+  no Story body gains an `Epic: #N` footer (linkage is parent→child only).
+- `depends_on` takes a sibling slug or `#<id>` (open Story).
 
 ## See also
 

package/.agents/workflows/qa-assist.md

@@ -42,7 +42,8 @@ Constraints delta.
 > triage-ready finding without breaking stride — then, when the testing pass is
 > done, turned into a plan in one batch.
 >
-> **Skills**: `core/qa-coverage-mapping`
+> **Rules**: [`testing-standards.md`](../rules/testing-standards.md)
+> (§ The Three Tiers — the tier-classification rules enrichment applies)
 
 ## Role framing
 
@@ -106,7 +107,8 @@ ledger is hard-gated.**
 
 Goal: become the operator's QA assistant before any observation arrives.
 
-1. Re-read the QA role framing and `core/qa-coverage-mapping` skill.
+1. Re-read the QA role framing and the tier-classification rules in
+   [`testing-standards.md`](../rules/testing-standards.md) (§ The Three Tiers).
 2. **Load codebase context.** Read the files in `project.docsContextFiles`
    (architecture, decisions, patterns) and, when the testing touches UI/routing,
    `docs/style-guide.md` / `docs/web-routes.md`. This is the context you will
@@ -176,17 +178,16 @@ every decision to the shared helpers; never re-derive them in prose.
    `gh issue view <ticketNumber> --json title,body,labels`, and verify each
    surface-map path resolves with `git cat-file -e HEAD:<path>` — flag every
    miss rather than citing a path that does not exist.
-4. **Compute the coverage verdict** for the surface the observation points at,
-   via [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — the
-   deterministic seam behind the
-   [`core/qa-coverage-mapping`](../skills/core/qa-coverage-mapping/SKILL.md)
-   skill. Read that skill for how to assemble the `surface` input and read the
-   per-tier `{present|absent}` verdict.
-5. **Name the missing test** (if any) from that verdict: take the lowest tier
-   the verdict marks `absent` (unit → contract → acceptance) and write one
-   concrete sentence describing the test that would close it. Every tier
-   `present` means no missing test. Record that sentence as the ledger item's
-   `missingTest`.
+4. **Read the coverage tiers** for the surface the observation points at:
+   gather the tests that exercise it and classify each by path per
+   [`testing-standards.md` § The Three Tiers](../rules/testing-standards.md#the-three-tiers)
+   — a `.feature` file is **acceptance**, a path containing `/contract/` or
+   `.contract.test.` is **contract**, and a path containing `.test.` or
+   `__tests__/` is **unit**. A skipped test leaves its tier uncovered.
+5. **Name the missing test** (if any): take the lowest tier with no live test
+   (unit → contract → acceptance) and write one concrete sentence describing
+   the test that would close it. Every tier covered means no missing test.
+   Record that sentence as the ledger item's `missingTest`.
 6. **Classify** the finding via
    [`classify-finding.js`](../scripts/lib/findings/classify-finding.js) so the
    tentative `class` resolves to the correct focus/meta label set. The helper
@@ -267,10 +268,12 @@ the `/qa-assist`-specific deltas are:
 - **Persistent, resumable rolling session** — `/qa-assist` defaults to resuming
   the same session and appending; a reused session carries the untriaged backlog
   forward and never overwrites a prior ledger.
-- **Enrichment delegates where a helper exists** — the coverage verdict and
-  the finding classification come from their deterministic helpers, never from
-  prose. Context lookup and the missing-test sentence are the model's own work:
-  they are judgments, not computations, and routing them through a module only
+- **Enrichment delegates where a helper exists** — the finding classification
+  comes from its deterministic helper, never from prose; tier placement comes
+  from the three path rules in
+  [`testing-standards.md`](../rules/testing-standards.md#the-three-tiers).
+  Context lookup and the missing-test sentence are the model's own work: they
+  are judgments, not computations, and routing them through a module only
   bought a round-trip.
 
 ## See also

package/.agents/workflows/qa-explore.md

@@ -34,7 +34,7 @@ Constraints delta.
 > or Feature, a regression sweep over a risky surface before `/mandrel-deliver`, or a
 > structured agent-driven bug-hunt captured into a triageable ledger.
 >
-> **Skills**: `core/qa-coverage-mapping`, `stack/qa/qa-explore-driving`
+> **Skills**: `stack/qa/qa-harness`
 
 ## Role framing
 
@@ -45,15 +45,16 @@ the surface shows. Apply the QA skills below; there is no separate persona pack.
 ## Driving conventions
 
 Before you drive a surface, read the
-[`stack/qa/qa-explore-driving`](../skills/stack/qa/qa-explore-driving/SKILL.md)
-skill — the **one** conventions reference for the *how* of agent-driven
-exploration (navigation-first driving as the default; static driving as the
-documented interim chosen at Plan time only where no seam resolves;
-authenticated driving through the resolved environment's `signInSeam`; broken
-navigation is a finding, not a workaround). The driving method (drive vs.
-static) is a **Plan-phase decision recorded in the ledger**; do not switch
-methods mid-surface without a new Plan note. Do not restate these conventions
-inline — the skill owns them.
+[`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)
+skill — the **one** conventions reference for the *how* of agent-driven driving,
+shared with the known-scenario sweep (navigation-first driving as the default;
+static driving as the documented interim chosen at Plan time only where no seam
+resolves; authenticated driving through the resolved environment's
+`signInSeam`; broken navigation is a finding, not a workaround). Its § 5 carries
+the exploratory-mode deltas. The driving method (drive vs. static) is a
+**Plan-phase decision recorded in the ledger**; do not switch methods
+mid-surface without a new Plan note. Do not restate these conventions inline —
+the skill owns them.
 
 ## Slash Command
 
@@ -110,7 +111,7 @@ then the captured ledger), and wait. If the operator does not confirm, hold.
 Goal: agree on **what** will be explored and **how the agent will drive it**
 before touching the surface.
 
-1. Re-read the `stack/qa/qa-explore-driving` skill and resolve the contract and
+1. Re-read the `stack/qa/qa-harness` skill and resolve the contract and
    session (above).
 2. **Resolve the target environment** via
    [`resolveQaEnvironment`](../scripts/lib/qa/resolve-qa-contract.js) — it keys
@@ -149,8 +150,8 @@ Goal: **the agent drives the confirmed surface itself** and records its
 observations. **This phase is strictly read-only.**
 
 > **Read-only invariant.** The agent observes; it never mutates. Per
-> [`stack/qa/qa-explore-driving`](../skills/stack/qa/qa-explore-driving/SKILL.md)
-> § 3 (inviolable per [`security-baseline.md`](../rules/security-baseline.md)),
+> [`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)
+> § 2 (inviolable per [`security-baseline.md`](../rules/security-baseline.md)),
 > do **not** edit source, run write commands, file or label GitHub issues,
 > change tickets, submit destructive forms, or alter the product under test. The
 > only write Capture performs is **appending ledger lines to
@@ -170,17 +171,16 @@ For each observation the agent makes while driving:
 
 1. **Redact first** (per [`helpers/qa-core.md`](helpers/qa-core.md)) — scrub the
    evidence string through `redactEvidence` before it touches disk.
-2. **Compute the coverage verdict** for the surface the observation points at,
-   via [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — the
-   deterministic seam behind the
-   [`core/qa-coverage-mapping`](../skills/core/qa-coverage-mapping/SKILL.md)
-   skill. Read that skill for how to assemble the `surface` input and read the
-   per-tier `{present|absent}` verdict.
-3. **Name the missing test** (if any) from that verdict: take the lowest tier
-   the verdict marks `absent` (unit → contract → acceptance) and write one
-   concrete sentence describing the test that would close it. Every tier
-   `present` means no missing test. Record that sentence as the ledger item's
-   `missingTest` (or `null`).
+2. **Read the coverage tiers** for the surface the observation points at:
+   gather the tests that exercise it and classify each by path per
+   [`testing-standards.md` § The Three Tiers](../rules/testing-standards.md#the-three-tiers)
+   — a `.feature` file is **acceptance**, a path containing `/contract/` or
+   `.contract.test.` is **contract**, and a path containing `.test.` or
+   `__tests__/` is **unit**. A skipped test leaves its tier uncovered.
+3. **Name the missing test** (if any): take the lowest tier with no live test
+   (unit → contract → acceptance) and write one concrete sentence describing
+   the test that would close it. Every tier covered means no missing test.
+   Record that sentence as the ledger item's `missingTest` (or `null`).
 4. **Append a `QaLedgerItem`** to the ledger (shape per
    [`helpers/qa-core.md`](helpers/qa-core.md)): a stable `id`, the redacted
    `evidence`, the `coverage` label (the `surface`, or `unknown`), a tentative
@@ -215,7 +215,7 @@ resumed session will pick up.
 Beyond the shared core ([`helpers/qa-core.md`](helpers/qa-core.md): contract +
 loud failure, session/ledger, redact-first, QaLedgerItem, triage, HITL gate)
 and the driving conventions
-([`stack/qa/qa-explore-driving`](../skills/stack/qa/qa-explore-driving/SKILL.md)),
+([`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)),
 the `/qa-explore`-specific deltas are:
 
 - **Agent-led, bounded per surface.** The agent drives one named surface per
@@ -231,10 +231,11 @@ the `/qa-explore`-specific deltas are:
   and fall back to static.
 - **Broken navigation is a finding, not a workaround** — never URL-jump around a
   missing affordance, a nav 404, or a guard redirect loop.
-- **Delegate the coverage verdict to the helper.** Tier placement comes from
-  [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — deterministic,
-  never re-derived in prose. The missing-test sentence is yours to write from
-  that verdict's lowest `absent` tier.
+- **Read tier placement from the rule, not from prose you invent.** The three
+  path rules in
+  [`testing-standards.md` § The Three Tiers](../rules/testing-standards.md#the-three-tiers)
+  decide which tier a test occupies; the missing-test sentence is yours to write
+  from the lowest uncovered tier.
 
 ## See also
 

package/.agents/workflows/qa-run.md

@@ -29,7 +29,8 @@ the agent never invents those decisions in prose.
 > passes before `/mandrel-deliver`, or on demand while debugging a Story's
 > user-visible behavior in a live browser.
 >
-> **Skills**: `stack/qa/gherkin-authoring`, `stack/qa/playwright-bdd`
+> **Skills**: `stack/qa/qa-harness` (driving and instrumentation
+> conventions), `stack/qa/gherkin-authoring` and `stack/qa/playwright-bdd`
 > (authoring reference; this harness owns execution)
 
 ## Slash Command

package/docs/CHANGELOG.md

@@ -15,6 +15,20 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.41.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.40.0...mandrel-v2.41.0) (2026-09-06)
+
+
+### Added
+
+* /mandrel-plan adopts an existing open Epic and declares depends_on edges on existing open Stories ([#5155](https://github.com/dsj1984/mandrel/issues/5155)) ([#5156](https://github.com/dsj1984/mandrel/issues/5156)) ([9119f31](https://github.com/dsj1984/mandrel/commit/9119f313146ab08ed676909f9b0a61671c4d6069))
+
+
+### Changed
+
+* **agents:** retire four frontier-known rules/skills, fold two more into rules (refs [#5158](https://github.com/dsj1984/mandrel/issues/5158)) ([#5162](https://github.com/dsj1984/mandrel/issues/5162)) ([065f883](https://github.com/dsj1984/mandrel/commit/065f8839fafcc7064e4ad6d2ea30f2bfebbd5c0c))
+* **qa:** fold qa-explore-driving into qa-harness (refs [#5159](https://github.com/dsj1984/mandrel/issues/5159)) ([#5163](https://github.com/dsj1984/mandrel/issues/5163)) ([2fbc8db](https://github.com/dsj1984/mandrel/commit/2fbc8db5a420450414cfd046bb6418e0c210bf7f))
+* **rules:** trim surviving rules and core skills to their contracts (refs [#5160](https://github.com/dsj1984/mandrel/issues/5160)) ([#5164](https://github.com/dsj1984/mandrel/issues/5164)) ([f0e6a62](https://github.com/dsj1984/mandrel/commit/f0e6a62feaba275377c9cc435f03ea6089008148))
+
 ## [2.40.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.39.0...mandrel-v2.40.0) (2026-09-06)
 
 

package/package.json

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

package/.agents/rules/changelog-style.md

@@ -1,180 +0,0 @@
-# CHANGELOG Style Contract
-
-This rule governs the shape of per-release entries in the project CHANGELOG
-(typically `docs/CHANGELOG.md` or `CHANGELOG.md`). It applies whenever a
-release entry is authored or edited — most commonly inside Story #N's
-docs sweep before `/mandrel-deliver` opens the release PR.
-
-The contract is **guidance-tier**: no automated gate fails a close when an
-entry drifts off-template. It still binds every author.
-
-## Goal
-
-A reader scanning release notes should identify what ships in a release in
-under 30 seconds. Breaking changes, config-shape changes, and CLI renames
-must be impossible to miss. Internal refactor detail belongs in commit
-messages and PR descriptions — not here.
-
-## Per-Release Entry Shape
-
-Every entry starts with a version header line already produced by the
-release tooling:
-
-```markdown
-## [X.Y.Z] - YYYY-MM-DD
-```
-
-Immediately below, the entry MUST have:
-
-1. **A short section header** naming the theme of the release — one line,
-   Sentence case, no trailing punctuation.
-
-   ```markdown
-   ### Epic-runner throughput & caching pass
-   ```
-
-2. **A 1–3 sentence theme paragraph** that tells the reader, in plain
-   English, what the release is about and why it matters. No bullets, no
-   sub-headers, no code fences.
-
-3. **Bullets of user-visible changes**, grouped by natural topic if the
-   release spans more than one theme. Each bullet leads with a bold phrase
-   naming the change, followed by a one- or two-sentence explanation.
-
-```markdown
-## [5.21.0] - 2026-04-24
-
-### Epic-runner throughput & caching pass
-
-Performance and observability pass across the epic-runner hot paths — wave
-gating, commit assertion, progress reporting, and label polling. Caching
-and bounded concurrency throughout; new per-phase timing surface.
-
-- **Bounded-concurrency parallelism.** Wave gating, commit assertion, and
-  progress reporting now fan out in parallel with a configurable cap.
-- **Per-phase timing surface.** Story close posts a structured comment
-  with per-phase timings; the Epic progress comment aggregates median
-  and p95 across closed stories.
-```
-
-## Bullets: What Counts as "User-Visible"
-
-Include:
-
-- New CLI commands, flags, or scripts the operator invokes.
-- New or renamed labels, ticket shapes, or workflow phases the operator
-  touches.
-- New or renamed configuration keys, with the old → new mapping if any.
-- New behavioural guarantees (e.g., "retries on transient errors").
-- Bug fixes the operator would otherwise trip over.
-- Performance changes with a user-observable magnitude.
-
-Exclude:
-
-- Internal refactors with no behavioural delta.
-- Test additions, coverage bumps, lint cleanups.
-- Module renames or file moves invisible to operators.
-- Per-phase implementation details ("now uses a BFS walker").
-
-## Banned Content
-
-The following MUST NOT appear in a release entry:
-
-- **Per-ticket citations.** No `(Epic #553)`, `(resolves #612)`,
-  `(Story #645)` in bullet text. The theme paragraph may reference the
-  Epic once when the release is scoped to one Epic — that is the only
-  allowed citation, and only there.
-- **Internal file paths** (`lib/orchestration/epic-runner/commit-assertion.js`,
-  `.agents/scripts/story-init.js`). Callers care what changed, not
-  where it lives.
-- **Internal function, class, or method names** (`finalizeMerge`,
-  `WorkspaceProvisioner.verify`, `cascadeCompletion`). Name the behaviour,
-  not the symbol — unless the symbol is part of the public API.
-- **Test counts** (`47 new tests`, `95% coverage`). Tests are a means, not
-  a ship artefact.
-- **Module-sizing stats** (`shrinks epic-runner from 840 to 420 LOC`).
-- **Implementation mechanics** (`BFS walker`, `Promise.all over parents`,
-  `exponential backoff with 3 attempts, 500ms base`) unless the mechanism
-  is part of a new public contract.
-
-## Mandatory Prominence
-
-The following categories MUST be called out visibly — typically in **bold**
-at the start of a bullet, or in a short dedicated section above the
-bullet list:
-
-- **Breaking changes.** A bullet leading with `**Breaking:**` or a
-  `### Breaking Changes` sub-section. Include the migration path.
-- **Config-shape changes.** Moved, removed, renamed, or newly-required
-  config keys. Old key → new key, or removal notice with remediation.
-- **CLI renames.** Old command → new command, including whether the old
-  name remains as a deprecation alias and for how long.
-- **Schema shape changes** on structured comments, manifest files, or
-  public API payloads. Readers parsing these surfaces must be told.
-
-If a release ships any of the above, they belong at the top of the bullet
-list (or in a dedicated sub-section), not buried mid-list.
-
-## Line-Count Guidance
-
-Soft ceilings, not hard fails:
-
-- **Non-major release** (patch or minor): **≤60 lines**, including
-  header, theme paragraph, blank lines, and bullets.
-- **Major release**: **≤150 lines**. Major releases span larger surface
-  and warrant more prominence.
-
-If an entry exceeds the ceiling, prefer splitting a genuinely multi-theme
-release into grouped sub-sections over padding the bullet list. Before
-accepting a long entry, ask: which bullets are user-visible, and which
-are internal detail that migrated in from the Epic body?
-
-## Worked Example — On-Contract
-
-Off-contract entries — the style that drove the Epic #553 retro action item —
-pack several `###` sub-sections into one release and leak internal function
-names (`finalizeMerge`, `mergeFeatureBranch`, `ensure()`, `reap()`),
-implementation mechanics, internal step numbering, and lock-file name lists
-operators cannot act on. The on-contract version collapses all of that:
-
-```markdown
-## [5.8.7] - 2026-04-15
-
-### Parallel-wave merge robustness
-
-Parallel story waves kept tripping over each other at integration time.
-This release reduces the conflict surface at story close and stabilises
-worktree cleanup.
-
-- **Pre-merge rebase at story close** shrinks the conflict window to
-  each story's real delta; conflicts above the triage threshold abort
-  and surface to the operator.
-- **Shared-store worktrees.** Per-story worktrees link a shared
-  `node_modules` store, so parallel waves no longer duplicate installs
-  or leave residue that blocks reap.
-- **`/mandrel-deliver` auto-invokes pre-merge gates** (code review, retro)
-  inline. `--skip-code-review` is available as an override.
-- **Closure sweep covers Epic Health tickets** in addition to PRD and
-  Tech Spec tickets.
-- **Stale-lock sweep** on the shared `.git/` directory runs at
-  `/mandrel-deliver` start, clearing lock files left behind by interrupted
-  operations.
-```
-
-What changed: one theme section instead of five; the paragraph gives the
-"why" in two sentences; each bullet leads with the user-visible behaviour
-and drops internal symbols, file paths, and step numbers; the override
-flag (`--skip-code-review`) is kept because it is part of the public CLI
-surface; the lock-file list is dropped because operators do not act on
-individual lock names.
-
-## When to Deviate
-
-- **Major releases** may warrant multiple `###` sub-sections under a
-  single version header when the release genuinely spans multiple themes.
-  Keep each sub-section on-contract individually.
-- **Security fixes** may include CVE-style detail and remediation steps
-  beyond normal bullet shape — those callouts are always on-contract.
-- **When in doubt**, cut more aggressively. A reader can always follow
-  the Epic link for detail; they cannot un-read bullets that told them
-  nothing.

package/.agents/rules/shell-conventions.md

@@ -1,61 +0,0 @@
-# Shell & Terminal Conventions
-
-This rule applies when running shell commands during agent execution. The host
-shell varies — agents must adapt to the environment.
-
-## Detecting the Shell
-
-Before chaining commands, check the host shell. Common signals:
-
-- `$env:COMSPEC` set / `pwsh.exe` or `powershell.exe` → PowerShell
-- `$SHELL` set to `/bin/bash`, `/bin/zsh`, etc. → POSIX shell
-- Claude Code system prompt or harness directive announces the shell
-
-## PowerShell (Windows)
-
-PowerShell 5.1 (default on Windows) does **not** support `&&` as a statement
-separator and will throw a parser error. PowerShell 7+ does, but agents
-running on Windows should not assume version 7+.
-
-- **Standard separator**: `;` runs the next command regardless of the first's
-  exit status.
-- **Success chaining (logical AND)**: `; if ($?) { ... }` runs the second
-  command only when the first succeeded.
-- **Example**: `git add . ; if ($?) { git commit -m "..." }`
-
-Other PowerShell-isms agents must respect:
-
-- Use `$null` (not `/dev/null`).
-- Use `$env:VAR` (not `$VAR`).
-- Use backtick (`` ` ``) for line continuation, not backslash.
-
-## POSIX Shells (bash / zsh)
-
-`&&` and `||` work natively. No translation needed.
-
-- **Success chaining**: `cmd1 && cmd2`
-- **Fallback**: `cmd1 || cmd2`
-
-## Cross-Platform Tips
-
-- Prefer the host's tool wrappers (Bash tool, etc.) over raw shell strings
-  when the harness exposes them — they normalize quoting and escaping.
-- For multi-step pipelines that must run identically across platforms, write
-  a Node/Python script and invoke that, rather than chaining shell builtins.
-
-## Searching the Workspace
-
-Prefer, in order: the host's dedicated grep tool (ripgrep-backed — normalizes
-quoting, respects `.gitignore`, streams results), then `git grep` in a git
-repo (`-l` for filenames only), then `rg` outside a git repo or when you need
-multiline / type filters. Do not read whole files to scan for a pattern.
-
-### PowerShell-specific anti-patterns
-
-- If you must use `Select-String`, pass `-List` when you only need to
-  detect existence or collect file paths — without it, every match streams
-  through the pipeline.
-- NEVER chain `Select-Object -Unique` or `Sort-Object` directly after a
-  highly recursive `Get-ChildItem` on large trees. Both block the pipeline,
-  hold every result in memory, and frequently hang the terminal. Stream
-  through `Where-Object` filters first, or pre-narrow with a glob.