mandrel 1.94.0 → 2.0.0

package/.agents/workflows/deliver.md

@@ -1,200 +1,148 @@
 ---
 description:
-  Unified delivery entry point. Inspects the ticket type(s) and
-  Epic-reference state of the supplied IDs, composes a sequential segment
-  plan over any mix of Epics and standalone Stories, then delegates each
-  segment to the Epic wave loop or the standalone multi-Story fan-out —
-  preserving every flag and the parallel-delivery contract of the retired
-  commands.
+  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 [Epic IDs...] | [Story IDs...]
+# /deliver <storyId...> | --run <planRunId>
 
 ## Role
 
-Router. `/deliver` owns input classification, segment-plan composition, and
-path selection only — all phase content lives in the two path helpers:
+Single delivery path. `/deliver` owns input resolution and sequencing only —
+every Story runs through
+[`helpers/deliver-story.md`](helpers/deliver-story.md) (the evolved
+single-Story engine). There is no Epic wave loop, no `epic/<id>` integration
+branch, and no `--no-ff` wave merges.
 
-- [`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` continuous ready-set
-  loop, operator confirmation, parallel fan-out to
-  [`helpers/single-story-deliver`](helpers/single-story-deliver.md)).
+## Inputs
 
-## Input matrix (authoritative)
+| Invocation | Behavior |
+| --- | --- |
+| `/deliver <storyId>` | Deliver one Story via `helpers/deliver-story.md`. |
+| `/deliver <storyId> <storyId> ...` | Sequence Stories in `depends_on` order via `stories-wave-tick.js`; each ready Story runs `deliver-story`. Default concurrency is **3**. |
+| `/deliver --run <planRunId>` | Resolve Stories labeled `plan-run::<planRunId>` (envelope includes `dag` + `done`); sequence as above; after the last Story lands, run the per-run epilogue. |
 
-Fetch each supplied ID's labels and body (`type::*` label, `Epic: #N`
-reference) before routing:
+Any ticket that is not `type::story`, or that still carries an `Epic: #N`
+reference, is a hard error naming the ID and the fix (close or re-plan as a
+v2 Story).
 
