mandrel 2.0.0 → 2.2.0

package/.agents/schemas/agentrc.schema.json

@@ -249,7 +249,12 @@
           "type": "array",
           "items": {
             "type": "string",
-            "enum": ["state-transition", "story-merged", "operator-message"]
+            "enum": [
+              "state-transition",
+              "story-merged",
+              "story-closing",
+              "operator-message"
+            ]
           },
           "uniqueItems": true
         },
@@ -258,11 +263,13 @@
           "items": {
             "type": "string",
             "enum": [
-              "epic-started",
-              "epic-progress",
-              "epic-blocked",
-              "epic-unblocked",
-              "epic-complete"
+              "state-transition",
+              "story-merged",
+              "story-closing",
+              "operator-message",
+              "merge.unlanded",
+              "merge.flip-failed",
+              "loop.tick"
             ]
           },
           "uniqueItems": true
@@ -311,29 +318,12 @@
       },
       "additionalProperties": false
     },
-    "planningContext": {
-      "type": "object",
-      "properties": {
-        "maxBytes": {
-          "type": "integer",
-          "minimum": 1024
-        },
-        "summaryMode": {
-          "type": "string",
-          "enum": ["auto", "always", "never"]
-        }
-      },
-      "additionalProperties": false
-    },
     "planning": {
       "type": "object",
       "properties": {
         "riskHeuristics": {
           "$ref": "#/$defs/listOrExtenderOfStrings"
         },
-        "context": {
-          "$ref": "#/$defs/planningContext"
-        },
         "codebaseSnapshot": {
           "$ref": "#/$defs/codebaseSnapshot"
         },
@@ -426,7 +416,7 @@
     },
     "lease": {
       "type": "object",
-      "description": "Story #3480 (Epic #3457). Assignee-as-lease primitive. ttlMs is the staleness window — a ticket claim whose owner has not emitted a story.heartbeat within this many milliseconds is reclaimable by another operator. Defaults to 900000 (15 min) in lib/config/limits.js.",
+      "description": "Story #3480 (Epic #3457). Assignee-as-lease primitive. ttlMs is the staleness window — a ticket claim whose owner's last heartbeat is older than this many milliseconds is reclaimable by another operator. Defaults to 900000 (15 min) in lib/config/limits.js. Note the shipped guards fail closed (there is no live heartbeat source), so a stranded claim is cleared with --steal rather than by TTL expiry.",
       "properties": {
         "ttlMs": {
           "type": "integer",
@@ -461,11 +451,6 @@
           "type": "integer",
           "minimum": 1,
           "description": "Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff."
-        },
-        "verifyConcurrencyCap": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Bounded-concurrency cap for the per-wave verifyWaveResults loop (Epic #3019 Tech Spec §1.4). Separate from the wave-execution `concurrencyCap` so operators can tune ticket-verification parallelism independently of Story dispatch parallelism. Default 4."
         }
       },
       "additionalProperties": false
@@ -1076,10 +1061,6 @@
           "type": "integer",
           "minimum": 1
         },
-        "miDropMustRefactor": {
-          "type": "number",
-          "minimum": 0
-        },
         "requireSiblingTest": {
           "type": "boolean"
         }
@@ -1092,10 +1073,6 @@
         "enabled": {
           "type": "boolean"
         },
-        "miDropCap": {
-          "type": "number",
-          "minimum": 0
-        },
         "crapJumpCap": {
           "type": "number",
           "minimum": 0
@@ -1173,19 +1150,31 @@
     },
     "mergeWatch": {
       "type": "object",
-      "description": "Knobs consumed by the MergeWatcher lifecycle listener (Story #2896, Epic #2880). `intervalSeconds` is the poll cadence between `gh pr view --json mergeCommit,mergedAt` probes after epic.merge.armed; `maxBudgetSeconds` is the total wall-clock budget before the watcher surfaces `agent::blocked` with reason `budget-exceeded`.",
+      "description": "Knobs consumed by the close-and-land merge wait (Story #4543; defaults in `lib/orchestration/merge-poll.js`). `intervalSeconds` is the poll cadence between `gh pr view` probes after the arm. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. `updateAttempts` caps the bounded update of a behind-the-base PR.",
       "properties": {
         "intervalSeconds": {
           "type": "integer",
           "minimum": 1,
           "default": 30,
-          "description": "Seconds between MergeWatcher polls. Default 30."
+          "description": "Seconds between merge-wait polls. Default 30."
+        },
+        "maxWaitSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 300,
+          "description": "Per-invocation merge-wait bound (seconds). Default 300 (5 minutes) — chosen to fit inside a single host tool invocation (~10 min ceiling) alongside the close gates that precede the wait. Expiry yields `pending` (exit 3), never a block. Headless callers with no host ceiling raise this to land in one block."
         },
         "maxBudgetSeconds": {
           "type": "integer",
           "minimum": 1,
           "default": 3600,
-          "description": "Total wall-clock budget (seconds) for the MergeWatcher poll loop. Default 3600 (60 minutes)."
+          "description": "Cumulative wall-clock budget (seconds) across merge-wait resumes, anchored at the PR's createdAt. Default 3600 (60 minutes). Exhausting this classifies the block and transitions the Story to agent::blocked."
+        },
+        "updateAttempts": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 3,
+          "description": "Maximum times the merge wait will bring a behind-the-base PR up to date before giving up on the branch. Default 3. Set 0 to disable the update."
         }
       },
       "additionalProperties": false
