mandrel 2.0.0 → 2.1.0

package/.agents/workflows/deliver.md

@@ -1,87 +1,118 @@
 ---
 description:
-  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.
+  Unified delivery entry point. Takes a list of Story ids, resolves their
+  dependency graph from live state, and delivers each via the single
+  deliver-story engine — story-<id> → PR → main.
 ---
 
-# /deliver <storyId...> | --run <planRunId>
+# /deliver <storyId...>
 
 ## Role
 
-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.
+Single delivery path with a single input shape: **a list of Story ids**.
+`/deliver` owns input resolution and sequencing only — every Story runs
+through [`helpers/deliver-story.md`](helpers/deliver-story.md). There is no
+Epic wave loop, no `epic/<id>` integration branch, and no `--no-ff` wave
+merges.
+
+The dependency graph is **discovered, not declared**: `resolve-stories.js`
+reads it from live state (body edges ∪ native GitHub `blocked_by` edges,
+with every blocker resolved against its real issue state). You never hand it
+a graph, and there is no batch label — which is what lets you deliver
+Stories **across plan runs and over time**: a Story whose blocker landed
+weeks ago in a different run is simply ready.
 
 ## Inputs
 
 | 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. |
+| `/deliver <storyId> <storyId> ...` | Resolve the set with `resolve-stories.js`, then sequence by the discovered graph via `stories-wave-tick.js`. Default concurrency is **3**. |
+
+Any named ticket that is not `type::story`, or that still carries an
+`Epic: #N` footer, is a hard error naming the id and the fix (close or
+re-plan as a v2 Story). Resolution refuses the whole set rather than
+silently dropping the offending id and under-delivering.
 
