@ikon85/agent-workflow-kit 0.37.0 → 0.39.0

package/scripts/worktree-lifecycle/setup.py

@@ -10,6 +10,9 @@ import zlib
 from pathlib import Path
 
 from core import (
+    BaselineBackfillDeferred,
+    capture_artifact_baseline,
+    ensure_artifact_baseline,
     LifecycleError,
     load_profile,
     local_branch_exists,
@@ -137,6 +140,17 @@ def create(args: argparse.Namespace) -> Path:
         ensure_reusable_base(
             main, repo=target, rev="HEAD", base=args.base, label=f"worktree {target}"
         )
+        try:
+            ensure_artifact_baseline(
+                target,
+                reject_ignored_patterns=profile.landing_generated_artifact_patterns,
+            )
+        except BaselineBackfillDeferred as error:
+            print(
+                "Baseline backfill deferred; preserve the worktree, remove generated "
+                f"blockers or commit/stash tracked work, then retry: {error}",
+                file=sys.stderr,
+            )
         print(f"Worktree already exists: {target} ({branch})")
         return target
 
@@ -157,6 +171,7 @@ def create(args: argparse.Namespace) -> Path:
                 issue=args.issue,
                 branch=branch,
             )
+        capture_artifact_baseline(target)
     except Exception:
         remove_failed_worktree(main, target, branch, not branch_existed)
         raise

package/scripts/wrapup-land.py

@@ -71,6 +71,14 @@ INFRA_FAILURE_RE = re.compile(
 )
 
 
+ABANDON_ATTEMPT_FLAG = "--abandon-unfinished-attempt"
+RECOVER_CANONICAL_CLEANUP_FLAG = "--recover-canonical-cleanup"
+CANONICAL_DRIFT_RECOVERY_HINT = (
+    f"rerun land with {RECOVER_CANONICAL_CLEANUP_FLAG} to revalidate the frozen "
+    "landing evidence against canonical policy and resume teardown"
+)
+
+
 class Stop(Exception):
     def __init__(self, step: str, reason: str, detail: str = ""):
         super().__init__(reason)
@@ -437,18 +445,215 @@ def load_worktree_cleanup_core():
     return module
 
 
