mandrel 2.31.0 → 2.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.31.0",
+  "version": "2.33.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -28,10 +28,12 @@
     "coverage:update": "node .agents/scripts/update-coverage-baseline.js",
     "coverage:reanchor": "node .agents/scripts/update-coverage-baseline.js --full-scope",
     "baseline:agents-loc": "node baselines/agents-loc-baseline.mjs",
+    "baselines:scope": "node .agents/scripts/check-baseline-scope.js",
+    "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
     "lint": "node .agents/scripts/run-lint.js && npm run docs:check",
     "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-lifecycle-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
-    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-lifecycle-doc-drift.js && node .agents/scripts/check-doc-links.js && node .agents/scripts/check-gherkin-placeholders.js && npm run skills:check",
+    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
     "skills:check": "node .agents/scripts/generate-skills-index.js --check",
     "format": "biome format --write .",
@@ -43,6 +45,8 @@
     "check:context-budget": "node .agents/scripts/check-context-budget.js",
     "check:cyclomatic": "node .agents/scripts/check-cyclomatic.js",
     "cyclomatic:update": "node .agents/scripts/check-cyclomatic.js --update",
+    "dead-exports:update": "node .agents/scripts/update-dead-exports-baseline.js && node .agents/scripts/update-dead-exports-baseline.js --production",
+    "check:knip-entries": "node .agents/scripts/check-knip-entries.js",
     "check:schema-refs": "node .agents/scripts/check-schema-references.js",
     "check:workflow-citations": "node .agents/scripts/check-workflow-citations.js",
     "crap:check": "node .agents/scripts/check-baselines.js --gate crap",
@@ -87,6 +91,7 @@
     "@biomejs/biome": "^2.5.0",
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
+    "@cucumber/gherkin": "^42.0.1",
     "c8": "^11.0.0",
     "chokidar": "^5.0.0",
     "husky": "^9.1.7",
@@ -101,26 +106,30 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.1",
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
-    "string-argv": "^0.3.2",
     "typhonjs-escomplex": "^0.1.0"
   },
   "peerDependencies": {
+    "@cucumber/gherkin": ">=32.0.0",
     "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
+    "@cucumber/gherkin": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     }
   },
   "//": {
+    "peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
     "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.2.0 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended.",
     "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions."
   },
   "overrides": {
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.1",
     "markdown-it": "^14.2.0"
   }
 }

package/.agents/schemas/lifecycle/checkpoint.written.schema.json