@@ -1217,7 +1206,7 @@
         },
         "navigability": {
           "type": "object",
-          "description": "Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /deliver's risk-routed ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op.",
+          "description": "Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /deliver's per-Story ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op.",
           "properties": {
             "routeGlobs": {
               "type": "array",
@@ -1235,7 +1224,7 @@
             },
             "journeySuite": {
               "type": "string",
-              "description": "Path or command for the per-persona journey suite /deliver's risk-routed ceremony runs."
+              "description": "Path or command for the per-persona journey suite /deliver's per-Story ceremony runs."
             }
           },
           "additionalProperties": false
@@ -1257,7 +1246,7 @@
     },
     "acceptanceEval": {
       "type": "object",
-      "description": "Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the working diff against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on).",
+      "description": "Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds, then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the loop is a hard cutover (always on).",
       "properties": {
         "maxRounds": {
           "type": "integer",
@@ -1350,12 +1339,12 @@
               "type": "number",
               "minimum": 0,
               "maximum": 1,
-              "description": "Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Risk-routed ceremony sends a low-risk acceptance cluster down the contract-identical inline critic path, but this fraction of low-risk clusters is still forced through a fresh-context critic so low risk never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Default 0.2. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js)."
+              "description": "Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Default 0.2. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js)."
             },
             "ceremonyProfile": {
               "type": "string",
               "enum": ["minimal", "standard", "strict"],
-              "description": "Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = risk-routed with the maker-checker sampling floor."
+              "description": "Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff, with the maker-checker sampling floor."
             },
             "closeAndLand": {
               "type": "boolean",
@@ -1370,7 +1359,7 @@
             "auditResultsAutoFile": {
               "type": "boolean",
               "default": true,
-              "description": "When true (default), the Epic finalize listener auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Epic."
+              "description": "When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story."
             },
             "retroProposals": {
               "type": "boolean",

package/.agents/schemas/audit-rules.json

@@ -7,7 +7,10 @@
       "substitutionKeys": []
     },
     "audit-architecture": {
-      "triggers": { "gates": ["gate1", "gate3"] },
+      "triggers": {
+        "gates": ["gate1", "gate3"],
+        "filePatterns": [".agents/scripts/lib/**", "lib/**", "bin/**", "src/**"]
+      },
       "scope": "cumulative",
       "substitutionKeys": []
     },
@@ -58,6 +61,7 @@
           "**/frontend/**/*.js"
         ]
       },
+      "target": "web",
       "scope": "local",
       "substitutionKeys": []
     },
