mandrel 2.24.0 → 2.26.0

package/.agents/workflows/helpers/deliver-story.md

@@ -1,179 +1,164 @@
 ---
 description:
-  Execute one Story end-to-end. Creates story-<id> from main, implements in a
-  worktree (optional ## Slicing checkpoints), runs derived-level ceremony,
-  opens a PR against main, and lands.
+  Execute one Story end-to-end: story-<id> from main, implemented in a worktree
+  (optional ## Slicing checkpoints), derived-level ceremony, PR against main.
 mandatoryReads: [deliver-digest.md]
 ---
 
 # /deliver-story #[Story ID]
 
-> **Lean spine.** Happy path + gate list; edge-case, recovery, and
-> reference detail lives in
-> [`deliver-story-reference.md`](deliver-story-reference.md) ("reference"
-> below); consult on demand. Invoked by [`/deliver`](../deliver.md).
->
-> **Read [`deliver-digest.md`](deliver-digest.md) once, first.** It is the
-> one bundled read of what every delivery needs — dispatch decision, engine
-> invariants, the change-set/ceremony incantation, the acceptance-eval gate,
-> and the terminal-envelope contract — replacing the per-session re-reads of
-> the helper set and `story-deliver-terminal.schema.json`. The steps below
-> cite it as "digest § N" rather than restating it.
+> **Lean spine.** Happy path + gate list; edge-case, recovery and reference
+> detail lives in [`deliver-story-reference.md`](deliver-story-reference.md)
+> ("reference" below). Invoked by [`/deliver`](../deliver.md).
+> **Read [`deliver-digest.md`](deliver-digest.md) once, first** — the one
+> bundled read every delivery needs. Steps cite it as "digest § N".
 
 ## Overview
 
-The **one** delivery engine in v2 — every Story (a **one-Story** run
-goes inline with inline critics; engine, gates, envelope byte-identical):
+The **one** delivery engine in v2:
 
 ```text
-single-story-init.js → implement + commits → derived-level ceremony
-  → single-story-close.js (gates, push, PR → main, agent::closing)
+single-story-init.js → implement + commits → derived-level ceremony → push
+  ──hand-off──▶ single-story-close.js (gates, PR → main, agent::closing)
   → CI watch + merge → single-story-confirm-merge.js (agent::done)
 ```
 
-An `Epic: #N` reference marks a v1 ticket — **stop** and re-plan. The
-engine's trait table is reference § Engine invariants. Prerequisites: a
-`type::story` issue, clean `gh auth status`, and `project.baseBranch` on
-local and `origin`.
+An `Epic: #N` reference marks a v1 ticket — **stop** and re-plan. Engine
+traits and prerequisites: reference § Engine invariants.
+
+## Who owns which step
+
+Steps 0–2 belong to whoever implements. **Step 3 belongs to the orchestrator
+that dispatched the work**, never to a spawned worker.
+
+- **Inline dispatch** (a one-Story run — digest § 1): one session is both
+  roles and walks Steps 0→7, no hand-off.
+- **Sub-agent dispatch**: the `story-worker` stops at Step 2.5 with the branch
+  pushed and returns a hand-off; the dispatching `/deliver` session runs Step 3
+  **in its own turn** and **serializes the tail — one close at a time across
+  the run**, even though implementation ran in parallel (reference § Step 3).
+
+**A worker returning no terminal envelope is expected, not a failure.** Only
+Step 3 mints one, so a hand-off is the normal sub-agent return. Never
+re-dispatch the Story on it — the branch exists, and re-running Step 0 under
+live work is how one Story gets two closes. Resume per § Recovery instead.
 
 ## Step 0 — Initialize (`single-story-init.js`)
 
-From the **main checkout**, **synchronously** with the maximum Bash
-timeout — the per-tree install can take minutes; never `run_in_background`:
+From the **main checkout**, **synchronously** with the maximum Bash timeout —
+the per-tree install can take minutes; never `run_in_background`:
 
 ```bash
 node .agents/scripts/single-story-init.js --story <storyId>
 ```
 
 Every script below documents its own flags — run it with `--help`.
-It validates `type::story`, **acquires the Story lease**
-(fails closed on a foreign assignee), fetches `origin`, seeds `story-<id>`
-from `baseBranch` (idempotent reuse), materializes a worktree, runs a
-guarded merged-`story-*` sweep, and flips `agent::executing` (reference
-§ Step 0). Capture `workCwd` from the result envelope.
+It validates `type::story`, takes the Story lease, seeds `story-<id>` from
+`baseBranch`, materializes a worktree and flips `agent::executing` (reference
+§ Step 0). Capture `workCwd` from the envelope.
 
-**Land or block.** `remoteVerified: false` → flip
-`agent::blocked` quoting `remoteProbe.detail` and stop. Implementing outside
-the worktree/branch/PR path or committing to local `main` is forbidden —
-close's push is the only sanctioned landing.
+**Land or block.** `remoteVerified: false` → flip `agent::blocked` quoting
+`remoteProbe.detail` and stop. Implementing outside the worktree/branch/PR path,
+or committing to local `main`, is forbidden.
 
 **Step 0.5 — `cd "<workCwd>"`**, and prefix every path-based
-Edit/Write/Read with that absolute root — the `cd` alone does not scope
-those tools (reference § Worktree scope is not just the Bash cwd).
+Edit/Write/Read with that absolute worktree root — the `cd` alone does not
+scope those tools (reference § Worktree scope).
 
 ## Step 1 — Implementation
 
 One branch, one PR to `main`, commits against the inline `acceptance[]` /
-`verify[]` (and `## Spec`):
-
-1. Read the Story body; the acceptance criteria are the contract. Docs are
-   digest-first; read a caller-provided `checklistPath` before writing
-   (reference § Step 1).
-2. Implement. Walk any `## Slicing` rows as **intra-session checkpoints**
-   (commit + flip each row) — never sibling tickets.
-3. Commit on the Story branch; iterate with quick advisory gates
-   (`typecheck`, `lint`, scoped tests) — the full close chain runs in
-   Step 3.
-4. Run the **full test command** once in the worktree (`npm test`) **before
-   Step 1a** — repo-invariant guards outside the Story's scoped greps are
-   the failure class that bounces deliveries. Fix and commit first.
-5. Run the self-eval loop (Step 1a).
+`verify[]` and `## Spec`:
+
+1. Read the Story body; its acceptance criteria are the contract. Docs are
+   digest-first; read a caller-provided `checklistPath` first, and walk any
+   `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
+2. Implement and commit on the Story branch, iterating with quick advisory
+   gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3.
+3. Run `npm test` once in the worktree **before Step 1a**: repo-invariant
+   guards outside the Story's scoped greps are the failure class that bounces
+   deliveries. Fix and commit first, then run the self-eval loop.
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 
 Run the loop and score it with `acceptance-eval.js` — **digest § 4** carries
-the invocation and the proceed / redraft / block contract; per-round critic
-mechanics live in the single-homed include
-[`acceptance-self-eval.md`](acceptance-self-eval.md).
-
-**`proceed`** → Step 2 then Step 3. **`block`** → **do not close**: post a
-`friction` comment and flip `agent::blocked` — commands and the
-`evidence-gate.js --standalone` evidence-share mechanic: reference
-§ Step 1a.
+the invocation and the proceed / redraft / block contract; per-round mechanics
+live in [`acceptance-self-eval.md`](acceptance-self-eval.md). **`proceed`** →
+Step 2. **`block`** → **do not close**: post a `friction` comment and flip
+`agent::blocked` (reference § Step 1a).
 
 ## Step 2 — Ceremony (profile + derived level)
 
-Ceremony is `delivery.routing.ceremonyProfile` × the **derived change
-level** — never a planner-authored verdict. **Digest § 3** is the
-incantation: compute the change set once, derive the level, resolve
-fresh-vs-inline critics with `ceremony-routing.js`; a lite Story runs
-inline regardless (routing edge cases: reference § Step 2). Hard gates always
-run in Step 3 — the derived level never disables them; do **not** pre-run the
-close chain here.
+Ceremony is `delivery.routing.ceremonyProfile` × the **derived change level**,
+never a planner-authored verdict. **Digest § 3** is the incantation (change set
+once, derive the level, resolve critics with `ceremony-routing.js`); edge cases
+are reference § Step 2. Hard gates always run in Step 3 — the derived level
+never disables them; do **not** pre-run the chain here.
+
+### Step 2.5 — Push and hand off (sub-agent dispatch only)
+
+Push `story-<storyId>` to `origin` and confirm the remote ref moved. Return the
+hand-off — Story id, `workCwd`, branch, pushed head SHA, self-eval verdict,
+`verify[]` evidence — then stop. Do not open the PR; do not compose a terminal
+envelope. An inline run skips this.
 
 ## Step 3 — Close and land (`single-story-close.js`)
 
+**The orchestrator's step** (§ Who owns which step), run in the **foreground**,
+serialized against sibling Stories:
+
 ```bash
 node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo>
 ```
 
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
-post-land tail in one process. Run it and **branch on the terminal envelope's
-`status`** per the table in **digest § 5** (`landed` → Step 7; `pending` → run
-`nextCommand`; `blocked`/`checks-failed` → Step 4; `failed` → diagnose and
-re-run). Gate output is captured to
-`temp/orchestration/close-gates-<storyId>.log` — a clean run prints a digest
-line, a red gate replays its tail inline.
-
-Internals (gate order, base-sync, auto-merge arming), the merge-wait
-budgets, the slow-CI **async** confirm mode (launch the `pending`
-envelope's `nextCommand` as **background** Bash, never a foreground
-poll), the `autoMerge` policy, and every close flag: reference
-§ Step 3 — Merge wait, async mode, and flags.
-
-## Steps 4–6 — Recovery router (**recovery-only**)
-
-A `landed` envelope means everything ran — go straight to Step 7. Enter a
-recovery path **only** when the envelope routes you there:
-
-- **`blocked` / `checks-failed`** → fix, push a new commit (auto-merge stays
-  armed), resume via `nextCommand`; triage per
-  [`rules/ci-remediation.md`](../../rules/ci-remediation.md). The watch is
-  internally blocking — never end a turn with prose and an unconfirmed
-  merge. Reference § Step 4.
-- **`pending`** → run `nextCommand` (`single-story-confirm-merge.js`) until
-  resolved. Reference § Step 5.
-- **`tail.statusResync: false`** → reference § Step 5.5;
-  **`tail.refCleanup` / `tail.baseFastForward: false`** → reference § Step 6.
-
-## Step 7 — Return contract (**required as a sub-agent**) {#return-contract}
-
-End your turn by relaying the validated envelope close emits between its
+post-land tail in one process. Never background it, never delegate it to a
+child, and never end your turn while it is still running: "close is running"
+is not a return value. Branch on the envelope's `status` per **digest § 5**
+(`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
+→ Step 4; `failed` → diagnose, re-run). Gate output is captured.
+
+Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
+`autoMerge` policy and every close flag: reference § Step 3.
+
+## Step 7 — Return contract {#return-contract}
+
+Relay the validated envelope close emits between its
 `--- STORY DELIVER TERMINAL ---` markers — never free-form prose, never a
-hand-composed object. Statuses, exits, and required fields: **digest § 5**
-(whose SSOT is the shipped
-[schema](../../schemas/story-deliver-terminal.schema.json)).
-`pending` is the only sanctioned no-merge ending, returned only when your own
-budget is exhausted. Reference § Step 7.
+hand-composed object. Statuses, exits and fields: **digest § 5** (SSOT: the
+shipped [schema](../../schemas/story-deliver-terminal.schema.json)).
+`pending` is the only sanctioned no-merge ending.
 
-## Recovering a stranded Story {#recover}
+## Steps 4–6 — Recovery (**recovery-only**) {#recover}
+
+A `landed` envelope means everything ran — go to Step 7. Enter recovery **only**
+when the envelope routes you there; procedures are reference §§ Step 4–6.
+Two rules the spine keeps: a red **disarms auto-merge**,
+so only a green on a NEW head SHA re-arms it — a re-run is refused; fix at source
+and push ([`rules/ci-remediation.md`](../../rules/ci-remediation.md)). And a
+`tail.*: false` degrades the report, never the land.
+
+**Watch exit codes** — `pr-watch-with-update.js` exits 0 green, 1 only when a
+required check genuinely failed (or the PR is unreadable), 2 slow-but-not-red:
+still-running, unresolved, **or** `notYetStarted` — no required context attached
+inside `attachWindowMs`. Never route a 2 onto the red path; nothing is broken
+and no digest exists to read.
 
 **Lost envelope first: read it off disk.** Close persists each to
 `temp/orchestration/story-deliver-terminal-<storyId>.json`; branch on it per
-digest § 5. Otherwise (killed run, re-run refusal, merged-but-label-stale)
-do not guess — probe **read-only** with
+digest § 5. Otherwise do not guess — probe **read-only** with
 `node .agents/scripts/deliver-recover.js --story <storyId>`; it prints the
 **one** next command with its evidence, never a menu. A live close answers
 `close-in-flight`: wait, never re-init underneath it.
 
 ## Idempotence & constraints
 
-Every script no-ops safely on re-run (init re-prints `workCwd`; close and
-confirm-merge short-circuit on a closed / `agent::done` Story; the PR probe
-reuses an open PR).
-
-- **Never** push the Story branch directly to `main` — the PR is the only
-  merge surface.
-- **Always** prefix path-based tools with the absolute `workCwd` root
-  (Step 0.5); close's wrong-tree guard is a backstop.
-- **Report state, not process** — mirror the close envelope's fields; no
-  step narration.
-- Drive every `agent::*` transition through
-  `update-ticket-state.js --ticket <id> --state <state>`.
+Every script no-ops safely on re-run (reference § Idempotence). **Never** push
+the Story branch to `main` — the PR is the only merge surface. Report state,
+not process. Drive `agent::*` through
+`update-ticket-state.js --ticket <id> --state <state>`.
 
 ## See also
 
-- [`deliver-digest.md`](deliver-digest.md) — the one bundled framework read.
-- [`/deliver`](../deliver.md) — unified entry point.
-- [`deliver-story-reference.md`](deliver-story-reference.md) — all on-demand
-  detail.
+[`deliver-digest.md`](deliver-digest.md), [`/deliver`](../deliver.md),
+[`deliver-story-reference.md`](deliver-story-reference.md).

package/.agents/workflows/helpers/plan-reference.md

@@ -36,6 +36,22 @@ whole surface exists to remove.
 Mixed ids and prose in one invocation is a **hard error**: refuse and ask which
 was meant, rather than guessing a mode and doing the wrong work.
 
+## Default-single split policy — what the seam means
+
+The spine's two escape hatches from N=1 are narrow on purpose:
+
+- **Near-zero overlap** — the pieces touch disjoint files and neither's
+  acceptance criteria can be scored without the other having landed.
+- **Architectural seam** — different deployables, or a migration and its
+  consumer: work that cannot share one branch and one PR without one half
+  sitting unverifiable behind the other.
+
+Everything else is one Story with `## Slicing` checkpoints. When N>1 does
+apply, **every acceptance criterion belongs to exactly one Story** —
+`assertAcceptancePartition` refuses a split whose criteria repeat across
+siblings, because a verbatim-shared criterion is the signature of coupled work
+cut in half rather than genuinely separable work.
+
 ## Unknown triage — AFK vs HITL
 
 Every open question interrogation surfaces is triaged by **who can resolve
@@ -98,6 +114,14 @@ Resume `/plan` at step 2 (Author) **in this same session** — the interrogation
 is still valid and re-paying for it buys nothing. This bounce-back is not an
 escalation.
 
+**Under `--yes` the offer is recorded and planning proceeds** — it is *never*
+auto-downgraded to light. An unattended run has nobody to confirm the reroute,
+and a suggestion is not a confirmation. The same rule governs unknown triage
+unattended: AFK unknowns are still researched, but no free-form operator
+question is asked — each HITL unknown lands in Key Assumptions marked a
+decision-made-by-default, so the record shows what was decided for the operator
+rather than pretending it was decided with them.
+
 Escalation in the *other* direction — an over-scope prompt on the light path —
 is terminal and requires a fresh session. The rule that separates the two, and
 why it must not be flattened into symmetry:
@@ -191,12 +215,14 @@ ceilings on `STORY_SHAPE_CEILINGS` in
   against the repo before overriding one (authoring `creates` for a file
   that exists at base is a validator rejection). The persist gates stay
   authoritative: they probe the base branch ref, not the working tree.
-- **Keep `## Spec` near contract-level prose.** Persist emits an
-  **advisory** warning past ~250 words (`SPEC_SOFT_WORD_BUDGET`) — it never
-  fails the persist, but it is the nudge toward a contract-level
+- **Keep `## Spec` near contract-level prose.** **Aim for ~250 words; an
+  advisory warning fires past 350** (`SPEC_SOFT_WORD_BUDGET`). Two numbers,
+  two jobs: ~250 is the authoring target — the nudge toward a contract-level
   Spec (interfaces, invariants, load-bearing constraints; no per-file
-  behavior narration). The hard fail-closed ceiling (~1500 tokens,
-  `spec-spill.js`) is unchanged.
+  behavior narration) — while 350 is the slacker threshold at which persist
+  actually warns, so the warning marks a real outlier instead of ordinary
+  variance. Neither fails the persist. The hard fail-closed ceiling
+  (~1500 tokens, `spec-spill.js`) is unchanged.
 
 A faithfully-filled skeleton — placeholders replaced, pre-resolved entries
 kept, tags valid — passes the persist ticket validators with no
@@ -289,11 +315,29 @@ output shape standalone. When the kill-switch is off
 (`roleScopedAgents: false`) or the host cannot spawn at this depth, fall back
 to a generic sub-agent and hand it the same charter (the `consolidation` /
 `pre-mortem` definitions in [`plan-critic.md`](../../agents/plan-critic.md)).
+**When both critics fire, dispatch them in a single turn.** Consolidation and
+pre-mortem read the same immutable draft, share no write path, and neither
+consumes the other's verdict — the textbook independent fan-out of
+[`parallel-tooling.md`](parallel-tooling.md) Rule 3. Issue both `Agent` calls
+together in one assistant turn rather than awaiting the first verdict before
+spawning the second; serialized critics double the round's wall clock and buy
+nothing, because you fold both verdicts into the same re-author round anyway.
+
 Either way the critic is **maker-blind**: hand it the draft artifacts
 (`stories.json`, and `techspec.md` when present) — never the authoring
 transcript or the reasons the planner believed its own draft is sound. A
 critic that reads the maker's case grades the case, not the draft.
 
+## What `--dry-run` actually gates
+
+`plan-persist.js --dry-run` is the same command with GitHub writes suppressed,
+and every gate runs before the first `createIssue` would fire — the validator,
+the body parse, the DAG, the capacity and Spec-budget ceilings, the
+reachability check, the split and supersede partitions, and the Tech Spec fold.
+That is the whole point of running it first: a dry run that comes back clean
+has already paid for every deterministic refusal, so the real persist has
+nothing left to discover except network failure.
+
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.