@@ -1,13 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/checkpoint.written.schema.json",
-  "title": "checkpoint.written",
-  "description": "Self-emitted by CheckpointPointerWriter after the pointer file is updated. Carries the phase header for tracing and the last-completed seqId for the resume contract.",
-  "type": "object",
-  "required": ["phase", "lastCompletedSeqId"],
-  "properties": {
-    "phase": { "type": "string", "minLength": 1 },
-    "lastCompletedSeqId": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/close-validate.end.schema.json

@@ -1,18 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/close-validate.end.schema.json",
-  "title": "close-validate.end",
-  "description": "Emitted at the end of the close-validate sub-phase. ok=true => every gate passed; ok=false => failedGate identifies the first failed gate. durationMs is wall-clock time spent in the gate chain. Story #2250.",
-  "type": "object",
-  "required": ["epicId", "storyId", "ok"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "storyId": { "type": "integer", "minimum": 1 },
-    "ok": { "type": "boolean" },
-    "gateCount": { "type": "integer", "minimum": 0 },
-    "failedGate": { "type": "string", "minLength": 1 },
-    "exitCode": { "type": "integer" },
-    "durationMs": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/close-validate.start.schema.json

@@ -1,13 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/close-validate.start.schema.json",
-  "title": "close-validate.start",
-  "description": "Emitted at the start of the close-validate sub-phase (pre-merge gate chain typecheck/lint/test/format/maintainability/crap). Story #2250.",
-  "type": "object",
-  "required": ["epicId", "storyId"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "storyId": { "type": "integer", "minimum": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/code-review.end.schema.json

@@ -1,30 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/code-review.end.schema.json",
-  "title": "code-review.end",
-  "description": "Emitted at the end of the code-review sub-phase. Carries a review-finding severity summary so the lifecycle ledger surfaces critical/high/medium/suggestion counts directly. The payload MUST NOT carry any secret-key-denylist fields (token, password, secret, apiKey, webhookUrl) — the LedgerWriter enforces this, but the schema's `additionalProperties: false` keeps the surface tight. Story #2252.",
-  "type": "object",
-  "required": ["epicId", "status"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "status": {
-      "type": "string",
-      "enum": ["ok", "no-changes", "invalid"]
-    },
-    "severity": {
-      "type": "object",
-      "required": ["critical", "high", "medium", "suggestion"],
-      "properties": {
-        "critical": { "type": "integer", "minimum": 0 },
-        "high": { "type": "integer", "minimum": 0 },
-        "medium": { "type": "integer", "minimum": 0 },
-        "suggestion": { "type": "integer", "minimum": 0 }
-      },
-      "additionalProperties": false
-    },
-    "halted": { "type": "boolean" },
-    "posted": { "type": "boolean" },
-    "durationMs": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/code-review.start.schema.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/code-review.start.schema.json",
-  "title": "code-review.start",
-  "description": "Emitted at the start of the code-review sub-phase (Phase D of the close-tail). Story #2252.",
-  "type": "object",
-  "required": ["epicId"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/intervention.recorded.schema.json

@@ -1,15 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/intervention.recorded.schema.json",
-  "title": "intervention.recorded",
-  "description": "Emitted whenever the host LLM performs an out-of-band manual intervention during an Epic delivery (e.g., AskUserQuestion, manual git restore/reset, --no-ff recovery merge, story-close --skipValidation). The InterventionRecorder listener appends the payload to the epic-run-state-store's manualInterventions array; a non-empty array disqualifies the Epic from auto-merge.",
-  "type": "object",
-  "required": ["epicId", "reason"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "reason": { "type": "string", "minLength": 1 },
-    "source": { "type": "string", "minLength": 1, "default": "host-llm" },
-    "ts": { "type": "string", "format": "date-time" }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/loop.tick.schema.json

@@ -1,20 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/loop.tick.schema.json",
-  "title": "loop.tick",
-  "description": "Emitted once per pass of a host-driven loop (e.g. a recurring loop command or a long-running poll) so each round lands an inspectable ledger record. Surfaces the loop as forward-progress evidence the /deliver idle watchdog already scans — distinct from story.heartbeat, which carries Story-phase info for a single in-flight Story. A loop is not tied to a Story tier: loop.tick carries a free-form loopName, a monotonic round counter, the configured cadence, and a status so a host loop never runs silently. cadence is the loop's configured interval label (e.g. '5m', 'self-paced'); status is the per-round verdict (running while the loop continues, done when it terminates normally, blocked when it stalls).",
-  "type": "object",
-  "required": ["event", "loopName", "round", "cadence", "status", "timestamp"],
-  "properties": {
-    "event": { "type": "string", "const": "loop.tick" },
-    "loopName": { "type": "string", "minLength": 1 },
-    "round": { "type": "integer", "minimum": 0 },
-    "cadence": { "type": "string", "minLength": 1 },
-    "status": {
-      "type": "string",
-      "enum": ["running", "done", "blocked"]
-    },
-    "timestamp": { "type": "string", "format": "date-time" }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/notification.emitted.schema.json

@@ -1,18 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/notification.emitted.schema.json",
-  "title": "notification.emitted",
-  "description": "Self-emitted by NotifyDispatcher after each webhook/comment dispatch. Carries the upstream event name, the channel, the severity, and the ok flag for trace fidelity.",
-  "type": "object",
-  "required": ["event", "channel", "severity", "ok"],
-  "properties": {
-    "event": { "type": "string", "minLength": 1 },
-    "channel": { "type": "string", "enum": ["webhook", "comment"] },
-    "severity": {
-      "type": "string",
-      "enum": ["info", "warn", "error", "critical"]
-    },
-    "ok": { "type": "boolean" }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/pr.created.schema.json

@@ -1,14 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/pr.created.schema.json",
-  "title": "pr.created",
-  "description": "Emitted by Finalizer immediately after gh pr create (or short-circuit). Must be preceded by acceptance.reconcile.ok from the same run.",
-  "type": "object",
-  "required": ["prUrl", "head", "base"],
-  "properties": {
-    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
-    "head": { "type": "string", "minLength": 1 },
-    "base": { "type": "string", "minLength": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/retro.end.schema.json

@@ -1,16 +0,0 @@
-{
-  "$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/run-<id>/ when written. Story #2252.",
-  "type": "object",
-  "required": ["epicId", "posted"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 },
-    "posted": { "type": "boolean" },
-    "compact": { "type": "boolean" },
-    "retroPath": { "type": "string", "minLength": 1 },
-    "durationMs": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/retro.start.schema.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/retro.start.schema.json",
-  "title": "retro.start",
-  "description": "Emitted at the start of the retro sub-phase (Phase E of the close-tail). Story #2252.",
-  "type": "object",
-  "required": ["epicId"],
-  "properties": {
-    "epicId": { "type": "integer", "minimum": 1 }
-  },
-  "additionalProperties": false
-}

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

@@ -1,13 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/story.blocked.schema.json",
-  "title": "story.blocked",
-  "description": "Emitted from the story-close path when a Story transitions to agent::blocked.",
-  "type": "object",
-  "required": ["storyId", "reason"],
-  "properties": {
-    "storyId": { "type": "integer", "minimum": 1 },
-    "reason": { "type": "string", "minLength": 1 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/story.dispatch.end.schema.json

@@ -1,17 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/story.dispatch.end.schema.json",
-  "title": "story.dispatch.end",
-  "description": "Appended to the Epic ledger by emit-story-dispatch-end.js when a child story sub-agent returns, so /deliver's idle watchdog can subtract completed Stories from the in-flight set. Subscribed by CheckpointPointerWriter via SUBSCRIBED_END_EVENTS. Sibling ordering within a wave is not guaranteed; ordering between waves is.",
-  "type": "object",
-  "required": ["storyId", "outcome", "durationMs"],
-  "properties": {
-    "storyId": { "type": "integer", "minimum": 1 },
-    "outcome": {
-      "type": "string",
-      "enum": ["done", "blocked", "failed", "skipped"]
-    },
-    "durationMs": { "type": "integer", "minimum": 0 }
-  },
-  "additionalProperties": false
-}

package/.agents/schemas/lifecycle/story.dispatch.start.schema.json

@@ -1,15 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/story.dispatch.start.schema.json",
-  "title": "story.dispatch.start",
-  "description": "Emitted before a story is handed to the host-LLM for Agent-tool fanout. lifecycle-emit-story-dispatch.js appends the {storyId, waveIndex, dispatchedAt, attempt} shape to the Epic ledger so /deliver's host loop can durably ledger every dispatch attempt for in-flight reconciliation (Story #2891).",
-  "type": "object",
-  "required": ["storyId", "waveIndex"],
-  "properties": {
-    "storyId": { "type": "integer", "minimum": 1 },
-    "waveIndex": { "type": "integer", "minimum": 0 },
-    "dispatchedAt": { "type": "string", "format": "date-time" },
-    "attempt": { "type": "integer", "minimum": 1 }
-  },
-  "additionalProperties": false
-}

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

@@ -1,13 +0,0 @@
-{
-  "$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 main (single-story/confirm-merge.js).",
-  "type": "object",
-  "required": ["storyId", "sha"],
-  "properties": {
-    "storyId": { "type": "integer", "minimum": 1 },
-    "sha": { "type": "string", "minLength": 7 }
-  },
-  "additionalProperties": false
-}