@@ -147,6 +151,7 @@
         "keywords": ["seo", "meta", "structured data", "schema.org", "sitemap"],
         "filePatterns": ["**/*.html", "**/sitemap*", "**/robots.txt"]
       },
+      "target": "web",
       "scope": "local",
       "substitutionKeys": []
     },
@@ -160,6 +165,7 @@
           "**/*.css"
         ]
       },
+      "target": "web",
       "scope": "local",
       "substitutionKeys": []
     },
@@ -173,8 +179,60 @@
           "route tree"
         ]
       },
+      "target": "web",
       "scope": "global",
       "substitutionKeys": []
     }
+  },
+  "sensitivePaths": {
+    "security": {
+      "description": "Authentication, authorization, session, and secret-handling surfaces.",
+      "filePatterns": [
+        "**/auth/**",
+        "**/authn/**",
+        "**/authz/**",
+        "**/crypto/**",
+        "**/session/**",
+        "**/*credential*",
+        "**/*permission*",
+        "**/*.pem",
+        "**/*.key"
+      ]
+    },
+    "data-migration": {
+      "description": "Schema migrations and seed data — changes that rewrite persisted state.",
+      "filePatterns": [
+        "**/migrations/**",
+        "**/migrate/**",
+        "**/seeds/**",
+        "**/*.sql",
+        "**/schema.prisma"
+      ]
+    },
+    "billing": {
+      "description": "Money movement: payment, checkout, invoicing, and subscription surfaces.",
+      "filePatterns": [
+        "**/billing/**",
+        "**/payment/**",
+        "**/payments/**",
+        "**/checkout/**",
+        "**/invoice*/**",
+        "**/subscription*/**"
+      ]
+    },
+    "destructive-mutation": {
+      "description": "Irreversible mutation paths — deletion, purge, and teardown.",
+      "filePatterns": ["**/*delete*", "**/*destroy*", "**/*purge*"]
+    },
+    "public-api": {
+      "description": "The externally-consumed contract surface: routes, controllers, and API schemas.",
+      "filePatterns": [
+        "**/api/**",
+        "**/routes/**",
+        "**/controllers/**",
+        "**/openapi/**",
+        "**/graphql/**"
+      ]
+    }
   }
 }

package/.agents/schemas/audit-rules.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://mandrel.dev/schemas/audit-rules.schema.json",
   "title": "AuditRulesManifest",
-  "description": "Schema describing the audit-rules.json manifest read by select-audits.js and lib/audit-suite/runner.js. The manifest enumerates registered audit workflows and the triggers / substitution keys each one accepts.",
+  "description": "Schema describing the audit-rules.json manifest read by lib/audit-suite/selector.js and lib/audit-suite/runner.js. The manifest enumerates registered audit workflows and the triggers / substitution keys each one accepts, plus the sensitive-path classes that derive review depth from a change set.",
   "type": "object",
   "required": ["version", "audits"],
   "additionalProperties": false,
@@ -19,9 +19,35 @@
         "^[a-z][a-z0-9-]*$": { "$ref": "#/definitions/auditEntry" }
       },
       "additionalProperties": false