-def ensure_worktree_removable(wt: str, main_tree: str):
-    profile_path = Path(main_tree) / "docs/agents/workflow-capabilities.json"
-    if not profile_path.is_file():
-        return None
+def load_candidate_landing_profile(core, wt: str):
+    """Let the committed worktree policy nominate evidence without deletion."""
+    result = core.run(
+        [
+            "git", "show",
+            "HEAD:docs/agents/workflow-capabilities.json",
+        ],
+        cwd=Path(wt),
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise core.LifecycleError(
+            f"committed landing profile cannot be read from worktree HEAD: {detail}"
+        )
+    candidate = core.load_profile_text(result.stdout)
+    if not candidate.landing_generated_artifact_policy_configured:
+        raise core.LifecycleError(
+            "worktree landing artifact policy is not configured; "
+            "run setup-workflow and commit the explicit policy decision first"
+        )
+    return candidate
+
+
+def load_merged_canonical_profile(core, main_tree: str):
+    """Read the merged canonical cleanup policy from origin/main."""
+    result = core.run(
+        [
+            "git", "show",
+            "origin/main:docs/agents/workflow-capabilities.json",
+        ],
+        cwd=Path(main_tree),
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise core.LifecycleError(
+            f"canonical landing profile cannot be read from origin/main: {detail}"
+        )
+    canonical = core.load_profile_text(result.stdout)
+    if not canonical.landing_generated_artifact_policy_configured:
+        raise core.LifecycleError(
+            "merged canonical landing artifact policy is not configured"
+        )
+    return canonical
+
+
+def load_canonical_landing_profile(core, wt: str, main_tree: str):
+    """Authorize deletion only after the candidate policy is canonical."""
+    candidate = load_candidate_landing_profile(core, wt)
+    canonical = load_merged_canonical_profile(core, main_tree)
+    if (
+        candidate.landing_generated_artifact_patterns
+        != canonical.landing_generated_artifact_patterns
+        or candidate.scratch_patterns != canonical.scratch_patterns
+    ):
+        raise core.LifecycleError(
+            "worktree cleanup policy differs from merged canonical origin/main"
+            f"; {CANONICAL_DRIFT_RECOVERY_HINT}"
+        )
+    if not core.landing_attempt_exists(core.landing_attempt_path(Path(wt))):
+        raise core.LifecycleError(
+            "landing attempt is missing before canonical cleanup authorization"
+        )
+    attempt = core.landing_start_artifact_inventory(candidate, Path(wt))
+    if (
+        attempt["policyDigest"]
+        != core.landing_cleanup_policy_digest(canonical)
+    ):
+        raise core.LifecycleError(
+            "landing attempt cleanup policy differs from merged canonical origin/main"
+            f"; {CANONICAL_DRIFT_RECOVERY_HINT}"
+        )
+    return canonical
+
+
+def load_canonical_recovery_profile(core, wt: str, main_tree: str):
+    """Authorize post-merge cleanup from canonical policy alone after drift.
+
+    The committed worktree candidate is deliberately never consulted here: after
+    canonical drift it is stale, and trusting it could only widen what may be
+    deleted. Every authority boundary re-validates the frozen evidence against
+    the merged canonical policy instead.
+    """
+    canonical = load_merged_canonical_profile(core, main_tree)
+    core.canonical_recovery_evidence(canonical, Path(wt))
+    return canonical
+
+
+def landing_start_artifact_inventory(wt: str, main_tree: str) -> dict:
     core = load_worktree_cleanup_core()
     try:
-        profile = core.load_profile(profile_path)
-        assessment = core.cleanup_assessment(
+        profile = load_candidate_landing_profile(core, wt)
+        return core.landing_start_artifact_inventory(profile, Path(wt))
+    except core.LegacyLandingAttempt as error:
+        # Legacy, not damage: report the classification and the safe route out
+        # verbatim, without the corruption framing of a guard failure.
+        raise Stop("cleanup", str(error)) from error
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def landing_verified_scratch_evidence(
+    wt: str,
+    main_tree: str,
+    *,
+    expected_baseline_digest: str | None = None,
+    landing_start_files: tuple[str, ...] = (),
+) -> tuple[dict, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.verified_landing_scratch_evidence(
             profile,
-            Path(main_tree),
             Path(wt),
-            merge_target="origin/main",
+            expected_baseline_digest=expected_baseline_digest,
+            landing_start_files=landing_start_files,
+        )
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def freeze_landing_artifact_evidence(
+    wt: str,
+    main_tree: str,
+    *,
+    push_succeeded: bool,
+) -> tuple[dict, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.freeze_landing_artifact_evidence(
+            profile,
+            Path(wt),
+            push_succeeded=push_succeeded,
+        )
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def reopen_frozen_landing_attempt(wt: str, main_tree: str) -> tuple[dict, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.reopen_frozen_landing_attempt(profile, Path(wt))
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def abandon_unfinished_landing_attempt(wt: str, main_tree: str) -> str:
+    core = load_worktree_cleanup_core()
+    try:
+        return str(core.abandon_unfinished_landing_attempt(Path(wt)))
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def canonical_recovery_evidence(wt: str, main_tree: str) -> tuple[dict, ...]:
+    """Revalidate the frozen landing evidence against canonical policy alone."""
+    core = load_worktree_cleanup_core()
+    try:
+        canonical = load_merged_canonical_profile(core, main_tree)
+        return core.canonical_recovery_evidence(canonical, Path(wt))
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def landing_verified_scratch_files(
+    wt: str,
+    main_tree: str,
+    *,
+    expected_baseline_digest: str | None = None,
+) -> tuple[str, ...]:
+    core = load_worktree_cleanup_core()
+    try:
+        profile = load_candidate_landing_profile(core, wt)
+        return core.verified_landing_scratch_files(
+            profile,
+            Path(wt),
+            expected_baseline_digest=expected_baseline_digest,
+        )
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
+def ensure_worktree_removable(
+    wt: str,
+    main_tree: str,
+    *,
+    verified_scratch_files: tuple[str, ...] = (),
+    verified_scratch_evidence: tuple[dict, ...] = (),
+    profile_loader=None,
+):
+    core = load_worktree_cleanup_core()
+    # Resolved at call time so the module attribute stays the single seam.
+    loader = profile_loader or load_canonical_landing_profile
+    try:
+        profile = loader(core, wt, main_tree)
+        kwargs = {"merge_target": "origin/main"}
+        paths = (
+            tuple(item["path"] for item in verified_scratch_evidence)
+            or verified_scratch_files
+        )
+        if paths:
+            kwargs["verified_scratch_files"] = paths
+        if verified_scratch_evidence:
+            kwargs["verified_scratch_evidence"] = verified_scratch_evidence
+        assessment = core.cleanup_assessment(
+            profile, Path(main_tree), Path(wt), **kwargs
         )
     except core.LifecycleError as error:
         raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
@@ -461,6 +666,71 @@ def ensure_worktree_removable(wt: str, main_tree: str):
     return assessment
 
 
+def remove_verified_worktree_scratch(
+    wt: str,
+    main_tree: str,
+    assessment,
+    *,
+    verified_scratch_files: tuple[str, ...] = (),
+    verified_scratch_evidence: tuple[dict, ...] = (),
+    profile_loader=None,
+):
+    """Re-verify and delete only assessed regular scratch files."""
+    core = load_worktree_cleanup_core()
+    loader = profile_loader or load_canonical_landing_profile
+    try:
+        profile = loader(core, wt, main_tree)
+        evidence = verified_scratch_evidence
+        paths = tuple(item["path"] for item in evidence) or verified_scratch_files
+        latest = core.cleanup_assessment(
+            profile,
+            Path(main_tree),
+            Path(wt),
+            merge_target="origin/main",
+            verified_scratch_files=paths,
+            verified_scratch_evidence=evidence,
+        )
+        if latest.reasons:
+            raise core.LifecycleError(
+                "cleanup changed before removal: " + "; ".join(latest.reasons)
+            )
+        if (
+            latest.branch != assessment.branch
+            or latest.scratch_files != assessment.scratch_files
+            or latest.assumptions != assessment.assumptions
+            or latest.root_device != assessment.root_device
+            or latest.root_inode != assessment.root_inode
+            or latest.scratch_evidence != assessment.scratch_evidence
+        ):
+            raise core.LifecycleError(
+                "cleanup changed before removal: inventory no longer matches preview"
+            )
+        with core.verified_worktree_root(
+            latest.worktree,
+            latest.root_device,
+            latest.root_inode,
+        ) as root_descriptor:
+            core.remove_authorized_scratch(
+                profile,
+                root_descriptor,
+                latest.scratch_files,
+                latest.scratch_evidence,
+            )
+        final = core.cleanup_assessment(
+            profile,
+            Path(main_tree),
+            Path(wt),
+            merge_target="origin/main",
+        )
+        if final.reasons:
+            raise core.LifecycleError(
+                "cleanup changed after scratch removal: " + "; ".join(final.reasons)
+            )
+        return final
+    except core.LifecycleError as error:
+        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+
+
 # ---------- drift log (ANNAHMEN.md) ----------
 
 def parse_annahmen(text: str, default_section: str) -> tuple[list[dict], list[str]]:
@@ -686,6 +956,105 @@ def cmd_commit(args) -> dict:
     return {"committed": True, "sha": sha, "allowed_matches": bool(hits)}
 
 
+def retire_local_branch(branch: str, main_tree: str, report: dict) -> None:
+    """Fast-forward main, then retire the merged local branch with `-d` only."""
+    git(["fetch", "origin", "--prune"], cwd=main_tree)
+    git(["checkout", "main"], cwd=main_tree)
+    p = git(["pull", "--ff-only"], cwd=main_tree)
+    if p.returncode != 0:
+        raise Stop("5 main-ff", "no fast-forward possible — diverged main is an anomaly",
+                   (p.stderr or p.stdout).strip()[-1000:])
+    if git(["show-ref", "--verify", "--quiet", f"refs/heads/{branch}"],
+           cwd=main_tree).returncode != 0:
+        report["branch_retired"] = "already absent"
+        return
+    if branch in worktree_map(main_tree)[1]:
+        report["branch_retired"] = "refused: still checked out"
+        report["warnings"].append(
+            f"branch -d {branch} refused (still checked out?) — never -D"
+        )
+        return
+    p = git(["branch", "-d", branch], cwd=main_tree)
+    report["branch_retired"] = p.returncode == 0
+    if p.returncode != 0:
+        report["warnings"].append(
+            f"branch -d {branch} refused: {(p.stderr or '').strip()[:200]}"
+        )
+
+
+def recover_canonical_cleanup(
+    branch: str,
+    wt: str | None,
+    wt_exists: bool,
+    main_tree: str,
+) -> dict:
+    """Resume post-merge teardown after canonical cleanup-policy drift.
+
+    Canonical drift keeps the normal path fail-closed: the attempt is bound to
+    the policy that nominated its evidence, and that binding is never relaxed.
+    This route is the supported way out, not a bypass — it re-reads the merged
+    canonical policy, requires the branch to already be an ancestor of canonical
+    `origin/main`, and revalidates every frozen identity against that canonical
+    policy before the same shared assessment and removal primitives run. Nothing
+    outside the revalidated evidence can be deleted, and rerunning it after a
+    successful teardown is a no-op.
+    """
+    report: dict = {
+        "recovery": "canonical-cleanup",
+        "branch": branch,
+        "warnings": [],
+    }
+    git(["fetch", "origin", "main"], cwd=main_tree, check=True)
+    if not wt_exists:
+        report["worktree_removed"] = None
+        report["cleanup_guard"] = None
+        retire_local_branch(branch, main_tree, report)
+        report["main_sha"] = git(["log", "--oneline", "-1"], cwd=main_tree,
+                                 check=True).stdout.strip()
+        return report
+    assert wt is not None
+    if git(["status", "--porcelain"], cwd=wt, check=True).stdout.strip():
+        raise Stop("recover-cleanup", "worktree dirty — run `commit` first", wt)
+    if git(["merge-base", "--is-ancestor", branch, "origin/main"],
+           cwd=main_tree).returncode != 0:
+        raise Stop(
+            "recover-cleanup",
+            "branch is not merged into canonical origin/main — canonical cleanup "
+            "recovery only resumes an already-merged teardown",
+            branch,
+        )
+    evidence = canonical_recovery_evidence(wt, main_tree)
+    assessment = ensure_worktree_removable(
+        wt,
+        main_tree,
+        verified_scratch_evidence=evidence,
+        profile_loader=load_canonical_recovery_profile,
+    )
+    report["cleanup_guard"] = {
+        "assumptions_read": bool(assessment.assumptions),
+        "landing_generated_files": [item["path"] for item in evidence],
+    }
+    report["killed_processes"] = kill_worktree_processes(wt)
+    remove_verified_worktree_scratch(
+        wt,
+        main_tree,
+        assessment,
+        verified_scratch_evidence=evidence,
+        profile_loader=load_canonical_recovery_profile,
+    )
+    p = git(["worktree", "remove", wt], cwd=main_tree)
+    if p.returncode != 0:
+        raise Stop("recover-cleanup", "git worktree remove refused — no --force; "
+                   "check for surviving processes (lsof/pgrep)",
+                   (p.stderr or p.stdout).strip()[-1000:])
+    git(["worktree", "prune"], cwd=main_tree)
+    report["worktree_removed"] = wt
+    retire_local_branch(branch, main_tree, report)
+    report["main_sha"] = git(["log", "--oneline", "-1"], cwd=main_tree,
+                             check=True).stdout.strip()
+    return report
+
+
 def cmd_land(args) -> dict:
     report: dict = {"stops": [], "warnings": []}
     main_tree, branches = worktree_map()
@@ -697,14 +1066,46 @@ def cmd_land(args) -> dict:
     branch = args.branch
     wt = branches.get(branch)
     wt_exists = wt is not None and Path(wt).is_dir()
+    if getattr(args, "recover_canonical_cleanup", False):
+        return recover_canonical_cleanup(branch, wt, wt_exists, main_tree)
     profile = load_profile()
     default_section = profile.get("headings", {}).get("vorBau", "Vor Bau zu klären")
 
     # drift markers from the build-time log — mechanical, no gate
     markers: list[dict] = []
+    landing_attempt: dict | None = None
+    generated_evidence: tuple[dict, ...] = ()
     if wt_exists:
         if git(["status", "--porcelain"], cwd=wt, check=True).stdout.strip():
             raise Stop("land", "worktree dirty — run `commit` first", wt)
+        if getattr(args, "abandon_unfinished_attempt", False):
+            return {
+                "landing_attempt_abandoned": abandon_unfinished_landing_attempt(
+                    wt, main_tree
+                ),
+                "files_removed": [],
+                "next": (
+                    "current files remain protected; classify or move blockers, "
+                    "then rerun land"
+                ),
+            }
+        landing_attempt = landing_start_artifact_inventory(wt, main_tree)
+        if landing_attempt["state"] == "started" and not landing_attempt["newAttempt"]:
+            raise Stop(
+                "cleanup",
+                "unfinished landing generator attempt has no frozen output evidence; "
+                f"classify its files, then rerun with {ABANDON_ATTEMPT_FLAG}",
+            )
+        # Retained structural backstop: a journal on the active contract always
+        # carries an empty `generatedFiles`, because a landing-start blocker is
+        # refused before the journal is written. A non-empty list therefore means
+        # tampered or migrated evidence — never a path this run may claim.
+        if landing_attempt["generatedFiles"]:
+            raise Stop(
+                "cleanup",
+                "landing-start generated paths are consumer-owned and protected: "
+                + ", ".join(landing_attempt["generatedFiles"]),
+            )
         annahmen = Path(wt) / "ANNAHMEN.md"
         if annahmen.is_file():
             markers, malformed = parse_annahmen(annahmen.read_text(), default_section)
@@ -716,9 +1117,25 @@ def cmd_land(args) -> dict:
 
     # Step 0b — push
     if wt_exists:
-        p = git(["push", "-u", "origin", branch], cwd=wt)
-        if p.returncode != 0:
-            raise Stop("0b push", "push rejected", (p.stderr or p.stdout).strip()[-2000:])
+        assert landing_attempt is not None
+        if landing_attempt["state"] == "frozen" and landing_attempt["pushSucceeded"]:
+            generated_evidence = freeze_landing_artifact_evidence(
+                wt, main_tree, push_succeeded=True
+            )
+        else:
+            if landing_attempt["state"] == "frozen":
+                # Validate every previously frozen identity before a retry can
+                # invoke the generator-capable pre-push hook.
+                reopen_frozen_landing_attempt(wt, main_tree)
+            p = git(["push", "-u", "origin", branch], cwd=wt)
+            generated_evidence = freeze_landing_artifact_evidence(
+                wt, main_tree, push_succeeded=p.returncode == 0
+            )
+            if p.returncode != 0:
+                raise Stop(
+                    "0b push", "push rejected",
+                    (p.stderr or p.stdout).strip()[-2000:],
+                )
 
     # Step 0c — ensure PR + final body
     p = run(["gh", "pr", "view", branch, "--json", "number,state,body"])
@@ -789,12 +1206,24 @@ def cmd_land(args) -> dict:
     # Step 2 — kill the worktree's dev server, then Step 4 — teardown
     if wt_exists:
         git(["fetch", "origin", "main"], cwd=main_tree, check=True)
-        cleanup = ensure_worktree_removable(wt, main_tree)
+        generated = tuple(item["path"] for item in generated_evidence)
+        cleanup = ensure_worktree_removable(
+            wt,
+            main_tree,
+            verified_scratch_files=generated,
+            verified_scratch_evidence=generated_evidence,
+        )
         report["cleanup_guard"] = {
-            "active": cleanup is not None,
-            "assumptions_read": bool(cleanup and cleanup.assumptions),
+            "assumptions_read": bool(cleanup.assumptions),
+            "landing_generated_files": list(generated),
         }
         report["killed_processes"] = kill_worktree_processes(wt)
+        remove_verified_worktree_scratch(
+            wt,
+            main_tree,
+            cleanup,
+            verified_scratch_evidence=generated_evidence,
+        )
         p = git(["worktree", "remove", wt], cwd=main_tree)
         if p.returncode != 0:
             raise Stop("4 worktree-remove", "git worktree remove refused — no --force; "
@@ -922,6 +1351,24 @@ def main() -> int:
     l.add_argument("--body-file", help="final PR body (create or overwrite)")
     l.add_argument("--anchor", help="wave-anchor issue # (derived via parent-of when omitted)")
     l.add_argument("--skip-malformed-drift", action="store_true")
+    recovery = l.add_mutually_exclusive_group()
+    recovery.add_argument(
+        ABANDON_ATTEMPT_FLAG,
+        action="store_true",
+        help=(
+            "archive an interrupted pre-freeze landing attempt without deleting "
+            "or claiming its ambiguous files"
+        ),
+    )
+    recovery.add_argument(
+        RECOVER_CANONICAL_CLEANUP_FLAG,
+        action="store_true",
+        help=(
+            "after canonical cleanup-policy drift, revalidate the frozen landing "
+            "evidence against canonical origin/main and resume the merged "
+            "worktree's teardown idempotently"
+        ),
+    )
     args = ap.parse_args()
 
     try:

package/src/cli.mjs

@@ -16,6 +16,7 @@ import {
 } from './lib/contributionRouting.mjs';
 import { CONSUMER_ORIGIN, KIT_ORIGIN } from './lib/manifest.mjs';
 import { nonInteractiveUpdateDecision } from './lib/updateDecisions.mjs';
+import { renderRequiredMigration } from './lib/consumerMigrations.mjs';
 import { currentAgentSurface } from './lib/agentSurfaceRegistry.mjs';
 import { createCommandAdapter } from '../scripts/release-state.mjs';
 import { installedIdentityFromDir } from '../scripts/release-parity.mjs';
@@ -43,6 +44,8 @@ export async function runCli({
   const keepDeleted = args.includes('--keep-deleted');
   const restoreDeleted = args.includes('--restore-deleted');
   const ownershipState = args.find((arg) => arg.startsWith('--as='))?.slice('--as='.length);
+  // Machine-readable rendering of the same update record the interactive run prints.
+  const jsonReport = cmd === 'update' && args.includes('--json');
   let exitCode = 0;
 
   if (cmd === 'update' && keepDeleted && restoreDeleted) {
@@ -57,7 +60,7 @@ export async function runCli({
     return 1;
   }
 
-  p.intro('agent-workflow-kit');
+  if (!jsonReport) p.intro('agent-workflow-kit');
 
   try {
   if (cmd === 'init') {
@@ -94,6 +97,11 @@ export async function runCli({
       releaseIdentities,
       routingProfile: routingProfileOptions(yes),
     });
+    if (jsonReport) {
+      process.stdout.write(`${JSON.stringify(updateDocument(r), null, 2)}\n`);
+      if (r.state === 'failed') return 1;
+      return r.state === 'conflicted' ? 2 : 0;
+    }
     printPlan(r);
     printRoutingProfile(r.routingProfile);
     for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (not applied): ${c.path}`);
@@ -183,12 +191,31 @@ export async function runCli({
     p.outro('');
   }
 } catch (err) {
+  if (jsonReport) {
+    process.stdout.write(`${JSON.stringify({
+      schemaVersion: UPDATE_DOCUMENT_SCHEMA_VERSION, state: 'failed', error: err.message,
+    }, null, 2)}\n`);
+    return 1;
+  }
   p.cancel(`Error: ${err.message}`);
   return 1;
 }
   return exitCode;
 }
 
+const UPDATE_DOCUMENT_SCHEMA_VERSION = 1;
+
+/** The single structured update record; `printPlan` renders the same source. */
+function updateDocument(r) {
+  return {
+    schemaVersion: UPDATE_DOCUMENT_SCHEMA_VERSION,
+    state: r.state,
+    status: r.status ?? null,
+    report: r.report,
+    ...(r.error ? { error: renderUpdateFailure(r) } : {}),
+  };
+}
+
 const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
 if (invokedPath === fileURLToPath(import.meta.url)) {
   process.exitCode = await runCli();
@@ -211,6 +238,10 @@ function printPlan(r) {
       lines.push(`${label}: ${r.availability[key].join(', ') || 'none'}`);
     }
   }
+  for (const action of r.requiredMigrations ?? []) {
+    lines.push(renderRequiredMigration(action));
+    lines.push(`  ${action.consequence} ${action.remediation}`);
+  }
   for (const owned of r.ownedDiffs ?? []) {
     lines.push(`${owned.state} ${owned.path}`);
     if (owned.binary) {