package/.agents/workflows/memory-consolidate.md

@@ -0,0 +1,116 @@
+---
+description: >-
+  Attended consolidation pass over this project's agent memory pool — merge
+  duplicates, verify claims against the current tree, prune with operator
+  confirmation, rewrite the index, and stamp the pool so the /plan advisory
+  goes quiet.
+---
+
+# /memory-consolidate [--dry-run]
+
+Agent memory drifts as the codebase moves: a workaround gets fixed, a budget
+changes, two sessions save the same lesson twice. This is the sweep that
+corrects it — and the **only** sanctioned writer of the memory pool outside a
+session's own point-of-write corrections.
+
+**Attended by contract.** Mandrel ships the trigger, the grounding and the
+receipt; it never mutates the operator's personal memory store unsupervised.
+Nothing here runs on a schedule, and no step deletes a file before Gate #2.
+
+## Step 0 — Resolve the pool
+
+`MANDREL_MEMORY_DIR` wins outright; otherwise the pool is
+`~/.claude/projects/<cwd-slug>/memory/`, where `<cwd-slug>` is the absolute
+working directory with every `/` and `.` replaced by `-`.
+
+Report the resolved path and the entry count. **No pool → say so in one line
+and stop** — an absent substrate is a clean no-op, never an error, and never a
+reason to create one.
+
+Each project (and each worktree) has its own pool: consolidate the pool of the
+checkout you are in, and never reach across into another.
+
+## Step 1 — Read the pool
+
+Read `MEMORY.md` and every `*.md` entry. Group them by subject so duplicates
+and supersessions surface together. Do not judge an entry from its index line —
+the index is a pointer, the file is the claim.
+
+## Step 2 — Classify each entry
+
+Verify before you keep. Run `ls` / `grep` against the **current tree** for the
+paths, flags, budgets and gate names an entry cites; re-measure a number rather
+than trusting it (`wc -c` a file whose byte budget is quoted).
+
+| Verdict | Means | Action |
+| --- | --- | --- |
+| `fresh` | Claims re-confirmed against the tree | Leave byte-identical |
+| `correct` | Core lesson holds, a detail has moved | Rewrite the detail in place, keep the entry |
+| `duplicate` | Same lesson as another entry | Merge into the richer one, propose the thinner for pruning |
+| `superseded` | The thing it warns about is fixed or retired | Strike the claim, keep the correction visible |
+| `dead` | Subject no longer exists at all | Propose for pruning |
+
+**A closed issue is the subject of a retrospective, never evidence of
+staleness.** These pools are largely delivery write-ups — "delivered this
+Story", "fixed by that PR". The referenced issue being closed is what the
+memory is *about*: the normal, healthy shape. A retired predecessor of this
+workflow marked exactly that pattern stale, which is why it no longer exists.
+Use `github.owner` / `github.repo` from `.agentrc.json` when an issue
+genuinely needs probing, and treat an unreachable probe as unknown — never
+as dead.
+
+Prefer `correct` over `dead`. A rewritten entry keeps hard-won context; a
+deleted one costs a future session the same mistake.
+
+## Step 3 — Gate #1: present the plan
+
+Write the full proposal to `temp/memory/consolidation-<date>.md` — per entry:
+verdict, evidence, and the exact edit or merge proposed. Summarize inline:
+counts per verdict and the specific prune candidates by name.
+
+**STOP.** Do not edit until the operator responds.
+
+## Step 4 — Apply the edits
+
+On confirmation, apply the `correct`, `duplicate` and `superseded` rewrites.
+Preserve each entry's frontmatter contract (`name`, `description`, `metadata`)
+and keep `[[wiki-link]]` references resolvable — a merge that orphans a link
+has moved the problem, not fixed it.
+
+## Step 5 — Gate #2: confirm every deletion
+
+**Deletion is never implied by Gate #1.** Name each file proposed for pruning
+with its one-line reason, and offer **mark-vs-delete**: marking the claim
+superseded in place is the default and always available. Wait for an explicit
+yes; delete only what the operator names. Silence is not consent.
+
+## Step 6 — Rewrite the index and stamp
+
+Rewrite `MEMORY.md` so it holds exactly one pointer line per surviving entry —
+title, link, hook. It is loaded into context every session, so it carries
+pointers only, never memory content.
+
+Then write the receipt to `.consolidation-stamp.json` in the pool root:
+
+```json
+{ "lastConsolidatedAt": "<ISO-8601 timestamp>" }
+```
+
+The `/plan` Phase 0 advisory reads this file; until it is written, the nudge
+keeps firing. Write it **only** after Gate #2 — the stamp asserts an operator
+reviewed the pass, so writing it early makes it a lie.
+
+Close with counts: entries read, corrected, merged, pruned, and the new total.
+
+## Constraints
+
+- `--dry-run` runs Steps 0–3 and stops: the report is written, nothing mutates.
+- Never delete an entry the operator did not name. Never write the stamp on a
+  dry run or a declined gate.
+- Never invent memories here — this pass corrects and prunes what sessions
+  wrote; new memories come from the sessions that learned them.
+
+## See also
+
+[`/plan`](plan.md) (surfaces the advisory at its Gate #1),
+[`/deliver`](deliver.md) (point-of-write corrections as work lands).