@ikon85/agent-workflow-kit 0.27.1 → 0.29.0

package/scripts/test_render_anchor.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Behavior tests for the pure Tier-2 anchor renderer."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPTS = Path(__file__).resolve().parent
+REPO = SCRIPTS.parent
+SKILLS = (
+    REPO / ".claude/skills/to-issues/SKILL.md",
+    REPO / ".agents/skills/to-issues/SKILL.md",
+)
+sys.path.insert(0, str(SCRIPTS))
+SPEC = importlib.util.spec_from_file_location(
+    "render_anchor", SCRIPTS / "render-anchor.py"
+)
+render_anchor = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(render_anchor)
+
+
+class RenderDocumentsGoldenTest(unittest.TestCase):
+    def test_filled_template_and_prd_render_both_documents(self):
+        template = "**Welle 12 — Safer publish.**\n\n## Slices\n| K1 |\n"
+        prd = (
+            "<!-- prd-source-id: safer-publish -->\n"
+            "<!-- prd-content-fp: abc123 -->\n"
+            "**plan_revision:** r4\n"
+            "<!-- prd: awaiting-decomposition -->\n\n"
+            "# Safer publish\n\nFull rationale.\n"
+        )
+
+        rendered = render_anchor.render_documents(template, prd)
+
+        self.assertEqual(rendered.anchor_body, template)
+        self.assertEqual(
+            rendered.archive_body,
+            "📄 Full PRD (archive, r4) — the body carries navigation/decisions only\n\n"
+            "# Safer publish\n\nFull rationale.\n",
+        )
+
+    def test_only_canonical_markers_in_the_head_block_are_stripped(self):
+        template = "Lean anchor\n"
+        prd = (
+            "<!-- wave-stub-source: safer-publish -->\n"
+            "<!-- prd-source-id: safer-publish -->\n"
+            "**plan_revision:** r5\n"
+            "<!-- prd: awaiting-decomposition -->\n\n"
+            "# PRD\n\n"
+            "```md\n**plan_revision:** fake\n"
+            "<!-- prd-source-id: quoted-example -->\n```\n\n"
+            "> **plan_revision:** quoted-fake\n"
+        )
+
+        rendered = render_anchor.render_documents(template, prd)
+
+        self.assertEqual(
+            rendered.archive_body,
+            "📄 Full PRD (archive, r5) — the body carries navigation/decisions only\n\n"
+            "<!-- wave-stub-source: safer-publish -->\n\n# PRD\n\n"
+            "```md\n**plan_revision:** fake\n"
+            "<!-- prd-source-id: quoted-example -->\n```\n\n"
+            "> **plan_revision:** quoted-fake\n",
+        )
+
+    def test_duplicate_plan_revisions_fail_closed(self):
+        for revisions in (("r5", "r5"), ("r5", "r6")):
+            with self.subTest(revisions=revisions):
+                prd = (
+                    f"**plan_revision:** {revisions[0]}\n"
+                    f"**plan_revision:** {revisions[1]}\n\n# PRD\n"
+                )
+                with self.assertRaisesRegex(
+                    ValueError, "exactly one canonical plan_revision"
+                ):
+                    render_anchor.render_documents("Lean anchor\n", prd)
+
+    def test_plan_revision_requires_numeric_canonical_value(self):
+        for lookalike in ("rfoo", "r5!"):
+            with self.subTest(lookalike=lookalike, valid_revision=True):
+                malformed = f"**plan_revision:** {lookalike}"
+                prd = f"{malformed}\n**plan_revision:** r5\n\n# PRD\n"
+                rendered = render_anchor.render_documents("Lean anchor\n", prd)
+                self.assertIn(malformed, rendered.archive_body)
+
+            with self.subTest(lookalike=lookalike, valid_revision=False):
+                with self.assertRaisesRegex(
+                    ValueError, "exactly one canonical plan_revision"
+                ):
+                    render_anchor.render_documents(
+                        "Lean anchor\n", f"**plan_revision:** {lookalike}\n# PRD\n"
+                    )
+
+    def test_malformed_marker_lookalikes_are_preserved(self):
+        lookalikes = (
+            "<!-- prd-source-id: alpha --> trailing -->",
+            "<!-- prd-content-fp: abc > trailing -->",
+            "<!-- prd: program > trailing -->",
+        )
+        for lookalike in lookalikes:
+            with self.subTest(lookalike=lookalike):
+                prd = (
+                    f"{lookalike}\n"
+                    "<!-- prd-source-id: canonical -->\n"
+                    "<!-- prd-content-fp: abc123 -->\n"
+                    "**plan_revision:** r5\n"
+                    "<!-- prd: awaiting-decomposition -->\n\n# PRD\n"
+                )
+
+                rendered = render_anchor.render_documents("Lean anchor\n", prd)
+
+                self.assertIn(lookalike, rendered.archive_body)
+                self.assertNotIn(
+                    "<!-- prd-source-id: canonical -->", rendered.archive_body
+                )
+                self.assertNotIn(
+                    "<!-- prd-content-fp: abc123 -->", rendered.archive_body
+                )
+                self.assertNotIn(
+                    "<!-- prd: awaiting-decomposition -->", rendered.archive_body
+                )
+
+    def test_cli_emits_each_document_without_mutating_inputs(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            template = root / "anchor.md"
+            prd = root / "prd.md"
+            template.write_text("Lean anchor\n", encoding="utf-8")
+            prd.write_text(
+                "**plan_revision:** r2\n\n# Full PRD\n", encoding="utf-8"
+            )
+            original = (template.read_bytes(), prd.read_bytes())
+
+            first = self._run_cli(template, prd, "archive")
+            second = self._run_cli(template, prd, "archive")
+            anchor = self._run_cli(template, prd, "anchor")
+
+            self.assertEqual(first.stdout, second.stdout)
+            self.assertEqual(anchor.stdout, b"Lean anchor\n")
+            self.assertEqual((template.read_bytes(), prd.read_bytes()), original)
+
+    def test_cli_archive_is_utf8_when_python_io_encoding_is_ascii(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            template = root / "anchor.md"
+            prd = root / "prd.md"
+            template.write_text("Lean anchor\n", encoding="utf-8")
+            prd.write_text("**plan_revision:** r2\n\n# PRD\n", encoding="utf-8")
+
+            result = self._run_cli(
+                template,
+                prd,
+                "archive",
+                env={**os.environ, "PYTHONIOENCODING": "ascii"},
+            )
+
+            self.assertTrue(result.stdout.startswith("📄".encode("utf-8")))
+
+    def _run_cli(
+        self, template: Path, prd: Path, document: str, env: dict | None = None
+    ):
+        return subprocess.run(
+            [
+                sys.executable,
+                str(SCRIPTS / "render-anchor.py"),
+                "--template",
+                str(template),
+                "--prd",
+                str(prd),
+                "--document",
+                document,
+            ],
+            check=True,
+            capture_output=True,
+            env=env,
+        )
+
+
+class PromotionStateTableTest(unittest.TestCase):
+    EXPECTED_ROWS = {
+        "initial": (
+            "`S=yes`, `B=no`, `C=0`, `P=absent`",
+            "render + write body",
+        ),
+        "body-written": (
+            "`S=n/a`, `B=yes`, `C=0`, `P=absent`",
+            "reconcile + write archive comment",
+        ),
+        "comment-written": (
+            "`S=n/a`, `B=yes`, `C=exact-1`, `P=absent`",
+            "promote board state",
+        ),
+        "promoted": (
+            "`S=n/a`, `B=yes`, `C=exact-1`, `P=complete`",
+            "no-op; continue publish audit",
+        ),
+    }
+    EXPECTED_BOARD_OBSERVATIONS = {
+        "ordinary-prestate": "absent",
+        "stufe-1p-prestate": "absent",
+        "promoted": "complete",
+        "cluster-only": "partial",
+        "wrong-wave": "partial",
+    }
+
+    def test_all_four_observable_states_have_one_resume_action(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            start = text.index("<!-- promotion-state-table:start -->")
+            end = text.index("<!-- promotion-state-table:end -->", start)
+            rows = {}
+            for line in text[start:end].splitlines():
+                if line.startswith("| `"):
+                    cells = [cell.strip() for cell in line.strip("|").split("|")]
+                    rows[cells[0].strip("`")] = (cells[1], cells[2])
+            self.assertEqual(rows, self.EXPECTED_ROWS, str(path))
+
+    def test_corrupt_comments_and_partial_board_writes_are_drift(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            self.assertIn("`C=wrong-1`", text, str(path))
+            self.assertIn("`C=duplicates(<ids>)`", text, str(path))
+            self.assertIn("`P=partial`", text, str(path))
+            self.assertIn("drift and enters repair", text, str(path))
+
+    def test_stufe_1p_prestamp_is_not_partial_promotion(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            start = text.index("<!-- promotion-board-observation-table:start -->")
+            end = text.index("<!-- promotion-board-observation-table:end -->", start)
+            rows = {}
+            for line in text[start:end].splitlines():
+                if line.startswith("| `"):
+                    cells = [cell.strip() for cell in line.strip("|").split("|")]
+                    rows[cells[0].strip("`")] = cells[2].strip("`")
+            self.assertEqual(rows, self.EXPECTED_BOARD_OBSERVATIONS, str(path))
+
+    def test_post_initial_body_drift_requires_an_operator_decision(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            self.assertIn("outside the valid `initial` tuple", text, str(path))
+            self.assertIn("report the body diff", text, str(path))
+            self.assertRegex(text, r"explicit\s+operator decision", str(path))
+            self.assertNotIn(
+                "wrong/missing `B` → rerender and rewrite the body", text, str(path)
+            )
+
+    def test_stale_source_snapshot_stops_before_body_write(self):
+        for path in SKILLS:
+            text = path.read_text(encoding="utf-8")
+            self.assertRegex(text, r"Pre:\s+`S=yes`, `B=no`", str(path))
+            self.assertRegex(text, r"Post:\s+`S=n/a`, `B=yes`", str(path))
+            self.assertIn("`S=no`", text, str(path))
+            self.assertIn("re-fetch the remote body", text, str(path))
+            self.assertRegex(text, r"never\s+write the\s+stale render", str(path))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_retro_wrapup_contract.py

@@ -0,0 +1,117 @@
+"""Contract tests for retro enforcement and safe wrapup workflow chaining."""
+
+from pathlib import Path
+import re
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (".claude", ".agents")
+
+
+def skill(surface: str, name: str) -> str:
+    return (ROOT / surface / "skills" / name / "SKILL.md").read_text(
+        encoding="utf-8"
+    )
+
+
+def contract_text(surface: str, name: str) -> str:
+    """Return prose with Markdown emphasis removed for wording assertions."""
+    return re.sub(r"\s+", " ", skill(surface, name).replace("**", ""))
+
+
+class RetroEnforcementContract(unittest.TestCase):
+    def test_mechanical_check_precedes_target_and_weight_ladder(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "retro")
+                mechanical = text.index("### 3a. Mechanical enforcement check")
+                ladder = text.index("### 3b. Determine target + weight")
+                self.assertLess(mechanical, ladder)
+
+    def test_machine_checkable_findings_cannot_stop_at_prose(self):
+        required = (
+            "Could a machine decide this",
+            "implement the enforcement",
+            "tracked enforcement issue",
+            "explicit trade-off",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "retro")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+    def test_upstream_or_own_and_exact_sanitized_approval_survive(self):
+        required = (
+            "generic or project-specific",
+            "recommend `own`",
+            "sanitized preview",
+            "explicitly approves that exact text",
+            "does not need to be the kit maintainer",
+            "docs/agents/skills/<skill>.md",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "retro")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+
+class WrapupChainingContract(unittest.TestCase):
+    def test_retro_is_model_invocable_on_both_surfaces(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                frontmatter = skill(surface, "retro").split("---", 2)[1]
+                self.assertIn("disable-model-invocation: false", frontmatter)
+
+    def test_affirmative_retro_gate_chains_without_landing(self):
+        required = (
+            "invoke the `retro` skill immediately in this run",
+            "land nothing in this run",
+            "fresh explicit `/wrapup` invocation",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "wrapup")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+    def test_wrapup_does_not_forbid_its_affirmative_retro_chain(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "wrapup")
+                self.assertNotIn("never run by this skill", text.lower())
+
+    def test_only_model_invocable_non_deploying_workflows_chain(self):
+        required = (
+            "model-invocable",
+            "non-deploying",
+            "return control to the user",
+            "state the reason",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "wrapup")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+    def test_wrapup_remains_manual_and_program_propagation_remains_present(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = skill(surface, "wrapup")
+                self.assertIn("disable-model-invocation: true", text)
+                self.assertIn("user's `/wrapup` input IS the explicit", text)
+                self.assertIn("program-sync", text)
+                self.assertIn("Phasen-Gates", text)
+
+    def test_new_contract_is_reference_free(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                combined = skill(surface, "retro") + skill(surface, "wrapup")
+                self.assertNotIn("testreporter", combined.lower())
+                self.assertIsNone(re.search(r"#[0-9]{3,}", combined))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_skill_codex_exec_lifecycle.py

@@ -0,0 +1,123 @@
+"""Guard the Claude-only cross-model skills' thin codex-exec lifecycle."""
+
+import json
+import re
+import subprocess
+import unittest
+from pathlib import Path
+
+
+REPO = Path(__file__).resolve().parents[1]
+MANIFEST = REPO / ".claude/skills/skill-manifest.json"
+TARGETS = {
+    "codex-review": ("review", "read-only"),
+    "codex-build": ("build", "workspace-write"),
+    "grill-me-codex": ("review", "read-only"),
+    "grill-with-docs-codex": ("review", "read-only"),
+}
+
+
+class CodexExecSkillLifecycleTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        manifest = json.loads(MANIFEST.read_text(encoding="utf-8"))["skills"]
+        cls.skills = {}
+        for name, expected in TARGETS.items():
+            entry = manifest[name]
+            if entry["surfaces"] != ["claude"]:
+                raise AssertionError(f"{name} must remain Claude-only")
+            path = REPO / ".claude/skills" / name / "SKILL.md"
+            cls.skills[name] = (expected, path.read_text(encoding="utf-8"))
+
+    def test_all_four_skills_use_the_thin_wrapper_lifecycle(self):
+        self.assertEqual(len(self.skills), 4)
+        for name, ((profile, mode), body) in self.skills.items():
+            with self.subTest(skill=name):
+                self.assertIn(
+                    f"scripts/codex-exec.sh new --profile {profile} --mode {mode}",
+                    body,
+                )
+                self.assertRegex(body, r"scripts/codex-exec\.sh resume [\"']?\$RUN_ID")
+                self.assertRegex(body, r"scripts/codex-exec\.sh finalize [\"']?\$RUN_ID")
+                self.assertEqual(body.count("scripts/codex-exec.sh handle-failure"), 2)
+                self.assertNotRegex(
+                    body,
+                    r"scripts/codex-exec\.sh resume[^\n]*--mode",
+                    "resume must inherit the persisted mode",
+                )
+
+    def test_new_and_resume_are_thin_ordered_and_valid_bash(self):
+        for name, (_, body) in self.skills.items():
+            blocks = re.findall(
+                r"```bash\n(if ROUND_RESULT=\$\(scripts/codex-exec\.sh (?:new|resume).*?\nfi)\n```",
+                body,
+                re.DOTALL,
+            )
+            self.assertEqual(len(blocks), 2, name)
+            for block in blocks:
+                first_line = block.splitlines()[0]
+                is_resume = "scripts/codex-exec.sh resume " in first_line
+                success, failure = block.split("\nelse\n", 1)
+                self.assertIn("CODEX_REPORT=", success)
+                self.assertNotIn("CODEX_REPORT=", failure)
+                self.assertIn("scripts/codex-exec.sh handle-failure", failure)
+                self.assertIn("|| :", failure)
+                self.assertNotIn("json.load", failure)
+                handler = failure.index("handle-failure")
+                surfaced = failure.index('printf \'%s\\n\' "$FAILURE_RESULT" >&2')
+                stopped = failure.index("exit 1")
+                self.assertLess(handler, surfaced)
+                self.assertLess(surfaced, stopped)
+                if is_resume:
+                    self.assertIn('--run-id "$RUN_ID"', failure)
+                    self.assertNotIn("\n  RUN_ID=", success)
+                else:
+                    self.assertNotIn("--run-id", failure)
+                    self.assertLess(success.index("RUN_ID="), success.index("CODEX_REPORT="))
+                parsed = subprocess.run(
+                    ["bash", "-n"],
+                    input=block,
+                    text=True,
+                    capture_output=True,
+                    check=False,
+                )
+                self.assertEqual(parsed.returncode, 0, parsed.stderr)
+
+    def test_all_skills_abort_known_run_on_orchestration_cancellation(self):
+        for name, (_, body) in self.skills.items():
+            with self.subTest(skill=name):
+                cancellation = re.search(
+                    r"[Cc]ancellation or a decision to stop (?:orchestration|delegation)"
+                    r".*?scripts/codex-exec\.sh abort \"\$RUN_ID\"",
+                    body,
+                    re.DOTALL,
+                )
+                self.assertIsNotNone(cancellation)
+                self.assertRegex(body, r"scripts/codex-exec\.sh finalize [\"']?\$RUN_ID")
+
+        build = self.skills["codex-build"][1]
+        gate = build.split("## Step 5 — Human gate", 1)[1].split("## Hard rules", 1)[0]
+        self.assertLess(
+            gate.index("Rejected with another requested fix"),
+            gate.index("Cancellation or a decision to stop delegation"),
+        )
+
+    def test_no_skill_reimplements_codex_process_or_failure_mechanics(self):
+        forbidden = {
+            "copied round function": re.compile(r"\brun_codex_round\b"),
+            "copied status parser": re.compile(r"\bROUND_STATUS\b|\.get\(\"status\""),
+            "copied run-id cleanup": re.compile(r"\bFAILED_RUN_ID\b"),
+            "raw codex exec": re.compile(r"(?m)^\s*codex\s+exec\b"),
+            "manual liveness sleep": re.compile(r"\bsleep\s+90\b"),
+            "manual sandbox override": re.compile(r"\bsandbox_mode\s*="),
+            "manual process probe": re.compile(r"\bkill\s+-0\b"),
+            "manual codex pid": re.compile(r"\bCODEX_PID\b"),
+        }
+        for name, (_, body) in self.skills.items():
+            for label, pattern in forbidden.items():
+                with self.subTest(skill=name, forbidden=label):
+                    self.assertIsNone(pattern.search(body))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_tdd_contract.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Contract tests for existing-test-first TDD without weakening RED-first."""
+
+from pathlib import Path
+import re
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (
+    ROOT / ".claude" / "skills" / "tdd" / "SKILL.md",
+    ROOT / ".agents" / "skills" / "tdd" / "SKILL.md",
+)
+DECISIONS = ("REUSE", "EXTEND", "REPLACE", "NEW", "RETIRE", "NO-NEW-TEST")
+
+
+class TddContractTest(unittest.TestCase):
+    def texts(self):
+        return {path: path.read_text(encoding="utf-8") for path in SURFACES}
+
+    def test_each_behavior_gets_exactly_one_existing_test_first_decision(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn("### 2. Existing-Test-First Decision", text)
+                self.assertIn("For each planned behavior, record exactly one", text)
+                for decision in DECISIONS:
+                    self.assertEqual(
+                        len(re.findall(rf"^- \*\*{re.escape(decision)}\*\*", text, re.MULTILINE)),
+                        1,
+                        f"{decision} must have exactly one canonical definition",
+                    )
+
+    def test_new_files_require_rejecting_the_nearest_owner_with_a_reason(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn("nearest existing owner", text)
+                self.assertIn("rejected with a reason", text)
+
+    def test_red_first_is_unconditional_for_executable_behavior_and_bug_fixes(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn(
+                    "Every executable new behavior and bug fix must begin with a failing assertion",
+                    text,
+                )
+                self.assertIn("REUSE and NO-NEW-TEST never bypass this RED-first invariant", text)
+                self.assertRegex(
+                    text,
+                    r"an already-green\s+assertion does not prove the requested change",
+                )
+
+    def test_retirement_keeps_negative_tests_only_for_durable_absence(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn("delete the tests that specified the retired behavior", text)
+                self.assertIn("only when absence itself is a durable", text)
+
+    def test_worked_matrix_and_counted_handoff_cover_all_decisions(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                matrix = re.search(
+                    r"### Worked decision matrix\n(?P<body>.*?)(?=\n### |\n## )",
+                    text,
+                    re.DOTALL,
+                )
+                self.assertIsNotNone(matrix)
+                body = matrix.group("body")
+                for decision in DECISIONS:
+                    self.assertRegex(body, rf"\|\s*{re.escape(decision)}\s*\|")
+                self.assertIn("list every behavior and its one decision", text)
+                self.assertIn(
+                    "Reused X · Extended Y · New Z · Replaced/retired W",
+                    text,
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/cli.mjs

@@ -6,6 +6,8 @@ import { init } from './commands/init.mjs';
 import { update } from './commands/update.mjs';
 import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
+import { setOwnership } from './commands/own.mjs';
+import { CONSUMER_ORIGIN, KIT_ORIGIN } from './lib/manifest.mjs';
 import { createCommandAdapter } from '../scripts/release-state.mjs';
 import { installedIdentityFromDir } from '../scripts/release-parity.mjs';
 
@@ -21,6 +23,7 @@ const args = process.argv.slice(2);
 const cmd = args[0];
 const force = args.includes('--force');
 const yes = args.includes('--yes') || args.includes('-y');
+const owned = args.includes('--owned');
 
 p.intro('agent-workflow-kit');
 
@@ -35,15 +38,11 @@ try {
     p.outro('Next: run /setup-workflow to fill the project layer + board profile. ' +
       'To enable the drift-guard hook, add .claude/hooks/drift-guard.py to your settings.json hooks.');
   } else if (cmd === 'diff') {
-    const r = await diff({ kitRoot: KIT_ROOT, consumerRoot });
+    const r = await diff({ kitRoot: KIT_ROOT, consumerRoot, owned });
     printPlan(r);
     p.outro('Dry run — nothing written. Run `update` to apply.');
   } else if (cmd === 'update') {
-    const decide = async (_action, path) => {
-      if (yes) return true;
-      const ok = await p.confirm({ message: `Upstream removed ${path} — delete it locally?` });
-      return ok === true;
-    };
+    const decide = (action, path) => decideUpdate(action, path, yes);
     const releaseIdentities = await readUpdateRelease();
     const r = await update({
       kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide, releaseIdentities,
@@ -65,8 +64,13 @@ try {
     if (!ok) { p.cancel('Aborted.'); process.exit(0); }
     const r = await uninstall({ consumerRoot });
     p.outro(`removed ${r.removed.length} · retained (edited/referenced) ${r.retained.length}`);
+  } else if (cmd === 'own' || cmd === 'disown') {
+    if (!args[1]) throw new Error(`Usage: agent-workflow-kit ${cmd} <path>`);
+    const origin = cmd === 'own' ? CONSUMER_ORIGIN : KIT_ORIGIN;
+    await setOwnership({ consumerRoot, path: args[1], origin });
+    p.outro(`${args[1]} is now ${origin}-owned`);
   } else {
-    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall> [--force] [--yes]');
+    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall|own|disown> [<path>] [--force] [--yes] [--owned]');
     p.outro('');
   }
 } catch (err) {
@@ -76,12 +80,44 @@ try {
 
 function printPlan(r) {
   const lines = [];
-  for (const k of ['added', 'updated', 'userModified', 'unchanged', 'deleted', 'keptDeleted'])
+  for (const k of [
+    'added', 'updated', 'userModified', 'consumerOwned', 'unchanged',
+    'deleted', 'keptDeleted', 'collisions',
+  ])
     if (r[k]?.length) lines.push(`${k}: ${r[k].length}`);
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
+  for (const owned of r.ownedDiffs ?? []) {
+    lines.push(`${owned.state} ${owned.path}`);
+    if (owned.binary) {
+      lines.push(`  local: ${owned.local.size} bytes sha256:${owned.local.sha256}`);
+      lines.push(`  upstream: ${owned.upstream.size} bytes sha256:${owned.upstream.sha256}`);
+    } else if (owned.diff) {
+      lines.push(owned.diff);
+    }
+  }
   p.note(lines.join('\n') || 'no changes', 'plan');
 }
 
+async function decideUpdate(action, path, yes) {
+  if (action === 'delete') {
+    if (yes) return true;
+    return (await p.confirm({ message: `Upstream removed ${path} — delete it locally?` })) === true;
+  }
+  if (action === 'collision') {
+    if (yes) return 'replace';
+    const choice = await p.select({
+      message: `${path} already exists but is not tracked. Choose its ownership:`,
+      options: [
+        { value: 'keep-as-owned', label: 'Keep existing file as consumer-owned' },
+        { value: 'replace', label: 'Replace with kit file' },
+      ],
+    });
+    if (p.isCancel(choice)) throw new Error(`collision decision cancelled for ${path}`);
+    return choice;
+  }
+  throw new Error(`unknown update decision action: ${action}`);
+}
+
 async function readUpdateRelease() {
   const adapter = await createCommandAdapter({
     repoRoot: KIT_ROOT,