mandrel 2.0.0 → 2.2.0

package/.agents/docs/quality-gates.md

@@ -17,9 +17,8 @@ the lift the floor gate represents.
 
 The configuration knobs that drive these gates live in
 [`.agents/docs/configuration.md`](../docs/configuration.md) under
-`delivery.quality.*` and the framework-internal `DEFAULT_STORY_MERGE_RETRY` constant. This
-file is the runbook side — what the gate does, when it fires, and how to
-bootstrap or refresh it.
+`delivery.quality.*`. This file is the runbook side — what the gate does,
+when it fires, and how to bootstrap or refresh it.
 
 The **baseline envelope, per-kind shapes, component model, writer/reader
 contract, and floor-override path** are documented in the
@@ -37,14 +36,13 @@ it once and reuse the context as you read through any individual gate.
 ## Concurrent close safety
 
 `/deliver` may close multiple Stories from separate Story branches in quick
-succession. The push step inside `single-story-close.js` refreshes against the
-latest `main` and retries a rejected Story-branch push — bounded by
-`DEFAULT_STORY_MERGE_RETRY.maxAttempts` (3) and
-`DEFAULT_STORY_MERGE_RETRY.backoffMs` (`[250, 500, 1000]`) from
-`.agents/scripts/lib/config/runners.js`.
-A real
-content conflict (both stories touched the same lines) aborts the loop
-with a clear error and leaves the local tree clean for manual resolution.
+succession. Each Story rebases onto the latest `main` in its own base-sync
+phase (`phases/base-sync.js`) before the push, so concurrent closes serialize
+through their own worktrees rather than racing one shared branch. The push
+step itself does not retry: a rejected push fails the close non-zero and the
+operator resolves it, and a real content conflict (both Stories touched the
+same lines) surfaces at base-sync with a clear error, leaving the local tree
+clean for manual resolution.
 
 ---
 
@@ -262,9 +260,9 @@ per-round mechanic lives in
 with the gate CLI at
 [`.agents/scripts/acceptance-eval.js`](../scripts/acceptance-eval.js)).
 Each round, a fresh-context **critic pass** — independent of the
-implementing agent — scores the working diff against every inline
-`acceptance[]` item, using `verify[]` output as evidence, and yields one
-of three decisions:
+implementing agent — scores the change set its caller injected (never one
+it re-derives) against every inline `acceptance[]` item, using `verify[]`
+output as evidence, and yields one of three decisions:
 
 - **proceed** — all criteria met; the Story continues to close.
 - **redraft** — unmet criteria are redrafted and re-implemented, then
@@ -515,7 +513,7 @@ does not pause automatically on `risk::high`.
 
 The sole runtime HITL pause point is `agent::blocked`: when an agent
 encounters an unresolvable blocker (including unsafe destructive actions
-lacking explicit authorization), it flips the ticket/Epic to
+lacking explicit authorization), it flips the ticket to
 `agent::blocked`, posts friction context, and waits for operator resume
 (`agent::executing`).
 
@@ -753,10 +751,10 @@ Behaviour:
 - The `components` map is optional. When omitted, the default
   `{ "*": ["**"] }` applies and only `*` rows are ever evaluated.
 - The unified `check-baselines.js` reports breaches per component, with
-  `*` always present in the output. The per-component progress signals
-  (`crap-drift.js#detectComponentRegressions`,
-  `maintainability-drift.js#detectComponentRegressions`) name the
-  breached component in their bullet so a `*` rollup is not falsely
+  `*` always present in the output. The shared baselines kernel
+  (`lib/baselines/kernel.js`, via the per-kind rollups in
+  `lib/baselines/kinds/`) groups rows by component and names the
+  breached component in its output so a `*` rollup is not falsely
   implicated when only a component-scoped floor was crossed.
 
 #### Floor axes must match rollup axes

package/.agents/docs/workflows.md

@@ -14,10 +14,10 @@ modules, not runnable commands). The canonical workflow narrative lives in
 compose. This file is only for "which command does X?" lookups.
 
 Every command file lives at `.agents/workflows/<name>.md` and is projected
-into a flat `.claude/commands/` tree by `npm run sync:commands` (the
-UserPromptSubmit hook keeps it current) so it shows up as a bare `/<name>`
-slash command (e.g. `/deliver`). The projection writes only
-`.claude/commands/<name>.md` — there is no plugin manifest and no
+into a flat `.claude/commands/` tree by `npm run sync:commands` (kept
+current at install time and on every `mandrel sync`/`update`) so it shows
+up as a bare `/<name>` slash command (e.g. `/deliver`). The projection
+writes only `.claude/commands/<name>.md` — there is no plugin manifest and no
 marketplace listing. The commands load in every Claude Code environment.
 
 Loop units are the one namespaced exception: files under
