@ikon85/agent-workflow-kit 0.38.0 → 0.40.0

package/scripts/worktree-lifecycle/ignore_seed.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Offer the planning-artifact ignore rules for a consumer `.gitignore`.
+
+The shipped skills write `PLAN.md`, `PLAN-REVIEW-LOG.md`, and `ANNAHMEN.md`
+into a session worktree, but `.gitignore` is a consumer file the kit does not
+own: `init` and `update` never touch it. This helper is the one place that
+closes that gap, and it closes it only when a user explicitly approves the
+offer inside `/setup-workflow` (ADR 0008).
+
+Contract:
+
+- `preview` reads and reports; it never writes.
+- `apply` appends one marker block and nothing else. It never rewrites,
+  reorders, or removes an existing line, so a second run is a byte-identical
+  no-op once the rules are in place.
+- Rules a consumer already has — by any pattern, including a wildcard — are
+  reported as covered and never duplicated.
+- A marker block that the consumer has since edited is theirs: the helper
+  blocks instead of repairing it.
+- Nothing here runs during `init`/`update` reconciliation.
+
+Usage:
+  python3 scripts/worktree-lifecycle/ignore_seed.py preview [--repo PATH] [--json]
+  python3 scripts/worktree-lifecycle/ignore_seed.py apply   [--repo PATH] [--json]
+
+Exit codes: 0 previewed/appended/nothing-to-do · 2 blocked · 1 error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+MANIFEST = Path(__file__).resolve().parent / "plan-artifacts.json"
+
+BLOCK_START = "# >>> agent-workflow-kit: planning-artifacts/v1 >>>"
+BLOCK_END = "# <<< agent-workflow-kit: planning-artifacts/v1 <<<"
+BLOCK_NOTE = (
+    "# Planning artifacts the agent workflow skills write into a session\n"
+    "# worktree. They are session scratch, never part of the change. Added by\n"
+    "# setup-workflow on request; this block is yours to edit or delete.\n"
+)
+
+
+class IgnoreSeedError(RuntimeError):
+    """A safe, user-visible refusal."""
+
+
+@dataclass(frozen=True)
+class IgnorePlan:
+    """What an approval would append — and nothing more."""
+
+    repo: Path
+    gitignore_exists: bool
+    already_ignored: tuple[str, ...]
+    pending: tuple[str, ...]
+    tracked: tuple[str, ...]
+    block: str | None
+    status: str
+    detail: str
+
+    def as_dict(self) -> dict:
+        return {
+            "status": self.status,
+            "detail": self.detail,
+            "gitignoreExists": self.gitignore_exists,
+            "alreadyIgnored": list(self.already_ignored),
+            "pending": list(self.pending),
+            "tracked": list(self.tracked),
+            "block": self.block,
+        }
+
+
+def load_artifacts(manifest: Path = MANIFEST) -> tuple[str, ...]:
+    """Return the kit-declared planning artifacts, in declaration order."""
+    try:
+        document = json.loads(manifest.read_text(encoding="utf-8"))
+        return tuple(entry["path"] for entry in document["artifacts"])
+    except (OSError, json.JSONDecodeError, KeyError, TypeError) as error:
+        raise IgnoreSeedError(f"cannot read planning-artifact manifest: {error}") from error
+
+
+def _git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            ["git", *args], cwd=repo, capture_output=True, text=True,
+        )
+    except OSError as error:  # pragma: no cover - git absent
+        raise IgnoreSeedError(f"cannot run git: {error}") from error
+
+
+def is_ignored(repo: Path, path: str) -> bool:
+    """True when any ignore rule already matches `path`.
+
+    `--no-index` asks the pattern question, not the index question, so an
+    artifact that a consumer once committed still reports its real rule state.
+    """
+    return _git(repo, "check-ignore", "-q", "--no-index", "--", path).returncode == 0
+
+
+def is_tracked(repo: Path, path: str) -> bool:
+    """True when the artifact is committed — an ignore rule cannot untrack it."""
+    result = _git(repo, "ls-files", "--error-unmatch", "--", path)
+    return result.returncode == 0
+
+
+def render_block(paths: tuple[str, ...]) -> str:
+    """The exact text an approval appends."""
+    listed = "".join(f"{path}\n" for path in paths)
+    return f"{BLOCK_START}\n{BLOCK_NOTE}{listed}{BLOCK_END}\n"
+
+
+def _read_gitignore(repo: Path) -> tuple[bool, str]:
+    target = repo / ".gitignore"
+    try:
+        return True, target.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return False, ""
+    except OSError as error:
+        raise IgnoreSeedError(f"cannot read {target}: {error}") from error
+
+
+def plan(repo: Path, manifest: Path = MANIFEST) -> IgnorePlan:
+    """Report what an approval would change. Reads only."""
+    repo = Path(repo)
+    if not (repo / ".git").exists():
+        raise IgnoreSeedError(f"not a git repository: {repo}")
+    artifacts = load_artifacts(manifest)
+    exists, text = _read_gitignore(repo)
+    covered = tuple(path for path in artifacts if is_ignored(repo, path))
+    pending = tuple(path for path in artifacts if path not in covered)
+    tracked = tuple(path for path in artifacts if is_tracked(repo, path))
+    has_block = BLOCK_START in text
+
+    if not pending:
+        return IgnorePlan(
+            repo=repo, gitignore_exists=exists, already_ignored=covered,
+            pending=(), tracked=tracked, block=None, status="nothing-to-do",
+            detail="every planning artifact is already ignored",
+        )
+    if has_block:
+        return IgnorePlan(
+            repo=repo, gitignore_exists=exists, already_ignored=covered,
+            pending=pending, tracked=tracked, block=None, status="blocked",
+            detail=(
+                "the marker block exists but no longer covers "
+                f"{', '.join(pending)} — that block is consumer-owned; "
+                "edit .gitignore yourself"
+            ),
+        )
+    return IgnorePlan(
+        repo=repo, gitignore_exists=exists, already_ignored=covered,
+        pending=pending, tracked=tracked, block=render_block(pending),
+        status="append",
+        detail=f"would append {len(pending)} rule(s) in one marker block",
+    )
+
+
+def apply(repo: Path, manifest: Path = MANIFEST) -> IgnorePlan:
+    """Append the previewed block. Never rewrites an existing line."""
+    decision = plan(repo, manifest)
+    if decision.status != "append":
+        return decision
+    target = Path(repo) / ".gitignore"
+    _, text = _read_gitignore(Path(repo))
+    prefix = text
+    if prefix and not prefix.endswith("\n"):
+        prefix += "\n"
+    if prefix and not prefix.endswith("\n\n"):
+        prefix += "\n"
+    try:
+        target.write_text(prefix + decision.block, encoding="utf-8")
+    except OSError as error:
+        raise IgnoreSeedError(f"cannot write {target}: {error}") from error
+    return IgnorePlan(
+        repo=decision.repo, gitignore_exists=True,
+        already_ignored=decision.already_ignored, pending=decision.pending,
+        tracked=decision.tracked, block=decision.block, status="appended",
+        detail=f"appended {len(decision.pending)} rule(s) to .gitignore",
+    )
+
+
+def _report(decision: IgnorePlan, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(decision.as_dict(), indent=2))
+        return
+    print(f"{decision.status} — {decision.detail}")
+    if decision.already_ignored:
+        print(f"  already ignored: {', '.join(decision.already_ignored)}")
+    if decision.tracked:
+        print(
+            "  tracked in git (an ignore rule cannot untrack these): "
+            f"{', '.join(decision.tracked)}"
+        )
+    if decision.block:
+        label = "appended" if decision.status == "appended" else "would append"
+        print(f"  {label}:")
+        for line in decision.block.rstrip("\n").split("\n"):
+            print(f"    {line}")
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="ignore_seed.py")
+    parser.add_argument("command", choices=("preview", "apply"))
+    parser.add_argument("--repo", default=".")
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    try:
+        decision = plan(args.repo) if args.command == "preview" else apply(args.repo)
+    except IgnoreSeedError as error:
+        print(str(error), file=sys.stderr)
+        return 1
+    _report(decision, as_json=args.json)
+    return 2 if decision.status == "blocked" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/worktree-lifecycle/plan-artifacts.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "artifacts": [
+    {
+      "path": "PLAN.md",
+      "writtenBy": [
+        "grill-me",
+        "grill-with-docs",
+        "codex-review",
+        "grill-me-codex",
+        "grill-with-docs-codex",
+        "codex-build",
+        "orchestrate-wave"
+      ],
+      "why": "the locked plan a planning session hands to the implementing session"
+    },
+    {
+      "path": "PLAN-REVIEW-LOG.md",
+      "writtenBy": [
+        "codex-review",
+        "grill-me-codex",
+        "grill-with-docs-codex",
+        "codex-build"
+      ],
+      "why": "the append-only cross-model review transcript of that plan"
+    },
+    {
+      "path": "ANNAHMEN.md",
+      "writtenBy": [
+        "tdd",
+        "orchestrate-wave",
+        "wrapup"
+      ],
+      "why": "the build-time assumption-drift log wrapup propagates before teardown"
+    }
+  ]
+}

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)
@@ -461,9 +469,8 @@ def load_candidate_landing_profile(core, wt: str):
     return candidate
 
 
