@ikon85/agent-workflow-kit 0.30.0 → 0.31.0

package/scripts/test_skill_readiness_preflight.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Behavior contract for required-readiness planning preflights."""
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+READINESS = ROOT / "scripts/readiness.mjs"
+MANIFEST = ROOT / ".claude/skills/skill-manifest.json"
+SKILLS = ("to-prd", "to-issues", "to-waves", "board-to-waves")
+SPEC_SKILLS = ("to-issues", "to-waves")
+PREFLIGHT_START = "<!-- readiness:required-preflight:start -->"
+PREFLIGHT_END = "<!-- readiness:required-preflight:end -->"
+
+
+def write(root: Path, relative: str, body: str) -> None:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+
+
+def configure_issue_tracker(root: Path) -> None:
+    write(
+        root,
+        "docs/agents/issue-tracker.md",
+        "<!-- setup-workflow: state=filled -->\nGitHub Issues.\n",
+    )
+
+
+def configure_board(root: Path) -> None:
+    profile = {
+        "repo": "owner/repo",
+        "project": {"owner": "owner", "number": 1, "nodeId": "project"},
+        "fields": {
+            "status": {
+                "id": "status",
+                "options": {"Todo": "todo"},
+                "roles": {"triaged": "Todo"},
+            },
+            "wave": "wave",
+            "cluster": "cluster",
+        },
+        "labels": {"readyForAgent": "ready-for-agent"},
+    }
+    write(
+        root,
+        "docs/agents/board-sync.md",
+        "<!-- board-sync:profile -->\n```json\n"
+        f"{json.dumps(profile)}\n```\n",
+    )
+
+
+def configure_spec_completeness(root: Path) -> None:
+    write(
+        root,
+        "docs/conventions/spec-completeness.md",
+        "<!-- setup-workflow: state=filled -->\nVertical slice rules.\n",
+    )
+
+
+class PlanningReadinessPreflightTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+        write(
+            self.root,
+            ".claude/skills/skill-manifest.json",
+            MANIFEST.read_text(encoding="utf-8"),
+        )
+        write(
+            self.root,
+            "agent-workflow-kit.json",
+            json.dumps({
+                "kitVersion": "0.0.0-test",
+                "readinessContractVersion": 1,
+                "readinessDecisions": {},
+                "installed": [],
+            }),
+        )
+
+    def tearDown(self) -> None:
+        self.temp.cleanup()
+
+    def check(self, skill: str) -> dict:
+        completed = subprocess.run(
+            ["node", str(READINESS), "check", "--skill", skill, "--json", "--root", str(self.root)],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return json.loads(completed.stdout)
+
+    def snapshot(self) -> dict[Path, bytes]:
+        return {
+            path.relative_to(self.root): path.read_bytes()
+            for path in self.root.rglob("*") if path.is_file()
+        }
+
+    def test_missing_requirements_block_without_writing_fixture(self) -> None:
+        before = self.snapshot()
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                result = self.check(skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(result["capabilities"]["issueTracker"]["state"], "missing")
+                self.assertEqual(result["capabilities"]["managedBoard"]["state"], "missing")
+        self.assertEqual(self.snapshot(), before)
+
+    def test_invalid_requirement_is_visible_and_check_remains_read_only(self) -> None:
+        configure_board(self.root)
+        configure_spec_completeness(self.root)
+        write(
+            self.root,
+            "docs/agents/issue-tracker.md",
+            "<!-- setup-workflow: state=stub -->\npartial\n",
+        )
+        before = self.snapshot()
+        result = self.check("to-prd")
+        self.assertEqual(result["verdict"], "blocked")
+        self.assertEqual(result["capabilities"]["issueTracker"]["state"], "invalid")
+        self.assertEqual(self.snapshot(), before)
+
+    def test_managed_board_not_applicable_makes_every_board_writer_inapplicable(self) -> None:
+        configure_issue_tracker(self.root)
+        configure_spec_completeness(self.root)
+        manifest = json.loads((self.root / "agent-workflow-kit.json").read_text(encoding="utf-8"))
+        manifest["readinessDecisions"]["managedBoard"] = "not-applicable"
+        write(self.root, "agent-workflow-kit.json", json.dumps(manifest))
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                result = self.check(skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(
+                    result["capabilities"]["managedBoard"]["state"],
+                    "not-applicable",
+                )
+
+    def test_spec_completeness_blocks_only_the_slicing_flows(self) -> None:
+        configure_issue_tracker(self.root)
+        configure_board(self.root)
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                result = self.check(skill)
+                expected = "blocked" if skill in SPEC_SKILLS else "ready"
+                self.assertEqual(result["verdict"], expected)
+                if skill in SPEC_SKILLS:
+                    self.assertEqual(
+                        result["capabilities"]["specCompleteness"]["state"],
+                        "missing",
+                    )
+
+    def test_ready_state_and_skill_prose_share_one_silent_first_step(self) -> None:
+        configure_issue_tracker(self.root)
+        configure_board(self.root)
+        configure_spec_completeness(self.root)
+        for skill in SKILLS:
+            with self.subTest(skill=skill):
+                self.assertEqual(self.check(skill)["verdict"], "ready")
+                source = (ROOT / ".claude/skills" / skill / "SKILL.md").read_text(encoding="utf-8")
+                mirror = (ROOT / ".agents/skills" / skill / "SKILL.md").read_text(encoding="utf-8")
+                source_block = source.split(PREFLIGHT_START, 1)[1].split(PREFLIGHT_END, 1)[0]
+                mirror_block = mirror.split(PREFLIGHT_START, 1)[1].split(PREFLIGHT_END, 1)[0]
+                self.assertEqual(source_block, mirror_block)
+                self.assertIn(f"node scripts/readiness.mjs check --skill {skill} --json", source_block)
+                self.assertIn("before any remote write", source_block)
+                self.assertIn("Ready is silent", source_block)
+                self.assertIn("Run `/setup-workflow`, then rerun", source_block)
+                first_mutation = min(
+                    position for token in ("board-sync.py create", "gh issue edit")
+                    if (position := source.find(token)) >= 0
+                )
+                self.assertLess(source.find(PREFLIGHT_START), first_mutation)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_skill_required_readiness.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""Focused contract tests for required operational-skill readiness gates."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILLS = {
+    "triage": ("issueTracker", "managedBoard", "triageLabels"),
+    "local-ci": ("localCiRecipe",),
+    "project-release": ("projectReleaseProfile",),
+    "security-audit": ("securityAuditRunbook",),
+}
+
+
+def write(root: Path, relative: str, body: str) -> None:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+
+
+def snapshot(root: Path) -> dict[str, bytes]:
+    return {
+        str(path.relative_to(root)): path.read_bytes()
+        for path in root.rglob("*")
+        if path.is_file()
+    }
+
+
+def check(root: Path, skill: str) -> dict:
+    run = subprocess.run(
+        [
+            "node",
+            str(ROOT / "scripts/readiness.mjs"),
+            "check",
+            "--skill",
+            skill,
+            "--json",
+            "--root",
+            str(root),
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return json.loads(run.stdout)
+
+
+def seed_manifest(root: Path, decisions: dict[str, str] | None = None) -> None:
+    write(
+        root,
+        ".claude/skills/skill-manifest.json",
+        (ROOT / ".claude/skills/skill-manifest.json").read_text(encoding="utf-8"),
+    )
+    write(
+        root,
+        "agent-workflow-kit.json",
+        json.dumps(
+            {
+                "kitVersion": "fixture",
+                "readinessContractVersion": 1,
+                "readinessDecisions": decisions or {},
+                "installed": [],
+            }
+        ),
+    )
+
+
+def seed_valid_evidence(root: Path) -> None:
+    sentinel = "<!-- setup-workflow: state=filled -->\nconfigured\n"
+    write(root, "docs/agents/issue-tracker.md", sentinel)
+    write(root, "docs/agents/triage-labels.md", sentinel)
+    board = {
+        "repo": "owner/repo",
+        "project": {"owner": "owner", "number": 1, "nodeId": "project"},
+        "fields": {
+            "status": {
+                "id": "status",
+                "options": {"Done": "done"},
+                "roles": {"done": "Done"},
+            },
+            "wave": "wave",
+            "cluster": "cluster",
+        },
+        "labels": {"readyForAgent": "ready-for-agent"},
+    }
+    write(
+        root,
+        "docs/agents/board-sync.md",
+        f"<!-- board-sync:profile -->\n```json\n{json.dumps(board)}\n```\n",
+    )
+    write(root, "docs/agents/skills/local-ci.md", sentinel)
+    write(
+        root,
+        "docs/agents/workflow-capabilities.json",
+        json.dumps(
+            {
+                "schemaVersion": 1,
+                "projectRelease": {
+                    "versionFiles": ["package.json"],
+                    "tagPrefix": "v",
+                },
+            }
+        ),
+    )
+    write(
+        root,
+        "docs/agents/skills/security-audit.md",
+        "<!-- setup-workflow: state=filled -->\n"
+        "Use `docs/security/audit-runbook.md`.\n",
+    )
+    write(root, "docs/security/audit-runbook.md", "# Audit\nConcrete checks.\n")
+
+
+def readiness_section(body: str) -> str:
+    match = re.search(
+        r"^## Required readiness preflight\n[\s\S]*?(?=^## |\Z)", body, re.MULTILINE
+    )
+    if not match:
+        raise AssertionError("required readiness preflight section is missing")
+    return match.group(0).strip()
+
+
+class RequiredReadinessSkillTests(unittest.TestCase):
+    def test_every_operational_skill_gates_before_mutation(self) -> None:
+        first_mutation = {
+            "triage": "## Triage a specific issue",
+            "local-ci": "## The two profiles",
+            "project-release": "## Workflow",
+            "security-audit": "## Workflow — two-model run",
+        }
+        for skill, capabilities in SKILLS.items():
+            with self.subTest(skill=skill):
+                body = (ROOT / ".claude/skills" / skill / "SKILL.md").read_text(
+                    encoding="utf-8"
+                )
+                heading = "## Required readiness preflight"
+                self.assertIn(heading, body)
+                self.assertLess(body.index(heading), body.index(first_mutation[skill]))
+                self.assertIn(
+                    f"node scripts/readiness.mjs check --skill {skill} --json", body
+                )
+                for capability in capabilities:
+                    self.assertIn(f"`{capability}`", body)
+                for state in ("missing", "pending", "not-applicable", "invalid"):
+                    self.assertIn(f"`{state}`", body)
+                self.assertIn("verdict is silent", body)
+                self.assertIn("Never ", body)
+                mirror = (ROOT / ".agents/skills" / skill / "SKILL.md").read_text(
+                    encoding="utf-8"
+                )
+                self.assertEqual(readiness_section(mirror), readiness_section(body))
+
+        project_release = (
+            ROOT / ".claude/skills/project-release/SKILL.md"
+        ).read_text(encoding="utf-8")
+        preflight = project_release.index(
+            "node scripts/readiness.mjs check --skill project-release --json"
+        )
+        helper = project_release.index("node scripts/project-release.mjs preview")
+        self.assertLess(preflight, helper)
+        self.assertIn("helper remains the authority", project_release)
+
+    def test_helper_blocks_missing_prerequisites_without_side_effects(self) -> None:
+        for skill, capabilities in SKILLS.items():
+            with self.subTest(skill=skill), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root)
+                before = snapshot(root)
+                result = check(root, skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(
+                    {name: result["capabilities"][name]["state"] for name in capabilities},
+                    {name: "missing" for name in capabilities},
+                )
+                self.assertEqual(snapshot(root), before)
+
+    def test_helper_distinguishes_pending_not_applicable_invalid_and_ready(self) -> None:
+        invalid_evidence = {
+            "triage": ("docs/agents/issue-tracker.md", "<!-- setup-workflow: state=stub -->\n"),
+            "local-ci": ("docs/agents/skills/local-ci.md", "<!-- setup-workflow: state=stub -->\n"),
+            "project-release": ("docs/agents/workflow-capabilities.json", "{}\n"),
+            "security-audit": (
+                "docs/agents/skills/security-audit.md",
+                "<!-- setup-workflow: state=filled -->\nno project runbook\n",
+            ),
+        }
+        for skill, capabilities in SKILLS.items():
+            capability = capabilities[0]
+            with self.subTest(skill=skill, state="pending"), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root, {capability: "pending"})
+                self.assertEqual(check(root, skill)["capabilities"][capability]["state"], "pending")
+
+            with self.subTest(skill=skill, state="invalid"), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root)
+                seed_valid_evidence(root)
+                write(root, *invalid_evidence[skill])
+                result = check(root, skill)
+                self.assertEqual(result["verdict"], "blocked")
+                self.assertEqual(result["capabilities"][capability]["state"], "invalid")
+
+            with self.subTest(skill=skill, state="ready"), tempfile.TemporaryDirectory() as temp:
+                root = Path(temp)
+                seed_manifest(root)
+                seed_valid_evidence(root)
+                before = snapshot(root)
+                result = check(root, skill)
+                self.assertEqual(result["verdict"], "ready")
+                self.assertTrue(
+                    all(item["state"] == "ready" for item in result["capabilities"].values())
+                )
+                self.assertEqual(snapshot(root), before)
+
+        with self.subTest(skill="triage", state="not-applicable"), tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            seed_manifest(root, {"managedBoard": "not-applicable"})
+            seed_valid_evidence(root)
+            (root / "docs/agents/board-sync.md").unlink()
+            result = check(root, "triage")
+            self.assertEqual(result["verdict"], "blocked")
+            self.assertEqual(result["capabilities"]["managedBoard"]["state"], "not-applicable")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_skill_setup_workflow_seeds.py

@@ -213,6 +213,28 @@ class IdempotencyRule(unittest.TestCase):
 
 
 class SeedTemplatesValid(unittest.TestCase):
+    def test_prod_readiness_choice_and_transaction_contract_is_complete(self):
+        for surface in (".claude", ".agents"):
+            text = (REPO / surface / "skills/setup-workflow/SKILL.md").read_text(
+                encoding="utf-8"
+            )
+            for token in (
+                "Configure now", "Configure later",
+                "decision set prodTarget pending",
+                "wrapup.deployReport omitted (prodTarget pending)",
+                "`prodTarget` does not permit this choice",
+                "Preview the exact local `## Prod` replacement",
+                "external mutation retains its own separate",
+                "activeBlocks` must be exactly `[\"deployReport\"]`",
+            ):
+                self.assertIn(token, text, f"{surface} missing {token!r}")
+            preserve = re.search(
+                r"Preserve each file's\s+`## Workflow` and `## Agent skills` "
+                r"blocks byte-for-byte",
+                text,
+            )
+            self.assertIsNotNone(preserve, surface)
+
     def test_census_effect_contract_executes_every_transition_and_repeats_without_writes(self):
         effects = load_census_setup_effects()
         self.assertEqual(

package/src/cli.mjs

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import * as p from '@clack/prompts';
 import { init } from './commands/init.mjs';
-import { update } from './commands/update.mjs';
+import { renderUpdateFailure, update } from './commands/update.mjs';
 import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
 import { setOwnership } from './commands/own.mjs';
@@ -49,7 +49,7 @@ try {
     });
     printPlan(r);
     for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (not applied): ${c.path}`);
-    if (r.state === 'failed') throw new Error(`candidate update failed: ${r.error}`);
+    if (r.state === 'failed') throw new Error(renderUpdateFailure(r));
     if (r.state === 'conflicted') {
       p.note(r.report.recommendation, 'recommendation');
       p.outro(`not applied · conflicts ${r.conflicts.length}`);
@@ -86,6 +86,14 @@ function printPlan(r) {
   ])
     if (r[k]?.length) lines.push(`${k}: ${r[k].length}`);
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
+  if (r.availability) {
+    for (const [key, label] of [
+      ['newlyAvailable', 'newly available'], ['newlyDegraded', 'newly degraded'],
+      ['newlyBlocked', 'newly blocked'], ['stillUnresolved', 'still unresolved'],
+    ]) {
+      lines.push(`${label}: ${r.availability[key].join(', ') || 'none'}`);
+    }
+  }
   for (const owned of r.ownedDiffs ?? []) {
     lines.push(`${owned.state} ${owned.path}`);
     if (owned.binary) {

package/src/commands/update.mjs

@@ -1,7 +1,9 @@
 import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { assertConsumerReleaseParity } from '../../scripts/release-parity.mjs';
-import { activateCandidate, stageConsumer, verifyCandidate } from '../lib/updateCandidate.mjs';
+import {
+  activateCandidate, adoptReadinessCandidate, readReadinessManifest, stageConsumer, verifyCandidate,
+} from '../lib/updateCandidate.mjs';
 import { reconcile } from '../lib/updateReconcile.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
@@ -9,6 +11,12 @@ import {
 
 const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
+export function renderUpdateFailure(result) {
+  const failure = result.failure ?? { phase: 'unknown', consumerState: 'unknown' };
+  return `candidate update failed · phase: ${failure.phase} · ` +
+    `consumerState: ${failure.consumerState} · ${result.error}`;
+}
+
 /**
  * Transactionally reconcile a consumer with a parity-proven kit release.
  * checking -> preview/awaiting_decision -> staging -> verifying -> terminal state.
@@ -16,7 +24,8 @@ const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 export async function update(options) {
   const {
     kitRoot, consumerRoot, decide = () => false, dryRun = false,
-    releaseIdentities, verify = verifyCandidate, signal, onState = () => {}, resumeFrom,
+    releaseIdentities, verify = verifyCandidate, activate = activateCandidate,
+    signal, onState = () => {}, resumeFrom,
   } = options;
   const history = [];
   const transition = async (state) => { history.push(state); await onState(state); };
@@ -30,6 +39,8 @@ export async function update(options) {
     throw new Error('not initialised — run `init` first');
   }
   const consumerManifestBefore = await readFile(consumerManifestPath);
+  const priorReadinessManifest = await readReadinessManifest(consumerRoot);
+  const nextReadinessManifest = await readReadinessManifest(kitRoot);
 
   const decisions = new Map();
   const choosePreview = async (action, path) => {
@@ -39,7 +50,21 @@ export async function update(options) {
     return decisions.get(key);
   };
   const preview = await reconcile({ kitRoot, consumerRoot, decide: choosePreview, dryRun: true });
+  let previewFailure;
+  try {
+    Object.assign(preview, await previewReadinessAdoption({
+      kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest,
+    }));
+  } catch (error) {
+    previewFailure = error;
+  }
   await transition('preview');
+  if (previewFailure) {
+    return {
+      ...await terminal(preview, 'failed', history, transition), error: previewFailure.message,
+      failure: { phase: 'staging', consumerState: 'unchanged' },
+    };
+  }
   if (dryRun) return { ...preview, state: 'preview', history };
   if (preview.conflicts.length) return terminal(preview, 'conflicted', history, transition);
   const resolvedPreview = await resolvePreview({
@@ -52,11 +77,28 @@ export async function update(options) {
     return { ...await terminal(resolvedPreview, 'applied', history, transition), status: 'current' };
   }
   return applyTransaction({
-    kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, signal, resumeFrom,
-    consumerManifestBefore, history, transition,
+    kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, activate, signal, resumeFrom,
+    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
   });
 }
 
+async function previewReadinessAdoption(context) {
+  const { kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest } = context;
+  const candidateRoot = await stageConsumer(consumerRoot);
+  try {
+    await reconcile({
+      kitRoot, consumerRoot: candidateRoot,
+      decide: (action) => action === 'collision' ? 'keep-as-owned' : false,
+    });
+    return await adoptReadinessCandidate({
+      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+      nextManifest: nextReadinessManifest,
+    });
+  } finally {
+    await rm(candidateRoot, { recursive: true, force: true });
+  }
+}
+
 async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decide, transition }) {
   if (preview.deleted.length || preview.keptDeleted.length || preview.collisions.length) {
     await transition('awaiting_decision');
@@ -73,11 +115,12 @@ async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decid
 
 async function applyTransaction(context) {
   const {
-    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
-    consumerManifestBefore, history, transition,
+    kitRoot, consumerRoot, pkg, preview, decisions, verify, activate, signal, resumeFrom,
+    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
   } = context;
   let candidateRoot = resumeFrom;
   let keepCandidate = false;
+  let phase = 'staging';
   try {
     await transition('staging');
     if (candidateRoot && preview.collisionResolutions.length) {
@@ -90,6 +133,16 @@ async function applyTransaction(context) {
         decide: (action, path) => decisions.get(decisionKey(action, path)),
       });
     }
+    const readiness = await adoptReadinessCandidate({
+      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+      nextManifest: nextReadinessManifest,
+    });
+    preview.generated = readiness.generated;
+    preview.availability = readiness.availability;
+    if (readiness.incompatible.length) {
+      throw new Error(`monotonic compatibility would block existing skill core: ${readiness.incompatible.join(', ')}`);
+    }
+    phase = 'verification';
     await transition('verifying');
     const abort = async () => {
       keepCandidate = true;
@@ -98,12 +151,16 @@ async function applyTransaction(context) {
     if (signal?.aborted) return abort();
     await verify(candidateRoot);
     if (signal?.aborted) return abort();
-    await activateCandidate({
+    phase = 'activation';
+    await activate({
       candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
     });
     return { ...await terminal(preview, 'applied', history, transition), status: 'updated' };
   } catch (error) {
-    return { ...await terminal(preview, 'failed', history, transition), error: error.message };
+    return {
+      ...await terminal(preview, 'failed', history, transition), error: error.message,
+      failure: { phase, consumerState: error.consumerState ?? 'unchanged' },
+    };
   } finally {
     if (candidateRoot && !keepCandidate) await rm(candidateRoot, { recursive: true, force: true });
   }