mandrel 1.94.0 → 2.1.0

package/.agents/instructions.md

@@ -8,15 +8,17 @@ set. You MUST strictly adhere to the following rules:
 
 ## 1. System Guardrails & Initialization
 
-### A. Persona Routing & Execution
+### A. Role Framing (no persona packs)
 
-When a task carries a `persona::<role>` label, or a user explicitly instructs
-"Act as [Role/Persona]" in chat, retrieve and strictly adopt the rules in
-`.agents/personas/[role].md`. Personas are advisory role framing, not a runtime
-injection — read the file when the label or the instruction points you at one.
+v2 has **no** `.agents/personas/` packs and **no** `persona::*` GitHub labels.
+Behavioral constraints come from this file, always-on / on-demand rules, and
+skills. Role-scoped spawn contexts (when used) live under `.agents/agents/`
+via `delivery.routing.roleScopedAgents`. QA auth identities (`qa.personas`)
+are a separate fixture concept — not agent behavior packs.
 
-- **Fallback:** If no persona is indicated, or the named file is missing,
-  default to `.agents/personas/engineer.md`.
+If a user says "act as [role]" in chat, apply the matching skill / workflow
+guidance (e.g. QA skills for verification work, security skill for threat
+modeling) rather than looking for a persona file.
 
 ### B. Skill Activation
 
@@ -36,9 +38,14 @@ The skill library uses a **two-tier architecture**:
 
 When a task involves a specific domain or technology, you MUST read the
 corresponding `.agents/skills/[tier]/[category]/[skill-name]/SKILL.md` file and
-apply its constraints. Review the skill's `examples/` directory or
-`examples.md` sibling **when present and relevant** to the task — most skills
-do not ship one, so do not probe blindly. When uncertain which skill applies,
+apply its constraints. A `SKILL.md` leads with its **Policy Capsule** — the
+contract, and the whole cost of activating the skill — followed by pointers
+into an on-demand `reference.md` sibling holding the long-form material
+(patterns, worked examples, checklists). This is the same split the always-on
+rules use (§ 1.F): read the capsule on activation, and open a `reference.md`
+section only when the task actually engages it. Review the skill's `examples/`
+directory or `examples.md` sibling **when present and relevant** to the task —
+most skills do not ship one, so do not probe blindly. When uncertain which skill applies,
 match the task against the one-line `description` in each skill's frontmatter
 (catalogued in `.agents/skills/skills.index.json`). Skills compose: a complete
 feature typically flows `idea-refinement` → the `/plan` workflow →
@@ -155,18 +162,17 @@ technology context is intentionally kept out of `.agentrc.json`.
 
 You MUST log telemetry about operational difficulty or automation
 opportunities you hit. Friction is a **local NDJSON signal**:
-`diagnose-friction.js` appends one `kind: friction` record to the per-Epic/
+`diagnose-friction.js` appends one `kind: friction` record to the per-run/
 per-Story `signals.ndjson` stream on local disk — not posted to the ticket at
 capture time; the retro phase surfaces the aggregate as routed proposals.
 
 - **Command**:
   `node .agents/scripts/diagnose-friction.js --story [STORY_ID] --cmd [FAILED_COMMAND]`
-  (add `--epic [EPIC_ID]` under an Epic).
 - **When to fire**: after repeated tool-validation errors, an unrecoverable
   command failure, ambiguity needing self-correction, or repetitive
   boilerplate steps a workflow/skill could simplify.
 
