mandrel 1.58.0 → 1.60.0

package/.agents/workflows/audit-documentation.md

@@ -0,0 +1,226 @@
+---
+description: Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report.
+---
+
+# Documentation Staleness & Completeness Audit
+
+## Role
+
+Staff Engineer & Documentation Steward
+
+## Context & Objective
+
+You are auditing the repository's primary prose documentation to verify it
+is **up to date and complete**. Prose docs rot silently: commands get
+renamed, scripts move, described workflows change shape, and
+version/topology claims go stale. The deterministic gates
+(`check-doc-links.js`, `check-lifecycle-doc-drift.js`,
+`validate-docs-freshness.js`) catch broken links, drift against generators,
+and Epic-scoped freshness — they cannot tell whether the prose still
+describes how the code actually behaves. That semantic verification is this
+lens's job.
+
+## Target set (config-driven union)
+
+The audit target set is **not** "all markdown in the repo". Build it as the
+union of:
+
+1. **`project.docsContextFiles`** from `.agentrc.json` (each entry resolved
+   against `project.paths.docsRoot`, default `docs/`; skip absent files
+   silently).
+2. **`delivery.docsFreshness.paths`** from `.agentrc.json`.
+3. **Conventional anchors:** the root `README.md`, `AGENTS.md` /
+   `CLAUDE.md`, `CONTRIBUTING.md` (when present), and top-level `docs/*.md`
+   (non-recursive).
+4. **An explicit `--paths` override** — when the operator invokes the lens
+   with `--paths <file ...>`, add those files to the union. This is the
+   escape hatch for everything outside 1–3; there is no dedicated config
+   key for it.
+
+**Generated docs are excluded from per-doc semantic review.** The output of
+`generate-config-docs.js`, `generate-lifecycle-docs.js`, and
+`generate-workflows-doc.js`, and the synced `.claude/commands/` mirrors, are
+generator-owned: hand-editing them is never the remediation. Instead, Step 1
+runs the generators' `--check` mode and emits a **single** "generator output
+dirty" finding when their output is stale — the remediation is "rerun the
+generator", not "edit the doc". Auto-generated changelog files
+(`docs/CHANGELOG.md`, release-please-owned) are likewise excluded from
+semantic review beyond Step 1's deterministic checks.
+
+## Scope (Epic mode)
+
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
+following block is populated with the Epic's change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to the intersection of the target-set union and
+  those files — plus any target-set doc whose claims describe code in the
+  change set (a renamed script invalidates every doc that references it).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full target-set audit defined in the remaining steps.
+
+## Execution strategy (dual-path)
+
+This lens runs along one of two execution paths. Both emit the **identical**
+report contract (Step 3); downstream consumers (`/deliver` Phase 4
+epic-audit, `audit-to-stories`) are agnostic to which path produced it.
+
+- **Orchestrated (dynamic-workflow) path.** When Claude Code's
+  [dynamic workflows](https://code.claude.com/docs/en/workflows) are
+  available, the saved project workflow
+  `.claude/workflows/audit-documentation.workflow.js` fans the semantic
+  dimensions below out as parallel read-only subagents — each agent walks
+  the full target set per doc for its dimension — runs an **adversarial
+  verify** stage (an independent agent re-checks every stale-claim finding
+  against the current code and drops claims it cannot reproduce — doc
+  staleness is notoriously false-positive-prone), then synthesises the
+  Step 3 report. The orchestrator derives its per-dimension prompts from
+  *this* markdown at run time — the lens stays the single source of truth;
+  the script does not fork a second copy of the spec. Step 1's
+  deterministic checkers still run in the calling session (the analysis
+  subagents are read-only and cannot execute them); their results are
+  passed to the workflow as the `deterministicFindings` input and folded
+  into the synthesis.
+- **Sequential (single-pass) path.** When dynamic workflows are unavailable,
+  follow Steps 1–3 below turn-by-turn exactly as before. This is the default
+  fallback and changes nothing about the existing behaviour.
+
+**Strategy selection** is computed by
+[`lib/dynamic-workflow/capability.js`](../scripts/lib/dynamic-workflow/capability.js)
+(`selectAuditStrategy`). The orchestrated path is chosen only when the runtime
+is Claude Code, `disableWorkflows` is not set (settings.json **or**
+`CLAUDE_CODE_DISABLE_WORKFLOWS`), and the Claude Code version meets the
+research-preview floor (`>= 2.1.154`). Any other runtime, a disabled setting,
+or an older version degrades gracefully to the sequential path.
+
+> **Capability degradation, not a contract shim.** This dual path is **not**
+> covered by the No-Shim / hard-cutover rule in
+> [`git-conventions.md`](../rules/git-conventions.md). That rule forbids
+> running two shapes of the *same contract* side by side. Here there is **one**
+> report contract; only the *execution strategy* is selected from a runtime
+> capability — the same pattern the protocol already endorses for live-docs
+> fallback in [`instructions.md` §1.C/§1.D](../instructions.md). The full
+> capability-degradation rationale lives in the
+> [`capability.js`](../scripts/lib/dynamic-workflow/capability.js) module
+> docstring; the orchestrated-run evidence and per-lens cost/precision gate
+> verdicts live in [`docs/roadmap.md`](../../docs/roadmap.md) (Part 3 —
+> Dynamic-Workflow Orchestration).
+
+**Forcing a path (for testing).** Set `MANDREL_AUDIT_STRATEGY=sequential` to
+verify the fallback path with the feature notionally disabled, or
+`MANDREL_AUDIT_STRATEGY=orchestrated` to pin the dynamic path. To exercise the
+real disable signals instead, set `CLAUDE_CODE_DISABLE_WORKFLOWS=1` (env) or
+`disableWorkflows: true` in `.claude/settings.json` and re-run the lens — both
+degrade to the sequential path.
+
+## Step 1: Deterministic Signal First
+
+> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
+
+Run the existing deterministic checkers before any semantic reading — they
+are cheap, exact, and de-duplicate the easy findings:
+
+```bash
+node .agents/scripts/check-doc-links.js
+node .agents/scripts/check-lifecycle-doc-drift.js
+node .agents/scripts/generate-config-docs.js --check
+node .agents/scripts/generate-lifecycle-docs.js --check
+node .agents/scripts/generate-workflows-doc.js --check
+```
+
+Fold the results in as findings:
+
+- **Checker failures** (broken links, lifecycle drift) become individual
+  findings with `Category: Link Integrity` (or `Generator Drift` for the
+  lifecycle gate), citing the checker output verbatim.
+- **Generator dirtiness** (any `--check` reporting stale output, including
+  a stale `.claude/commands/` mirror) becomes **one single finding** with
+  `Category: Generator Drift` — never per-line findings — whose
+  remediation is "rerun `npm run docs:gen` / `npm run sync:commands` and
+  commit the regenerated output".
+
+This lens orchestrates the existing checkers only; it does not add new
+deterministic checker scripts.
+
+## Step 2: Semantic Claim Verification & Completeness
+
+For every doc in the target set (minus the generated exclusions), verify
+its claims against the code — read the doc, extract its testable claims,
+and check each one:
+
+1. **Command & Script References:** Every referenced npm script exists in
+   `package.json`; every referenced CLI command and
+   `node .agents/scripts/<name>.js` invocation resolves to a real script
+   with the documented flags.
+2. **Path & Module References:** Every referenced file path, directory, and
+   module name exists at the stated location (account for moves and
+   renames).
+3. **Workflow & Contract Descriptions:** Described workflows, label
+   taxonomies (`agent::*`, `type::*`, `meta::*`), branch shapes
+   (`story-<id>`, `epic/<id>`), and artifact contracts match how the
+   current scripts actually behave — read the implementation when the
+   prose makes a behavioural claim.
+4. **Version & Topology Claims:** Version numbers, package names, release
+   topology, CI gate names, and tool-matrix claims are current.
+5. **Completeness:** Major surfaces with no documentation coverage in the
+   target set — workflows under `.agents/workflows/`, operator-facing
+   scripts under `.agents/scripts/`, and config keys in
+   `.agents/schemas/agentrc.schema.json` that no target-set doc mentions.
+   Report material gaps, not an exhaustive index.
+
+Severity guidance: **High** = the doc instructs something that no longer
+works (wrong command, deleted script, contract mismatch); **Medium** =
+materially outdated description or missing coverage of a major surface;
+**Low** = cosmetic drift, stale examples, tone/format inconsistencies.
+
+## Step 3: Output Requirements
+
+Generate and save a highly structured Markdown audit report to
+`{{auditOutputDir}}/audit-documentation-results.md`, using the exact
+template below.
+
+```markdown
+# Documentation Audit Report
+
+## Executive Summary
+
+[Overview of documentation health (High/Medium/Low confidence that the docs
+match the code), the deterministic-gate verdicts, and primary drift themes.]
+
+## Target Set Coverage
+
+| Doc    | Source                                                                | Verdict                         |
+| ------ | --------------------------------------------------------------------- | ------------------------------- |
+| [path] | [docsContextFiles · docsFreshness · anchor · --paths] | [Current · Drifted · Excluded (generated)] |
+
+## Detailed Findings
+
+[For every gap identified, use the following strict structure:]
+
+### [Short Title of the Issue]
+
+- **Category:** [Broken Instruction | Stale Description | Missing Coverage | Generator Drift | Link Integrity]
+- **Impact:** [High | Medium | Low]
+- **Current State:** [The doc, the exact claim, and what the code actually
+  does — cite file paths and lines on both sides]
+- **Recommendation & Rationale:** [The specific doc edit (or generator
+  rerun) and why it restores accuracy]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this doc fix independently]`
+```
+
+## Constraint
+
+This workflow is **read-only** with respect to the repository: run the
+deterministic checkers in `--check` mode only, and do not edit any
+documentation or code. The single write is the report artifact. Provide the
+analysis and remediation prompts; do not apply changes.

package/.agents/workflows/audit-lighthouse.md

@@ -31,7 +31,7 @@ inflate Performance scores misleadingly.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no

package/.agents/workflows/audit-performance.md

@@ -16,7 +16,7 @@ load.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
@@ -38,7 +38,7 @@ before this section existed.
 ## Execution strategy (dual-path)
 
 This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`/epic-deliver` Phase 4
+report contract (Step 3); downstream consumers (`/deliver` Phase 4
 epic-audit, `audit-to-stories`) are agnostic to which path produced it.
 
 - **Orchestrated (dynamic-workflow) path.** When Claude Code's

package/.agents/workflows/audit-privacy.md

@@ -17,7 +17,7 @@ insecure storage, or unnecessary collection of sensitive data.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no

package/.agents/workflows/audit-quality.md

@@ -26,7 +26,7 @@ integrations, and test environment stability.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
@@ -48,7 +48,7 @@ before this section existed.
 ## Execution strategy (dual-path)
 
 This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`/epic-deliver` Phase 4
+report contract (Step 3); downstream consumers (`/deliver` Phase 4
 epic-audit, `audit-to-stories`) are agnostic to which path produced it.
 
 - **Orchestrated (dynamic-workflow) path.** When Claude Code's

package/.agents/workflows/audit-security.md

@@ -16,7 +16,7 @@ potential attack vectors.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no
@@ -38,7 +38,7 @@ before this section existed.
 ## Execution strategy (dual-path)
 
 This lens runs along one of two execution paths. Both emit the **identical**
-report contract (Step 3); downstream consumers (`/epic-deliver` Phase 4
+report contract (Step 3); downstream consumers (`/deliver` Phase 4
 epic-audit, `audit-to-stories`) are agnostic to which path produced it.
 
 - **Orchestrated (dynamic-workflow) path.** When Claude Code's

package/.agents/workflows/audit-seo.md

@@ -20,7 +20,7 @@ indexes and AI-powered answer engines — without making any immediate changes.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no

package/.agents/workflows/audit-sre.md

@@ -17,7 +17,7 @@ actionable report that can be handed off for remediation before deployment.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no

package/.agents/workflows/audit-to-stories.md

@@ -3,7 +3,7 @@ description:
   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 /epic-plan --idea or opens standalone Stories.
+  either chains into /plan --idea or opens standalone Stories.
 ---
 
 # /audit-to-stories [audit-file-or-glob]
@@ -22,7 +22,7 @@ Dimension / Category, Current State, Recommendation, Agent Prompt).
 `/audit-to-stories` closes the loop: it parses those reports, groups
 related findings (including across audit dimensions), classifies each
 group as eligible-to-create or already-tracked, and — at the operator's
-choice — either chains into `/epic-plan --idea` for a single planned
+choice — either chains into `/plan --idea` for a single planned
 Epic or opens standalone Stories directly.
 
 The audit producers themselves are **not modified** by this workflow.
@@ -117,8 +117,8 @@ Ask:
 
 > How would you like these `<M>` Stories created?
 >
-> - **Single Epic via `/epic-plan`** **[Recommended]** — opens one Epic,
->   then chains into `/epic-plan --idea` so the standard PRD / Tech Spec
+> - **Single Epic via `/plan`** **[Recommended]** — opens one Epic,
+>   then chains into `/plan --idea` so the standard PRD / Tech Spec
 >   / WBS authoring handles decomposition. Grouped Stories become the
 >   seed for Phase 7 decomposition.
 > - **Individual standalone Stories** — opens one GitHub Issue per
@@ -128,7 +128,7 @@ Ask:
 
 ## Phase 5a — Single-Epic path
 
-Build the `/epic-plan` idea seed from the filtered plan envelope:
+Build the `/plan` idea seed from the filtered plan envelope:
 
 ```bash
 node .agents/scripts/audit-to-stories.js --emit-epic-seed \
@@ -138,16 +138,16 @@ node .agents/scripts/audit-to-stories.js --emit-epic-seed \
 
 The seed renders the canonical one-pager sections — Problem Statement,
 Recommended Direction, Key Assumptions (with links to every source
-report), MVP Scope (the M proposed Stories), Key Files (so `/epic-plan`
+report), MVP Scope (the M proposed Stories), Key Files (so `/plan`
 Phase 7 decompose has concrete anchors), Not Doing.
 
 Chain into the existing planning entrypoint:
 
 ```text
-/epic-plan --idea "<path-to-seed>"
+/plan --idea "<path-to-seed>"
 ```
 
-`/epic-plan` then runs ideation → duplicate-search → render Epic body
+`/plan` then runs ideation → duplicate-search → render Epic body
 → open Epic → Phase 7 / 8 decompose, as documented in its workflow.
 Each Story it spawns from the seed carries `context::audit:
 <reportLink>` and `audit-fingerprint: <sha>` in its body so future
@@ -225,7 +225,7 @@ summarising the run:
 - Final tally: `"<M> groups planned · <K> created · <J> skipped (open)
   · <L> skipped (re-occurring)"`.
 
-When the Single-Epic path ran, link the Epic the chained `/epic-plan`
+When the Single-Epic path ran, link the Epic the chained `/plan`
 opened. When the Standalone-Stories path ran, list every Issue URL.
 
 ## Constraints
@@ -250,7 +250,7 @@ opened. When the Standalone-Stories path ran, list every Issue URL.
 
 ## See also
 
-- [`/epic-plan`](epic-plan.md) — the planning pipeline `/audit-to-stories`
+- [`/plan`](helpers/plan-epic.md) — the planning pipeline `/audit-to-stories`
   chains into for the Single-Epic grouping mode.
 - [`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js) —
   the shared fingerprint/dedup/route helper this workflow and `qa-explore`

package/.agents/workflows/audit-ux-ui.md

@@ -16,7 +16,7 @@ and cohesive.
 
 ## Scope (Epic mode)
 
-When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+When this lens is invoked from `/deliver` Phase 4 (epic-audit), the
 following block is populated with the Epic's change-set file list.
 Otherwise — for any manual `/audit-<dimension>` invocation — the block
 renders the literal substitution token and you MUST treat it as **no

package/.agents/workflows/deliver.md

@@ -0,0 +1,85 @@
+---
+description:
+  Unified delivery entry point. Inspects the ticket type(s) and
+  Epic-reference state of the supplied IDs, then routes to the Epic wave
+  loop or the standalone multi-Story fan-out — preserving every flag and
+  the parallel-delivery contract of the retired commands.
+---
+
+# /deliver [Epic ID] | [Story IDs...]
+
+## Role
+
+Router. `/deliver` owns input classification and path selection only — all
+phase content lives in the two path helpers:
+
+- [`helpers/deliver-epic.md`](helpers/deliver-epic.md) — the full Epic
+  delivery loop (preflight, wave loop fanning out
+  [`helpers/epic-deliver-story`](helpers/epic-deliver-story.md),
+  close-validation, epic-audit, code-review, retro, finalize, watch,
+  auto-merge gate, cleanup).
+- [`helpers/deliver-stories.md`](helpers/deliver-stories.md) — the
+  standalone multi-Story path (`stories-wave-tick.js` wave plan, operator
+  confirmation, parallel fan-out to
+  [`helpers/single-story-deliver`](helpers/single-story-deliver.md)).
+
+## Input matrix (authoritative)
+
+Fetch each supplied ID's labels and body (`type::*` label, `Epic: #N`
+reference) before routing:
+
+| Input | Route |
+| --- | --- |
+| Exactly one `type::epic` ID | **Epic path** — run [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9 unchanged. |
+| One or more `type::story` IDs, none carrying an `Epic: #N` reference | **Standalone path** — run [`helpers/deliver-stories.md`](helpers/deliver-stories.md) Phases 0–3. |
+| Any Story carrying an `Epic: #N` reference | **Error**, naming the fix: `Story #<id> belongs to Epic #<n> — run /deliver <n>`. |
+| Mixed Epic + Story IDs, or more than one Epic | **Error**: separate invocations — one `/deliver <epicId>` per Epic, one `/deliver <id> [<id>...]` for the standalone set. |
+
+## Flags (forwarded per path)
+
+| Path | Flags |
+| --- | --- |
+| Epic | `--skip-epic-audit`, `--skip-code-review`, `--skip-retro`, `--full-retro`, `--steal`, `--as <handle>` |
+| Story | `--dep <from>:<to>`, `--yes`, `--concurrency <n>` |
+
+A flag passed to the wrong path is reported once as a no-op warning and
+ignored — never an error.
+
+**Multi-Story parallel contract (preserved verbatim).**
+
+```text
+/deliver <id> <id> … --dep <from>:<to> --concurrency <n> --yes
+```
+
+behaves exactly as the retired multi-Story command did: the same
+`stories-wave-tick.js` wave plan, the same operator confirmation gate
+(suppressed by `--yes`), and the same parallel fan-out — one Agent call per
+Story per wave, capped by the resolved `concurrencyCap` — to
+[`helpers/single-story-deliver`](helpers/single-story-deliver.md).
+
+## Procedure
+
+1. **Parse args.** At least one positive-integer ID is required.
+2. **Classify.** Fetch each ticket's labels + body and apply the input
+   matrix above. Refuse ambiguous input with the matrix's error messages —
+   never guess a route.
+3. **Delegate.** Read the selected path helper **in full** and execute it
+   from its entry phase, forwarding the absorbed flags. The helper's phase
+   numbering, watchdogs, gates, and scripts are unchanged — this router
+   adds no phase content.
+
+## Constraints
+
+- `/deliver` requires a planned ticket: an Epic at `agent::ready` (the
+  Epic helper's preflight enforces this) or well-formed standalone Stories.
+  Planning happens in [`/plan`](plan.md); the plan-review gate between the
+  two commands is a hard boundary.
+- The router performs no git or label mutations itself; the path helpers
+  own every script invocation.
+
+## See also
+
+- [`/plan`](plan.md) — the unified planning entry point.
+- [`helpers/deliver-epic.md`](helpers/deliver-epic.md) /
+  [`helpers/deliver-stories.md`](helpers/deliver-stories.md) — the path
+  helpers.

package/.agents/workflows/explain.md

@@ -14,7 +14,7 @@ description:
 landed (or is about to) and you want to be sure you actually understand it —
 the problem it solves, why it was solved this way, the design decisions, the
 edge cases, and the blast radius. It is the after-the-fact counterpart to
-[`/epic-plan`](epic-plan.md) Phase 11 (which walks the operator through a
+[`/plan`](helpers/plan-epic.md) Phase 11 (which walks the operator through a
 *plan* before delivery); both drive the same engine.
 
 ```text
@@ -39,7 +39,7 @@ contract.
 | Understand a change that already merged | `/explain <PR#>` |
 | Understand a branch before merging it | `/explain <branch>` |
 | Understand what you are about to commit | `/explain --staged` |
-| Understand a freshly planned Epic backlog | `/epic-plan` Phase 11 (automatic) |
+| Understand a freshly planned Epic backlog | `/plan` Phase 11 (automatic) |
 
 ## Step 1 — Resolve the subject
 
@@ -111,7 +111,7 @@ structured-question mechanism when it sharpens understanding.
 
 - [`core/knowledge-transfer`](../skills/core/knowledge-transfer/SKILL.md) —
   the comprehension engine this command drives.
-- [`/epic-plan`](epic-plan.md) — Phase 11 runs the same engine over a plan
+- [`/plan`](helpers/plan-epic.md) — Phase 11 runs the same engine over a plan
   before delivery.
 - `/code-review` (Claude Code built-in) — correctness review of a diff. A
   different concern: `/explain` builds *operator* understanding, not a defect

package/.agents/workflows/git-merge-pr.md

@@ -235,7 +235,7 @@ Merge the PR as a squash commit and delete the head branch. Call
 
 After the merge command returns, perform a conflict marker scan to confirm no
 stray markers entered the base branch. Delegate to `detect-merges.js` — it
-owns the scan logic and is the same script used by `/epic-deliver` Phase 5.3.
+owns the scan logic and is the same script used by `/deliver` Phase 5.3.
 
 ```powershell
 git checkout [BASE_BRANCH]

package/.agents/workflows/git-pr-all.md

@@ -7,7 +7,7 @@ description: >-
 # /git-pr-all [Message] [--draft] [--no-auto-merge] [--branch <name>] [--base <branch>]
 
 This workflow is the **ad-hoc PR ergonomics** counterpart to the heavyweight
-`/epic-deliver` pipeline. Use it when you have outstanding changes that do not
+`/deliver` pipeline. Use it when you have outstanding changes that do not
 belong to a planned Epic (typo fixes, file deletions, doc tweaks, dependency
 bumps, operator housekeeping) and you want a single command to take them from
 the working tree to a PR queued for auto-merge.
@@ -19,7 +19,7 @@ names. Quality gates remain enforced by the existing pre-push hook; this
 workflow does not bypass them.
 
 > **When to run**: After making changes on `main` (or any base branch) that
-> are too small or too out-of-band for `/epic-plan` + `/epic-deliver` but
+> are too small or too out-of-band for `/plan` + `/deliver` but
 > still need to land via the PR-required flow.
 >
 > **Persona**: `devops-engineer` · **Skills**:
@@ -123,7 +123,7 @@ git add -A
 
 > **Why `-A` and not explicit paths?** `/git-pr-all` is operator-driven
 > (not parallel-agent-driven), so the single-tree assumption that
-> blocks `git add .` inside `/story-deliver` does not apply here. See
+> blocks `git add .` inside `/deliver` does not apply here. See
 > the parallel-execution warning at the bottom of this file.
 
 Commit:
@@ -210,7 +210,7 @@ Print a single block to the operator:
    auto-merge: <enabled | draft | disabled>
 ```
 
-Do **not** poll CI. That is the `/epic-deliver` Phase 7 job and is
+Do **not** poll CI. That is the `/deliver` Phase 7 job and is
 overkill for ad-hoc changes. The operator (or GitHub's email
 notification) is the next watcher.
 
@@ -253,13 +253,13 @@ notification) is the next watcher.
 - **Never** force-push from `/git-pr-all`. This workflow is for opening
   new PRs, not for rewriting history. Force-pushes belong to
   `/git-merge-pr` (with `--force-with-lease` after a rebase) and
-  `/epic-deliver` Phase 7 (with the operator's explicit context).
+  `/deliver` Phase 7 (with the operator's explicit context).
 - **Always** delete the head branch on merge (Step 6's
   `--delete-branch` flag handles this for `--auto` mode; for
   `--no-auto-merge` PRs the operator is responsible for the cleanup).
 - **Always** prefer `--auto --squash --delete-branch` unless the
   operator explicitly opts out. The squash + auto-merge default gives
-  the same merge ergonomics `/epic-deliver` produces, so main's commit
+  the same merge ergonomics `/deliver` produces, so main's commit
   history stays uniform across both surfaces.
 
 ---
@@ -267,11 +267,14 @@ notification) is the next watcher.
 ## ⚠️ Parallel Story Execution
 
 Do **not** use this workflow from inside a parallel story-execution
-context (`/story-deliver #<storyId>`, `/epic-deliver` wave dispatch).
+context (`/deliver #<storyId>`, `/deliver` wave dispatch).
 `git add -A` sweeps any untracked files in the working tree, which in
-a shared working directory may belong to another agent. Use the
-explicit-staging + branch-guard pattern documented in
-`story-deliver.md` Step 1 in those contexts.
+a shared working directory may belong to another agent. In those
+contexts stage explicit paths only and confirm
+`git branch --show-current` reports the expected `story-<id>` branch
+before committing — see
+[`helpers/worktree-lifecycle.md`](helpers/worktree-lifecycle.md) for the
+shared-tree hazard and the worktree-isolation model that contains it.
 
 The same warning applies to any workflow that calls `git add .` or
 `git add -A`; this is not unique to `/git-pr-all` (see

package/.agents/workflows/git-push.md

@@ -54,7 +54,10 @@ attempting to commit or push again.
 ## ⚠️ Parallel Story Execution
 
 Do **not** use this workflow from inside a parallel story-execution context
-(`/story-deliver #<storyId>`). `git add .` sweeps any untracked files in the
+(`/deliver #<storyId>`). `git add .` sweeps any untracked files in the
 working tree, which in a shared working directory may belong to another agent.
-In that context, follow the explicit-staging + branch-guard pattern documented
-in `story-deliver.md` Step 1.
+In that context, stage explicit paths only and confirm
+`git branch --show-current` reports the expected `story-<id>` branch before
+committing — see
+[`helpers/worktree-lifecycle.md`](helpers/worktree-lifecycle.md) for the
+shared-tree hazard and the worktree-isolation model that contains it.

package/.agents/workflows/helpers/_merge-conflict-template.md

@@ -1,7 +1,7 @@
 # Merge Conflict Resolution — Shared Procedure
 
 Canonical, workflow-agnostic procedure for resolving merge / rebase conflicts.
-Referenced by `git-merge-pr.md`, `story-deliver.md`, and `epic-deliver.md`.
+Referenced by `git-merge-pr.md`, `deliver-stories.md`, and `deliver-epic.md`.
 
 ## Procedure
 

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -26,7 +26,7 @@ The loop is **always on** (a hard cutover — there is no flag to disable it) an
 **bounded** by `delivery.acceptanceEval.maxRounds` (default 2), which the
 resolver clamps into `[1, hard ceiling]` so the cap can never be switched off or
 run unbounded. It is **distinct from** the Epic-level acceptance-spec
-reconciliation in `/epic-deliver` Phase 7.1 (which fires once at finalize and
+reconciliation in `/deliver` Phase 7.1 (which fires once at finalize and
 only checks `@ac-*` Gherkin tag presence): this loop is per-Story,
 per-criterion, mid-delivery, and evaluates the actual work product.