+    },
+    "sensitivePaths": {
+      "type": "object",
+      "description": "Map of sensitive-path class name to the globs that identify it. A change set touching any registered pattern derives a `high` change level, which resolves review depth to `deep` and the acceptance critic to `fresh` regardless of how narrow the diff is (deriveChangeLevel in lib/orchestration/review-depth.js). This is configuration, not code: an operator extends the classes or their globs here without editing a module, and the globs run through the same picomatch machinery as the audit-lens `filePatterns` triggers above. An absent or empty block means no path is sensitive and depth falls back to diff width alone.",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": { "$ref": "#/definitions/sensitivePathClass" }
+      },
+      "additionalProperties": false
     }
   },
   "definitions": {
+    "sensitivePathClass": {
+      "type": "object",
+      "required": ["filePatterns"],
+      "additionalProperties": false,
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "What this class covers — why a change here warrants a deeper pass."
+        },
+        "filePatterns": {
+          "type": "array",
+          "description": "Glob patterns matched against the changed files of the diff under review.",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "minItems": 1
+        }
+      }
+    },
     "auditEntry": {
       "type": "object",
       "required": ["triggers", "scope"],
@@ -33,6 +59,12 @@
           "enum": ["local", "cumulative", "global"],
           "description": "Concern-ownership tier declaring the widest scope at which this lens's concern becomes decidable. `local` — decidable from a single Story's diff (verified at write-time + Story-scope review). `cumulative` — only decidable across the Epic's combined diff (verified at Epic close). `global` — evaluates a whole-product property regardless of the diff (verified at Epic close; exempt from change-set narrowing). All tier routing derives from this one field via resolveLensTier()."
         },