-| Input | Route |
-| --- | --- |
-| Exactly one `type::epic` ID | **Epic path** — resolve the Epic's delivery route (see [Epic delivery-route resolution](#epic-delivery-route-resolution) below), then run the selected helper's phases unchanged (single-segment plan; no confirmation prompt). |
-| 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 (single-segment plan; no confirmation prompt). |
-| Any combination of ≥1 `type::epic` IDs and ≥0 standalone `type::story` IDs | **Segment plan** — compose and execute the sequential segment plan below. |
-| Any Story carrying an `Epic: #N` reference (alone or mixed into an otherwise-valid set) | **Error**, naming every affected ID and the fix: `Story #<id> belongs to Epic #<n> — run /deliver <n>`. |
-
-Per-ID classification is unchanged: fetch the `type::*` label and probe the
-body for an `Epic: #N` reference before routing. Never guess a route.
-
-## Epic delivery-route resolution
-
-Every `type::epic` segment resolves to one of two delivery shapes before its
-helper runs. The routing is a pure function of the Epic's labels, its
-`epic-plan-state` checkpoint, and the config kill-switch — implemented in
-[`lib/orchestration/deliver-route.js`](../scripts/lib/orchestration/deliver-route.js)
-(`resolveEpicDeliveryRoute(epic, checkpoint, config)`), mirroring how the
-code-review depth resolver reads `planningRisk`/`decompose` off the same
-checkpoint. Fetch the Epic's labels and read its `epic-plan-state` structured
-comment, then apply the precedence (highest wins):
-
-1. **Kill-switch — overrides all.** `delivery.routing.singleDelivery === false`
-   (default `true`, read via `getDeliveryRouting`) forces **fan-out** for
-   *every* Epic, even a single-marked one. This is the instant, per-consumer
-   global revert that ships before the default flips — no code rollback, no
-   re-plan.
-2. **Single marker → single route.** The `delivery::single` label (primary)
-   **or** `decompose.shape === "single"` on the checkpoint (secondary). A
-   spec-only plan authored no Story tree; its `## Delivery Slicing` table is
-   the audit trail.
-3. **No marker → fan-out.** A legacy Epic (no marker, an authored Story tree)
-   or a genuinely-wide DAG. Deliver-time width only *advises* — it never
-   reroutes a single-marked Epic (that would orphan a tree that does not
-   exist; re-route = re-plan).
-
-**Route dispatch.**
-
-- **`fan-out`** → run [`helpers/deliver-epic.md`](helpers/deliver-epic.md)
-  Phases 1–9 unchanged (the wave loop fanning out per-Story sub-agents).
-- **`single`** → run
-  [`helpers/deliver-epic-single.md`](helpers/deliver-epic-single.md) (the
-  live flip, M4-B): a one-worktree in-session slice walk (prepare `--single` →
-  ordered `## Delivery Slicing` walk on `epic/<id>` → per-AC-cluster
-  acceptance critics) that **reuses `helpers/deliver-epic.md` Phases 3–9
-  byte-for-byte** for the merge tail. This is now the **default** shape for a
-  single-marked Epic. The kill-switch (`delivery.routing.singleDelivery=false`)
-  still forces this verdict back to `fan-out` — an instant global revert with
-  no code rollback.
-
-## Segment plan (mixed / multi-Epic input)
-
-When the supplied IDs span more than one Epic, or mix Epics with standalone
-Stories, the router composes a **segment plan** and executes the segments
-**strictly sequentially**:
-
-1. **Standalone segment first** (when any standalone Story IDs are
-   present): the full standalone-Story set forms **one** segment,
-   delivered via [`helpers/deliver-stories.md`](helpers/deliver-stories.md)
-   Phases 0–3 unchanged. It runs first because it is fast, each Story
-   merges to `main` independently, and each subsequent Epic segment's
-   Phase 7.0 base-sync then integrates those merges naturally instead of
-   the Epic PR opening behind base.
-2. **Epic segments in input order**: each `type::epic` ID forms its own
-   segment. Resolve its delivery route (see [Epic delivery-route
-   resolution](#epic-delivery-route-resolution)) and run the selected helper
-   unchanged — the `fan-out` route dispatches
-   [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9, the
-   `single` route dispatches
-   [`helpers/deliver-epic-single.md`](helpers/deliver-epic-single.md) (which
-   reuses that helper's Phases 3–9 for the merge tail).
-
-Sequential execution is a deliberate design decision: the Epic path assumes
-a single main checkout (prepare's checkout guard, Phase 7.0
-`git checkout epic/<id>`), holds a per-Epic lease, serializes same-machine
-sessions via `epic-merge-lock.js`, and constrains dispatch to one wave at a
-time. Segments are never interleaved or parallelized; running them one at a
-time keeps both helpers' machinery untouched.
-
-**Confirmation gate.** When the composed plan has more than one segment,
-present it to the operator before dispatching — the segments, the IDs in
-each, and the execution order — and wait for confirmation. `--yes`
-suppresses this prompt. Single-segment plans route directly with today's
-behavior (no new prompt; the standalone path's own Phase 1 confirmation
-still applies as before).
-
-**Failure policy.** A segment that ends non-complete (blocked, failed, or
-halted at a gate) **stops the run** — no subsequent segment dispatches.
-Report the terminal state: which segments completed, which segment halted
-(and why), and which segments never started. Name the resume command:
-re-running `/deliver` with the same IDs — both path helpers short-circuit
-already-done work (the Epic path resumes idempotently from its checkpoint;
-merged standalone Stories no-op).
-
-## Flags (scoped per segment)
-
-| Path | Flags |
+## Flags
+
+| Flag | Meaning |
 | --- | --- |
-| Epic | `--skip-epic-audit`, `--skip-code-review`, `--skip-retro`, `--full-retro`, `--steal`, `--as <handle>` |
-| Story | `--dep <from>:<to>`, `--yes`, `--concurrency <n>` |
+| `--run <planRunId>` | Deliver every Story in the plan-run (label `plan-run::<id>`). |
+| `--dep <from>:<to>` | Extra operator dependency edge (Story id → Story id). |
+| `--concurrency <n>` | Ready-set fan-out cap (default **3** from `delivery.deliverRunner.concurrencyCap`; set `1` for sequential). |
+| `--yes` | Suppress the multi-Story confirmation gate. |
+| `--steal` | Forwarded to `single-story-init.js` / lease steal. |
+| `--wait-merge` | Force close-and-land (default when `delivery.routing.closeAndLand` is true). |
+| `--no-wait-merge` | Opt out of close-and-land; stop at `agent::closing` for a human land. |
+
+## Procedure
+
+1. **Resolve the Story set.**
+   - Positional IDs → use them.
+   - `--run <planRunId>` →
+
+     ```bash
+     node .agents/scripts/resolve-plan-run.js --run <planRunId>
+     ```
+
+     Capture `stories[]`, `dag[]`, and `done[]` from the envelope. Prefer
+     the emitted `dag` — do **not** rebuild it by hand when `--run` was used.
+
+2. **Build the DAG (positional only).** When delivering positional IDs
+   (no `--run`), read `depends_on` / `blocked by` from each body and merge
+   `--dep` edges into a JSON DAG for `stories-wave-tick.js`:
+
+   ```json
+   [{ "id": 101, "dependsOn": [] }, { "id": 102, "dependsOn": [101] }]
+   ```
+
+3. **Confirm (N>1).** Present the order and wait unless `--yes`.
 
-In a segment plan, Epic-path flags apply to **every** Epic segment;
-Story-path flags apply to the standalone segment. `--yes` additionally
-suppresses the router's segment-plan confirmation gate above. A flag with
-no applicable segment in the plan is reported once as a no-op warning and
-ignored — never an error (the existing convention, restated for segment
-plans).
+4. **Sequence.** Loop until every Story is done:
 
-**Multi-Story parallel contract (preserved verbatim).**
+   ```bash
+   node .agents/scripts/stories-wave-tick.js \
+     --dag '<json>' --done <csv> --in-flight <n> --concurrency <n>
+   ```
+
+   For each `ready` Story id, read
+   [`helpers/deliver-story.md`](helpers/deliver-story.md) **in full** and
+   execute it (init → implement → ceremony → close-and-land). Under
+   `--yes` / injected helper content, execute directly without a re-read
+   turn.
+
+5. **Per-run epilogue (N>1).** After the last Story lands:
+
+   ```bash
+   # Plan-run label path:
+   node .agents/scripts/plan-run-epilogue.js --run <planRunId>
+
+   # Positional multi-Story path (synthesizes an adhoc planRunId):
+   node .agents/scripts/plan-run-epilogue.js --stories 101,102
+   ```
+
+   This executes, in order:
+   - `audit-roster` — selects cross-Story audit lenses over the combined
+     landed tip and posts `plan-run-audit-roster` on the primary Story;
+     the host MUST walk each listed lens against the combined diff
+   - `follow-up-rollup` — friction follow-ups across every Story in the
+     run (files issues when auto-file is on; posts `follow-ups`)
+   - `sibling-coherence` — Spec/Acceptance coherence check across sibling
+     bodies (`plan-run-sibling-coherence`)
+
+   A single-Story run skips the epilogue — follow-ups are captured on
+   merge confirm instead (`captureStoryFollowUps`).
+
+## Branch model (authoritative)
+
+Every Story:
 
 ```text
-/deliver <id> <id> … --dep <from>:<to> --concurrency <n> --yes
+story-<id>  →  PR  →  main (squash + required checks)
 ```
 
-preserves the retired multi-Story command's full surface — the same flags,
-the same operator confirmation gate (suppressed by `--yes`), and the same
-parallel fan-out to
-[`helpers/single-story-deliver`](helpers/single-story-deliver.md) — but
-schedules through `stories-wave-tick.js`'s **continuous ready-set loop**
-(the shared `selectReadySet` core) rather than a static wave plan: each
-Story dispatches the instant its own dependencies are done, capped by the
-resolved global `concurrencyCap` and guarded against file-overlap
-co-dispatch, exactly as the Epic path is. The parallelism lives **inside**
-the standalone segment; segments themselves remain strictly sequential.
+There is no `epic/<id>` integration branch and no `--no-ff` wave merge.
+Dependent Stories land sequentially so each builds on the previous merge
+to `main`.
 
-## Procedure
+## Ceremony (profiles + two scopes)
+
+Ceremony depth is selected by `delivery.routing.ceremonyProfile`
+(`minimal` | `standard` | `strict`, default `standard`) and the Story's
+planning risk:
+
+| Profile | Acceptance critic | When to use |
+| --- | --- | --- |
+| `minimal` | Always inline | Tiny trusted N=1 Stories |
+| `standard` | Risk-routed (+ sampling floor) | Default |
+| `strict` | Always fresh-context | High-assurance / regulated surfaces |
 
-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. Any Epic-attached Story ID is a hard error naming the
-   affected IDs and the fix — never guess a route.
-3. **Compose the segment plan.** Standalone-Story set (when present) as
-   one segment, then one segment per Epic ID in input order. For a
-   multi-segment plan, present it and wait for operator confirmation
-   (`--yes` suppresses).
-4. **Execute segments sequentially.** For each segment in order, read the
-   selected path helper **in full** and execute it from its entry phase,
-   forwarding the segment's scoped flags. The helper's phase numbering,
-   watchdogs, gates, and scripts are unchanged — this router adds no phase
-   content. Stop on the first non-complete segment per the failure policy.
-5. **Report.** On completion (or halt), summarize per-segment outcomes and,
-   when halted, the resume command.
+| Scope | What runs | Mechanism |
+| --- | --- | --- |
+| **Per-Story (always)** | Gates, branch discipline, close-and-land | `deliver-story` / `single-story-close` |
+| **Per-Story (profile + risk)** | Acceptance critic mode; review depth; audit lenses | `ceremony-routing.js` + `review-depth.js` + `code-review.js` |
+| **Per-run (N>1)** | Audit roster · follow-up roll-up · sibling coherence | `plan-run-epilogue.js` once at run end |
+| **Per-Story land** | Actionable follow-ups from friction | `captureStoryFollowUps` in confirm-merge |
 
 ## Constraints
 
-- **Land or block — never a silent local build (issue #4483).** The
-  helpers' orchestration path (worktrees, `story-<id>`/`epic/<id>` branches,
-  close-validation, PR) is the ONLY sanctioned delivery mechanism.
-  Executing story slices inline in this session and/or committing the
-  delivery to local `main` is expressly forbidden, regardless of how the
-  environment looks. Each path surfaces verified remote evidence
-  (`remoteVerified`) at entry; on `false`, transition the ticket to
-  `agent::blocked` quoting `remoteProbe.detail` and halt.
-- `/deliver` requires planned tickets: Epics at `agent::ready` (the
-  Epic helper's preflight enforces this, per segment) 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.
-- Segments execute strictly sequentially — never interleave a standalone
-  Story fan-out with an Epic wave loop, and never run two Epic segments
-  concurrently.
+- **Land or block — never a silent local build.** Worktrees, `story-<id>`
+  branches, close-validation, and PR-to-`main` are the only sanctioned
+  delivery mechanism. Attended delivers default to close-and-land
+  (`delivery.routing.closeAndLand: true`); use `--no-wait-merge` only when
+  a human will land the PR.
+- `/deliver` never plans — tickets come from [`/plan`](plan.md).
+- The router performs no git/label mutations; `deliver-story` owns every
+  script invocation per Story.
 
 ## 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, delegated to per segment.
+- [`/plan`](plan.md) — unified planning entry point.
+- [`helpers/deliver-story.md`](helpers/deliver-story.md) — the one Story
+  delivery engine.
+- Placeholder design Story for a fully deterministic deliver-run
+  orchestrator: [#4521](https://github.com/dsj1984/mandrel/issues/4521).

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

@@ -226,10 +226,9 @@ The merged-branch sweep recognizes three detection signals, in order:
    `git merge-tree --write-tree <base> <branch>` (git ≥ 2.38) produces a
    tree identical to `<base>`'s own tree — i.e. applying the branch's
    changes on top of `<base>` is a content no-op. This catches
-   `story-<id>` branches merged into `epic/<id>` whose Epic PR
-   **squash-merged** to `main` (the story commits are not ancestors of
-   `main` and the story branch usually has no PR of its own), and any
-   other branch whose content landed via a different route (a renamed
+   `story-<id>` branches whose PR **squash-merged** to `main` (the story
+   commits are not ancestors of `main`), and any other branch whose content
+   landed via a different route (a renamed
    head, a cherry-pick, a manual `merge --squash`). When git rejects
    `--write-tree` (git < 2.38) or the simulated merge conflicts, the
    probe is inconclusive and the branch keeps its existing `not-merged`

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 `deliver-stories.md` and `deliver-epic.md`.
+Referenced by `deliver.md` and `helpers/deliver-story.md`.
 
 ## Procedure
 

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

@@ -1,19 +1,16 @@
 ---
 description: >-
   Shared include for the bounded acceptance self-eval loop run during Story
-  delivery (both Epic-attached `epic-deliver-story` and standalone
-  `single-story-deliver`). Defines the per-round critic mechanic; each caller
-  supplies its own gate-decision wrapper (snapshot vs. label transitions).
+  delivery (`helpers/deliver-story`). Defines the per-round critic mechanic;
+  the caller supplies its gate-decision wrapper (label transitions).
 ---
 
 # Bounded acceptance self-eval loop (shared include)
 
 > **Include module.** Not a slash command. Referenced from
-> [`epic-deliver-story.md`](epic-deliver-story.md) and
-> [`single-story-deliver.md`](single-story-deliver.md) at their respective
-> Step 1a. This file is the **single prose home** for the per-round critic
-> mechanic; each caller layers only its own wrapper (snapshot transitions vs.
-> standalone label transitions, and whether to pass `--epic`).
+> [`deliver-story.md`](deliver-story.md) at Step 1a. This file is the
+> **single prose home** for the per-round critic mechanic; the caller layers
+> only its wrapper (Story label transitions).
 
 After the implementation commits land and **before** the Story proceeds to
 close, run an explicit, **independent** eval pass that scores the working diff
@@ -25,10 +22,9 @@ satisfies *this Story's* acceptance criteria.
 The loop is **always on** (a hard cutover — there is no flag to disable it) and
 **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 `/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.
+run unbounded. It is **distinct from** the per-run `sibling-coherence` epilogue
+step (`planRunEpilogue` for N>1): this loop is per-Story, per-criterion,
+mid-delivery, and evaluates the actual work product.
 
 ## Per round
 
@@ -50,8 +46,8 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    > review-depth and risk → audit-lens routers). Resolve it per cluster with
    > `resolveCeremonyForRisk` from
    > [`ceremony-routing.js`](../../scripts/lib/orchestration/ceremony-routing.js)
-   > using the Epic's `planningRisk.overallLevel` and
-   > `delivery.routing.freshCriticSampleRate`:
+   > using the **Story's** `planningRisk.overallLevel` (or folded
+   > `risk-verdict`) and `delivery.routing.freshCriticSampleRate`:
    > **`high`/`medium` risk → `fresh`** (spawn the critic); **`low` risk →
    > `inline`** (the contract-identical inline fallback below), **except** the
    > `freshCriticSampleRate` fraction of low-risk clusters the sampling floor
@@ -100,15 +96,9 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      HEAD-sha key enforces "unchanged HEAD") and pass the exact gate name:
 
      ```bash
-     # Epic-attached Story:
      node <main-repo>/.agents/scripts/evidence-gate.js \
-       --epic-id <epicId> --scope-id <storyId> --gate lint \
+       --standalone --scope-id <storyId> --gate lint \
        --worktree <worktree> -- npm run lint
-
-     # Standalone Story (no parent Epic) — use --standalone, omit --epic-id:
-     node <main-repo>/.agents/scripts/evidence-gate.js \
-       --standalone --scope-id <storyId> --gate typecheck \
-       --worktree <worktree> -- <resolved typecheck command>
      ```
 
      Close's `shouldSkip` then short-circuits that gate when HEAD is
@@ -122,13 +112,11 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      one `{ index, criterion, verdict: met|partial|unmet, evidence,
      verifyEvidence[] }` record per acceptance item.
 2. **Decide.** Run the gate against the verdict (the caller's Step 1a names the
-   exact invocation — standalone omits `--epic`; the Epic-attached path passes
-   `--epic <epicId>` so the per-criterion signal lands on the Epic-scoped
-   stream):
+   exact invocation — omit `--epic`):
 
    ```bash
    node <main-repo>/.agents/scripts/acceptance-eval.js \
-     --story <storyId> [--epic <epicId>] --verdict <verdict-path>
+     --story <storyId> --verdict <verdict-path>
    ```
 
    The gate validates the verdict against the schema, applies the round cap,
@@ -138,11 +126,10 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      close.
    - **`decision: "redraft"`** (some `partial`/`unmet`, rounds remaining) →
      exit 0. Redraft the flagged criteria (named in `unmetCriteria[]`), commit
-     the fix, and re-run the eval pass for the next round.
+     the fix, and start another round.
    - **`decision: "block"`** (round cap reached, criteria still unmet) → exit
      non-zero. **Do not proceed to close.** Take the caller's blocked path
-     (transition to `agent::blocked` / flip the snapshot to `blocked`) and post
-     a `friction` comment naming the unmet criteria and their evidence. Never
-     silently proceed to close.
+     (transition to `agent::blocked`) and post a `friction` comment naming the
+     unmet criteria and their evidence. Never silently proceed to close.
 
 Write the verdict files under `temp/` only — they are scratch artifacts.