-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)
+def load_merged_canonical_profile(core, main_tree: str):
+    """Read the merged canonical cleanup policy from origin/main."""
     result = core.run(
         [
             "git", "show",
@@ -482,6 +489,13 @@ def load_canonical_landing_profile(core, wt: str, main_tree: str):
         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
@@ -489,11 +503,9 @@ def load_canonical_landing_profile(core, wt: str, main_tree: str):
     ):
         raise core.LifecycleError(
             "worktree cleanup policy differs from merged canonical origin/main"
+            f"; {CANONICAL_DRIFT_RECOVERY_HINT}"
         )
-    attempt_path = core.artifact_baseline_path(Path(wt)).with_name(
-        core.LANDING_ATTEMPT_FILE
-    )
-    if not os.path.lexists(attempt_path):
+    if not core.landing_attempt_exists(core.landing_attempt_path(Path(wt))):
         raise core.LifecycleError(
             "landing attempt is missing before canonical cleanup authorization"
         )
@@ -504,17 +516,22 @@ def load_canonical_landing_profile(core, wt: str, main_tree: str):
     ):
         raise core.LifecycleError(
             "landing attempt cleanup policy differs from merged canonical origin/main"
+            f"; {CANONICAL_DRIFT_RECOVERY_HINT}"
         )
     return canonical
 
 