+        "target": {
+          "type": "string",
+          "enum": ["web", "any"],
+          "description": "Target-applicability gate: the kind of project this lens can say anything about. `web` — the lens reads a rendered web surface (pages, routes, HTML/CSS, design tokens) and is skipped entirely on a project that has none, however well its keyword or file-pattern triggers match. `any` — always applicable. ABSENT MEANS `any`: omitting the key never changes a lens's behaviour. Applicability is decided by the hasWebSurface() probe in lib/audit-suite/selector.js from observables in the consumer's own checkout — configured navigability routeGlobs, a declared web-framework dependency, or a tracked .html/.css/.jsx/.tsx source file — and NOT from an .agentrc key, so a consumer with a real web surface keeps these lenses with no configuration. The probe fails OPEN: an indeterminate answer treats the project as web-capable, because a wasted lens run is recoverable and silently dropped coverage is not.",
+          "default": "any"
+        },
         "substitutionKeys": {
           "type": "array",
           "description": "Substitution keys this audit accepts via run-audit-suite --substitution. Empty array means no caller-supplied keys are allowed.",

package/.agents/schemas/lifecycle/README.md

@@ -10,8 +10,7 @@ throw.
 Each event in the Tech Spec taxonomy has a `<event>.schema.json`
 file. The ledger record (`emitted | completed | failed` union)
 lives in `ledger-record.schema.json` and is consumed by
-`ledger-writer.js` and the `lib/orchestration/lifecycle/ledger-diff.js`
-assertion helpers.
+`ledger-writer.js`.
 
 Schemas are intentionally permissive (`additionalProperties: true`)
 on inner objects whose shape is dictated by upstream tooling (e.g.

package/.agents/schemas/lifecycle/ledger-record.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/ledger-record.schema.json",
   "title": "Lifecycle ledger record (emitted | completed | failed)",
-  "description": "Append-only NDJSON record shape for temp/run-<id>/lifecycle.ndjson. Three discriminated kinds; consumers (LedgerWriter, the ledger-diff assertion helpers, TraceLogger) discriminate on `kind`.",
+  "description": "Append-only NDJSON record shape for temp/run-<id>/lifecycle.ndjson. Three discriminated kinds; consumers (LedgerWriter, TraceLogger) discriminate on `kind`.",
   "oneOf": [
     { "$ref": "#/$defs/emitted" },
     { "$ref": "#/$defs/completed" },

package/.agents/schemas/lifecycle/merge.flip-failed.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/merge.flip-failed.schema.json",
+  "title": "merge.flip-failed",
+  "description": "Emitted when a delivery run observed a CONFIRMED merge but the agent::closing → agent::done label write itself failed. Deliberately distinct from merge.unlanded (Story #4539): the merge landed, so attributing this to an unlanded merge sends the operator to branch protection and required checks when the real fault is an API failure on the label write, remedied by re-running single-story-confirm-merge.js. scope distinguishes the epic-path (ticketId = epicId) from the standalone story-path (ticketId = storyId).",
+  "type": "object",
+  "required": [
+    "event",
+    "scope",
+    "ticketId",
+    "prNumber",
+    "blockClass",
+    "reason",
+    "elapsedSeconds"
+  ],
+  "properties": {
+    "event": { "type": "string", "const": "merge.flip-failed" },
+    "scope": {
+      "type": "string",
+      "enum": ["epic", "story"]
+    },
+    "ticketId": { "type": "integer", "minimum": 1 },
+    "prNumber": { "type": "integer", "minimum": 1 },
+    "blockClass": {
+      "type": "string",
+      "enum": ["merged-flip-failed"]
+    },
+    "reason": { "type": "string", "minLength": 1 },
+    "elapsedSeconds": { "type": "number", "minimum": 0 },
+    "timestamp": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/merge.unlanded.schema.json

@@ -25,6 +25,7 @@
       "type": "string",
       "enum": [
         "checks-pending-timeout",
+        "checks-failed",
         "branch-protection-human-required",
         "arm-failure",
         "api-race-other",

package/.agents/schemas/lifecycle/story.merged.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/story.merged.schema.json",
   "title": "story.merged",
-  "description": "Emitted from the story-close path after a Story branch successfully merges into epic/<id>.",
+  "description": "Emitted from the story-close path after a Story branch successfully merges into main (single-story/confirm-merge.js).",
   "type": "object",
   "required": ["storyId", "sha"],
   "properties": {

package/.agents/schemas/signal-event.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/signal-event.schema.json",
   "title": "SignalEvent",
-  "description": "One NDJSON line emitted by the signals writer (Epic #1030; canonical envelope cutover Epic #4406 / Story #4413). Runtime events live in append-only NDJSON on local disk under temp/epic-<eid>/stories/story-<sid>/signals.ndjson (per-Story) and temp/epic-<eid>/signals.ndjson (Epic-level wave lifecycle); tickets carry only summaries (story-perf-summary, epic-perf-report). `kind: trace` is the raw tool-call trace; the named kinds are derived signals. This is the ONLY shape — the legacy `timestamp` / `epic` aliases and the `source: { tool }` provenance object were deleted in the same PR that moved every writer (no read-side compatibility branch).",
+  "description": "One NDJSON line emitted by the signals writer (Epic #1030; canonical envelope cutover Epic #4406 / Story #4413). Runtime events live in append-only NDJSON on local disk under temp/run-<id>/stories/story-<sid>/signals.ndjson (per-Story) and temp/run-<id>/signals.ndjson (Epic-level wave lifecycle); The stream stays local: Story #4545 deleted the perf-summary / perf-report comment surface that used to roll it up onto tickets, leaving the retro as the consumer. `kind: trace` is the raw tool-call trace; the named kinds are derived signals. This is the ONLY shape — the legacy `timestamp` / `epic` aliases and the `source: { tool }` provenance object were deleted in the same PR that moved every writer (no read-side compatibility branch).",
   "type": "object",
   "additionalProperties": true,
   "required": ["kind", "ts"],
@@ -33,7 +33,7 @@
     "source": {
       "type": "string",
       "enum": ["framework", "consumer"],
-      "description": "Framework/consumer classification injected by `tagSignalSource` (signals-writer.js) for records appended via appendSignal/appendEpicSignal. Reserved exclusively for this classifier tag — the originating tool/surface lives in `emitter`."
+      "description": "Framework/consumer classification injected by `tagSignalSource` (signals-writer.js) for records appended via appendSignal. Reserved exclusively for this classifier tag — the originating tool/surface lives in `emitter`."
     },
     "emitter": {
       "type": "object",
@@ -57,7 +57,7 @@
     "category": {
       "type": "string",
       "minLength": 1,
-      "description": "Top-level friction category (e.g. Execution Error, baseline-refresh-regression). Read directly by perf-aggregator frictionByCategory and the retro routed-proposal extraction — never nested under details."
+      "description": "Top-level friction category (e.g. Execution Error, baseline-refresh-regression). Read directly by the retro routed-proposal extraction — never nested under details."
     },
     "phase": {
       "type": ["string", "null"],

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-deliver-terminal.schema.json",
+  "title": "story-deliver-terminal",
+  "description": "The single terminal envelope every Story close-and-land invocation emits (Story #4543). Before this schema, the delivery tail had two divergent prose return contracts — one in .agents/workflows/helpers/deliver-story.md, a different one in .agents/agents/story-worker.md — and neither was validated by anything, so a caller could not tell a landed Story from a parked one without re-probing GitHub. This is the SSOT both now reference rather than restate. status is exactly one of landed | pending | blocked | failed; phase names where the run ended; tail carries per-step booleans so a partial-tail degradation is visible without failing an otherwise-landed merge; nextCommand names the single command that resumes or remediates the run, drawn from the same vocabulary deliver-recover.js prints.",
+  "type": "object",
+  "required": [
+    "kind",
+    "storyId",
+    "status",
+    "phase",
+    "elapsedSeconds",
+    "nextCommand"
+  ],
+  "properties": {
+    "kind": { "type": "string", "const": "story-deliver-terminal" },
+    "storyId": { "type": "integer", "minimum": 1 },
+    "status": {
+      "type": "string",
+      "description": "landed — the PR merged, the Story is agent::done, and the post-land tail was attempted. pending — a bounded wait expired with the PR still in flight; NO label was mutated and no merge.unlanded event was emitted, so the run is resumable via nextCommand. blocked — a classified hard block; the Story carries agent::blocked and blocked.blockClass names the class. failed — a phase crashed; phase names which one.",
+      "enum": ["landed", "pending", "blocked", "failed"]
+    },
+    "phase": {
+      "type": "string",
+      "description": "The pipeline phase the run ended in. Mirrors the close pipeline's phase names so a terminal envelope is attributable to one step.",
+      "enum": [
+        "init",
+        "wrong-tree-guard",
+        "close-validation",
+        "base-sync",
+        "push",
+        "pull-request",
+        "code-review",
+        "auto-merge",
+        "confirm-merge",
+        "post-land",
+        "done"
+      ]
+    },
+    "storyBranch": { "type": ["string", "null"] },
+    "baseBranch": { "type": ["string", "null"] },
+    "pr": {
+      "type": ["object", "null"],
+      "description": "Live PR facts as observed at terminal time. null before a PR exists (an early-phase failure). `number` is nullable for the real case where `gh pr create` returned a URL the /pull/<n> parser could not read: the PR exists and its url is known, but nothing can address it by number — including auto-merge, which is why that path reports autoMergeReason: pr-number-unparseable.",
+      "required": ["number"],
+      "properties": {
+        "number": { "type": ["integer", "null"], "minimum": 1 },
+        "url": { "type": ["string", "null"] },
+        "state": {
+          "type": ["string", "null"],
+          "description": "GitHub PR state as last probed (OPEN | MERGED | CLOSED)."
+        },
+        "checksStatus": {
+          "type": ["string", "null"],
+          "description": "Aggregate required-check rollup at terminal time.",
+          "enum": [
+            "success",
+            "pending",
+            "still-running",
+            "failure",
+            "unknown",
+            null
+          ]
+        },
+        "autoMergeEnabled": { "type": ["boolean", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "gates": {
+      "type": "object",
+      "description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one.",
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["passed", "failed", "skipped"]
+      }
+    },
+    "tail": {
+      "type": ["object", "null"],
+      "description": "Per-step outcomes of the post-land tail. Deliberately per-step booleans rather than one aggregate success bit: the worktree-reap defect this repo fixed existed precisely because a phase reported an outcome it never checked, and an aggregate invites that class of bug back. A false here degrades the report, never the land.",
+      "required": [
+        "followUps",
+        "statusResync",
+        "refCleanup",
+        "baseFastForward"
+      ],
+      "properties": {
+        "followUps": { "type": "boolean" },
+        "statusResync": { "type": "boolean" },
+        "refCleanup": { "type": "boolean" },
+        "baseFastForward": { "type": "boolean" },
+        "details": {
+          "type": "object",
+          "description": "Per-step diagnostic detail — the reason a false step reported false.",
+          "additionalProperties": { "type": ["string", "null"] }
+        }
+      },
+      "additionalProperties": false
+    },
+    "blocked": {
+      "type": ["object", "null"],
+      "description": "Present iff status === \"blocked\". blockClass comes from the shared classifier (merge-block-class.js) or the merged-flip-failed terminal, never an ad hoc string.",
+      "required": ["blockClass", "reason"],
+      "properties": {
+        "blockClass": {
+          "type": "string",
+          "enum": [
+            "checks-pending-timeout",
+            "checks-failed",
+            "branch-protection-human-required",
+            "arm-failure",
+            "api-race-other",
+            "predicate-refused",
+            "merged-flip-failed"
+          ]
+        },
+        "reason": { "type": "string", "minLength": 1 },
+        "frictionCommentId": {
+          "type": ["string", "null"],
+          "description": "Pointer to the friction comment carrying the operator-facing remediation."
+        }
+      },
+      "additionalProperties": false
+    },
+    "failure": {
+      "type": ["object", "null"],
+      "description": "Present iff status === \"failed\".",
+      "required": ["reason"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "nextCommand": {
+      "type": ["string", "null"],
+      "description": "The single command that advances this Story from where it stopped, or null when status === \"landed\" and nothing remains. Shares its vocabulary with deliver-recover.js so recovery and normal resumption speak one language."
+    },
+    "elapsedSeconds": { "type": "number", "minimum": 0 },
+    "waitBudget": {
+      "type": ["object", "null"],
+      "description": "Merge-wait accounting. maxWaitSeconds bounds THIS invocation (defaulting under the host's single-tool-invocation ceiling); cumulativeSeconds is anchored at the PR's createdAt so a resume does not restart the clock, and maxBudgetSeconds bounds that cumulative total.",
+      "properties": {
+        "maxWaitSeconds": { "type": "integer", "minimum": 1 },
+        "waitedSeconds": { "type": "number", "minimum": 0 },
+        "cumulativeSeconds": { "type": "number", "minimum": 0 },
+        "maxBudgetSeconds": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "timestamp": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/validation-evidence.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "validation-evidence",
   "title": "Validation Evidence",
-  "description": "Per-scope record of which validation gates have passed against which commit SHA. Written by lib/validation-evidence.js under the per-Epic temp tree at temp/epic-<epicId>/validation-evidence.json (Epic-scoped) or temp/epic-<epicId>/stories/story-<storyId>/validation-evidence.json (Story-scoped). Standalone Stories (no parent Epic) use a storyId-anchored keyspace at temp/standalone/stories/story-<storyId>/validation-evidence.json. All paths are gitignored via temp/. Consumed by close-validation, epic-code-review, the acceptance self-eval critic, and /deliver Phase 3 (close-validation) to skip identical re-runs against an already-validated tree. The `storyId` field carries the scope id and equals the epic id for Epic-scoped records.",
+  "description": "Per-scope record of which validation gates have passed against which commit SHA. Written by lib/validation-evidence.js under the per-Epic temp tree at temp/run-<id>/validation-evidence.json (Epic-scoped) or temp/run-<id>/stories/story-<storyId>/validation-evidence.json (Story-scoped). Standalone Stories (no parent Epic) use a storyId-anchored keyspace at temp/standalone/stories/story-<storyId>/validation-evidence.json. All paths are gitignored via temp/. Consumed by close-validation, epic-code-review, the acceptance self-eval critic, and /deliver Phase 3 (close-validation) to skip identical re-runs against an already-validated tree. The `storyId` field carries the scope id and equals the epic id for Epic-scoped records.",
   "type": "object",
   "required": ["storyId", "schemaVersion", "records"],
   "properties": {