-The schema validation, the standalone (no-Epic) stream path, and the
+The schema validation, the standalone stream path, and the
 never-silently-dropped guarantee are reference detail — see
 [`docs/execution-reference.md` § Friction telemetry](docs/execution-reference.md#friction-telemetry).
 
@@ -201,19 +207,11 @@ recurred, and what assumption you would test next, then either Re-Plan or
 hand back to the operator. Do not paper over the loop with another
 just-in-case retry.
 
-This protocol is not soft-prompt-only — it has a runtime substrate. While
-executing as a Story delivery sub-agent (via `helpers/epic-deliver-story`
-or `helpers/single-story-deliver`), you MUST emit a `story.heartbeat`
-lifecycle event on every Task transition (or whenever you stall on a
-long-running step) so the parent `/deliver` idle watchdog (§ 2e of
-`.agents/workflows/helpers/deliver-epic.md`, re-ticked every 30 minutes via
-`wave-tick.js --check-idle 30`) can distinguish a child still making
-progress from a dead one. If you genuinely cannot proceed, transition to
-`agent::blocked` and exit non-zero — never fall silent. A child with no
-recent `story.heartbeat`, no commit on its `story-<id>` branch, and no
-`agent::blocked` label is exactly the failure mode the idle watchdog is
-built to catch, and the watchdog will re-dispatch (or escalate) the Story
-without your participation.
+While executing as a Story delivery sub-agent (via `helpers/deliver-story`),
+if you genuinely cannot proceed you MUST transition to `agent::blocked` and
+exit non-zero — **never fall silent**. A stalled child that reports nothing
+is indistinguishable from a dead one, and the parent `/deliver` run can only
+escalate what you surface.
 
 ### J. HITL Blocker Escalation (Safe Execution)
 
@@ -243,8 +241,7 @@ resolve by this **total ordering** (higher wins):
    (§ 1.E).
 2. **This file** — `.agents/instructions.md`.
 3. **Global rules** — `.agents/rules/*.md` (§ 1.F).
-4. **The active persona** — `.agents/personas/[role].md` (§ 1.A).
-5. **Skills** — `.agents/skills/**/SKILL.md` (§ 1.B).
+4. **Skills** — `.agents/skills/**/SKILL.md` (§ 1.B).
 
 Two carve-outs refine the ordering:
 
@@ -252,23 +249,25 @@ Two carve-outs refine the ordering:
   tier overlap, the narrower, more-specific statement governs the broader one
   (e.g. a stack-specific skill refines a general core skill; a per-rule
   statement refines a cross-rule one).
-- **`rules/security-baseline.md` is inviolable.** No persona, skill, or local
-  override may relax a security MUST. A security constraint that conflicts
-  with any lower-tier guidance — or with a local override — always wins,
-  regardless of its tier position above.
+- **`rules/security-baseline.md` is inviolable.** No skill or local override
+  may relax a security MUST. A security constraint that conflicts with any
+  lower-tier guidance — or with a local override — always wins, regardless of
+  its tier position above.
 
 ---
 
 ## 2. FinOps & Token Budgeting (Economic Guardrails)
 
-Mandrel does **not** enforce live LLM spend from response metadata. It caps
-**hydrated prompt size** (`delivery.maxTokenBudget`, section-aware elision) and
-runs optional **pre-dispatch estimates** (`delivery.preflight.*`); your host
-runtime owns session quota and hard stops. The config keys, the ≈4-char/token
-estimate, and the elision behaviour are reference detail — see
+Mandrel does **not** enforce live LLM spend from response metadata, and it has
+no operator-tunable context budget. What it does bound are fixed framework
+ceilings — the `/plan` context envelope and plan-time Story sizing — and they
+**fail closed** with a message naming what to trim, rather than silently
+handing the model a truncated context. Your host runtime owns session quota and
+hard stops. The constants, the ≈4-char/token estimate, and the trim options are
+reference detail — see
 [`docs/execution-reference.md` § FinOps & token budgeting](docs/execution-reference.md#finops--token-budgeting-economic-guardrails).
-Consult it when a task prompt was elided or `/deliver` refused a fan-out on
-budget grounds.
+Consult it when `/plan` refused an over-ceiling envelope or an over-budget
+Story count.
 
 ---
 
@@ -276,76 +275,51 @@ budget grounds.
 
 1. **Context First:** Before proposing any solution, understand the
    repository's tech stack, historical context, and structure.
-   - **Digest-first Reading (planning & interactive tasks, Story #4433)**:
-     For planning (`/plan`) and interactive tasks, read the project's **docs
-     digest** before reading any full doc file — do not read every file
-     listed in `project.docsContextFiles` up front. The epic planning path
-     ensures (generates or reuses) a per-Epic docs digest — a single compact
-     outline (path, byte size, heading outline with line numbers, and the
-     first paragraph under each `##`) built from `project.docsContextFiles`
-     — at `temp/epic-<epicId>/docs-digest.md` (`plan-context.js`, via the
-     shared generator in
-     `.agents/scripts/lib/orchestration/docs-digest.js`; the same file the
-     `/deliver` story sub-agents below already consume). Use the digest to
-     decide which docs bear on the task at hand, then **pull the full file
-     on demand** (jump to the section at the line number the digest names)
-     when a section actually bears on the decision. The decisions log
-     (`decisions.md`) may be either a single-file dated-entry log or an
-     **index** into a `decisions/` ADR directory — both are first-class
-     layouts (see
+   - **Digest-first Reading (Story #4433)** — stated once here; it governs
+     every call site. **Never ingest the whole `project.docsContextFiles` set
+     up front.** Read the **docs digest** — a compact outline (path, byte
+     size, heading outline with line numbers, and the first paragraph under
+     each `##`) built from those files — decide which docs bear on the task at
+     hand, then **pull the full file on demand**, jumping to the section at
+     the line number the digest names. This is a hard cutover: no
+     read-every-file branch is retained on any path.
+
+     The call sites differ only in how the digest reaches you — the
+     discipline above is identical for all of them:
+     - `/plan` and interactive tasks — a file at `temp/run-<id>/docs-digest.md`
+       (`plan-context.js`, via the shared generator in
+       `.agents/scripts/lib/orchestration/docs-digest.js`).
+     - `/deliver` Story sub-agents (`helpers/deliver-story`) — the
+       `docsDigestPath` the caller threads.
+     - Standalone-Story planning (`story-plan.js --emit-context`) — inline as
+       `corpusContext.docsDigest` (no per-run directory to anchor a
+       file), alongside `corpusContext.relevantSections`.
+
+     When no digest exists for the task at hand — an ad hoc task outside
+     `/deliver`, `project.docsContextFiles` unset, or a null `docsDigestPath` —
+     there is **no mandatory docs read**: read a full doc only when the task's
+     own context points you at one.
+
+     The decisions log (`decisions.md`) may be either a single-file
+     dated-entry log or an **index** into a `decisions/` ADR directory — both
+     are first-class layouts (see
      [`skills/core/documentation-and-adrs`](skills/core/documentation-and-adrs/SKILL.md)).
-     When it is an index, treat the index like any other digested doc —
-     link-follow the per-ADR bodies under `decisions/` on demand, not
-     auto-loaded into every task's context. When no digest exists yet for
-     the task at hand (an ad hoc interactive task with no Epic in scope, or
-     `project.docsContextFiles` unset) there is no mandatory docs read —
-     read a full doc only when the task itself points you at one. This is a
-     hard cutover: there is no read-every-`docsContextFiles`-file branch
-     retained.
-   - **Digest-first Reading (`/deliver` story sub-agents)**: A `/deliver`
-     Story delivery sub-agent (dispatched via `helpers/epic-deliver-story` or
-     `helpers/single-story-deliver`) does **not** re-read the full
-     `project.docsContextFiles` set per Story. Instead it reads the **per-Epic
-     docs digest** — the same file and shape described above — that
-     `epic-deliver-prepare.js` writes to
-     `temp/epic-<epicId>/docs-digest.md` and the parent threads into the
-     child prompt as `docsDigestPath`. Use the digest to decide which docs are
-     relevant to the Story at hand, then **pull the full file on demand**
-     (reading the section at the line number the digest names) when a section
-     bears on the change. When `docsDigestPath` is null (the project has no
-     `project.docsContextFiles` configured) there is no digest to read and no
-     per-Story docs mandate — read a full doc only if the Story's own context
-     points you at one. This is the hard cutover from the former
-     read-every-file-per-Story rule: delivery children no longer ingest the
-     whole docs set up front.
-   - **Standalone-Story planning path (`story-plan.js --emit-context`)**:
-     The standalone counterpart to `/plan` for Stories that do not attach
-     to an Epic does not write a `docs-digest.md` file at all — there is
-     no per-Epic directory to anchor one. Instead `buildCorpusContext`
-     (`.agents/scripts/lib/planning-corpus.js`) builds the same compact
-     digest shape in memory and threads it inline as
-     `corpusContext.docsDigest` on the `--emit-context` envelope, next to
-     `corpusContext.relevantSections` (ranked excerpts from existing
-     Epics' Tech Spec sections). Treat `corpusContext.docsDigest` exactly
-     like the file-based digest above — decide relevance from the outline,
-     then pull the full file on demand — the only difference is the
-     delivery mechanism (inline JSON field vs. a temp file path), not the
-     content or the digest-first discipline.
+     Treat an index like any other digested doc: link-follow the per-ADR
+     bodies on demand rather than auto-loading them.
    - **Conditional Reads**: When the task touches UI copy, layout, or
      routing and the corresponding file is present in the project, also
      read `docs/style-guide.md` and `docs/web-routes.md`. Skip both when
      absent or unrelated to the task — they are not part of the universal
      mandatory set.
-   - **Epic Context**: Additionally, read the current Epic's body — the
-     single planning document (ideation sections plus the folded Tech
-     Spec sections; Story #4324 retired the separate context tickets) —
-     and the task-specific instructions.
+   - **Story Context**: Additionally, read the current Story's body — the
+     inline `## Spec` plus its `acceptance[]` / `verify[]` entries — and
+     the task-specific instructions.
    - **Optimization**: For large projects, prioritize targeted retrieval
      (semantic code search or focused text search) to isolate specific
      schemas or decisions before reading broad files.
 2. **Plan First:** For non-trivial tasks (3+ steps or architectural
-   decisions), enter **Plan Mode**. Update the Epic body's Tech Spec
-   sections (via `/plan`) or create a new Technical Specification document
+   decisions), enter **Plan Mode**. Update the Story's `## Spec`
+   (via `/plan`) or create a new Technical Specification document
    in the `docs/` root (if not already handled by a ticket) before
    touching code.
 3. **Artifacts over Chat:** Create log files for test results, build
@@ -396,24 +370,23 @@ budget grounds.
 
 ---
 
-## 5. Git & Epic Protocol (Strict Standards)
+## 5. Git & Story Protocol (Strict Standards)
 
 To maintain a clean and readable repository history, you MUST follow these
-strict conventions for all epic-related Git operations. See
+strict conventions for all Story-related Git operations. See
 [`.agents/rules/git-conventions.md`](rules/git-conventions.md) for the full
 canonical reference.
 
 ### A. Branch Naming (Canonical)
 
-Epic execution uses two branch shapes. The runtime creates and maintains
-them automatically; agents commit on the execution branch only.
+v2 delivery uses one branch shape. The runtime creates and maintains it
+via `single-story-init.js`; agents commit on that branch only.
 
-| Purpose          | Format                       | Owner                  | Notes                                                                                         |
-| ---------------- | ---------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
-| Story execution  | `story-<storyId>`            | `story-init.js` | Per-Story worktree at `.worktrees/story-<storyId>/`. All Story implementation commits land here. |
-| Epic integration | `epic/<epicId>`              | `/deliver` slash command | Story branches merge into this branch with `--no-ff`. Pushed per wave.                       |
+| Purpose         | Format            | Owner                   | Notes                                                                 |
+| --------------- | ----------------- | ----------------------- | --------------------------------------------------------------------- |
+| Story execution | `story-<storyId>` | `single-story-init.js`  | Per-Story worktree at `.worktrees/story-<storyId>/`. PR target is `main` (squash + required checks). There is no `epic/<id>` integration branch and no `--no-ff` wave merge. |
 
-- **Verification**: After `story-init.js` returns, confirm
+- **Verification**: After `single-story-init.js` returns, confirm
   `git branch --show-current` reports `story-<storyId>` before making any
   commits. If it does not, **STOP** and re-init.
 
@@ -429,31 +402,32 @@ prompted.
 
 ### C. History Hygiene
 
-Prioritize a clean `epic/[EPIC_ID]` branch. Story branches are merged into
-the Epic branch automatically by `helpers/epic-deliver-story` (via
-`story-close.js`); the Epic branch reaches `main` via the pull request that
-`/deliver` opens at the end of its run — the operator merges through
-the GitHub UI. There is no in-script merge to `main`.
-
-### D. Ticket hierarchy (2-tier)
-
-Mandrel uses a **2-tier ticket hierarchy** (Epic → Story).
-Acceptance criteria and verification steps live inline on the Story
-body (`acceptance[]` / `verify[]`); there is no Feature tier and no
-`type::task` ticket layer. Thematic grouping lives as prose in the
-Epic body (which also carries the folded Tech Spec sections).
-
-- The decomposer emits only `type::epic` and `type::story` issues;
-  Stories attach directly to the Epic.
-- Each Story-implementation phase is executed by
-  `helpers/epic-deliver-story` (Epic-attached) or
-  `helpers/single-story-deliver` (standalone). There is no per-Task
-  sub-loop; the agent authors commit subjects directly per
-  [`rules/git-conventions.md`](rules/git-conventions.md) and references
-  the parent Story via `(refs #<storyId>)`.
-- Story branches, the Epic-branch integration target, the wave-loop
-  fan-out, and the `epic/<id>` → `main` PR merge model are the same
-  as Section 5.A.
+Every Story reaches `main` via its own PR (`story-<id>` → squash + required
+checks). `helpers/deliver-story` / `single-story-close.js` open that PR;
+there is no Epic integration branch and no in-script push to `main`.
+
+### D. Ticket hierarchy (Story-only)
+
+v2 collapses the ticket model to **Story**. Acceptance criteria and
+verification steps live inline on the Story body (`acceptance[]` /
+`verify[]`); the folded Tech Spec lives inline in `## Spec` (over-budget
+Specs fail closed — split or tighten; never write under `docs/`). Optional
+`depends_on` edges order rare multi-Story runs — and, because `/deliver`
+resolves them from live state, they order Stories **across plan runs and
+over time**, not just within one batch.
+
+- `/plan` emits one or more `type::story` issues (default N=1). There is no
+  batch label: `/deliver` takes ids and discovers the graph.
+- Each Story is executed by `helpers/deliver-story` (invoked from
+  [`/deliver`](workflows/deliver.md)). There is no per-Task sub-loop; the
+  agent authors commit subjects directly per
+  [`rules/git-conventions.md`](rules/git-conventions.md) and references the
+  Story via `(refs #<storyId>)`.
+- Branch model matches Section 5.A (`story-<id>` → PR → `main`).
+- There is no `type::epic` / `type::task` label and no Epic issue form. An
+  Epic is at most an optional untyped human umbrella issue outside
+  orchestration; `/deliver` refuses tickets that still carry an
+  `Epic: #N` footer.
 
 ---
 
@@ -471,12 +445,12 @@ To keep the repository clean and avoid polluting the Git history:
 
 ## 7. Complexity-Aware Execution
 
-The dispatcher automatically calculates the execution plan for an Epic. A
-Story is a **capability slice a frontier model delivers and self-verifies in
-one pass** — a broad footprint is normal when the change is cohesive. The
-numeric sizing backstop lives in one place: `DEFAULT_TASK_SIZING` in
-`.agents/scripts/lib/orchestration/ticket-validator-sizing.js` (operator
-override via `planning.taskSizing`). Do not re-slice a capability-sized
+`/plan` sizes each Story as a **capability slice a frontier model delivers
+and self-verifies in one pass** — a broad footprint is normal when the
+change is cohesive. The session-capacity backstop lives in one place:
+`DEFAULT_MODEL_CAPACITY` in
+`.agents/scripts/lib/orchestration/ticket-validator-sizing.js` (framework
+constant — not operator-tunable). Do not re-slice a capability-sized
 Story into per-module fragments just because it touches many files.
 
 ### A. When You See `⚠️ COMPLEXITY WARNING`

package/.agents/rules/ci-remediation.md

@@ -1,12 +1,11 @@
 # CI Failure Triage & Remediation
 
 This rule applies when a delivery path is watching a pull request's CI checks
-and a required check is red (or repeatedly slow) — the Epic Phase 8
-watch-and-iterate loop
-([`deliver-epic.md`](../workflows/helpers/deliver-epic.md)) and the standalone
+and a required check is red (or repeatedly slow) — the `/deliver` router
+([`deliver.md`](../workflows/deliver.md)) runs each Story through the
 single-Story Step 4 CI watch + fix loop
-([`single-story-deliver.md`](../workflows/helpers/single-story-deliver.md))
-both hand off to it. It is the single triage brain those mechanisms defer to:
+([`deliver-story.md`](../workflows/helpers/deliver-story.md)), which hands off
+to it. It is the single triage brain that mechanism defers to:
 the watcher (`pr-watch-with-update.js`) surfaces the failing check, the run
 link, and the failure signature; this rule decides what to do next.
 
@@ -27,8 +26,8 @@ guess.
 
 Fetch the failing job log and record the failure signature (the failing check
 name, the run id / run link, and the first distinctive error line). The
-watcher already writes this to `temp/epic-<epicId>-ci-digest.{json,md}` (Epic
-path) or surfaces it inline (standalone path) — start from that digest.
+watcher already writes this to `temp/story-<id>-ci-digest.{json,md}` — start
+from that digest.
 
 ### 2. Classify the failure
 
@@ -50,18 +49,15 @@ path) or surfaces it inline (standalone path) — start from that digest.
 A deterministic failure caused by the diff is remediated at source. Use the
 existing per-check fix table — do **not** duplicate it here:
 
-- **Epic Phase 8**:
-  [`deliver-epic-reference.md` § Phase 8 — Watch-and-iterate remediation](../workflows/helpers/deliver-epic-reference.md#phase-8--watch-and-iterate-remediation)
-  (§ 8.1 Remediation).
-- **Standalone Step 4**:
-  [`single-story-deliver-reference.md` § Step 4 — CI watch + fix recovery](../workflows/helpers/single-story-deliver-reference.md#step-4--ci-watch--fix-recovery).
+- **Story Step 4**:
+  [`deliver-story-reference.md` § Step 4 — CI watch + fix recovery](../workflows/helpers/deliver-story-reference.md#step-4--ci-watch--fix-recovery).
 
 In short: lint/format → `npm run lint` + biome apply; maintainability/crap
 baseline drift → re-run the ratcheted script and fix at source (refresh a
 baseline only when the diff demonstrably can't be covered); test failure →
 reproduce with `npm test`, fix source or test; coverage threshold → add tests.
-Commit the fix on the delivery branch (`epic/<epicId>` or `story-<storyId>`),
-push, and re-run the watcher. Auto-merge stays armed across retries.
+Commit the fix on the delivery branch (`story-<storyId>`), push, and re-run the
+watcher. Auto-merge stays armed across retries.
 
 ## Infra, transient, and flaky failures ARE root-cause defects
 
@@ -75,7 +71,7 @@ get to wave it off because "CI was flaky."
    genuine attempt, that itself is a finding — record it in the issue you file
    in step 4.
 2. **Check whether it also fails on `main`.** Run the same check against an
-   unmodified `main` (or the Epic base branch) checkout. If it fails on `main`
+   unmodified `main` checkout. If it fails on `main`
    too, the defect is **pre-existing** — it is not caused by the diff under
    review, and the fix belongs in a separate change, not silently folded into
    this delivery.

package/.agents/rules/git-conventions-reference.md

@@ -37,8 +37,10 @@ which deleted the existing compatibility shim layer across
 `wave-session.js`, `IExecutionAdapter` / `ManualDispatchAdapter`, lifecycle
 emit shims, and duplicate progress/comment writers in one pass. The
 per-finding closing references (audit Findings #10, #11, #13, #17) live in
-the merged PRs and the Epic #2646 history; the standing forward-looking
-audit lives at [`docs/roadmap.md`](../../docs/roadmap.md) (Part 1 — Model-Evolution Audit).
+the merged PRs and the Epic #2646 history; the Part 1 — Model-Evolution
+Audit analysis this section grew out of is preserved at
+`docs/roadmap.md` @ tag `mandrel-v1.94.0` (see the Historical-anchors
+table in the live [`docs/roadmap.md`](../../docs/roadmap.md)).
 
 Practical guidance when authoring a contract change:
 
@@ -79,15 +81,14 @@ checkout — reaping its own merged refs and fast-forwarding the base branch.
 `/git-cleanup` is a recovery tool, not a routine chore.** The mechanics behind
 that invariant:
 
-Every flow that lands work — `/deliver` (Epic and standalone-Story paths),
-`/git-deliver` — is responsible for leaving the local checkout tidy without
+Every flow that lands work — `/deliver` and `/git-deliver` — is responsible
+for leaving the local checkout tidy without
 operator intervention:
 
-- **Fast-forwarding the base branch is owned by the flow.** The standalone
-  multi-Story path fast-forwards `main` itself in its summary phase (via
-  `git-cleanup.js --fast-forward-main --execute --yes`); the Epic path
-  fast-forwards `epic/<id>` / `main` on its merge-and-reap beat. No workflow
-  ends by telling the operator to "run `/git-cleanup` afterwards to catch up".
+- **Fast-forwarding the base branch is owned by the flow.** `/deliver`
+  fast-forwards `main` itself in its cleanup phase (via
+  `git-cleanup.js --fast-forward-main --execute --yes`). No workflow ends by
+  telling the operator to "run `/git-cleanup` afterwards to catch up".
 - **Reaping merged local refs is owned by the flow's next boot.** `/plan` and
   `/git-deliver` open with a **protected boot sweep**
   (`boot-sweep.js`) that fast-forwards `main`, prunes stale remote-tracking
@@ -118,55 +119,44 @@ operator intervention:
   owning flow's hygiene step regressed — fix the flow, do not codify the manual
   sweep.
 
-### Shared-checkout contention (Story #4460)
-
-`story-close.js`'s merge phase runs `git checkout <epic-branch>` directly in
-the **shared main repo checkout** (`close-inputs.js` resolves `mainCwd` to
-`PROJECT_ROOT`), not an isolated worktree. `lib/epic-merge-lock.js` guards
-that checkout with a **per-Epic** filesystem lock
-(`epic-<epicId>.merge.lock`) so two `story-close.js` runs for the **same**
-Epic serialize against each other — but nothing stops a **different**
-Epic's concurrently-running `story-close.js` from treating the same shared
-checkout as scratch space at the same time.
-
-- **Recognition signature**: a `git checkout`/`git switch` failure during
-  the merge phase whose message is `error: Your local changes ... would be
-  overwritten by checkout`, where the shared checkout is parked on a
-  **different** epic's branch (e.g. `epic/4405`) than the one the current
-  `story-close.js` run is trying to merge (e.g. `epic/4425`), with
-  uncommitted edits that belong to that other Epic's delivery. This was
-  observed live during Epic #4425 delivery (Stories #4427/#4428) colliding
-  with a concurrently-running Epic #4405 session, and had to be worked
-  around by hand via `git stash push -u`.
-- **The fix — `assertSharedCheckoutAvailable`**
-  (`lib/orchestration/story-close/shared-checkout-guard.js`), called from
-  `runFinalizeMerge` in `lib/orchestration/story-close/merge-runner.js`
-  immediately before the merge-phase `git checkout <epicBranch>`. It
-  **composes with, not replaces,** the per-Epic lock:
-  - It first checks the shared common `.git/` dir for a **foreign**
-    (different-epic) `epic-*.merge.lock` file whose recorded PID is still
-    alive (`findForeignActiveEpicLock` in `lib/epic-merge-lock.js`). If
-    found, the merge phase fails fast with a diagnostic naming the holding
-    epic id, its lock-file path, and its PID/acquired-at timestamp —
-    instead of surfacing the raw git checkout error.
-  - It then checks whether the shared checkout is simply dirty (via `git
-    status --porcelain`), regardless of whose branch is checked out, and
-    reports the dirty file list plus the currently-checked-out branch in
-    the failure diagnostic.
-  - It never inspects the **caller's own** epic-id lock namespace, so
-    same-epic concurrent `story-close.js` runs continue to serialize
-    solely through `withEpicMergeLock` (the existing per-Epic lock) before
-    this guard ever executes — this guard only ever refuses on a truly
-    _foreign_ epic's live lock or unrelated dirt.
-- **Not fixed by this guard**: the guard reports the contention early and
-  actionably; it does not redesign the merge phase to use an isolated
-  worktree, and it does not change `restoreStartingBranch`'s existing
-  dirty-tree refusal behavior (`phases/branch-restore.js`) — both remain
-  out of scope. Resolution of an actual collision is still manual: wait for
-  the other Epic's story-close run to finish, or — only once you have
-  independently confirmed that process is no longer running — remove the
-  stale lock file and resolve the dirty tree by hand (stash/commit/reset;
-  never `git reset --hard` or `git checkout --force`).
+### Shared-checkout contention (Stories #4460, #4424, #4545)
+
+**One delivery per checkout is the model.** v2 has no Epic integration branch
+and no merge phase that parks the shared checkout on someone else's branch:
+each Story works in its own worktree (`.worktrees/story-<id>/`) and lands by
+pushing `story-<id>` and opening a PR. The Epic-era collision this section used
+to describe — `story-close.js` running `git checkout <epic-branch>` in the
+shared main checkout under a per-Epic `epic-*.merge.lock` — is gone with the
+machinery that caused it (Story #4545 deleted the last of that prose; the six
+modules it named had already been removed in the v2.0.0 cutover).
+
+Two guards remain, and they cover different hazards:
+
+- **Per-Story lease** (`lib/orchestration/single-story-lease-guard.js`). The
+  standalone path has no Epic-scoped dispatch manifest to serialize two
+  operators driving the **same** Story, so `single-story-init.js` takes an
+  exclusive, time-bounded lease on the Story ticket (assignee-as-lease) and
+  clears it at close. It **fails closed** on a foreign assignee — there is no
+  heartbeat ledger to judge staleness from — so a foreign holder always blocks
+  unless you pass `--steal`, which you should do only after independently
+  confirming the other run is dead.
+
+- **Wrong-tree guard** (`lib/orchestration/single-story-close/phases/wrong-tree-guard.js`,
+  Stories #3364 / #4424). `cd <workCwd>` steers the Bash tool's cwd but does
+  **not** scope path-based Edit/Write tools, which resolve absolute paths and
+  ignore cwd. An agent whose shell is correctly inside the worktree can still
+  edit the main checkout; close then gates a clean worktree and opens a
+  silent empty-diff PR. The guard inspects
+  `git -C <mainCheckout> status --porcelain` and intersects stray **tracked**
+  paths with the Story's own diff-path set, so a concurrent session's unrelated
+  dirt does not false-positive (framework-gap #4420). Untracked files are
+  ignored as scratch.
+
+- **Recognition signature**: close aborts naming stray files in the main
+  checkout that intersect the Story's diff. **Resolution**: relocate those
+  edits under the worktree, restore the main checkout
+  (`git -C <main-repo> checkout -- <files>`), then re-run `/deliver <storyId>`.
+  Never `git reset --hard` or `git checkout --force` to clear the way.
 
 ## Documentation Freshness Gate
 

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

@@ -12,28 +12,22 @@ live in the on-demand
 **before** doing the matching work; the core below is sufficient for every
 routine commit, branch, and PR.
 
-## Canonical Branching (v5 Orchestration)
-
-### Epic Base Branch
-
-Each Epic operates on a dedicated **Epic base branch** named `epic/[EPIC_ID]`
-(e.g., `epic/98`). This branch is created from the project's base branch
-(`main` by default) and serves as the integration target for all Stories
-within that Epic.
-
-### Story-Level Branching
-
-All tasks within a Story MUST be committed to a shared **Story branch**:
-`story-<storyId>` (e.g., `story-104`). The runtime owns Story branch
-creation via `story-init.js`; agents commit on the active Story branch only.
-
-> **Commit subjects.** Under the 2-tier hierarchy
-> (Epic → Story), Stories have no child tickets. Commits
-> land on `story-<storyId>` directly from the agent and the
-> Conventional Commit subject references the parent Story via
-> `(refs #<storyId>)`. See
-> [`.agents/instructions.md` § 5.D](../instructions.md) for the
-> full hierarchy contract.
+## Canonical Branching (v2)
+
+### Story branch → PR → main
+
+Every Story lands on a dedicated **Story branch** named `story-<storyId>`
+(e.g., `story-104`), seeded from `project.baseBranch` (`main` by default).
+The runtime owns branch creation via `single-story-init.js`; agents commit
+on that branch only. Close opens a PR against `main` (squash + required
+checks). There is **no** `epic/<id>` integration branch and no `--no-ff`
+wave merge.
+
+> **Commit subjects.** Stories have no child tickets. Commits land on
+> `story-<storyId>` directly from the agent and the Conventional Commit
+> subject references the Story via `(refs #<storyId>)`. See
+> [`.agents/instructions.md` § 5.D](../instructions.md) for the hierarchy
+> contract.
 
 ## Conventional Commits