-def landing_artifact_baseline_digest(wt: str, main_tree: str) -> str:
-    core = load_worktree_cleanup_core()
-    try:
-        load_candidate_landing_profile(core, wt)
-        return core.load_artifact_baseline(Path(wt)).digest
-    except core.LifecycleError as error:
-        raise Stop("cleanup", f"shared cleanup guard failed: {error}") from error
+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:
@@ -522,6 +539,10 @@ def landing_start_artifact_inventory(wt: str, main_tree: str) -> dict:
     try:
         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
 
@@ -581,6 +602,16 @@ def abandon_unfinished_landing_attempt(wt: str, main_tree: str) -> str:
         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,
@@ -605,10 +636,13 @@ def ensure_worktree_removable(
     *,
     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 = load_canonical_landing_profile(core, wt, main_tree)
+        profile = loader(core, wt, main_tree)
         kwargs = {"merge_target": "origin/main"}
         paths = (
             tuple(item["path"] for item in verified_scratch_evidence)
@@ -639,11 +673,13 @@ def remove_verified_worktree_scratch(
     *,
     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 = load_canonical_landing_profile(core, wt, main_tree)
+        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(
@@ -920,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()
@@ -931,13 +1066,13 @@ 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] = []
-    artifact_baseline_digest: str | None = None
-    landing_start_files: tuple[str, ...] = ()
     landing_attempt: dict | None = None
     generated_evidence: tuple[dict, ...] = ()
     if wt_exists:
@@ -959,16 +1094,18 @@ def cmd_land(args) -> dict:
             raise Stop(
                 "cleanup",
                 "unfinished landing generator attempt has no frozen output evidence; "
-                "classify its files, then rerun with --abandon-unfinished-attempt",
+                f"classify its files, then rerun with {ABANDON_ATTEMPT_FLAG}",
             )
-        landing_start_files = tuple(landing_attempt["generatedFiles"])
-        if landing_start_files:
+        # 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_start_files),
+                + ", ".join(landing_attempt["generatedFiles"]),
             )
-        artifact_baseline_digest = landing_attempt["baselineDigest"]
         annahmen = Path(wt) / "ANNAHMEN.md"
         if annahmen.is_file():
             markers, malformed = parse_annahmen(annahmen.read_text(), default_section)
@@ -1077,18 +1214,16 @@ def cmd_land(args) -> dict:
             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)
-        if cleanup is not None:
-            cleanup = remove_verified_worktree_scratch(
-                wt,
-                main_tree,
-                cleanup,
-                verified_scratch_evidence=generated_evidence,
-            )
+        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; "
@@ -1216,14 +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")
-    l.add_argument(
-        "--abandon-unfinished-attempt",
+    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) {