mandrel 1.94.0 → 2.1.0

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/epic-<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/retro.end.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/retro.end.schema.json",
   "title": "retro.end",
-  "description": "Emitted at the end of the retro sub-phase. `posted` indicates whether the retro structured comment was upserted onto the Epic; `retroPath` is the local mirror path under temp/epic-<id>/ when written. Story #2252.",
+  "description": "Emitted at the end of the retro sub-phase. `posted` indicates whether the retro structured comment was upserted onto the Epic; `retroPath` is the local mirror path under temp/run-<id>/ when written. Story #2252.",
   "type": "object",
   "required": ["epicId", "posted"],
   "properties": {

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": {

package/.agents/scripts/acceptance-eval.js

@@ -32,26 +32,20 @@
  * — this CLI is the decision + signal boundary, mirroring how the existing
  * gates separate decision from ticket mutation.
  *
- * Two invocation shapes (Epic #4475, M4-B):
- *   - Per-Story (fan-out): the diff is one Story's; round scoping is per
- *     Story off the Story's `signals.ndjson`.
- *   - Per-AC-cluster (single delivery): `--epic <id> --cluster <clusterId>`
- *     with NO `--story`. The verdict scores one AC cluster of the Epic's
- *     `## Acceptance Table` against the cumulative `main..epic/<id>` diff;
- *     round scoping is per cluster off the Epic's `signals.ndjson`. This is
- *     the acceptance-dilution guard — `ceil(totalACs / clusterCeiling)`
- *     independent maker-blind critic passes, one per cluster.
+ * One invocation shape: per-Story. The diff is one Story's; round scoping
+ * is per Story off the Story's `signals.ndjson`. (v2.0.0 removed the Epic
+ * tier along with the per-AC-cluster `--epic <id> --cluster <id>` mode that
+ * scored an Epic `## Acceptance Table` against a `main..epic/<id>` diff.)
  *
  * CLI:
- *   --story <id>           Story ID (required unless --cluster is given).
- *   --epic <id>            Parent Epic ID (required with --cluster).
- *   --cluster <id>         AC-cluster id for the single-delivery critic.
+ *   --story <id>           Story ID (required).
  *   --verdict <path>       Path to the round's verdict JSON (required).
  *   --no-signal            Suppress the signal emit (tests).
  *
  * Stdout: a single JSON envelope
  *   { storyId, epicId, decision, round, cap, capReached, totalCriteria,
  *     metCount, unmetCriteria[], signalEmitted }
+ *   (`epicId` is retained as a always-null field for envelope stability.)
  *
  * @see .agents/scripts/lib/orchestration/acceptance-eval-decision.js
  * @see .agents/schemas/acceptance-eval-verdict.schema.json
@@ -68,10 +62,7 @@ import addFormats from 'ajv-formats';
 import { runAsCli } from './lib/cli-utils.js';
 import { getAcceptanceEval, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import {
-  appendEpicSignal,
-  appendSignal,
-} from './lib/observability/signals-writer.js';
+import { appendSignal } from './lib/observability/signals-writer.js';
 import {
   buildAcceptanceEvalSignal,
   decideAcceptanceEval,
@@ -139,22 +130,14 @@ function parseCliArgs(argv) {
     args: argv,
     options: {
       story: { type: 'string' },
-      epic: { type: 'string' },
-      cluster: { type: 'string' },
       verdict: { type: 'string' },
       'no-signal': { type: 'boolean', default: false },
     },
     strict: false,
   });
   const storyId = Number.parseInt(values.story ?? '', 10);
-  const epicRaw = Number.parseInt(values.epic ?? '', 10);
   return {
     storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
-    epicId: Number.isInteger(epicRaw) && epicRaw > 0 ? epicRaw : null,
-    clusterId:
-      typeof values.cluster === 'string' && values.cluster.length > 0
-        ? values.cluster
-        : null,
     verdictPath: values.verdict ?? null,
     emitSignal: values['no-signal'] !== true,
   };
@@ -168,7 +151,6 @@ function parseCliArgs(argv) {
  *
  * @param {object} args
  * @param {number} args.storyId
- * @param {number | null} args.epicId
  * @param {object} args.verdict — validated verdict object.
  * @param {object} args.config — resolved `.agentrc.json`.
  * @param {boolean} args.emitSignal
@@ -182,23 +164,18 @@ function parseCliArgs(argv) {
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
 export async function runAcceptanceEval(
-  { storyId, epicId, clusterId = null, verdict, config, emitSignal, round },
+  { storyId, verdict, config, emitSignal, round },
   deps = {},
 ) {
   const {
     appendSignalFn = appendSignal,
-    appendEpicSignalFn = appendEpicSignal,
     deriveRoundFn = deriveAcceptanceEvalRound,
   } = deps;
-  const clusterMode =
-    typeof clusterId === 'string' &&
-    clusterId.length > 0 &&
-    Number.isInteger(epicId);
   const { maxRounds } = getAcceptanceEval(config);
   const resolvedRound =
     Number.isInteger(round) && round >= 1
       ? round
-      : deriveRoundFn({ epicId: epicId ?? null, storyId, clusterId, config });
+      : deriveRoundFn({ epicId: null, storyId, config });
   const outcome = decideAcceptanceEval({
     verdict,
     maxRounds,
@@ -208,21 +185,16 @@ export async function runAcceptanceEval(
   let signalEmitted = false;
   if (emitSignal) {
     const signal = {
-      ...buildAcceptanceEvalSignal({ storyId, epicId, outcome, clusterId }),
+      ...buildAcceptanceEvalSignal({ storyId, epicId: null, outcome }),
       ts: new Date().toISOString(),
     };
     try {
-      // Cluster mode (single delivery) writes to the epic-level signals
-      // stream so per-cluster round counts survive resume; the per-Story
-      // path writes to the Story stream (unchanged).
-      signalEmitted = clusterMode
-        ? await appendEpicSignalFn({ epicId, signal, config })
-        : await appendSignalFn({
-            epicId,
-            storyId,
-            signal,
-            config,
-          });
+      signalEmitted = await appendSignalFn({
+        epicId: null,
+        storyId,
+        signal,
+        config,
+      });
     } catch (err) {
       // Observability is best-effort — a failed signal write must never
       // take down the gate. The decision still stands.
@@ -236,8 +208,7 @@ export async function runAcceptanceEval(
 
   const envelope = {
     storyId: storyId ?? null,
-    epicId: epicId ?? null,
-    ...(clusterMode ? { clusterId } : {}),
+    epicId: null,
     decision: outcome.decision,
     round: outcome.round,
     cap: outcome.cap,
@@ -261,19 +232,11 @@ export async function runAcceptanceEval(
 }
 
 export async function main(argv = process.argv.slice(2)) {
-  const { storyId, epicId, clusterId, verdictPath, emitSignal } =
-    parseCliArgs(argv);
+  const { storyId, verdictPath, emitSignal } = parseCliArgs(argv);
 
-  // Epic #4475 (M4-B): two invocation shapes.
-  //   - Per-Story (fan-out): --story <id> [--epic <id>].
-  //   - Per-AC-cluster (single delivery): --epic <id> --cluster <id> (no
-  //     --story); the verdict scores one AC cluster of the Epic's Acceptance
-  //     Table against the cumulative main..epic/<id> diff.
-  const clusterMode = Boolean(clusterId) && Number.isInteger(epicId);
-  if (!storyId && !clusterMode) {
+  if (!storyId) {
     throw new Error(
-      'Usage: node acceptance-eval.js --story <id> [--epic <id>] --verdict <path> [--no-signal]\n' +
-        '   or: node acceptance-eval.js --epic <id> --cluster <clusterId> --verdict <path> [--no-signal]',
+      'Usage: node acceptance-eval.js --story <id> --verdict <path> [--no-signal]',
     );
   }
   if (!verdictPath) {
@@ -305,13 +268,8 @@ export async function main(argv = process.argv.slice(2)) {
   const verdict = validateVerdict(parsed);
 
   // A verdict whose embedded storyId disagrees with the CLI flag is a
-  // wiring error worth failing on, not a silent mismatch. Skipped in cluster
-  // mode (no --story; the verdict scores an AC cluster, not a Story).
-  if (
-    !clusterMode &&
-    Number.isInteger(verdict.storyId) &&
-    verdict.storyId !== storyId
-  ) {
+  // wiring error worth failing on, not a silent mismatch.
+  if (Number.isInteger(verdict.storyId) && verdict.storyId !== storyId) {
     throw new Error(
       `acceptance-eval: verdict storyId (${verdict.storyId}) does not match --story ${storyId}.`,
     );
@@ -320,8 +278,6 @@ export async function main(argv = process.argv.slice(2)) {
   const config = resolveConfig();
   const { envelope, exitCode } = await runAcceptanceEval({
     storyId,
-    epicId,
-    clusterId,
     verdict,
     config,
     emitSignal,

package/.agents/scripts/agents-bootstrap-github.js

@@ -3,7 +3,7 @@
  * agents-bootstrap-github — Idempotent Label & Field Setup
  *
  * Creates the required label taxonomy and project board custom fields
- * for the v5 Epic-centric flow on a target GitHub repo. Idempotent —
+ * for the v5 Story-centric flow on a target GitHub repo. Idempotent —
  * skips resources that already exist.
  *
  * Usage: