mandrel 1.92.0 → 1.94.0

package/.agents/personas/engineer.md

@@ -1,119 +1,33 @@
-# Role: Senior Software Engineer (General)
+# Role: Software Engineer (default)
 
-## 1. Primary Objective
+You are the builder. You turn a Story's binding contract into clean, tested,
+type-safe code. This is the default persona; it covers backend, shared
+libraries, and cross-cutting work.
 
-You are the builder. Your goal is to write clean, efficient, and bulletproof
-code that executes the plans designed by the Architect. You value **type
-safety**, **testability**, and **readability**.
+**Golden rule:** never guess. When the Story's acceptance is silent on a
+business rule, stop and ask rather than invent one.
 
-**Golden Rule:** Never guess. If a requirement is missing from the Architect's
-plan, stop and ask. Do not invent business logic.
-
-> **Note:** For platform-specific frontend work, prefer the dedicated
-> `engineer-web.md` or `engineer-mobile.md` personas. This general persona is
-> best suited for backend implementation, shared libraries, and cross-cutting
-> concerns that are not scoped to a single platform.
-
-## 2. Interaction Protocol
-
-1. **Read Context:** Before writing a single line, read the parent Epic
-   body — the single planning document, including its `## User Stories`
-   section and the folded Tech Spec sections (`## Delivery Slicing`
-   onward; Story #4324 retired the separate Tech Spec ticket) — plus the
-   docs digest (digest-first with pull-on-demand; see
-   [`.agents/instructions.md` § 3](../instructions.md) — there is no
-   read-every-`project.docsContextFiles`-file mandate).
-2. **Workspace Awareness:** Identify if you are working in a monorepo or a
-   standard repo. Ensure all commands (installing packages, running scripts) are
-   executed in the correct workspace/directory. Check `package.json` or the
-   workspace root configuration to determine the correct scope.
-3. **Implementation:** Write the code in small, logical chunks (atomic steps).
-4. **Verification:** Immediately write/run a test or verification script to
-   ensure the code works.
-5. **Cleanup:** Remove debug logs and comments that only explain _what_ code
-   does (keep comments that explain _why_).
-
-## 3. Coding Standards
-
-### A. Type Safety & Validation
-
-- **Strict Typing:** Always utilize the strictest settings of the project's
-  language (e.g., `strict: true` in TypeScript). Avoid `any` or untyped
-  variables.
-- **Interfaces:** Export interfaces/types for all props and data models.
-- **Validation:** Use the project's established schema validation library for
-  all API inputs and external data parsing.
-
-### B. Function Design
-
-- **Single Responsibility:** A function should do one thing. If it's too long,
-  refactor.
-- **Pure Functions:** Prefer pure functions (output depends only on input) to
-  make testing easier.
-- **Early Returns:** Use guard clauses to handle errors early and reduce
-  nesting.
-
-### C. Implementation Latitude (Logged Deviation)
+## Implementation Latitude (logged deviation)
 
 A Story's `changes[]` and `references[]` are an **advisory implementation
-sketch** — the author's best prediction of the file footprint, not a binding
-instruction. Its `acceptance[]` and `verify[]` arrays are the **binding
-contract** and the only definition of "done."
+sketch** of the file footprint. Its `acceptance[]` and `verify[]` arrays are the
+**binding contract** and the only definition of done.
 
 - **You MAY deviate from the suggested approach** when the real codebase
-  diverges from the sketch — touch a different file, choose a different
-  internal seam, fold or split the predicted edits — **provided you record
-  the rationale**. Note the deviation and the reason in your commit body (or
-  the Story's progress comment), e.g. `the sketched helper already exists in
-  lib/x.js, so I extended it rather than creating lib/y.js`. This converts
-  silent drift into a logged signal a reviewer can audit.
-- **The latitude is bounded and never overrides the inviolable layer.** It
-  applies to the **implementation approach only**. It does **not** license
-  deviating from `acceptance[]` / `verify[]` (you MUST still satisfy every
-  acceptance item and run every verify command to green), and it does **not**
-  license relaxing any `rules/security-baseline.md` MUST or any other
-  inviolable rule. When in doubt, the binding contract and the security
-  baseline win — per the precedence ordering in
-  [`.agents/instructions.md` § 1.K](../instructions.md).
-- **Unlogged deviation is the anti-pattern.** Reshaping the footprint without
-  recording why is the silent drift this latitude exists to surface. If you
-  cannot state the reason in a sentence, re-examine whether the deviation is
-  warranted.
-
-## 4. Testing & Verification
-
-1. **Test-Driven:** Write tests for utilities, logic helpers, and API routes
-   using the project's configured testing framework.
-2. **Self-Correction:** If you run a command and it fails, **read the error**,
-   analyze it, and fix it automatically.
-3. **Verification Before Done:** Never mark a task complete without proving it
-   works.
-
-## 5. File Management & Safety
-
-- **Filename Comment:** Always start code blocks with the file path (e.g.,
-  `// src/lib/utils.ts`).
-- **Create/Edit:** You are authorized to create new files and edit existing
-  ones.
-- **Delete:** **NEVER** delete a file without explicit user confirmation.
-- **Imports:** Respect the project's import alias conventions (e.g.,
-  `@/components/`).
-
-## 6. Scope Boundaries
-
-**This persona does NOT:**
-
-- Design system architecture or write technical specifications.
-- Write PRDs, user stories, or make product scoping decisions.
-- Design UX flows, component states, or visual hierarchy.
-- Manage CI/CD pipelines, infrastructure, or deployment configuration.
-- Write or execute E2E test plans (use `qa-engineer.md` for that).
-
-**Automatic Referral Protocol:** If you are asked to perform a task that falls
-outside the responsibilities defined in this file, **do not attempt it**.
-Instead:
-
-1. Briefly state which part of the request is outside your scope.
-2. Read the `.agents/personas/` directory to identify the correct persona.
-3. Automatically adopt that persona's instructions for the out-of-scope portion
-   of the work and continue execution seamlessly.
+  diverges from the sketch — touch a different file, pick a different seam, fold
+  or split the predicted edits — **provided you record the rationale** in the
+  commit body or the Story's progress comment (e.g. "the sketched helper already
+  exists in `lib/x.js`, so I extended it rather than creating `lib/y.js`").
+  Logged deviation turns silent drift into a signal a reviewer can audit;
+  unlogged reshaping is the anti-pattern this latitude exists to surface.
+- **The latitude applies to the implementation approach only.** It does **not**
+  license deviating from `acceptance[]` / `verify[]` (satisfy every item and run
+  every verify command to green), and it does **not** license relaxing a
+  `rules/security-baseline.md` MUST. When in doubt the binding contract and the
+  security baseline win (precedence: `.agents/instructions.md` § 1.K).
+
+## Working rhythm
+
+Write in small atomic steps and prove each one with a test before moving on.
+When a command fails, read the error and fix it rather than working around it.
+Never mark a task done without running its `verify[]` commands to green.

package/.agents/personas/security-engineer.md

@@ -13,8 +13,7 @@ all third-party services will be compromised. Design every system to fail
 securely.
 
 > **Note:** For CI/CD pipeline security gates and secret scanning automation,
-> coordinate with `devops-engineer.md`. For production incident response and
-> secret rotation, coordinate with `sre.md`.
+> coordinate with `devops-engineer.md`.
 
 ## 2. Interaction Protocol
 

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

@@ -0,0 +1,225 @@
+# Git Conventions — Reference (on-demand)
+
+**This rule applies when** you are reasoning about a git-history mechanic that
+the always-on core [`git-conventions.md`](git-conventions.md) deliberately
+summarizes: authoring a **contract change** (config/schema/lifecycle/label/API
+shape), triaging a **push-hook false-negative**, resolving **shared-checkout
+merge contention**, satisfying the **documentation-freshness gate**, or routing
+a retrospective signal via a **`meta::*` label**. The core carries the
+per-commit MUSTs; this file carries the detail behind them. Nothing here
+relaxes a core MUST — read it when the matching work is in play.
+
+## Contract Cutovers — No Shim Layer
+
+Mandrel ships as the `mandrel` npm package, whose consumers pin an
+exact lockfile version; they opt into breaks at upgrade time. Operator policy
+for any contract change (config shape, baseline shape, schema, lifecycle
+payload, ticket label, dispatch artifact, public API of a script) is
+therefore:
+
+1. **Hard cutovers only.** Contract changes ship as a single in-tree
+   migration of every producer and consumer. There is no parallel
+   old-shape support code, no read-side tolerance branch, and no
+   feature flag that toggles between the two shapes.
+2. **The PR diff IS the migration.** A consumer upgrading to a release
+   with the change adopts the new shape by upgrading the
+   `mandrel` package (`mandrel update`). The PR that lands on
+   `main` already moved every internal call site; consumers move on the
+   same beat by upgrading.
+3. **No deprecation ledger, no version-windowed sunsets.** The framework
+   does not track "to be removed in vX.Y" entries or run two shapes side
+   by side for a release window. If a shape changes, the old shape is
+   deleted in the same PR.
+
+The codifying decision is **Epic #2646** (the "Hard-Cutover Cleanup Epic"),
+which deleted the existing compatibility shim layer across
+`config-resolver.js`, `lib/config/*.js`, `lib/baselines/`,
+`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).
+
+Practical guidance when authoring a contract change:
+
+- If you are tempted to add a "legacy shape" branch in a parser or
+  resolver, **don't** — update every call site instead, and delete the
+  old shape in the same PR.
+- If you cannot land every call site in a single PR (e.g. a
+  cross-repository change), the contract change is too large for one
+  hard cutover. Split the contract itself, not the rollout.
+- Schema versions remain useful as **identifiers** (so a future consumer
+  can detect "I cannot read this artifact"); they are **not** an
+  invitation to keep multiple readers alive in the same release.
+
+## Push Validation — the known false-negative signature
+
+The core rule is: **never bypass hooks** (`--no-verify`, `--no-gpg-sign`, or
+other hook-skipping flags) unless the operator explicitly authorizes it, and
+if a hook fails, investigate the underlying cause. One recognized exception
+signature is worth naming:
+
+- **Known false-negative signature**: a `pre-push`/`pre-commit` failure
+  whose message is a _zero-match_ error (e.g. Biome's
+  `No files were processed in the specified paths`) rather than a
+  reported violation, combined with an agent CWD under a harness-managed
+  worktree path a consumer's lint config ignores (e.g.
+  `.claude/worktrees/<name>/` against a `files.includes` glob like
+  `"!**/.claude"`), is a **consumer-tooling gap**, not a real lint
+  failure. It does not authorize `--no-verify`. See
+  [`worktree-lifecycle.md` § Harness-worktree ⇄ consumer-lint-ignore interaction](../workflows/helpers/worktree-lifecycle.md#harness-worktree-consumer-lint-ignore-interaction-story-152)
+  for the recognition signature and the sanctioned consumer-side fix
+  (`--no-errors-on-unmatched` or equivalent) before escalating via
+  `agent::blocked`.
+
+## Local checkout hygiene — full mechanics
+
+**Invariant (stated in the core): the delivering flow owns tidying the local
+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
+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".
+- **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
+  refs, and reaps every local branch whose PR is already merged — skipping any
+  candidate with unpushed work, a dirty worktree, or a still-open parent
+  ticket. A branch a flow leaves behind (e.g. a `/git-deliver` feature branch
+  whose PR merges out of band) is therefore reaped automatically at the next
+  workflow boot, not left for the operator to sweep by hand. `boot-sweep.js`
+  defaults its `--include` glob to `story-*` — a bare invocation only sweeps
+  Story branches; `/plan` and `/git-deliver` widen the scope to their own
+  branch namespaces (`epic/*`, `feat/*`, `fix/*`, `chore/*`, `docs/*`,
+  `refactor/*`) by passing `--include` explicitly at their boot call site.
+  A branch the planner detects only via the weaker content-equivalence
+  signal (`detectedBy: 'content-merged'`, Story #4395's
+  `git merge-tree --write-tree` probe — content already landed in the base
+  branch by another route, such as a squash-merged Epic PR, with no merged
+  PR or git ancestry of its own) is **never** reaped by the boot sweep: it
+  is report-only, surfaced under `contentMerged` in the result envelope and
+  a routing hint in the summary line (Story #4396), so the operator can
+  send it to `/git-cleanup` for a confirmed, eyeballed reap.
+- **`/git-cleanup` is recovery, not routine.** Run it by hand only to recover
+  an unusual state the automated hygiene does not cover — triaging stashes,
+  reaping across non-standard branch namespaces, or `--remote` pruning after a
+  force-push diverged a tip. It is **not** the expected way to keep `main`
+  current or to clear merged branches after a normal delivery; the delivering
+  flows already own that. If you find yourself reaching for `/git-cleanup`
+  after every routine `/deliver` or `/git-deliver` run, that is a signal the
+  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`).
+
+## Documentation Freshness Gate
+
+The `validate-docs-freshness.js` gate (run during `/deliver`) asks a
+falsifiable question of every doc in `delivery.docsFreshness.paths` +
+`project.docsContextFiles`: **was this doc actually updated for the Epic?**
+A doc passes on either of two conditions, but they are not
+interchangeable:
+
+- **Living docs are satisfied by being rewritten, not annotated.** For
+  any non-changelog doc (architecture, decisions, README, guides, …) the
+  gate passes **only** when an Epic-referencing commit touched the file —
+  a commit whose message references `#<epicId>` and changes the doc.
+  Rewrite the doc as part of the Epic's work; do not sprinkle `#<epicId>`
+  into its prose to satisfy the check. An appended `#<epicId>` annotation
+  alone **fails** the gate for these files, and the failure message names
+  the file and the rewrite-not-append contract.
+- **`#<epicId>` body annotations pass only for changelog files.** A
+  changelog-class file (basename matches `/changelog/i`, e.g.
+  `docs/CHANGELOG.md`) may pass on a body annotation, because an appended
+  release note keyed to the Epic is the legitimate, expected update there.
+  This is the single sanctioned annotation path; every other doc must use
+  the rewrite path above.
+
+This restriction exists to remove the perverse incentive by which the
+gate would otherwise reward manufacturing fake provenance — appending
+Epic-ID history into living docs purely to clear the check.
+
+## Meta Labels (Retrospective Signal Routing)
+
+Two `meta::*` labels route retrospective signals into durable substrates so
+the `/plan` Phase 0 fetcher (see
+[`prior-feedback-fetcher.js`](../scripts/lib/feedback-loop/prior-feedback-fetcher.js))
+can surface open feedback issues to the planner. Both labels live in
+[`label-constants.js`](../scripts/lib/label-constants.js) under the
+`META_LABELS` export — reference them by symbol from scripts rather than
+hard-coding the string.
+
+### `meta::framework-gap`
+
+Apply this label to a GitHub issue that surfaces a defect, missing
+capability, or weak ergonomic in the **framework itself** (anything under
+`.agents/` or the dispatcher engine). Typical sources: a retrospective that
+identifies a workflow that does not yet exist, a hook that should fire but
+does not, or a script-level usability problem that should be solved
+upstream rather than worked around in a consumer project.
+
+### `meta::consumer-improvement`
+
+Apply this label to a GitHub issue that surfaces an improvement that lives
+in a **consumer project** (workflow tweaks, ergonomic asks, doc polish, or
+project-local automation). The work is scoped to the consumer's
+`.agents/`-driven layer or the consumer's own codebase, not to upstream
+framework changes. Issues that span both axes should carry both labels —
+`fetchPriorFeedback` dedupes by issue number so a dual-labeled issue
+appears exactly once in the planner context.

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

@@ -1,7 +1,16 @@
 # Git & Version Control Conventions
 
 This rule applies globally to all repository changes to maintain a clean git
-history.
+history. It is the **always-on core**: branch shapes, the Conventional-Commit
+subject contract, issue references, and the non-negotiable push/hygiene MUSTs.
+
+Deeper mechanics — the hard-cutover contract policy, the push-hook
+false-negative signature, shared-checkout merge contention, the
+documentation-freshness gate, and the `meta::*` retrospective-routing labels —
+live in the on-demand
+[`git-conventions-reference.md`](git-conventions-reference.md). Read that file
+**before** doing the matching work; the core below is sufficient for every
+routine commit, branch, and PR.
 
 ## Canonical Branching (v5 Orchestration)
 
@@ -44,49 +53,6 @@ creation via `story-init.js`; agents commit on the active Story branch only.
   titles edited in the GitHub UI; author the PR title in conventional form
   so the squash commit on `main` parses cleanly for release-please.
 
-## Contract Cutovers — No Shim Layer
-
-Mandrel ships as the `mandrel` npm package, whose consumers pin an
-exact lockfile version; they opt into breaks at upgrade time. Operator policy
-for any contract change (config shape, baseline shape, schema, lifecycle
-payload, ticket label, dispatch artifact, public API of a script) is
-therefore:
-
-1. **Hard cutovers only.** Contract changes ship as a single in-tree
-   migration of every producer and consumer. There is no parallel
-   old-shape support code, no read-side tolerance branch, and no
-   feature flag that toggles between the two shapes.
-2. **The PR diff IS the migration.** A consumer upgrading to a release
-   with the change adopts the new shape by upgrading the
-   `mandrel` package (`mandrel update`). The PR that lands on
-   `main` already moved every internal call site; consumers move on the
-   same beat by upgrading.
-3. **No deprecation ledger, no version-windowed sunsets.** The framework
-   does not track "to be removed in vX.Y" entries or run two shapes side
-   by side for a release window. If a shape changes, the old shape is
-   deleted in the same PR.
-
-The codifying decision is **Epic #2646** (the "Hard-Cutover Cleanup Epic"),
-which deleted the existing compatibility shim layer across
-`config-resolver.js`, `lib/config/*.js`, `lib/baselines/`,
-`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).
-
-Practical guidance when authoring a contract change:
-
-- If you are tempted to add a "legacy shape" branch in a parser or
-  resolver, **don't** — update every call site instead, and delete the
-  old shape in the same PR.
-- If you cannot land every call site in a single PR (e.g. a
-  cross-repository change), the contract change is too large for one
-  hard cutover. Split the contract itself, not the rollout.
-- Schema versions remain useful as **identifiers** (so a future consumer
-  can detect "I cannot read this artifact"); they are **not** an
-  invitation to keep multiple readers alive in the same release.
-
 ## Push Validation & Reliability
 
 To prevent "silent" push failures (e.g., hidden by multi-command chains or
@@ -106,19 +72,12 @@ rejected by `pre-push` hooks):
     contained more than the linting fix.
 4.  **Never bypass hooks**: Do not use `--no-verify`, `--no-gpg-sign`, or
     other hook-skipping flags unless the operator explicitly authorizes it.
-    If a hook fails, investigate the underlying cause.
-    - **Known false-negative signature**: a `pre-push`/`pre-commit` failure
-      whose message is a _zero-match_ error (e.g. Biome's
-      `No files were processed in the specified paths`) rather than a
-      reported violation, combined with an agent CWD under a harness-managed
-      worktree path a consumer's lint config ignores (e.g.
-      `.claude/worktrees/<name>/` against a `files.includes` glob like
-      `"!**/.claude"`), is a **consumer-tooling gap**, not a real lint
-      failure. It does not authorize `--no-verify`. See
-      [`worktree-lifecycle.md` § Harness-worktree ⇄ consumer-lint-ignore interaction](../workflows/helpers/worktree-lifecycle.md#harness-worktree-consumer-lint-ignore-interaction-story-152)
-      for the recognition signature and the sanctioned consumer-side fix
-      (`--no-errors-on-unmatched` or equivalent) before escalating via
-      `agent::blocked`.
+    If a hook fails, investigate the underlying cause. One recognized
+    exception — a Biome _zero-match_ failure under a harness-managed
+    worktree path the consumer's lint config ignores — is a consumer-tooling
+    gap, **not** authorization to skip the hook; its recognition signature
+    and sanctioned fix live in
+    [`git-conventions-reference.md` § Push Validation](git-conventions-reference.md).
 
 ## Local checkout hygiene
 
@@ -127,149 +86,15 @@ own merged refs and fast-forwarding the base branch. `/git-cleanup` is a
 recovery tool, not a routine chore.**
 
 Every flow that lands work — `/deliver` (Epic and standalone-Story paths),
-`/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".
-- **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
-  refs, and reaps every local branch whose PR is already merged — skipping any
-  candidate with unpushed work, a dirty worktree, or a still-open parent
-  ticket. A branch a flow leaves behind (e.g. a `/git-deliver` feature branch
-  whose PR merges out of band) is therefore reaped automatically at the next
-  workflow boot, not left for the operator to sweep by hand. `boot-sweep.js`
-  defaults its `--include` glob to `story-*` — a bare invocation only sweeps
-  Story branches; `/plan` and `/git-deliver` widen the scope to their own
-  branch namespaces (`epic/*`, `feat/*`, `fix/*`, `chore/*`, `docs/*`,
-  `refactor/*`) by passing `--include` explicitly at their boot call site.
-  A branch the planner detects only via the weaker content-equivalence
-  signal (`detectedBy: 'content-merged'`, Story #4395's
-  `git merge-tree --write-tree` probe — content already landed in the base
-  branch by another route, such as a squash-merged Epic PR, with no merged
-  PR or git ancestry of its own) is **never** reaped by the boot sweep: it
-  is report-only, surfaced under `contentMerged` in the result envelope and
-  a routing hint in the summary line (Story #4396), so the operator can
-  send it to `/git-cleanup` for a confirmed, eyeballed reap.
-- **`/git-cleanup` is recovery, not routine.** Run it by hand only to recover
-  an unusual state the automated hygiene does not cover — triaging stashes,
-  reaping across non-standard branch namespaces, or `--remote` pruning after a
-  force-push diverged a tip. It is **not** the expected way to keep `main`
-  current or to clear merged branches after a normal delivery; the delivering
-  flows already own that. If you find yourself reaching for `/git-cleanup`
-  after every routine `/deliver` or `/git-deliver` run, that is a signal the
-  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`).
-
-## Documentation Freshness Gate
-
-The `validate-docs-freshness.js` gate (run during `/deliver`) asks a
-falsifiable question of every doc in `delivery.docsFreshness.paths` +
-`project.docsContextFiles`: **was this doc actually updated for the Epic?**
-A doc passes on either of two conditions, but they are not
-interchangeable:
-
-- **Living docs are satisfied by being rewritten, not annotated.** For
-  any non-changelog doc (architecture, decisions, README, guides, …) the
-  gate passes **only** when an Epic-referencing commit touched the file —
-  a commit whose message references `#<epicId>` and changes the doc.
-  Rewrite the doc as part of the Epic's work; do not sprinkle `#<epicId>`
-  into its prose to satisfy the check. An appended `#<epicId>` annotation
-  alone **fails** the gate for these files, and the failure message names
-  the file and the rewrite-not-append contract.
-- **`#<epicId>` body annotations pass only for changelog files.** A
-  changelog-class file (basename matches `/changelog/i`, e.g.
-  `docs/CHANGELOG.md`) may pass on a body annotation, because an appended
-  release note keyed to the Epic is the legitimate, expected update there.
-  This is the single sanctioned annotation path; every other doc must use
-  the rewrite path above.
-
-This restriction exists to remove the perverse incentive by which the
-gate would otherwise reward manufacturing fake provenance — appending
-Epic-ID history into living docs purely to clear the check.
-
-## Meta Labels (Retrospective Signal Routing)
-
-Two `meta::*` labels route retrospective signals into durable substrates so
-the `/plan` Phase 0 fetcher (see
-[`prior-feedback-fetcher.js`](../scripts/lib/feedback-loop/prior-feedback-fetcher.js))
-can surface open feedback issues to the planner. Both labels live in
-[`label-constants.js`](../scripts/lib/label-constants.js) under the
-`META_LABELS` export — reference them by symbol from scripts rather than
-hard-coding the string.
-
-### `meta::framework-gap`
-
-Apply this label to a GitHub issue that surfaces a defect, missing
-capability, or weak ergonomic in the **framework itself** (anything under
-`.agents/` or the dispatcher engine). Typical sources: a retrospective that
-identifies a workflow that does not yet exist, a hook that should fire but
-does not, or a script-level usability problem that should be solved
-upstream rather than worked around in a consumer project.
-
-### `meta::consumer-improvement`
-
-Apply this label to a GitHub issue that surfaces an improvement that lives
-in a **consumer project** (workflow tweaks, ergonomic asks, doc polish, or
-project-local automation). The work is scoped to the consumer's
-`.agents/`-driven layer or the consumer's own codebase, not to upstream
-framework changes. Issues that span both axes should carry both labels —
-`fetchPriorFeedback` dedupes by issue number so a dual-labeled issue
-appears exactly once in the planner context.
+`/git-deliver` — leaves the local checkout tidy without operator
+intervention: it fast-forwards the base branch itself, and reaps its own
+merged local refs on the next workflow boot (the `boot-sweep.js` protected
+sweep). Do **not** end a workflow by telling the operator to run
+`/git-cleanup` to catch up; `/git-cleanup` is for recovering an unusual state
+the automated hygiene does not cover. The boot-sweep scope rules, the
+content-merged report-only case, and the shared-checkout merge-contention
+guard are detailed in
+[`git-conventions-reference.md` § Local checkout hygiene](git-conventions-reference.md).
 
 ## Pull Requests