mandrel 1.58.0 → 1.60.0

package/.agents/schemas/epic-spec.schema.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/epic-spec.schema.json",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "title": "Epic Spec (declarative structural SSOT)",
-  "description": "Canonical structural specification for an Epic and its children (Features, Stories), consumed by the epic-spec-reconciler. Lives on disk as .agents/epics/<epic-id>.yaml. The reconciler diffs this spec against live GitHub state and applies structural mutations (Create/Update/Close/Relink) behind a dry-run default. Slugs are stable, GH-incarnation-independent identifiers used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping persisted in the sibling .agents/epics/<epic-id>.state.json. This schema describes the 3-tier structural shape only (Epic → Feature → Story with inline Story-level acceptance[]/verify[]); agent-execution state (agent::* labels) is intentionally not modelled — that surface belongs to the wave-runner, not the reconciler.",
+  "description": "Canonical structural specification for an Epic and its child Stories, consumed by the epic-spec-reconciler. Lives on disk as .agents/epics/<epic-id>.yaml. The reconciler diffs this spec against live GitHub state and applies structural mutations (Create/Update/Close/Relink) behind a dry-run default. Slugs are stable, GH-incarnation-independent identifiers used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping persisted in the sibling .agents/epics/<epic-id>.state.json. This schema describes the 2-tier structural shape only (Epic → Story with inline Story-level acceptance[]/verify[]); agent-execution state (agent::* labels) is intentionally not modelled — that surface belongs to the wave-runner, not the reconciler.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["epic", "features"],
+  "required": ["epic", "stories"],
   "properties": {
     "$schema": {
       "type": "string",
@@ -15,16 +15,16 @@
     "version": {
       "type": "string",
       "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Optional schema-shape identifier. Identification-only — readers MUST NOT branch behavior on this value. Bumped to 3.0.0 when Task-level decomposition was removed under the 3-tier collapse (Epic #3078)."
+      "description": "Optional schema-shape identifier. Identification-only — readers MUST NOT branch behavior on this value. Bumped to 4.0.0 when the Feature tier was removed under the 2-tier collapse (Story #4041); 3.0.0 removed Task-level decomposition (Epic #3078)."
     },
     "epic": {
       "$ref": "#/$defs/epic",
       "description": "The Epic this spec describes. Carries the GH issue number, human title, and structural labels (type::epic plus any project-specific structural tags). Execution-state labels (agent::*) MUST NOT appear here."
     },
-    "features": {
+    "stories": {
       "type": "array",
-      "description": "Ordered list of Features under this Epic. Order is preserved for human readability but is not load-bearing — wave ordering is driven by stories[].wave + dependsOn, not by feature position.",
-      "items": { "$ref": "#/$defs/feature" }
+      "description": "Ordered list of Stories under this Epic. Order is preserved for human readability but is not load-bearing — execution order is driven by stories[].wave + dependsOn, not by array position.",
+      "items": { "$ref": "#/$defs/story" }
     },
     "gates": {
       "$ref": "#/$defs/gates",
@@ -36,12 +36,12 @@
       "type": "string",
       "minLength": 1,
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable kebab-case identifier used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping. Slugs must be unique within their scope (features within an epic, stories within a feature). Slugs are not GH issue numbers — they survive Epic re-incarnations and ticket renumbering. Pattern: lowercase alphanumeric + hyphens, must start with [a-z0-9]."
+      "description": "Stable kebab-case identifier used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping. Slugs must be unique within the Epic's stories[] array. Slugs are not GH issue numbers — they survive Epic re-incarnations and ticket renumbering. Pattern: lowercase alphanumeric + hyphens, must start with [a-z0-9]."
     },
     "label": {
       "type": "string",
       "minLength": 1,
-      "description": "A GitHub label name. Structural labels only (e.g. type::epic, type::feature, type::story, persona::*, area::*). Execution-state labels in the AGENT_LABELS allow-list (agent::*) MUST NOT appear in the spec — they are owned by the wave-runner and the reconciler refuses to write them."
+      "description": "A GitHub label name. Structural labels only (e.g. type::epic, type::story, persona::*, area::*). Execution-state labels in the AGENT_LABELS allow-list (agent::*) MUST NOT appear in the spec — they are owned by the wave-runner and the reconciler refuses to write them."
     },
     "labels": {
       "type": "array",
@@ -53,7 +53,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["id", "title"],
-      "description": "Top-level Epic descriptor. Unlike Features/Stories (which are slug-keyed and may not exist in GH yet), the Epic always has a real GH issue number — the spec lives at .agents/epics/<id>.yaml and that <id> is the same number used here.",
+      "description": "Top-level Epic descriptor. Unlike Stories (which are slug-keyed and may not exist in GH yet), the Epic always has a real GH issue number — the spec lives at .agents/epics/<id>.yaml and that <id> is the same number used here.",
       "properties": {
         "id": {
           "type": "integer",
@@ -67,7 +67,7 @@
         },
         "body": {
           "type": "string",
-          "description": "Optional Epic body. When present, the reconciler updates the GH issue body to match. When omitted, the GH issue body is left untouched (allowing operator-curated bodies to coexist with structural reconciliation). Multi-line markdown is fully supported."
+          "description": "Optional Epic body. When present, the reconciler updates the GH issue body to match. When omitted, the GH issue body is left untouched (allowing operator-curated bodies to coexist with structural reconciliation). Multi-line markdown is fully supported. Thematic grouping of Stories — formerly the Feature tier's job — lives here (and in the Tech Spec) as prose."
         },
         "labels": {
           "$ref": "#/$defs/labels",
@@ -75,45 +75,15 @@
         }
       }
     },
-    "feature": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["slug", "title", "stories"],
-      "description": "A Feature groups Stories under a common product/architectural theme. Features themselves are GitHub issues (type::feature) when materialised by the reconciler — they carry no execution state, only structure.",
-      "properties": {
-        "slug": {
-          "$ref": "#/$defs/slug",
-          "description": "Stable kebab-case identifier for this Feature. Must be unique within the parent Epic's features[] array."
-        },
-        "title": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable Feature title."
-        },
-        "body": {
-          "type": "string",
-          "description": "Optional Feature body. Same semantics as epic.body — written by the reconciler when present, left untouched when omitted."
-        },
-        "labels": {
-          "$ref": "#/$defs/labels",
-          "description": "Structural labels attached to this Feature (e.g. type::feature plus any project-specific structural tags)."
-        },
-        "stories": {
-          "type": "array",
-          "description": "Ordered list of Stories under this Feature. Order is for readability; execution order is driven by stories[].wave + dependsOn.",
-          "items": { "$ref": "#/$defs/story" }
-        }
-      }
-    },
     "story": {
       "type": "object",
       "additionalProperties": false,
       "required": ["slug", "title", "wave"],
-      "description": "A Story is the unit of agent execution — exactly one Story branch (story-<id>) and exactly one Story sub-agent per Story per wave. Stories declare their wave assignment and inter-Story dependencies via slug references; the wave-runner consumes these to schedule the parallel fan-out. Under the 3-tier collapse (Epic #3078), Stories carry inline acceptance[] + verify[] arrays that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface; there is no child-Task decomposition.",
+      "description": "A Story is the unit of agent execution — exactly one Story branch (story-<id>) and exactly one Story sub-agent per Story per wave. Stories are direct children of the Epic (2-tier hierarchy, Story #4041). They declare their wave assignment and inter-Story dependencies via slug references; the wave-runner consumes these to schedule the parallel fan-out. Stories carry inline acceptance[] + verify[] arrays that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface; there is no child-Task decomposition.",
       "properties": {
         "slug": {
           "$ref": "#/$defs/slug",
-          "description": "Stable kebab-case identifier for this Story. Must be unique within the parent Feature's stories[] array, and is the value referenced by sibling Stories' dependsOn arrays."
+          "description": "Stable kebab-case identifier for this Story. Must be unique within the Epic's stories[] array, and is the value referenced by sibling Stories' dependsOn arrays."
         },
         "title": {
           "type": "string",
@@ -144,7 +114,7 @@
         },
         "acceptance": {
           "type": "array",
-          "description": "Inline acceptance criteria for this Story (Epic #3078 — 3-tier collapse). Each entry is a single user-visible acceptance statement that the Story-level agent must satisfy. Acts as the Story-level outcome contract that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface.",
+          "description": "Inline acceptance criteria for this Story. Each entry is a single user-visible acceptance statement that the Story-level agent must satisfy. Acts as the Story-level outcome contract that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface.",
           "items": {
             "type": "string",
             "minLength": 1,
@@ -153,7 +123,7 @@
         },
         "verify": {
           "type": "array",
-          "description": "Inline verification commands for this Story (Epic #3078 — 3-tier collapse). Each entry is a shell-runnable command (typically a contract test invocation) that proves the corresponding acceptance[] entries hold.",
+          "description": "Inline verification commands for this Story. Each entry is a shell-runnable command (typically a contract test invocation) that proves the corresponding acceptance[] entries hold.",
           "items": {
             "type": "string",
             "minLength": 1,

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

@@ -1,7 +1,7 @@
 # Lifecycle event schemas
 
 JSON Schemas for the lifecycle event taxonomy consumed by the
-`/epic-deliver` lifecycle bus
+`/deliver` lifecycle bus
 (`lib/orchestration/lifecycle/bus.js`). The bus validates every
 emit payload against one of these schemas before invoking
 listeners; a schema mismatch fails the emit and propagates the

package/.agents/schemas/lifecycle/story.dispatch.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/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 /epic-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.",
+  "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": {

package/.agents/schemas/lifecycle/story.dispatch.start.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.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 /epic-deliver's host loop can durably ledger every dispatch attempt for in-flight reconciliation (Story #2891).",
+  "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": {

package/.agents/schemas/lifecycle/story.heartbeat.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.heartbeat.schema.json",
   "title": "story.heartbeat",
-  "description": "Emitted by story-phase.js inside a Story's implementation loop. Surfaces the in-progress Story as an inspectable ledger event so /epic-deliver's host-loop reconciler can confirm a long Story is still making forward progress between dispatch and merge — distinct from story.dispatch.start (one per Story per attempt) and story.merged (one per Story per close). The 3-tier hierarchy has no child Task tickets, so the heartbeat carries phase info only. The optional operator field (Story #3480) records the handle holding the assignee-as-lease claim on the Story so the ticket-lease primitive can decide claim liveness from the most-recent heartbeat for a given owner.",
+  "description": "Emitted by story-phase.js inside a Story's implementation loop. Surfaces the in-progress Story as an inspectable ledger event so /deliver's host-loop reconciler can confirm a long Story is still making forward progress between dispatch and merge — distinct from story.dispatch.start (one per Story per attempt) and story.merged (one per Story per close). The 2-tier hierarchy has no child Task tickets, so the heartbeat carries phase info only. The optional operator field (Story #3480) records the handle holding the assignee-as-lease claim on the Story so the ticket-lease primitive can decide claim liveness from the most-recent heartbeat for a given owner.",
   "type": "object",
   "required": ["event", "storyId", "epicId", "phase", "timestamp"],
   "properties": {

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); both are gitignored via temp/. Consumed by close-validation, epic-code-review, and /epic-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/epic-<epicId>/validation-evidence.json (Epic-scoped) or temp/epic-<epicId>/stories/story-<storyId>/validation-evidence.json (Story-scoped); both are gitignored via temp/. Consumed by close-validation, epic-code-review, 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/README.md

@@ -49,7 +49,7 @@ that the file was meaningfully updated during this Epic's lifecycle
 
 **When to run.** Optional. Useful as a pre-merge spot check when an
 Epic should have produced documentation updates; the standard
-`/epic-deliver` flow does **not** invoke this gate today.
+`/deliver` flow does **not** invoke this gate today.
 
 **Usage.**
 

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

@@ -16,7 +16,7 @@
  *      and the resolved, undisableable round cap
  *      (`delivery.acceptanceEval.maxRounds`, clamped to `[1, ceiling]`).
  *   3. Emit one per-criterion `acceptance-eval` signal into the retro /
- *      feedback substrate so the retro and `/epic-plan` Phase 0 feedback
+ *      feedback substrate so the retro and `/plan` Phase 0 feedback
  *      fetch can see which acceptance items needed rework and the round
  *      count.
  *   4. Print a single JSON envelope and exit:
@@ -61,6 +61,7 @@ import { appendSignal } from './lib/observability/signals-writer.js';
 import {
   buildAcceptanceEvalSignal,
   decideAcceptanceEval,
+  deriveAcceptanceEvalRound,
 } from './lib/orchestration/acceptance-eval-decision.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -152,17 +153,33 @@ function parseCliArgs(argv) {
  * @param {object} args.verdict — validated verdict object.
  * @param {object} args.config — resolved `.agentrc.json`.
  * @param {boolean} args.emitSignal
+ * @param {number} [args.round] — explicit round override (tests). When
+ *   absent, the round is derived by counting prior `acceptance-eval`
+ *   signals in the Story's `signals.ndjson` (Story #4019); the verdict's
+ *   self-reported `round` is never load-bearing for the cap.
  * @param {object} [deps]
  * @param {Function} [deps.appendSignalFn]
+ * @param {Function} [deps.deriveRoundFn]
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
 export async function runAcceptanceEval(
-  { storyId, epicId, verdict, config, emitSignal },
+  { storyId, epicId, verdict, config, emitSignal, round },
   deps = {},
 ) {
-  const { appendSignalFn = appendSignal } = deps;
+  const {
+    appendSignalFn = appendSignal,
+    deriveRoundFn = deriveAcceptanceEvalRound,
+  } = deps;
   const { maxRounds } = getAcceptanceEval(config);
-  const outcome = decideAcceptanceEval({ verdict, maxRounds });
+  const resolvedRound =
+    Number.isInteger(round) && round >= 1
+      ? round
+      : deriveRoundFn({ epicId: epicId ?? null, storyId, config });
+  const outcome = decideAcceptanceEval({
+    verdict,
+    maxRounds,
+    round: resolvedRound,
+  });
 
   let signalEmitted = false;
   if (emitSignal) {

package/.agents/scripts/acceptance-spec-reconciler.js

@@ -301,7 +301,7 @@ export function renderBlockerMessage({
     lines.push(`  Pending (@pending-only coverage): ${pending.join(', ')}`);
   }
   lines.push(
-    `Author or de-pend scenarios under tests/features/** tagged @epic-${epicId}-ac-<n> so every AC ID is satisfied, then re-run /epic-deliver.`,
+    `Author or de-pend scenarios under tests/features/** tagged @epic-${epicId}-ac-<n> so every AC ID is satisfied, then re-run /deliver.`,
   );
   return lines.join('\n');
 }
@@ -420,7 +420,7 @@ export async function reconcileAcceptanceSpec({
     }
     // Defence in depth — the start gate would normally catch this.
     throw new Error(
-      `[acceptance-spec-reconciler] Epic #${epicId} has no linked context::acceptance-spec ticket and no acceptance::n-a waiver label. Re-run /epic-plan Phase 7 or apply the waiver.`,
+      `[acceptance-spec-reconciler] Epic #${epicId} has no linked context::acceptance-spec ticket and no acceptance::n-a waiver label. Re-run /plan Phase 7 or apply the waiver.`,
     );
   }
 

package/.agents/scripts/analyze-execution.js

@@ -18,7 +18,7 @@
  *     fetching each `story-perf-summary` structured comment from the
  *     ticketing provider. Posts the
  *     `<!-- structured:epic-perf-report -->` comment on the Epic ticket.
- *     Run from the retro composer / `/epic-deliver` Phase 6.0.
+ *     Run from the retro composer / `/deliver` Phase 6.0.
  *
  * Both modes are idempotent: `upsertStructuredComment` deletes the prior
  * marker before posting the new one.
@@ -27,7 +27,7 @@
  * NDJSON for a Story, no children for an Epic) so the close pipelines
  * never block on observability output. Hard failures (bad CLI args,
  * provider error, schema-violating payload) exit non-zero — the call
- * sites in post-merge-pipeline / `/epic-deliver` Phase 5 treat that
+ * sites in post-merge-pipeline / `/deliver` Phase 5 treat that
  * as a non-fatal warning.
  *
  * This file is a thin CLI: it wires the I/O readers from

package/.agents/scripts/assert-branch.js

@@ -20,11 +20,9 @@
  */
 
 import { fileURLToPath } from 'node:url';
-
-import { PROJECT_ROOT } from './lib/config-resolver.js';
 import { gitSpawn } from './lib/git-utils.js';
-
 import { Logger } from './lib/Logger.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
 export function assertBranch(expected, { cwd = PROJECT_ROOT } = {}) {
   if (!expected || typeof expected !== 'string') {
     return { ok: false, reason: 'missing --expected <branch>' };

package/.agents/scripts/audit-to-stories.js

@@ -13,7 +13,7 @@
  *     stdout when --json is set).
  *
  *   --emit-epic-seed --plan <plan.json> --out <path>
- *     Read the plan envelope from disk, render the `/epic-plan --idea`
+ *     Read the plan envelope from disk, render the `/plan --idea`
  *     seed markdown, persist to --out.
  *
  *   --emit-stories --plan <plan.json>

package/.agents/scripts/bootstrap.js

@@ -1353,7 +1353,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   // the failure is surfaced, not silently rolled back), but they MUST NOT
   // exit 0. `executeGithubBootstrap` records `report.github.error` instead
   // of throwing; detect it here and exit non-zero with a distinct final
-  // status line so `create-mandrel` and CI see the failure (Story #3898).
+  // status line so `mandrel init` and CI see the failure (Story #3898).
   const githubError = result.state?.report?.github?.error;
   if (githubError) {
     Logger.error(