@@ -43,7 +43,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
 | `/audit-lighthouse` | Run a Lighthouse audit (Performance / Accessibility / Best Practices / SEO) and produce a structured findings report |
 | `/audit-navigability` | Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens (Epic #4131, F2/F3) exempt from the cross-epic-leak guard and routed onto route-adding change sets. |
-| `/audit-performance` | Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations. |
+| `/audit-performance` | Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`single-story-close`, dispatcher, gates); propose remediations. |
 | `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |
 | `/audit-quality` | Audit test coverage gaps, flaky tests, missing assertions, and test-pyramid balance; recommend a remediation batch. |
 | `/audit-security` | Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report. |
@@ -51,7 +51,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
 | `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --seed-file or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
-| `/deliver` | Unified delivery entry point. Delivers one or more Stories via the single deliver-story engine — story-<id> → PR → main. Sequences N>1 by depends\_on and runs the per-run epilogue once at the end. |
+| `/deliver` | Unified delivery entry point. Takes a list of Story ids, resolves their dependency graph from live state, and delivers each via the single deliver-story engine — story-<id> → PR → main. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |

package/.agents/instructions.md

@@ -38,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 →
@@ -157,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).
 
@@ -203,15 +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/deliver-story`), 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`
-sequencer 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 stall shape the parent run must detect and escalate.
+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)
 
@@ -258,14 +258,16 @@ Two carve-outs refine the ordering:
 
 ## 2. FinOps & Token Budgeting (Economic Guardrails)
 
-Mandrel does **not** enforce live LLM spend from response metadata. It caps
-**planning context budget** (`planning.context.maxBytes`) and related
-envelopes; 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.
 
 ---
 
@@ -273,70 +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/run-<id>/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/deliver-story`) does
-     **not** re-read the full `project.docsContextFiles` set per Story. When
-     the caller threads a `docsDigestPath`, use that compact outline to decide
-     which docs are relevant, then **pull the full file on demand**. When
-     `docsDigestPath` is null 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
@@ -429,10 +412,12 @@ 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 plan-runs.
+`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); N>1 shares a
-  `plan-run::<id>` label.
+- `/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

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

@@ -26,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
 
@@ -71,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/gherkin-standards.md

@@ -23,6 +23,16 @@ scenarios. Use the canonical set below; do not invent ad-hoc tags.
 - `@flaky` — operational quarantine tag. Scenarios carrying this tag are
   excluded from the gating suite and run in a dedicated non-blocking job
   until stabilized. Treat `@flaky` as a debt marker, not a permanent label.
+- `@skip` — scaffold-gating tag. Applied to scenarios scaffolded ahead of
+  their implementation (e.g. by a wave-0 BDD scaffold Story); the scenario
+  is excluded from the gating suite until the implementing Story removes
+  the tag (the "de-skip" edit). Unlike `@flaky`, `@skip` marks planned
+  not-yet-implemented behavior, never a stability problem.
+
+Retired: the `@epic-<id>-ac-N` namespaced AC tag. Its consumer
+(`acceptance-spec-reconciler.js`) was deleted in the v2 Epic removal, so
+the tag is inert — do not apply it to new scenarios. The `mandrel update`
+migration strips surviving instances from consumer feature files.
 
 Rules:
 

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:
 
@@ -117,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/schemas/acceptance-eval-verdict.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "acceptance-eval-verdict",
   "title": "Acceptance Self-Eval Verdict",
-  "description": "Structured output of one independent (fresh-context) acceptance self-eval round (Story #3819). Produced by the critic pass in the Story-implementation phase (helpers/deliver-story.md Step 1a), written under the gitignored temp tree, and consumed by acceptance-eval.js to enforce the bounded round cap and decide whether the Story proceeds to `closing`, redrafts, or escalates to `agent::blocked`. The author MUST NOT be the evaluator — the verdict is an independent judgment of the working diff against each inline acceptance[] item.",
+  "description": "Structured output of one independent (fresh-context) acceptance self-eval round (Story #3819). Produced by the critic pass in the Story-implementation phase (helpers/deliver-story.md Step 1a), written under the gitignored temp tree, and consumed by acceptance-eval.js to enforce the bounded round cap and decide whether the Story proceeds to `closing`, redrafts, or escalates to `agent::blocked`. The author MUST NOT be the evaluator — the verdict is an independent judgment of the caller-injected change set against each inline acceptance[] item.",
   "type": "object",
   "required": ["storyId", "schemaVersion", "round", "criteria"],
   "properties": {
@@ -52,7 +52,7 @@
           "verdict": {
             "type": "string",
             "enum": ["met", "partial", "unmet"],
-            "description": "Per-criterion judgment of the working diff. `met` clears the criterion; `partial` and `unmet` both trigger a redraft round (subject to the cap)."
+            "description": "Per-criterion judgment of the caller-injected change set. `met` clears the criterion; `partial` and `unmet` both trigger a redraft round (subject to the cap)."
           },
           "evidence": {
             "type": "string",