@ikon85/agent-workflow-kit 0.38.0 → 0.40.0

package/scripts/test_drift_guard_diagnostics.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""Diagnostics contract for the handoff drift guard.
+
+Three independent gaps, one guard:
+
+  * the issue anchor may only come from the handoff repository's OWN issues —
+    a link to a foreign repository's issue must never become the anchor;
+  * a census block must name the checkout it evaluated, and say so explicitly
+    when the session sits in a different worktree of the same repository;
+  * `--census-status` must report WHAT drifted, bounded, not only that the
+    topology fingerprint moved.
+"""
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parents[1]
+HOOKS = ROOT / ".claude" / "hooks"
+sys.path.insert(0, str(HOOKS))
+SPEC = importlib.util.spec_from_file_location("drift_guard", HOOKS / "drift-guard.py")
+DRIFT_GUARD = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(DRIFT_GUARD)
+
+GIT_IDENTITY = [
+    "-c", "user.name=drift-guard-test",
+    "-c", "user.email=drift-guard@example.invalid",
+    "-c", "commit.gpgsign=false",
+]
+
+
+class DriftGuardDiagnosticsTest(unittest.TestCase):
+    def make_repo(self, remote=None):
+        temporary = tempfile.TemporaryDirectory(prefix="awk-drift-guard-")
+        root = Path(temporary.name)
+        self.addCleanup(temporary.cleanup)
+        (root / "src").mkdir()
+        (root / "package.json").write_text('{"name":"consumer"}\n', encoding="utf-8")
+        (root / "src" / "index.mjs").write_text("export const ready = true;\n", encoding="utf-8")
+        subprocess.run(["git", "init", "--quiet"], cwd=root, check=True)
+        subprocess.run(["git", "add", "."], cwd=root, check=True)
+        if remote:
+            subprocess.run(["git", "remote", "add", "origin", remote], cwd=root, check=True)
+        return root
+
+    def enable(self, root):
+        census = root / ".census"
+        census.mkdir(exist_ok=True)
+        (census / "profile.json").write_text(json.dumps({
+            "schemaVersion": 1,
+            "enabled": True,
+            "decisions": [],
+            "localScanners": [],
+            "overrides": [],
+        }) + "\n", encoding="utf-8")
+
+    def activate_current(self, root):
+        fresh = DRIFT_GUARD.scan_census_status(root)["fresh"]
+        (root / ".census" / "active.json").write_text(
+            json.dumps(fresh) + "\n", encoding="utf-8"
+        )
+
+    def write_payload(self, root, name, content):
+        handoff = root / ".handoff"
+        handoff.mkdir(exist_ok=True)
+        return {
+            "tool_name": "Write",
+            "tool_input": {"file_path": str(handoff / name), "content": content},
+        }
+
+    def census_status(self, root, *extra):
+        completed = subprocess.run(
+            [sys.executable, str(HOOKS / "drift-guard.py"), "--census-status", *extra],
+            cwd=root, capture_output=True, check=True, text=True,
+        )
+        return json.loads(completed.stdout)
+
+    # --- anchor extraction ------------------------------------------------
+
+    def test_foreign_repository_issue_link_never_becomes_the_anchor(self):
+        root = self.make_repo(remote="git@github.com:acme/consumer.git")
+        content = (
+            "Refresh landed as chore PR "
+            "[#2281](https://github.com/acme/consumer/pull/2281).\n"
+            "Reported upstream: "
+            "[kit#276](https://github.com/iKon85/agent-workflow-kit/issues/276)\n"
+        )
+
+        issue = DRIFT_GUARD.extract_issue(
+            self.write_payload(root, "2026-07-26-2279.md", content), content, root
+        )
+
+        self.assertEqual(issue, 2279)
+
+    def test_own_repository_content_anchor_still_wins_over_the_filename(self):
+        for remote in (
+            "git@github.com:acme/consumer.git",
+            "https://github.com/acme/consumer.git",
+            "ssh://git@github.com/acme/consumer",
+        ):
+            with self.subTest(remote=remote):
+                root = self.make_repo(remote=remote)
+                content = (
+                    "Anchor [#2280](https://github.com/acme/consumer/issues/2280) — "
+                    "upstream [#276](https://github.com/iKon85/agent-workflow-kit/issues/276)\n"
+                )
+
+                issue = DRIFT_GUARD.extract_issue(
+                    self.write_payload(root, "2026-07-26-2279.md", content), content, root
+                )
+
+                self.assertEqual(issue, 2280)
+
+    def test_without_a_parsable_remote_the_filename_anchor_is_preferred(self):
+        root = self.make_repo()
+        content = "Upstream [#276](https://github.com/iKon85/agent-workflow-kit/issues/276)\n"
+
+        issue = DRIFT_GUARD.extract_issue(
+            self.write_payload(root, "2026-07-26-2279.md", content), content, root
+        )
+
+        self.assertEqual(issue, 2279)
+
+    def test_without_remote_and_without_filename_anchor_the_content_anchor_remains(self):
+        root = self.make_repo()
+        content = "Anchor [#276](https://github.com/iKon85/agent-workflow-kit/issues/276)\n"
+
+        issue = DRIFT_GUARD.extract_issue(
+            self.write_payload(root, "session-notes.md", content), content, root
+        )
+
+        self.assertEqual(issue, 276)
+
+    def test_a_foreign_only_handoff_without_a_filename_anchor_fails_open(self):
+        root = self.make_repo(remote="git@github.com:acme/consumer.git")
+        content = "Upstream [#276](https://github.com/iKon85/agent-workflow-kit/issues/276)\n"
+        payload = self.write_payload(root, "session-notes.md", content)
+
+        self.assertIsNone(DRIFT_GUARD.extract_issue(payload, content, root))
+        with patch.object(DRIFT_GUARD, "run_check") as check:
+            self.assertEqual(DRIFT_GUARD.should_block(payload), (False, ""))
+        check.assert_not_called()
+
+    def test_block_message_names_the_own_anchor_not_the_foreign_issue(self):
+        root = self.make_repo(remote="git@github.com:acme/consumer.git")
+        content = (
+            "Refresh landed as chore PR "
+            "[#2281](https://github.com/acme/consumer/pull/2281).\n"
+            "Reported upstream: "
+            "[kit#276](https://github.com/iKon85/agent-workflow-kit/issues/276)\n"
+        )
+        payload = self.write_payload(root, "2026-07-26-2279.md", content)
+        checked = []
+
+        def check(issue, intent):
+            checked.append(issue)
+            return {"deny_recommended": True, "violations": [f"#{issue}: plan_revision missing"]}
+
+        with patch.object(DRIFT_GUARD, "run_check", side_effect=check):
+            blocked, message = DRIFT_GUARD.should_block(payload)
+
+        self.assertEqual(checked, [2279])
+        self.assertTrue(blocked)
+        self.assertIn("#2279", message)
+        self.assertNotIn("276", message)
+
+    # --- evaluated checkout -----------------------------------------------
+
+    def test_census_block_message_names_the_evaluated_checkout(self):
+        root = self.make_repo()
+        result = {"state": "refresh_required", "reasons": ["topology"], "overrides": []}
+
+        message = DRIFT_GUARD.build_census_block_message(2279, result, root, root)
+
+        self.assertIn(str(root), message)
+        self.assertIn("evaluated checkout", message)
+        self.assertIn("worktree", message)
+        self.assertIn("$census-update", message)
+
+    def test_a_sibling_worktree_working_directory_is_named_explicitly(self):
+        root = self.make_repo()
+        subprocess.run(["git", *GIT_IDENTITY, "commit", "--quiet", "-m", "init"],
+                       cwd=root, check=True)
+        sibling = root / "sibling-worktree"
+        subprocess.run(["git", "worktree", "add", "--quiet", str(sibling), "-b", "slice"],
+                       cwd=root, check=True)
+        result = {"state": "refresh_required", "reasons": ["topology"], "overrides": []}
+
+        from_sibling = DRIFT_GUARD.build_census_block_message(2279, result, root, sibling)
+        from_root = DRIFT_GUARD.build_census_block_message(2279, result, root, root)
+        from_elsewhere = DRIFT_GUARD.build_census_block_message(
+            2279, result, root, self.make_repo()
+        )
+
+        self.assertIn(str(sibling), from_sibling)
+        self.assertIn("different worktree", from_sibling)
+        self.assertNotIn("different worktree", from_root)
+        self.assertNotIn("different worktree", from_elsewhere)
+
+    def test_a_blocked_build_handoff_reports_the_checkout_it_evaluated(self):
+        root = self.make_repo()
+        payload = self.write_payload(
+            root, "2279.md", "Build [#2279](https://github.com/acme/consumer/issues/2279)\n"
+        )
+        refresh = {
+            "state": "refresh_required", "block_handoff": True,
+            "reasons": ["topology"], "overrides": [],
+        }
+
+        with patch.object(DRIFT_GUARD, "run_check", return_value={"deny_recommended": False}), \
+             patch.object(DRIFT_GUARD, "evaluate_census", return_value=refresh):
+            blocked, message = DRIFT_GUARD.should_block(payload)
+
+        self.assertTrue(blocked)
+        self.assertIn("evaluated checkout", message)
+        self.assertIn(str(root), message)
+
+    # --- drift delta -------------------------------------------------------
+
+    def test_census_status_reports_what_drifted(self):
+        root = self.make_repo()
+        self.enable(root)
+        self.activate_current(root)
+        (root / "src" / "added.mjs").write_text("export const added = true;\n", encoding="utf-8")
+        (root / "test").mkdir()
+        (root / "test" / "proof.test.mjs").write_text("// evidence\n", encoding="utf-8")
+        (root / "src" / "index.mjs").write_text("export const ready = false;\n", encoding="utf-8")
+        subprocess.run(["git", "add", "."], cwd=root, check=True)
+
+        status = self.census_status(root)
+
+        self.assertEqual(status["state"], "refresh_required")
+        self.assertIn("topology", status["reasons"])
+        delta = status["delta"]
+        self.assertIn("src/added.mjs", delta["denominator"]["added"])
+        self.assertIn("src/index.mjs", delta["denominator"]["changed"])
+        self.assertEqual(delta["denominator"]["removed"], [])
+        self.assertIn("test/proof.test.mjs", delta["evidence"]["added"])
+        self.assertEqual(delta["families"]["added"], [])
+
+    def test_a_new_surface_and_a_removed_file_are_named_in_the_delta(self):
+        root = self.make_repo()
+        self.enable(root)
+        self.activate_current(root)
+        (root / "packages" / "api" / "src").mkdir(parents=True)
+        (root / "packages" / "api" / "src" / "index.mjs").write_text(
+            "export const api = true;\n", encoding="utf-8"
+        )
+        (root / "src" / "index.mjs").unlink()
+        subprocess.run(["git", "add", "--all"], cwd=root, check=True)
+
+        status = self.census_status(root)
+        delta = status["delta"]
+
+        self.assertIn("packages/api/src/index.mjs", delta["denominator"]["added"])
+        self.assertIn("src/index.mjs", delta["denominator"]["removed"])
+        self.assertIn("surface:packages/api", delta["families"]["added"])
+        self.assertIn("surface:src", delta["families"]["removed"])
+
+    def test_a_large_delta_stays_bounded_and_verbose_reports_everything(self):
+        root = self.make_repo()
+        self.enable(root)
+        self.activate_current(root)
+        grown = DRIFT_GUARD.CENSUS_DELTA_LIMIT + 7
+        for index in range(grown):
+            (root / "src" / f"grown-{index:03d}.mjs").write_text(
+                f"export const grown{index} = true;\n", encoding="utf-8"
+            )
+        subprocess.run(["git", "add", "."], cwd=root, check=True)
+
+        capped = self.census_status(root)["delta"]["denominator"]["added"]
+        verbose = self.census_status(root, "--verbose")["delta"]["denominator"]["added"]
+
+        self.assertEqual(len(capped), DRIFT_GUARD.CENSUS_DELTA_LIMIT + 1)
+        self.assertEqual(capped[-1], "…and 7 more")
+        self.assertEqual(len(verbose), grown)
+        self.assertIn("src/grown-000.mjs", verbose)
+
+    def test_a_census_without_an_active_snapshot_reports_no_delta(self):
+        root = self.make_repo()
+        self.enable(root)
+
+        status = self.census_status(root)
+
+        self.assertEqual(status["state"], "bootstrap")
+        self.assertIsNone(status.get("delta"))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_profile_globs.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""One repository-relative glob dialect backs every consumer-profile glob."""
+
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+DIALECT_MODULE = REPO / "scripts/profile_globs.py"
+ADVISORIES_CORE = REPO / "scripts/workflow-advisories/core.py"
+LIFECYCLE_CORE = REPO / "scripts/worktree-lifecycle/core.py"
+
+
+def load(name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_lifecycle_core():
+    module_dir = str(LIFECYCLE_CORE.parent)
+    if module_dir not in sys.path:
+        sys.path.insert(0, module_dir)
+    return load("profile_globs_lifecycle_core", LIFECYCLE_CORE)
+
+
+dialect = load("profile_globs_under_test", DIALECT_MODULE)
+
+
+class MatcherContract(unittest.TestCase):
+    """The documented dialect, exercised on the axes the contract names."""
+
+    def test_star_stays_inside_one_segment(self):
+        self.assertTrue(dialect.path_glob_matches("build.log", "*.log"))
+        self.assertFalse(dialect.path_glob_matches("logs/build.log", "*.log"))
+        self.assertTrue(dialect.path_glob_matches("logs/build.log", "logs/*.log"))
+        self.assertFalse(dialect.path_glob_matches("logs/a/build.log", "logs/*.log"))
+
+    def test_question_mark_matches_one_character_inside_one_segment(self):
+        self.assertTrue(dialect.path_glob_matches("a1.tmp", "a?.tmp"))
+        self.assertFalse(dialect.path_glob_matches("a/1.tmp", "a?1.tmp"))
+
+    def test_character_classes_stay_per_segment(self):
+        self.assertTrue(dialect.path_glob_matches("cache/7.tmp", "cache/[0-9].tmp"))
+        self.assertFalse(dialect.path_glob_matches("cache/x.tmp", "cache/[0-9].tmp"))
+        self.assertTrue(dialect.path_glob_matches("cache/x.tmp", "cache/[!0-9].tmp"))
+
+    def test_leading_globstar_covers_the_repository_root_and_nested_paths(self):
+        self.assertTrue(dialect.path_glob_matches("__pycache__/a.pyc", "**/__pycache__/**"))
+        self.assertTrue(dialect.path_glob_matches("src/__pycache__/a.pyc", "**/__pycache__/**"))
+        self.assertTrue(dialect.path_glob_matches("notes.md", "**/notes.md"))
+        self.assertTrue(dialect.path_glob_matches("a/b/notes.md", "**/notes.md"))
+
+    def test_directory_roots_match_every_depth_below_them(self):
+        self.assertTrue(dialect.path_glob_matches("dist-kit/a", "dist-kit/**"))
+        self.assertTrue(dialect.path_glob_matches("dist-kit/a/b", "dist-kit/**"))
+        self.assertTrue(dialect.path_glob_matches("dist-kit", "dist-kit/**"))
+        self.assertFalse(dialect.path_glob_matches("dist-kit/a/b", "dist-kit/*"))
+        self.assertFalse(dialect.path_glob_matches("dist-kitten/a", "dist-kit/**"))
+
+    def test_matching_is_case_sensitive_on_every_host(self):
+        self.assertTrue(dialect.path_glob_matches("PLAN.md", "PLAN.md"))
+        self.assertFalse(dialect.path_glob_matches("plan.md", "PLAN.md"))
+        self.assertFalse(dialect.path_glob_matches("Logs/a.log", "logs/*.log"))
+
+    def test_whole_path_must_match(self):
+        self.assertFalse(dialect.path_glob_matches("src/index.mjs", "src"))
+        self.assertFalse(dialect.path_glob_matches("src", "src/index.mjs"))
+
+
+class SharedMatcherContract(unittest.TestCase):
+    """Both shipped cores resolve to the one shared matcher, not a copy."""
+
+    def test_both_cores_share_one_matcher_object(self):
+        advisories = load("profile_globs_advisories_core", ADVISORIES_CORE)
+        lifecycle = load_lifecycle_core()
+        self.assertIs(advisories.path_glob_matches, lifecycle.path_glob_matches)
+
+    def test_the_shared_matcher_comes_from_the_shipped_dialect_module(self):
+        advisories = load("profile_globs_advisories_core", ADVISORIES_CORE)
+        shared = advisories.load_profile_globs()
+        self.assertEqual(Path(shared.__file__).resolve(), DIALECT_MODULE.resolve())
+        self.assertIs(advisories.path_glob_matches, shared.path_glob_matches)
+
+    def test_both_cores_name_the_same_shared_module(self):
+        advisories = load("profile_globs_advisories_core", ADVISORIES_CORE)
+        lifecycle = load_lifecycle_core()
+        self.assertEqual(
+            advisories.PROFILE_GLOBS_MODULE, lifecycle.PROFILE_GLOBS_MODULE,
+        )
+
+    def test_neither_core_keeps_a_second_matcher(self):
+        for core in (ADVISORIES_CORE, LIFECYCLE_CORE):
+            body = core.read_text(encoding="utf-8")
+            self.assertNotIn("fnmatch.fnmatch(", body)
+            self.assertNotIn("def path_glob_matches", body)
+
+
+class AdvisorySurfaceContract(unittest.TestCase):
+    """Advisory globs select the same paths the lifecycle globs would."""
+
+    def decision_for(self, globs, changed):
+        core = load("profile_globs_advisories_surface", ADVISORIES_CORE)
+        profile = {
+            "stopChecks": {
+                "surfaces": [{"globs": globs, "command": ["python3", "-c", "pass"]}],
+                "timeoutSeconds": 3,
+                "outputBudget": 300,
+            },
+        }
+        with tempfile.TemporaryDirectory() as root:
+            return core.stop_check_decision(
+                profile, {"changed_files": changed}, Path(root),
+            )
+
+    def test_single_segment_glob_no_longer_crosses_a_directory(self):
+        self.assertIsNone(self.decision_for(["*.py"], ["pkg/mod.py"]).context)
+        self.assertIsNotNone(self.decision_for(["*.py"], ["mod.py"]).context)
+
+    def test_globstar_covers_root_and_nested_paths(self):
+        self.assertIsNotNone(self.decision_for(["**/*.py"], ["pkg/mod.py"]).context)
+        self.assertIsNotNone(self.decision_for(["**/*.py"], ["mod.py"]).context)
+
+    def test_directory_root_glob_covers_every_depth(self):
+        self.assertIsNotNone(self.decision_for(["src/**"], ["src/a/b.mjs"]).context)
+        self.assertIsNone(self.decision_for(["src/*"], ["src/a/b.mjs"]).context)
+
+    def test_advisory_matching_is_case_sensitive(self):
+        self.assertIsNone(self.decision_for(["src/**"], ["SRC/a.mjs"]).context)
+
+
+class MigrationClassifier(unittest.TestCase):
+    """Legacy patterns whose match set changes are named, never rewritten."""
+
+    def test_literal_pattern_is_stable(self):
+        self.assertEqual(dialect.classify_pattern("PLAN.md").effects, ())
+
+    def test_single_segment_wildcard_narrows(self):
+        migration = dialect.classify_pattern("*.log")
+        self.assertIn(dialect.NARROWS, migration.effects)
+        self.assertIn("/", migration.witnesses[dialect.NARROWS])
+
+    def test_nested_wildcard_without_globstar_narrows(self):
+        self.assertIn(
+            dialect.NARROWS, dialect.classify_pattern("dist-kit/*").effects,
+        )
+
+    def test_leading_globstar_widens_at_the_repository_root(self):
+        migration = dialect.classify_pattern("**/__pycache__/**")
+        self.assertIn(dialect.WIDENS, migration.effects)
+        self.assertEqual(migration.witnesses[dialect.WIDENS], "__pycache__")
+
+    def test_directory_root_globstar_widens_onto_the_directory_itself(self):
+        migration = dialect.classify_pattern("dist-kit/**")
+        self.assertIn(dialect.WIDENS, migration.effects)
+        self.assertEqual(migration.witnesses[dialect.WIDENS], "dist-kit")
+
+    def test_bare_globstar_is_stable(self):
+        self.assertEqual(dialect.classify_pattern("**").effects, ())
+
+    def test_character_class_pattern_is_stable(self):
+        self.assertEqual(dialect.classify_pattern("cache/[0-9].tmp").effects, ())
+
+    def test_case_effect_only_applies_to_the_case_normalizing_legacy(self):
+        insensitive = dialect.classify_pattern("PLAN.md", case_insensitive_legacy=True)
+        self.assertIn(dialect.CASE_NARROWS, insensitive.effects)
+        self.assertEqual(dialect.classify_pattern("PLAN.md").effects, ())
+
+
+class ProfileScan(unittest.TestCase):
+    """Every shipped consumer-profile glob key is reachable from one scan."""
+
+    document = {
+        "worktreeLifecycle": {"scratchPatterns": ["PLAN.md", "*.log"]},
+        "wrapup": {"landingGeneratedArtifactPatterns": ["dist-kit/**"]},
+        "workflowAdvisories": {
+            "baseline": {"sourceGlobs": ["src/**"]},
+            "preRefactor": {"surfaces": [{"globs": ["frontend/*"]}]},
+            "stopChecks": {"surfaces": [{"globs": ["backend/**"]}]},
+        },
+    }
+
+    def locations(self):
+        return [finding.location for finding in dialect.scan_profile(self.document)]
+
+    def test_scan_reaches_every_shipped_glob_key(self):
+        self.assertEqual(self.locations(), [
+            "worktreeLifecycle.scratchPatterns[0]",
+            "worktreeLifecycle.scratchPatterns[1]",
+            "wrapup.landingGeneratedArtifactPatterns[0]",
+            "workflowAdvisories.baseline.sourceGlobs[0]",
+            "workflowAdvisories.preRefactor.surfaces[0].globs[0]",
+            "workflowAdvisories.stopChecks.surfaces[0].globs[0]",
+        ])
+
+    def test_cleanup_keys_are_marked_as_deletion_authority(self):
+        authority = {
+            finding.location: finding.deletion_authority
+            for finding in dialect.scan_profile(self.document)
+        }
+        self.assertTrue(authority["worktreeLifecycle.scratchPatterns[0]"])
+        self.assertTrue(authority["wrapup.landingGeneratedArtifactPatterns[0]"])
+        self.assertFalse(authority["workflowAdvisories.baseline.sourceGlobs[0]"])
+
+    def test_advisory_globs_carry_the_case_normalizing_legacy(self):
+        legacy = {
+            finding.location: finding.migration.effects
+            for finding in dialect.scan_profile(self.document)
+        }
+        self.assertIn(
+            dialect.CASE_NARROWS,
+            legacy["workflowAdvisories.baseline.sourceGlobs[0]"],
+        )
+        self.assertNotIn(
+            dialect.CASE_NARROWS,
+            legacy["worktreeLifecycle.scratchPatterns[0]"],
+        )
+
+    def test_malformed_sections_are_skipped_without_raising(self):
+        self.assertEqual(dialect.scan_profile({"worktreeLifecycle": []}), ())
+        self.assertEqual(dialect.scan_profile("not a profile"), ())
+
+
+class MigrationReport(unittest.TestCase):
+    """The review command reports; it never edits the consumer profile."""
+
+    def run_check(self, document, *args):
+        with tempfile.TemporaryDirectory() as root:
+            path = Path(root) / "workflow-capabilities.json"
+            body = json.dumps(document, indent=2) + "\n"
+            path.write_text(body, encoding="utf-8")
+            result = subprocess.run(
+                [sys.executable, str(DIALECT_MODULE), str(path), *args],
+                capture_output=True, text=True,
+            )
+            self.assertEqual(path.read_text(encoding="utf-8"), body)
+            return result
+
+    def test_stable_profile_exits_zero(self):
+        result = self.run_check({
+            "worktreeLifecycle": {"scratchPatterns": ["PLAN.md"]},
+        })
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_changed_pattern_exits_one_and_names_witness_and_authority(self):
+        result = self.run_check({
+            "wrapup": {"landingGeneratedArtifactPatterns": ["**/__pycache__/**"]},
+        })
+        self.assertEqual(result.returncode, 1, result.stderr)
+        self.assertIn("wrapup.landingGeneratedArtifactPatterns[0]", result.stdout)
+        self.assertIn(dialect.WIDENS, result.stdout)
+        self.assertIn("__pycache__", result.stdout)
+        self.assertIn("deletion authority", result.stdout)
+
+    def test_json_output_is_machine_readable(self):
+        result = self.run_check(
+            {"worktreeLifecycle": {"scratchPatterns": ["*.log"]}}, "--json",
+        )
+        report = json.loads(result.stdout)
+        self.assertEqual(report["reviewed"], 1)
+        self.assertEqual(report["changed"], 1)
+        self.assertEqual(report["findings"][0]["effects"], [dialect.NARROWS])
+
+    def test_unreadable_profile_exits_two(self):
+        result = subprocess.run(
+            [sys.executable, str(DIALECT_MODULE), "does/not/exist.json"],
+            capture_output=True, text=True,
+        )
+        self.assertEqual(result.returncode, 2)
+        self.assertNotEqual(result.stderr.strip(), "")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/scripts/test_skill_setup_workflow_seeds.py

@@ -57,6 +57,31 @@ def update_workflow_action(
     return "create" if pull_requests_allowed else "skip"
 
 
+def board_branch_action(tracker, boards_found, project_scope, user_choice):
+    """Reference decision table for Section D's board branch (#24).
+
+    tracker:      the Section A choice.
+    boards_found: how many owner projects the discovery read found, or None when
+                  the read itself failed.
+    project_scope: does `gh` carry the write scope board creation needs?
+    user_choice:  the answer to the creation offer ("yes" / "no" / None).
+
+    "discover" fills the profile from an existing board, "create" runs the
+    bootstrap helper after an explicit yes, "stub" is the retryable stub path.
+    Creation is offered on exactly one branch — no board, with the scope — and a
+    decline, a missing scope, ambiguity, or a failed read all stay on the stub.
+    """
+    if tracker != "github":
+        return "not-applicable"
+    if boards_found is None or boards_found > 1:
+        return "stub"
+    if boards_found == 1:
+        return "discover"
+    if not project_scope:
+        return "stub"
+    return "create" if user_choice == "yes" else "stub"
+
+
 def load_census_setup_effects():
     """Parse the shipped seed's executable census transition contract."""
     seed = (SKILL / "census.md").read_text(encoding="utf-8")
@@ -559,6 +584,68 @@ class SeedTemplatesValid(unittest.TestCase):
         self.assertIn("Board status is authoritative", triage_skill)
 
 
+class BoardCreationOffer(unittest.TestCase):
+    """Section D offers board creation instead of refusing it (#24).
+
+    The mechanics live in `scripts/board_bootstrap.py` (spec:
+    `scripts/test_board_bootstrap.py`); what is pinned here is the prose
+    contract: an explicit user gate, one creation path, and every other branch
+    landing on the unchanged stub.
+    """
+
+    FIXTURES = [
+        # tracker, boards, scope, choice, expected
+        ("github", 0, True, "yes", "create"),
+        ("github", 0, True, "no", "stub"),
+        ("github", 0, True, None, "stub"),
+        ("github", 0, False, "yes", "stub"),
+        ("github", 1, True, None, "discover"),
+        ("github", 2, True, "yes", "stub"),
+        ("github", None, True, "yes", "stub"),
+        ("gitlab", 0, True, "yes", "not-applicable"),
+        ("local", 0, True, "yes", "not-applicable"),
+    ]
+
+    def test_decision_table(self):
+        for tracker, boards, scope, choice, expected in self.FIXTURES:
+            self.assertEqual(
+                board_branch_action(tracker, boards, scope, choice), expected,
+                f"{tracker}/{boards}/{scope}/{choice}",
+            )
+
+    def test_skill_offers_creation_on_both_surfaces(self):
+        for surface in (".claude", ".agents"):
+            skill = (REPO / surface / "skills/setup-workflow/SKILL.md").read_text(
+                encoding="utf-8")
+            for token in (
+                "python3 scripts/board_bootstrap.py create",
+                "--dry-run",
+                "never create a board without an explicit yes",
+                "Create it now",
+                "Not now",
+                "gh auth refresh -s project,read:project",
+                "state=filled",
+            ):
+                self.assertIn(token, skill, f"{surface} missing {token!r}")
+            # The refuted rationale must be gone: the CLI *can* provision the
+            # Status options via `--single-select-options`.
+            self.assertNotIn("cannot provision the Status options", skill)
+
+    def test_skill_routes_every_other_branch_to_the_unchanged_stub(self):
+        skill = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+        fallback = skill.split("**Fallback", 1)
+        self.assertEqual(len(fallback), 2, "the stub fallback must survive")
+        for token in ("declined", "scope", "read failure", "state=stub", "Retryable"):
+            self.assertIn(token, fallback[1][:1200], f"stub path missing {token!r}")
+        self.assertIn("never hand-write a `state=filled` profile", skill)
+
+    def test_seed_documents_the_offer_and_keeps_the_manual_path(self):
+        seed = (SKILL / "board-sync.md").read_text(encoding="utf-8")
+        self.assertIn("board_bootstrap.py", seed)
+        self.assertIn("gh auth refresh -s project,read:project", seed)
+        self.assertIn("Re-run `/setup-workflow`", seed)
+
+
 class SentinelProtectsFilledProfile(unittest.TestCase):
     """A consumer's filled board profile must never be rewritten on rerun."""