mandrel 2.14.0 → 2.16.0

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

@@ -1,6 +1,6 @@
 ---
 description: >-
-  The deliver path's one bundled framework read (Story #4736). Carries what
+  The deliver path's one bundled framework read. Carries what
   every Story delivery always needs — dispatch decision, engine invariants,
   the change-set/ceremony incantation, the acceptance-eval gate, and the
   terminal envelope contract — so the engine reads one file instead of
@@ -23,10 +23,10 @@ description: >-
 Read `stories[].dispatchMode` from the `resolve-stories.js` envelope. Two
 rules produce it, in order:
 
-1. **Run topology (#4736).** A run resolving **one** Story is `inline`
+1. **Run topology.** A run resolving **one** Story is `inline`
    whatever its shape — sub-agent isolation is load-bearing only against a
    *concurrent* sibling racing the same checkout, and a one-Story run has none.
-2. **Body shape (#4722).** In a multi-Story run, a lite-shaped body is
+2. **Body shape.** In a multi-Story run, a lite-shaped body is
    `inline`; a full-shaped body, an unparseable one, or a footprint touching a
    sensitive-path class is `subagent`. The `route::lite` label is a
    human-visible hint, never the control signal.
@@ -42,7 +42,6 @@ gates, same PR to `main`, same terminal envelope, byte for byte.
 | Ticket type | `type::story` only; an `Epic: #N` footer means **stop and re-plan** |
 | Branch | `story-<id>`, seeded from `project.baseBranch` (`main`) |
 | Merge target | `main` via PR (squash + required checks) — never a direct push |
-| Integration branch | **None** — no `epic/<id>`, no `--no-ff` wave merge |
 | Gates | Every close gate runs regardless of route; no route bypasses one |
 | State | Only via `update-ticket-state.js --ticket <id> --state <state>` |
 | Paths | Prefix every path-based tool with the absolute `workCwd` — `cd` does not scope them |
@@ -52,7 +51,7 @@ the only sanctioned landing. A silent local build is not a delivery.
 
 ## 3. Change set — computed once, handed to everyone
 
-One enumeration per Story (#4593). A critic that re-runs its own `git diff`
+One enumeration per Story. A critic that re-runs its own `git diff`
 can score a different set than the one that routed it:
 
 ```bash
@@ -76,7 +75,7 @@ fresh. An `inline` dispatch mode overrides all of it to inline critics. Close's
 
 ## 4. Acceptance self-eval (Step 1a, required)
 
-**One verdict-owner per cluster** (#4723) — the fresh critic *or* the inline
+**One verdict-owner per cluster** — the fresh critic *or* the inline
 self-eval, named by `verdictOwner`, never both and never a warm-up pass. It
 scores each `acceptance[]` item against the change set above, with `verify[]`
 output as evidence. Bounded by `delivery.acceptanceEval.maxRounds` (default 2).
@@ -96,7 +95,7 @@ Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
 `single-story-close.js` emits exactly one envelope on stdout between
 `--- STORY DELIVER TERMINAL ---` markers, schema-validated against
 [`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
-(#4543 — the SSOT; read the JSON only when you need a field this table omits).
+— the SSOT; read the JSON only when you need a field this table omits.
 Relay it verbatim; never hand-compose one, never substitute prose.
 
 | `status` | Exit | Meaning | You do |
@@ -113,7 +112,7 @@ Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
 reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
 reported, never omitted, so a missing gate is never read as a passing one.
 
-**Gate output is captured, not streamed (#4736).** Close writes gate lines to
+**Gate output is captured, not streamed.** Close writes gate lines to
 `temp/orchestration/close-gates-<storyId>.log` and reports a one-line digest on
 success; a failed gate replays its tail inline. `AGENT_LOG_LEVEL=verbose`
 restores live streaming.

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

@@ -0,0 +1,222 @@
+---
+description:
+  The unplanned prompt path shared by /deliver and /plan Gate #1. Judges a
+  prompt's predicted footprint, authors a receipt Story, then lands it through
+  the same single-story-init / single-story-close engine — every close gate
+  unchanged.
+---
+
+# Unplanned delivery (the prompt path)
+
+> **A path, not a command.** There is no `/deliver-light` to type. This file is
+> reached two ways — `/deliver "<prompt>"` (an operator describing small work)
+> and `/plan` Gate #1 (a seed the suggestion says fits the light ceilings, once
+> the operator confirms). Read
+> [`deliver-digest.md`](deliver-digest.md) once first — the engine invariants,
+> gates, and terminal-envelope contract below are its.
+
+## Role
+
+For a genuinely trivial change — a one-file fix, a small addition, a small
+amendment — the multi-session plan→deliver ceremony buys nothing the bare model
+lacks except **gates and landing**. This path keeps exactly those: one session
+straight to execution from a prompt, landing through the unchanged close path.
+It never relaxes a close gate, never bypasses the PR to `main`, and never lands
+over-scope work silently.
+
+Two callers, one gate: whichever door you arrived through, the suitability gate
+below is the decision. A `/plan` Gate #1 suggestion is a *suggestion* — it is
+read against seed-time signals (`DELIVER_LIGHT_SUGGESTION_CEILINGS`: artifacts,
+risk hits, sensitive-path classes), while the gate here is read against the
+predicted work's *effort and risk* (`STORY_SHAPE_CEILINGS`: change kinds,
+magnitude, uncertainty, deployable span). They are deliberately two different
+checks, so the gate still runs after a confirm.
+
+## Scope by effort, not by artifact count {#scope-by-effort}
+
+**Counting the footprint is the wrong axis.** Three identical one-line edits
+across three files is trivial work with a high count; a 200-line rewrite of one
+module is a single change. The axes are therefore effort and risk: distinct
+change **kinds** (N instances of one mechanical edit is one kind at N sites), a
+coarse **magnitude** bucket, and **uncertainty** — is the shape determined by
+the request, or does it still need the design decisions `/plan` exists to
+resolve?
+
+Because the predicted footprint is a *declaration* — a guess, and a gameable one
+— this gate is deliberately **coarse**: it rejects clearly-epic work only
+(multiple deployables, a migration plus its consumers, an explicit
+multi-capability enumeration). Size is enforced where ground truth is available:
+the diff backstop in step 4. Do not talk yourself past that one.
+
+Sensitivity is the exception and stays absolute: a footprint touching an auth,
+crypto, billing, or migration class routes `full` however small or mechanical.
+
+## Four invariants (do not skip one)
+
+1. **Suitability gate.** The prompt's predicted footprint is judged by the
+   shared effort/risk machinery (`deriveStoryShape` / `deriveChangeLevel`)
+   **and** a ledgered model verdict with a recorded reason. Both must agree on
+   `lite`.
+2. **Over-scope stops — it never hard-fails.** An over-ceiling prompt STOPS and
+   asks the operator to escalate to `/plan` or proceed light. Under `--yes` it
+   fails closed to an **`escalated` terminal envelope** that ends the session
+   (§ Escalation is terminal).
+3. **Diff-derived backstop.** After implementation the ACTUAL change set is
+   re-checked — the diff is the real scope signal — and an over-ceiling diff is
+   blocked rather than landed.
+4. **Minimal receipt Story.** A `type::story` is authored inline so `refs #`,
+   history, telemetry, and the `agent::executing → agent::done` state machine
+   all survive.
+
+## Procedure
+
+1. **Predict + gate.** Form the predicted footprint (new files, edited files,
+   acceptance count), judge its effort honestly (`--kinds` / `--magnitude` /
+   `--uncertainty`, per § Scope by effort), and record your ledgered verdict (a
+   recorded reason for `lite`), then run the gate — it documents every flag
+   itself, so run it with `--help` rather than guessing:
+
+   ```bash
+   node .agents/scripts/deliver-light.js --prompt "<prompt>" \
+     --creates <csv> --refactors <csv> --acceptance <n> \
+     --kinds <csv> --magnitude trivial|moderate|substantial \
+     --uncertainty determined|needs-design \
+     --route lite --reason "<why this is trivial>" [--amends '#<id>'] [--yes]
+   ```
+
+   Branch on `action` in the JSON envelope:
+   - **`proceed-light`** — the receipt Story is authored; read `storyId` and
+     `nextCommands`. Continue to step 2.
+   - **`ask-operator`** — predicted scope exceeds the light ceilings. STOP and
+     ask the operator to escalate to `/plan` or proceed light. Do not proceed
+     on your own. This is a **question, not a terminal** — wait for the answer.
+   - **over-scope under `--yes`** — no `action` to branch on: the gate emits an
+     **`escalated` terminal envelope** instead (exit 2). § Escalation is
+     terminal governs; you are finished.
+
+   `--amends '#<id>'` is the canonical light case — shape-checked identically; a
+   heavy amendment escalates to `/plan` like any other over-scope prompt.
+
+   **Entered from `/plan` Gate #1?** Fill `--creates` / `--refactors` /
+   `--acceptance` / `--reason` from the plan-context envelope's codebase
+   snapshot and `complexitySignals` rather than re-deriving them from the seed
+   text — Gate #1 has already done that work, and re-deriving throws away the
+   better signal. An `ask-operator` verdict here means the two ceiling sets
+   disagreed: **return to [`../plan.md`](../plan.md) step 2 (Author) in the same
+   session**, carrying the interrogation you already paid for. That bounce-back
+   is not an escalation and does not need a fresh session (§ Why the two
+   directions differ).
+
+2. **Init (same engine).** From the main checkout, synchronously, with the
+   maximum Bash timeout:
+
+   ```bash
+   node .agents/scripts/single-story-init.js --story <storyId>
+   ```
+
+   Capture `workCwd`; `remoteVerified: false` → flip `agent::blocked` and stop.
+   This is [`/deliver`](../deliver.md)'s worktree/branch/lease/label engine,
+   invoked, not reimplemented.
+
+3. **Implement + self-eval.** `cd` into `workCwd`, implement the change, run
+   `npm test` once in the worktree, then run the bounded acceptance self-eval
+   loop ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
+   on `story-<id>` with `(refs #<storyId>)`.
+
+4. **Diff backstop.** Before close, re-check the ACTUAL diff:
+
+   ```bash
+   node .agents/scripts/deliver-light.js --backstop --story <storyId>
+   ```
+
+   Exit `3` (`blocked: true`) means the landed diff exceeds the light ceilings
+   (file count or a sensitive-path class). STOP, flip `agent::blocked`, and
+   escalate to `/plan` — do not land. This is the pass that actually bounds
+   size, which is why the prediction gate above can afford to be coarse.
+
+5. **Close and land (same engine).** Exactly [`/deliver`](../deliver.md)'s close:
+
+   ```bash
+   node .agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo>
+   ```
+
+   Branch on the terminal envelope's `status` per
+   [`deliver-digest.md`](deliver-digest.md) § 5 — every close
+   gate runs byte-identical to the full path.
+
+## Escalation is terminal {#escalation-is-terminal}
+
+Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`
+envelope with **`status: "escalated"`**, `storyId: null`, and a `nextCommand`
+naming the `/plan` invocation that owns the work.
+
+**That envelope IS this session's terminal output.** Relay it and stop. There is
+no remaining step, no degraded fallback, and no smaller version of the work to
+attempt.
+
+**Invoking `/plan` in this same session is forbidden.** Hand the operator the
+`nextCommand`; `/plan` runs in a **fresh** session.
+
+This is not style — it is the empirical finding that motivated the envelope.
+A mandrel-bench 2.13.0 light-arm run read the escalation and continued anyway:
+it invoked `/plan` in-session and delivered. The in-session plan authored **one**
+Story against the scenario's 3–5 contract, where a fresh `/plan` session on the
+identical seed authored **four**. Planning inside a session already framed as
+small work under-decomposes, so walking past the escalation silently produced
+the very outcome the guard exists to prevent. The gate's decision was right both
+times; only the outcome's finality was missing.
+
+Nothing is left half-started: an escalated run creates **no receipt Story, no
+`story-<id>` branch, and no worktree** — the escalation path returns before
+every creation call site, and `escalation.created` records all three as `false`
+in a shape the schema pins, so a later run finds nothing to trip over.
+
+## Why the two directions differ {#why-the-two-directions-differ}
+
+Traffic runs both ways between this path and `/plan`, and the two directions
+have **deliberately different session rules**. It reads like an inconsistency;
+it is not. The rule:
+
+> **The direction whose guard is model judgment must break the session. The
+> direction whose guard is mechanical need not.**
+
+**Light → `/plan` must be a fresh session.** What is being protected is
+*authoring judgment*, and the empirical finding above is that a session already
+framed as small work under-decomposes — one Story against a 3–5 contract where
+a fresh session on the identical seed authored four. The frame is the hazard,
+so only a new session removes it.
+
+**`/plan` → light may stay in-session.** Gate #1 fires **before** authoring, so
+there is no authoring to corrupt, and the frame at that point is "plan this
+seed" — the neutral one, not the small one. Everything on the receiving side is
+mechanical: `STORY_SHAPE_CEILINGS`, the ledgered verdict, the diff backstop.
+None of them degrade because the context is large, so nothing is gained by
+paying for a fresh session.
+
+Do not "fix" this into symmetry in either direction. Making `/plan` → light
+require a fresh session throws away a paid-for interrogation for no guard.
+Letting light → `/plan` run in-session reintroduces the exact failure the
+`escalated` envelope exists to prevent.
+
+## Constraints
+
+- **Land, block, or escalate — never a silent local build.** The close push is
+  the only sanctioned landing; an `escalated` terminal is the only sanctioned
+  ending that delivers nothing, and it ends the session
+  (§ Escalation is terminal).
+- **No parallel engine.** This path invokes `single-story-init.js` and
+  `single-story-close.js`; it never reimplements worktree, branch, PR, or merge
+  mechanics.
+- **State only via `update-ticket-state.js`.** Drive every `agent::*`
+  transition through the script; report state, not process.
+
+## See also
+
+- [`/deliver`](../deliver.md) — the delivery entry point; routes here on a
+  free-text prompt.
+- [`/plan`](../plan.md) — routes here from Gate #1 on a confirmed suggestion,
+  and owns the work an over-scope prompt escalates to.
+- [`deliver-story.md`](deliver-story.md) — the one Story delivery engine every
+  path shares.
+- [`deliver-digest.md`](deliver-digest.md) — engine invariants, gates, and the
+  terminal-envelope contract.

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

@@ -9,7 +9,7 @@ description:
 # /deliver — reference appendix (on-demand)
 
 Reference-only detail split out of [`deliver.md`](../deliver.md) so the
-always-resident spine stays lean (Story #4708). Nothing here is a new MUST —
+always-resident spine stays lean. Nothing here is a new MUST —
 it is the mechanics an operator consults when the matching lever is engaged.
 
 ## Sequencing edge cases (`stories-wave-tick.js`)
@@ -18,13 +18,13 @@ Each beat re-probes live state: it re-resolves the graph, classifies **done**
 (`agent::done` or a closed issue — including foreign blockers that landed in
 another run), and derives **in-flight** from live `agent::executing` /
 `agent::closing` labels. You never compute `done` or `in-flight` — that
-accounting is read from reality every beat (Story #4594).
+accounting is read from reality every beat.
 
-**`--dispatched` is the one thing you must tell it (Story #4601).** List every
+**`--dispatched` is the one thing you must tell it.** List every
 Story id you have spawned this run. Live state cannot instantly report a Story
 you dispatched moments ago: `single-story-init.js` publishes `agent::executing`
-before the worktree install (Story #4620 moved it ahead of the multi-minute
-install, so the window is now short rather than minutes-long), but it is not
+before the worktree install (ahead of the multi-minute install, so the
+window is short rather than minutes-long), but it is not
 zero — until the label lands the Story still reads `agent::ready` and, without
 `--dispatched`, the next beat would hand it back and a second sub-agent would
 join the first on the same branch and worktree, interleaving commits.
@@ -34,10 +34,10 @@ is additive, not authoritative — the probe unions it into the label-derived se
 and then filters it against live state, so an id that has since gone
 `agent::done` is dropped for you. Re-listing an id costs nothing and cannot
 double-count a slot; *omitting* one is the only way to get this wrong. This is
-why `--dispatched` is not the `--done` bookkeeping #4594 retired, and why
+why `--dispatched` is not the retired `--done` bookkeeping, and why
 `--in-flight` remains rejected under `--probe-live`.
 
-**Cross-run de-confliction is automatic (Story #4620).** A Story another
+**Cross-run de-confliction is automatic.** A Story another
 operator is delivering is withheld without any bookkeeping from you: the probe
 reads the Story's assignee lease and, when it belongs to a different operator,
 withholds the Story and reports it in the envelope's
@@ -51,7 +51,7 @@ probe logs a warning and leans on init's lease refusal alone.
 
 ## Dispatch mechanics (role-scoped by default)
 
-**A single-Story run executes inline (Story #4736).** Sub-agent isolation is
+**A single-Story run executes inline.** Sub-agent isolation is
 load-bearing only for **concurrent** dispatch — two workers sharing a checkout
 would race on worktrees and branch refs — so a run resolving exactly one Story
 has no sibling to isolate from and pays the spawn premium for nothing (a boot is
@@ -61,7 +61,7 @@ a cache write at full rate; an inline continuation is a cache read at ~10%).
 retained in full for multi-Story waves, and the rule changes **where** the
 engine runs, never what runs — gates, PR, and terminal envelope are identical.
 
-**Lite-shaped Stories execute inline (Story #4722).** Before spawning anything,
+**Lite-shaped Stories execute inline.** Before spawning anything,
 read the Story's `dispatchMode` from the resolver envelope
 (`stories[].dispatchMode`, derived by `resolveStoryDispatchMode` in
 `lib/orchestration/complexity-gate.js` **from the fetched Story body's own
@@ -91,9 +91,10 @@ prompt: `storyId`; `docsDigestPath` (the per-run docs digest, null when
 `project.docsContextFiles` is unset); `checklistPath` (the footprint-matched
 write-time audit checklist, produced at dispatch, below); and the
 **change-set discipline** — the worker computes the change set once with
-`computeChangeSet` and hands that one list to every acceptance critic (Story #4593); it never lets a critic re-derive the diff.
+`computeChangeSet` and hands that one list to every acceptance critic; it
+never lets a critic re-derive the diff.
 
-**Produce `checklistPath` before the spawn (Story #4627).** Compute the payload
+**Produce `checklistPath` before the spawn.** Compute the payload
 from the Story's predicted footprint (its `changes[]` / `references[]` path
 entries) with `buildDispatchChecklist` and write it to the run temp dir, then
 thread the resulting path (empty when nothing matched):
@@ -124,6 +125,38 @@ execute it directly, in this turn, threading the same `docsDigestPath` /
 content, execute directly without a re-read turn. The engine, gates, and
 terminal envelope are identical either way — only the isolation differs.
 
+## Intent phrases (what replaced the flag table)
+
+`/deliver` has no operator-facing flags. The scripts still take every flag they
+always did — the workflow fills them in from what the operator said, the same
+derive-then-announce contract `/git-deliver` uses for its terminal level.
+
+| The operator says | You pass | Effect |
+| --- | --- | --- |
+| "I'll merge it myself", "don't wait", "just open the PR" | `--no-wait-merge` | Rest at `agent::closing` for a human land |
+| "wait for the merge", "land it" | `--wait-merge` | Close-and-land — already the default (`delivery.routing.closeAndLand`) |
+| "take the lease", "steal it", "it's mine, override" | `--steal` | Forwarded to `single-story-init.js` |
+| "one at a time", "sequentially", "no parallelism" | `--concurrency 1` | Serialize a multi-Story run |
+| "run <n> at once" | `--concurrency <n>` | One-run cap only |
+
+Two rules keep this honest:
+
+1. **Announce before acting.** Name the intent you read and the flag it fills
+   in. A misread phrase is then visible in one line rather than discovered at
+   the terminal envelope.
+2. **Silence means config, not a literal.** With no intent phrase, omit the
+   flag entirely so `delivery.deliverRunner.concurrencyCap` (and any
+   `.agentrc.local.json` override) wins. Filling in the config default as a
+   literal silently defeats that override — the failure this table most easily
+   causes.
+
+`--yes` is deliberately **absent** from the table. It is not an intent an
+operator expresses; it is a runner asserting *nobody is at the keyboard*, and
+it changes fail-closed behavior (it is what turns the unplanned path's
+over-scope stop into an `escalated` terminal envelope, and what auto-proceeds
+`/plan`'s gates). Cron, `/loop`, and headless dispatch set it. An attended run
+never does, however the operator phrases their impatience.
+
 ## Operator-merge implies no-wait
 
 `--no-auto-merge` and `delivery.ci.autoMerge: "strict"` leave the PR
@@ -163,8 +196,7 @@ Ceremony depth is selected by `delivery.routing.ceremonyProfile`
 (`minimal` | `standard` | `strict`, default `standard`) and the **change level
 derived from the Story's own diff** — the changed files' intersection with the
 sensitive-path classes in `audit-rules.json`
-(`review-depth.js#deriveChangeLevel`), not a planner-authored verdict
-(Story #4542):
+(`review-depth.js#deriveChangeLevel`), not a planner-authored verdict:
 
 | Profile | Acceptance critic | When to use |
 | --- | --- | --- |
@@ -179,7 +211,7 @@ sensitive-path classes in `audit-rules.json`
 | **Per-run (N>1)** | Audit roster · follow-up roll-up · sibling coherence | `plan-run-epilogue.js` once at run end |
 | **Per-Story land tail** | Follow-up capture · status resync · ref cleanup · base fast-forward | `single-story-close/phases/post-land.js` (in-process, per-step reported) |
 
-## Async merge-confirm mode (`delivery.mergeWatch.mode: "async"`, Story #4698)
+## Async merge-confirm mode (`delivery.mergeWatch.mode: "async"`)
 
 A slow-CI consumer can opt the close into `"async"` mode so the merge wait
 probes once for ~60s (catching an instant merge or an instantly-red required