-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).
+> **Retired (Story #4540).** `--run <planRunId>` and the `plan-run::<id>`
+> label are gone, along with `--dep`. Batch identity was the wrong axis:
+> it could not express an edge to a Story planned in another run, while
+> ordering already lives in the dependency edges themselves. Deliver the
+> ids; the graph resolves itself.
 
 ## Flags
 
 | Flag | Meaning |
 | --- | --- |
-| `--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). |
+| `--wait-merge` | Force close-and-land (the default; `delivery.routing.closeAndLand`, default `true`). |
 | `--no-wait-merge` | Opt out of close-and-land; stop at `agent::closing` for a human land. |
 
-## Procedure
+**Operator-merge implies no-wait.** `--no-auto-merge` and
+`delivery.ci.autoMerge: "strict"` deliberately leave the PR un-armed, so
+there is nothing for close to land: the Story rests at `agent::closing` for
+the human merge, and is **not** flipped to `agent::blocked`. An explicit
+`--wait-merge` does not override this — close cannot land a PR that was
+never armed. A genuine *arm failure* is different: it still waits and still
+blocks, because that is a fault to report rather than an operator decision
+to respect.
 
-1. **Resolve the Story set.**
-   - Positional IDs → use them.
-   - `--run <planRunId>` →
+## Procedure
 
-     ```bash
-     node .agents/scripts/resolve-plan-run.js --run <planRunId>
-     ```
+1. **Resolve the set.** One command, for one Story or many:
 
-     Capture `stories[]`, `dag[]`, and `done[]` from the envelope. Prefer
-     the emitted `dag` — do **not** rebuild it by hand when `--run` was used.
+   ```bash
+   node .agents/scripts/resolve-stories.js --ids <id,id,...>
+   ```
 
-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`:
+   Capture `stories[]`, `dag[]`, and `done[]` from the envelope. Do **not**
+   rebuild the graph by hand — it is discovered from live state, including
+   edges a body does not spell out and blockers outside the delivered set.
 
-   ```json
-   [{ "id": 101, "dependsOn": [] }, { "id": 102, "dependsOn": [101] }]
-   ```
+   Resolution hard-errors (exit 1) on a named id that is not a Story, still
+   carries an `Epic: #N` footer, or whose native dependency edges cannot be
+   read. A failed edge read is fatal by design: a missing gate would
+   co-dispatch a Story against an unlanded blocker.
 
-3. **Confirm (N>1).** Present the order and wait unless `--yes`.
+2. **Confirm (N>1).** Present the order and wait unless `--yes`.
 
-4. **Sequence.** Loop until every Story is done:
+3. **Sequence.** Loop until every Story is done:
 
    ```bash
    node .agents/scripts/stories-wave-tick.js \
-     --dag '<json>' --done <csv> --in-flight <n> --concurrency <n>
+     --dag '<dag from step 1>' --done <csv> --in-flight <n> --concurrency <n>
    ```
 
+   **Seed the first beat's `--done` from the resolver's `done[]`** — not from
+   an empty string. That array carries the blockers that have already landed,
+   including foreign ones outside the delivered set. Seeding it empty
+   discards exactly the cross-run resolution this step exists for, and the
+   run wedges on a blocker that finished weeks ago. On later beats, `--done`
+   is `done[]` plus every Story that has since closed.
+
+   Branch on the exit code:
+   - **0** — dispatch each `ready` id. An empty `ready` with work in flight
+     means "waiting"; keep looping.
+   - **2** — `cycleError`: the graph is self-referential. Fix the
+     `depends_on` declarations; do not retry.
+   - **3** — `wedged`: nothing is dispatchable, nothing is in flight, and
+     undone Stories are waiting on blockers that are not done. The envelope
+     names the stuck ids and their unmet blockers. Either land the blocker
+     first or include it in `--ids`. Do not retry unchanged — the state
+     cannot improve on its own.
+
    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:
+4. **Per-run epilogue (N>1).** After the last Story lands, keyed on the
+   delivered id set:
 
    ```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
    ```
 
@@ -112,21 +143,43 @@ to `main`.
 ## Ceremony (profiles + two scopes)
 
 Ceremony depth is selected by `delivery.routing.ceremonyProfile`
-(`minimal` | `standard` | `strict`, default `standard`) and the Story's
-planning risk:
+(`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):
 
 | Profile | Acceptance critic | When to use |
 | --- | --- | --- |
 | `minimal` | Always inline | Tiny trusted N=1 Stories |
-| `standard` | Risk-routed (+ sampling floor) | Default |
+| `standard` | Derived-level routed (+ sampling floor) | Default |
 | `strict` | Always fresh-context | High-assurance / regulated surfaces |
 
 | 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-Story (profile + derived level)** | Acceptance critic mode; review depth | `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 |
+| **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) |
+
+## Reading a Story's outcome
+
+Each Story's delivery ends in exactly one schema-validated terminal envelope
+([`story-deliver-terminal.schema.json`](../schemas/story-deliver-terminal.schema.json),
+Story #4543) — `landed` | `pending` | `blocked` | `failed`. That schema is the
+SSOT for the shape; this workflow does not restate its fields.
+
+`pending` is **not** a failure: the bounded merge wait expired with the PR
+healthy and in flight (or a human owns the merge), nothing was mutated, and
+the envelope's `nextCommand` names what resumes it. Run that command rather
+than re-dispatching the Story.
+
+For a Story in an unclear state — including the merged-but-label-stale one a
+`/deliver` re-run refuses outright — probe it read-only:
+
+```bash
+node .agents/scripts/deliver-recover.js --story <storyId>
+```
 
 ## Constraints
 

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

@@ -24,7 +24,7 @@ confirmation:
    already gone (or never existed) but whose `origin/<branch>` still
    points at a merged PR — even without `--remote`; `--remote` is still
    required to *delete* them. A third branch, whose content already
-   landed in `<base>` by another route (a squash-merged Epic PR, a
+   landed in `<base>` by another route (a squash-merged PR, a
    cherry-pick, a manual `merge --squash`), is caught by a
    **content-equivalence probe** (`git merge-tree --write-tree`,
    git ≥ 2.38) even when it has no merged PR of its own and is not a
@@ -40,7 +40,7 @@ passed, **all four phases run** sequentially. Pass any of
 narrow the run.
 
 > **When to run**: After a session that landed several PRs, or before
-> starting a new Epic / Story, to put the local checkout into a known
+> starting a new Story, to put the local checkout into a known
 > tidy state.
 >
 > **Persona**: `devops-engineer` · **Skills**:

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

@@ -10,7 +10,7 @@ description: >-
 # /git-deliver [Message] [--no-push] [--pr] [--draft] [--no-auto-merge] [--branch <name>] [--base <branch>]
 
 The **single source of truth** for getting outstanding working-tree changes
-out the door when they do not belong to a planned Epic (typo fixes, doc
+out the door when they do not belong to a planned Story (typo fixes, doc
 tweaks, dependency bumps, operator housekeeping, benchmark result commits
 from mandrel-bench's `/benchmark` Step 4). It is the ad-hoc counterpart to
 the heavyweight `/deliver` pipeline: one command that **detects the git

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

@@ -33,7 +33,7 @@ mid-delivery, and evaluates the actual work product.
    continuation of your implementing turn — so the evaluator does not grade its
    own homework.
 
-   > **Sub-agent type + risk-routed ceremony (Epic #4478, M7-B).** When
+   > **Sub-agent type + derived-level ceremony (Epic #4478, M7-B).** When
    > `delivery.routing.roleScopedAgents` is enabled (the **default**), dispatch
    > the critic with `subagent_type: acceptance-critic` — it boots on the
    > role-scoped [`acceptance-critic`](../../agents/acceptance-critic.md) context
@@ -42,20 +42,28 @@ mid-delivery, and evaluates the actual work product.
    > kill-switch is **off** (`roleScopedAgents: false`), fall back to
    > `subagent_type: general-purpose`.
    >
-   > **Whether to spawn fresh at all is risk-routed** (mirrors the risk →
-   > review-depth and risk → audit-lens routers). Resolve it per cluster with
-   > `resolveCeremonyForRisk` from
+   > **Whether to spawn fresh at all is routed off the derived change level**
+   > — the same signal `review-depth.js` resolves depth from, so the two
+   > decisions cannot disagree. Derive it with `deriveChangeLevel` from
+   > [`review-depth.js`](../../scripts/lib/orchestration/review-depth.js) over
+   > the Story's changed files (`git diff --name-only main...story-<id>`), then
+   > resolve the ceremony per cluster with `resolveCeremonyForRisk` from
    > [`ceremony-routing.js`](../../scripts/lib/orchestration/ceremony-routing.js)
-   > 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
-   > forces `fresh` so low risk never means zero independent checking; **missing
-   > / unknown risk → `fresh` + full ceremony** (fail-safe). This chooses
-   > fresh-vs-inline **per cluster only — it never changes the cluster count**.
+   > using that `derivedLevel` and `delivery.routing.freshCriticSampleRate`:
+   > **`high` (the diff touches a sensitive path registered in
+   > `audit-rules.json`) → `fresh`** (spawn the critic); **`low` (it touches
+   > none) → `inline`** (the contract-identical inline fallback below),
+   > **except** the `freshCriticSampleRate` fraction of low-level clusters the
+   > sampling floor forces `fresh` so a low level never means zero independent
+   > checking; **`null` / unknown (the diff could not be enumerated) → `fresh` +
+   > full ceremony** (fail-safe). This chooses fresh-vs-inline **per cluster
+   > only — it never changes the cluster count**.
    >
-   > **Inline-critic path (low-risk-routed OR nesting-absent harness).** The
+   > Story #4542 re-based this off the planner-authored risk verdict: a level
+   > the plan asserted about itself was exactly the signal that could *reduce*
+   > independent checking, and nothing verified it against the diff.
+   >
+   > **Inline-critic path (low-level-routed OR nesting-absent harness).** The
    > verdict is authored **inline** whenever the risk router above resolves to
    > `inline` (a low-risk cluster not caught by the sampling floor), and also as
    > a **fallback** on any harness that cannot spawn the fresh critic.

package/.agents/workflows/helpers/code-quality-guardrails.md

@@ -58,13 +58,13 @@ review-time prose rule.
 
 Per-file Maintainability Index (MI) is tracked in
 [`baselines/maintainability.json`](../../../baselines/maintainability.json).
-A commit that drops a file's MI by more than
-`delivery.quality.codingGuardrails.miDropMustRefactor` points (default
-`1.5`) requires a refactor in the same Story — not a baseline bump. The MI
-ratchet's per-file `tolerance` (default `0.5`) is a noise filter, **not**
-permission to spend the budget; the 1.5-point ceiling is the upper bound
-above which the change is treated as a regression that must be undone or
-offset, not absorbed.
+A commit that drops a file's MI by more than the configured
+`delivery.quality.gates.maintainability.tolerance` (default `0.5` points)
+requires a refactor in the same Story — not a baseline bump. `tolerance` is
+the single MI-drop control: it is not a noise filter beneath a separate
+must-refactor ceiling — any drop past it is treated as a regression that
+must be undone or offset, not absorbed. Set `tolerance` higher only when the
+project deliberately wants a looser MI-drop budget.
 
 `quality:preview --changed-since HEAD` shows the per-file MI delta in the
 working tree before the commit lands.

package/.agents/workflows/helpers/code-review.md

@@ -57,14 +57,16 @@ the argument envelope.
 
 ### Review depth (`depth`)
 
-`depth` is the risk-derived thoroughness lever introduced by Story #3876 and
-made a live consumed signal end to end by Story #3937. The live `/deliver`
-close path resolves it from the Story's judged `planningRisk` envelope
-(read from the per-Story `story-plan-state` checkpoint via
-[`resolveStoryPlanningRisk`](../../scripts/lib/orchestration/story-plan-state.js);
-`high` → `deep`, `low` → `light`, everything else — including a missing
-checkpoint — → `standard`) and passes it into `runCodeReview`.
-`runCodeReview` forwards `depth` to every provider's `runReview` input.
+`depth` is the thoroughness lever introduced by Story #3876, made a live
+consumed signal end to end by Story #3937, and re-based on an observable signal
+by Story #4542. `runCodeReview` derives it from the diff it already enumerates,
+via [`review-depth.js`](../../scripts/lib/orchestration/review-depth.js): the
+changed files' intersection with the `sensitivePaths` classes registered in
+`audit-rules.json` gives the level, their count gives the width, and
+`resolveDepth` folds the two (a sensitive path OR a wide diff → `deep`; neither,
+on a small diff → `light`; an unenumerable diff → `standard`). It takes no
+planner-authored input and reads no checkpoint. `runCodeReview` forwards `depth`
+to every provider's `runReview` input.
 
 It is an **input-only** signal: it changes *how thorough* the review is, never
 the findings envelope (`{ status, severity, posted, report, halted,
@@ -97,7 +99,7 @@ review yourself, honor the `depth` semantics above directly.
 2. Resolve `[BASE_REF]` from `baseRef` and `[HEAD_REF]` from `headRef`.
 3. Fetch the Story ticket and resolve the planning context from its own
    body: folded `## Spec` / `## Slicing`, acceptance criteria, and the
-   `story-plan-state` / `risk-verdict` structured comments when present.
+   `story-plan-state` structured comment when present.
 4. Read that Spec fully to understand the intended scope, architectural
    decisions, and acceptance criteria. Do **not** look for a parent Epic.
 
@@ -376,7 +378,7 @@ in-place.
      structured comment for the operator to triage in Step 5.
 2. **Leave the finding on the structured comment for Step 5.** Required
    when the finding falls into any of the following classes:
-   - `spec-deviation` — the change diverges from the Epic/Tech Spec.
+   - `spec-deviation` — the change diverges from the Story `## Spec`.
    - `secrets` — credentials, tokens, or PII surfaced in the diff.
    - `test-deletion` — coverage was removed without an explicit
      decision in the spec.

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

@@ -161,9 +161,11 @@ The `single-story-close.js` script, in order:
    would strand a CLOSED issue with no merged work if the PR later failed
    CI, went `BEHIND` base, or was closed without merging. The Story rests
    at `agent::closing` while the PR is open with auto-merge armed; the
-   `agent::done` flip (which closes the issue) is deferred to Step 5.5's
-   `single-story-confirm-merge.js`. A Story only reaches `agent::done` once
-   its PR to `main` is confirmed merged.
+   `agent::done` flip (which closes the issue) is deferred to Step 5's
+   merge confirmation — `single-story-confirm-merge.js` on a
+   `--no-wait-merge` run, or the in-close confirm phase on the
+   close-and-land default. (Step 5.5 is the Status-column resync.) A Story
+   only reaches `agent::done` once its PR to `main` is confirmed merged.
 5. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
    is enabled.
 6. **Releases the Story lease** (Story #3483). Clears the Story assignment
@@ -171,8 +173,12 @@ The `single-story-close.js` script, in order:
    unclaimed ticket. The release is a no-op when the operator no longer
    holds the claim (a later run took over via reclaim/steal), so a late
    close never yanks a live claim away from its current owner. Best-effort:
-   a release failure is logged but does not fail an otherwise-clean close —
-   the lease goes stale via TTL regardless. The close result carries
+   a release failure is logged but does not fail an otherwise-clean close.
+   Note the lease does **not** expire on its own: the standalone lease is
+   fail-closed by design (it anchors its heartbeat to now, so a foreign
+   claim always reads as live regardless of the configured TTL), so a
+   claim stranded by a failed release is cleared only by `--steal` or by
+   de-assigning the ticket. The close result carries
    `leaseReleased: <boolean>`.
 
 `--skip-validation` bypasses Step 1 (gates). Use only when re-running
@@ -289,9 +295,8 @@ when `--pr` is omitted) and:
 - **Story already `agent::done` / issue already closed** → idempotent
   `{ action: 'noop', reason: 'already-done' }`.
 
-This is the standalone counterpart to the epic path's post-merge
-`agent::done` flip in `post-merge-close.js` (#2155): the issue closes
-exactly when the work has merged, never at PR-open.
+The issue closes exactly when the work has merged, never at PR-open
+(#2155).
 
 ---
 
@@ -386,33 +391,69 @@ up").
 
 ## Step 7 — Return-contract detail
 
-**The auto-merge wait does not produce a fourth status.** There is no
-"pending" or "waiting" terminal — the CI/auto-merge wait is handled
-*internally* by blocking on `pr-watch-with-update.js` (Step 4) and confirming
-the merge (Step 5). You return **only** when you have reached a genuinely
-terminal state:
-
-- **`status: "done"`** — the PR is confirmed `state: "MERGED"` (Step 5),
-  the Story carries `agent::done`, and Steps 5.5 / 6 have run. `phase: "done"`,
-  `branchDeleted: true`.
-- **`status: "blocked"`** — you transitioned the Story to `agent::blocked`
-  and posted a `friction` comment (acceptance self-eval block in Step 1a, a
-  base-sync conflict, or an operator-blocking CI failure / Anti-Thrashing
-  stop in Step 4). `phase: "blocked"`, `blockerCommentId` set.
-- **`status: "failed"`** — an unrecoverable failure outside the blocked
-  protocol. `phase` reflects where it died.
-
-A turn that ends with prose ("I'll wait for the watch task…", "the next event
-will be its completion notification…") and an **unconfirmed merge** is a
-**contract violation** (the Story #1553 / PR #1554 failure mode): the parent
-wave loop cannot distinguish "still working" from "done but silent", and the
-Story strands at `agent::closing`. If you genuinely cannot confirm the merge,
-that is a `blocked` or `failed` outcome with the JSON contract — not a
-prose hand-off.
+The field-level contract is the shipped schema
+[`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
+(Story #4543) — not this file, and not
+[`agents/story-worker.md`](../../agents/story-worker.md). All three used to
+carry their own prose version; the schema is now the only definition. What
+follows is the *judgement* around it, which a schema cannot express.
+
+### `pending` is a real status — and it is not a park
+
+Earlier revisions asserted "the auto-merge wait does not produce a fourth
+status", on the reasoning that the wait is internally blocking so a run either
+merges or blocks. That was true only while the wait was unbounded — and it was
+never actually unbounded, because the host kills a tool invocation at ~10
+minutes. So a close-and-land whose CI outlived that ceiling took **no**
+terminal path at all: no event, no label, the Story parked at
+`agent::closing`. The status the model refused to name was the one that kept
+happening.
+
+`pending` names it, with its own exit code (3):
+
+- It is **resumable**: no label was mutated, no `merge.unlanded` was emitted,
+  and `nextCommand` names the one command that continues it. The cumulative
+  budget is anchored at the PR's `createdAt`, so resuming does not restart the
+  clock and the give-up bound still means something.
+- It is **not** a park. Returning `pending` because you would rather not wait
+  is the Story #1553 / PR #1554 failure mode wearing a schema. Return it only
+  when the bound genuinely expired, or a human owns the merge.
+
+The no-park rule is therefore unchanged in substance: a turn that ends with
+prose ("I'll wait for the watch task…", "the next event will be its
+completion notification…") and an unconfirmed merge is a **contract
+violation** — the parent cannot distinguish "still working" from "done but
+silent". What changed is that there is now an honest, machine-readable way to
+say "not finished, here is exactly how to continue" instead of a choice
+between lying and blocking forever.
+
+### Exit-code compatibility note (`--no-wait-merge`)
+
+Every close flag keeps its meaning, but the **exit code** of a
+`--no-wait-merge` (or `--no-auto-merge` / `autoMerge: "strict"`) run changed:
+it now exits **3** (`pending`) rather than 0, because the PR is open and a
+human still owns the merge. Reporting `landed` would be a lie, and `landed` is
+what exit 0 means. A wrapper that shells out and tests `exit == 0` to mean
+"close finished" must be updated to treat 3 as the operator-merge success
+path; `!= 0` no longer implies failure.
+
+### Per-status judgement
+
+- **`landed`** — the only status that means done. A `false` in `tail.*`
+  degrades the report, never the land: the merge is on the base branch, and
+  failing it because a Projects v2 mutation flaked would report a false
+  negative about work that demonstrably shipped.
+- **`pending`** — see above.
+- **`blocked`** — you (or the close pipeline) transitioned the Story to
+  `agent::blocked` and posted a `friction` comment. `blocked.blockClass` comes
+  from the shared classifier, never an ad hoc string, and
+  `blocked.frictionCommentId` points at the remediation.
+- **`failed`** — an unrecoverable failure outside the blocked protocol.
+  `phase` reflects where it died.
 
 > **Handoff discipline — report state, not process.** Populate the envelope
 > with essential terminal state only (mirroring the fields
-> `single-story-close.js` / `story-phase.js` already emit). Do not narrate the
+> `single-story-close.js` already emits). Do not narrate the
 > steps you took, and do not prescribe how the next stage should work. Prose
 > process commentary only bloats the hydrated prompt. When run **interactively** (no parent
 > aggregator), this JSON envelope is optional — relay terminal state to the