@christang/keel 5.3.3 → 5.3.5

package/scripts/validate_plugin.py

@@ -37,10 +37,13 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.3.3"
-PROTOCOL_VERSION = "5.3.3"
+PACKAGE_VERSION = "5.3.5"
+PROTOCOL_VERSION = "5.3.5"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
+# Mirrors KEEL_PACKAGE_NAME in scripts/install_to_repo.py, one of the two
+# signals is_keel_source_repo reads.
+KEEL_PACKAGE_NAME = "@christang/keel"
 OPENSPEC_CONFIG_PATH = Path("openspec/config.yaml")
 OPENSPEC_SCHEMA_ROOT = Path("openspec/schemas") / OPENSPEC_SCHEMA_NAME
 OPENSPEC_SURFACE_OVERLAY_START = (
@@ -50,7 +53,6 @@ OPENSPEC_SURFACE_OVERLAY_END = "<!-- keel:openspec-surface-overlay:end -->"
 
 SKILL_TARGETS = {"claude", "codex", "opencode"}
 HOOK_TARGETS = {"claude"}
-KEEL_HOOK_NAME = "keel-gate"
 AGENT_TARGETS: set[str] = set()
 ADAPTER_TARGETS = {"claude", "codex", "opencode"}
 AGENT_PROTOCOL_TARGETS = {"codex", "opencode"}
@@ -415,6 +417,28 @@ def validate_npm_package(errors: list[str]) -> None:
             errors.append(f"bin/keel.js missing required CLI support: {required}")
 
 
+# Path expressions rooted at a tree the retirement check above requires to be
+# absent. `src/core` and `src/skills` are live, so only the retired `src`
+# children are listed.
+# Keel subcommands that write. A scenario may point read-only ones at the
+# repository root; these need a fixture.
+MUTATING_KEEL_COMMANDS = (
+    "--install",
+    "--init",
+    "--uninstall",
+    "--clear",
+    "--update",
+    "--with-git-hooks",
+)
+
+RETIRED_PATH_EXPRESSIONS = (
+    r'ROOT\s*/\s*"dist"',
+    r'ROOT\s*/\s*"src"\s*/\s*"assets"',
+    r'ROOT\s*/\s*"src"\s*/\s*"hooks"',
+    r'ROOT\s*/\s*"src"\s*/\s*"adapters"',
+)
+
+
 def validate_paths(errors: list[str]) -> None:
     for directory in REQUIRED_DIRECTORIES:
         if not (ROOT / directory).is_dir():
@@ -448,6 +472,63 @@ def validate_paths(errors: list[str]) -> None:
                 f"retired custom distribution path must be removed: {retired}"
             )
 
+    validator_source = (ROOT / "scripts" / "validate_plugin.py").read_text(
+        encoding="utf-8"
+    )
+
+    # A scenario that writes to the repository it validates can satisfy the very
+    # condition another check asserts, and a check whose input its own run
+    # produces cannot fail. Reads against ROOT are fine and common; writes are
+    # not. Keyed on the mutating subcommand rather than on ROOT itself, so
+    # `--version`, `--doctor`, and the gates stay legal.
+    for line_number, line in enumerate(validator_source.splitlines(), start=1):
+        invocation = re.search(r"run_(?:keel|install)\(\s*ROOT\s*,([^)]*)", line)
+        if not invocation:
+            continue
+        if any(
+            re.search(rf'"{command}"', invocation.group(1))
+            for command in MUTATING_KEEL_COMMANDS
+        ):
+            errors.append(
+                "a scenario must not run a mutating Keel command against the "
+                "repository it validates; build a fixture instead: "
+                f"scripts/validate_plugin.py:{line_number}: {line.strip()}"
+            )
+
+    # Every Keel marker that carries a version is a shipped claim about which
+    # version this is. Derive the set from the markers that exist rather than a
+    # fixed list, because a fixed list is the next thing to fall behind — which
+    # is exactly how the `.codex/` overlays sat four versions back unnoticed.
+    for marker_file in sorted(ROOT.rglob("*")):
+        if not marker_file.is_file() or not marker_file.suffix in (".md", ".json"):
+            continue
+        relative = marker_file.relative_to(ROOT).as_posix()
+        if relative.startswith(("node_modules/", "openspec/changes/archive/", "keel/archive/")):
+            continue
+        try:
+            text = marker_file.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        for found in re.findall(r"keel:[a-z-]+(?::end)?\s+version=([0-9][^\s>]*)", text):
+            if found != PACKAGE_VERSION:
+                errors.append(
+                    "shipped version marker disagrees with the package version "
+                    f"{PACKAGE_VERSION}: {relative} says {found}"
+                )
+
+    # Asserting the trees are gone is not enough: a check that still resolves a
+    # path into one of them can only ever find nothing, and rglob over a missing
+    # directory yields no error, so the check reports success forever. Naming a
+    # retired tree in a string literal is fine — that is how the checks above
+    # state what must not exist; building a Path into one is not.
+    for line_number, line in enumerate(validator_source.splitlines(), start=1):
+        if any(re.search(pattern, line) for pattern in RETIRED_PATH_EXPRESSIONS):
+            errors.append(
+                "validator resolves a path under a retired distribution tree, "
+                "so the check it feeds can only iterate nothing: "
+                f"scripts/validate_plugin.py:{line_number}: {line.strip()}"
+            )
+
 
 def extract_managed_block(content: str) -> str | None:
     start_match = MANAGED_START_RE.search(content)
@@ -571,10 +652,20 @@ def validate_templates(errors: list[str]) -> None:
                     f"{template['name']} includes forbidden content: {forbidden}"
                 )
 
+    # What actually ships is whatever package.json declares, so derive the roots
+    # from there rather than naming a tree that can retire out from under the
+    # check the way `src/assets` and `dist` did.
+    packaged_roots = [
+        ROOT / entry
+        for entry in json.loads(
+            (ROOT / "package.json").read_text(encoding="utf-8")
+        ).get("files", [])
+        if (ROOT / entry).is_dir()
+    ]
+
     active_task_placeholders = [
         path.relative_to(ROOT).as_posix()
-        for base in (ROOT / "src" / "assets", ROOT / "dist")
-        if base.exists()
+        for base in packaged_roots
         for path in base.rglob("keel/TASK.md")
     ]
     if active_task_placeholders:
@@ -585,18 +676,9 @@ def validate_templates(errors: list[str]) -> None:
 
     backlog_assets = [
         path.relative_to(ROOT).as_posix()
-        for base in (ROOT / "src" / "assets", ROOT / "dist")
-        if base.exists()
+        for base in packaged_roots
         for path in base.rglob("keel/backlog/*")
     ]
-    backlog_assets.extend(
-        path.relative_to(ROOT).as_posix()
-        for path in (
-            ROOT / "src" / "assets" / "shared" / "backlog",
-            ROOT / "dist" / "shared" / "assets" / "backlog",
-        )
-        if path.exists()
-    )
     if backlog_assets:
         errors.append(
             "package must not include keel backlog assets: "
@@ -606,7 +688,6 @@ def validate_templates(errors: list[str]) -> None:
 
 def validate_openspec_schema(errors: list[str]) -> None:
     source_root = ROOT / "assets" / "openspec" / "schemas" / OPENSPEC_SCHEMA_NAME
-    dist_root = source_root
     required_files = [
         "schema.yaml",
         "templates/proposal.md",
@@ -615,13 +696,12 @@ def validate_openspec_schema(errors: list[str]) -> None:
         "templates/tasks.md",
     ]
 
-    for root_name, root in (("source", source_root), ("dist", dist_root)):
-        for relative in required_files:
-            if not (root / relative).is_file():
-                errors.append(
-                    f"OpenSpec {root_name} schema missing file: "
-                    f"{root.relative_to(ROOT).as_posix()}/{relative}"
-                )
+    for relative in required_files:
+        if not (source_root / relative).is_file():
+            errors.append(
+                "OpenSpec source schema missing file: "
+                f"{source_root.relative_to(ROOT).as_posix()}/{relative}"
+            )
 
     schema_path = source_root / "schema.yaml"
     tasks_template_path = source_root / "templates" / "tasks.md"
@@ -717,33 +797,11 @@ def validate_openspec_schema(errors: list[str]) -> None:
                     f"{forbidden}"
                 )
 
-    if source_root.is_dir() and dist_root.is_dir():
-        source_files = {
-            path.relative_to(source_root).as_posix(): path.read_text(encoding="utf-8")
-            for path in sorted(source_root.rglob("*"))
-            if path.is_file()
-        }
-        dist_files = {
-            path.relative_to(dist_root).as_posix(): path.read_text(encoding="utf-8")
-            for path in sorted(dist_root.rglob("*"))
-            if path.is_file()
-        }
-        if source_files != dist_files:
-            missing = sorted(set(source_files) - set(dist_files))
-            unexpected = sorted(set(dist_files) - set(source_files))
-            changed = sorted(
-                path
-                for path in set(source_files) & set(dist_files)
-                if source_files[path] != dist_files[path]
-            )
-            errors.append(
-                "OpenSpec dist schema differs from source"
-                + (
-                    f"; missing={missing}, unexpected={unexpected}, changed={changed}"
-                    if missing or unexpected or changed
-                    else ""
-                )
-            )
+    # A source-versus-dist comparison stood here, but `dist_root` was assigned
+    # `source_root`, so it diffed a directory against itself and could not fail.
+    # The pair that really needs comparing — this packaged copy against the
+    # repo-local one OpenSpec resolves — is asserted by
+    # `invalidation-authoring-surface`.
 
 
 def validate_skill_docs(errors: list[str]) -> None:
@@ -946,18 +1004,17 @@ def snapshot_files(root: Path) -> dict[str, str]:
     return snapshot
 
 
-def packaged_openspec_schema_install_paths() -> list[str]:
-    schema_root = (
-        ROOT
-        / "dist"
-        / "shared"
-        / "assets"
-        / "openspec"
-        / "schemas"
-        / OPENSPEC_SCHEMA_NAME
+def packaged_openspec_schema_install_paths(root: Path | None = None) -> list[str]:
+    # The root the installer itself reads (install_to_repo.openspec_schema_actions),
+    # which raises on the same condition. A validator that answered `[]` here left
+    # six install/uninstall/clear assertions iterating nothing and reporting pass.
+    schema_root = root if root is not None else (
+        ROOT / "assets" / "openspec" / "schemas" / OPENSPEC_SCHEMA_NAME
     )
     if not schema_root.is_dir():
-        return []
+        raise FileNotFoundError(
+            f"packaged OpenSpec schema root is missing: {schema_root}"
+        )
 
     return [
         (OPENSPEC_SCHEMA_ROOT / path.relative_to(schema_root)).as_posix()
@@ -2462,22 +2519,6 @@ def validate_update_default_registry_scenario() -> int:
     return 0
 
 
-def run_keel_hook(repo: Path, event: dict) -> subprocess.CompletedProcess[str]:
-    env = dict(os.environ)
-    env["KEEL_CLI"] = str(ROOT / "bin/keel.js")
-    return subprocess.run(
-        ["node", str(ROOT / "dist" / "claude" / "hooks" / KEEL_HOOK_NAME / "keel-gate.js")],
-        cwd=repo,
-        env=env,
-        input=json.dumps(event),
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        capture_output=True,
-        check=False,
-    )
-
-
 def gate_task(
     *,
     checked: bool,
@@ -3642,13 +3683,561 @@ SCHEMA_COPY_PAIRS = (
 )
 
 
+def validate_anchor_reverification_bound_scenario() -> int:
+    label = "anchor-reverification-bound"
+
+    # The fingerprint is described as recompiled and compared at resume,
+    # projection, and completion, with no stated bound. It holds while the
+    # change is live: the capsule records each authority's source as a path
+    # under the change directory, and archiving renames that directory. An
+    # unstated boundary reads as no boundary, so demonstrate where it is.
+    with tempfile.TemporaryDirectory(prefix="keel-anchor-bound-") as raw_tmp:
+        repo = Path(raw_tmp) / "repo"
+        repo.mkdir()
+        live = repo / "openspec/changes/demo/tasks.md"
+        write_text(live, task_contract_fixture(evidence=("Contract: pending", "M1: pending")))
+
+        recorded = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--record", "--json",
+        )
+        payload = json.loads(recorded.stdout)
+        if payload.get("status") != "pass":
+            report(f"{label} could not record an anchor on a live change.")
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+        anchor = payload["contract"]["fingerprint"]["value"]
+
+        # Live: recompiling reproduces the recorded value, which is the
+        # guarantee the resident protocol states.
+        again = json.loads(
+            run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+            ).stdout
+        )
+        if again["contract"]["fingerprint"]["value"] != anchor:
+            report(f"{label} a live anchor did not recompile to its recorded value.")
+            return 1
+
+        # Archived: the gate refuses to select the change at all, so the bound
+        # is enforced rather than merely documented.
+        archived = repo / "openspec/changes/archive/2026-07-28-demo/tasks.md"
+        write_text(archived, live.read_text(encoding="utf-8"))
+        refused = run_keel(
+            repo, "gate", "task-start",
+            "--change", "archive/2026-07-28-demo", "--task", "1.1",
+        )
+        if refused.returncode == 0 or "invalid change name" not in (
+            refused.stderr + refused.stdout
+        ):
+            report(
+                f"{label} the gate accepted an archived change; the bound this "
+                "documents is supposed to be enforced, not advisory."
+            )
+            report((refused.stderr or refused.stdout).strip())
+            return 1
+
+        # And the reason the refusal is right: compiling the archived copy
+        # directly yields a different fingerprint, because each authority's
+        # `source` names the directory the task now lives in.
+        probe = subprocess.run(
+            [
+                "node", "-e",
+                "const {loadTaskContract}=require(process.argv[1]);"
+                "const c=loadTaskContract(process.argv[2],'archive/2026-07-28-demo','1.1');"
+                "process.stdout.write(c.contract.fingerprint.value);",
+                str(ROOT / "src/core/task-contract.js"),
+                str(repo),
+            ],
+            text=True, encoding="utf-8", capture_output=True, check=False,
+        )
+        if probe.returncode != 0:
+            report(f"{label} could not compile the archived copy directly.")
+            report((probe.stderr or probe.stdout).strip())
+            return 1
+        if probe.stdout.strip() == anchor:
+            report(
+                f"{label} the archived copy reproduced the anchor, so the "
+                "documented bound no longer describes reality — revisit the "
+                "protocol wording rather than relaxing this check."
+            )
+            return 1
+
+    # And the resident protocol must say where the guarantee stops.
+    resident = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+    if "while its change is live" not in resident:
+        report(
+            f"{label} the resident protocol describes recompilation without "
+            "stating that it holds while the change is live."
+        )
+        return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+def validate_authoring_surface_owner_and_tags_scenario() -> int:
+    label = "authoring-surface-owner-and-tags"
+
+    # Both rules this change adds widen what a gate accepts. An author only
+    # benefits if the shipped surface says so, so the template, the artifact
+    # instruction the CLI hands back, and the resident protocol each state them.
+    template = (
+        ROOT / "openspec/schemas/keel-spec-driven/templates/tasks.md"
+    ).read_text(encoding="utf-8")
+    resident = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+
+    # Read the instruction the way an author receives it — through the CLI in a
+    # repository Keel installed — rather than from the schema file it is
+    # composed from, so a change that never reaches the author is a failure.
+    with tempfile.TemporaryDirectory(prefix="keel-authoring-surface-") as raw_tmp:
+        repo = Path(raw_tmp) / "repo"
+        repo.mkdir()
+        install = run_keel(repo, "--install")
+        if install.returncode != 0:
+            report(f"{label} keel --install failed.")
+            report((install.stderr or install.stdout).strip())
+            return 1
+        created = run_openspec(repo, "new", "change", "surface-probe")
+        if created is None:
+            report(f"{label} skipped: the openspec CLI is not on PATH.")
+            return 3
+        if created.returncode != 0:
+            report(f"{label} could not scaffold a change to read the instruction.")
+            report((created.stderr or created.stdout).strip())
+            return 1
+        instructions = run_openspec(
+            repo, "instructions", "tasks", "--change", "surface-probe"
+        )
+        if instructions is None or instructions.returncode != 0:
+            report(f"{label} could not read the tasks artifact instruction.")
+            if instructions is not None:
+                report((instructions.stderr or instructions.stdout).strip())
+            return 1
+        instruction = instructions.stdout
+
+    for surface, text in (("tasks template", template), ("tasks instruction", instruction)):
+        for needle in (
+            "regression",
+            "at least one check untagged",
+        ):
+            if needle not in text:
+                report(f"{label} {surface} does not describe the tag: {needle}")
+                return 1
+        # D6 — the wording trap: red and green accompany the bare label.
+        if "in addition to" not in text.lower():
+            report(
+                f"{label} {surface} still reads as though `.red`/`.green` "
+                "replace the bare M<n> Evidence rather than accompanying it."
+            )
+            return 1
+        if "repo-relative path that exists" not in text:
+            report(
+                f"{label} {surface} does not state the existing-path owner form."
+            )
+            return 1
+        if "HANDOFF" not in text:
+            report(f"{label} {surface} does not state that HANDOFF is refused.")
+            return 1
+
+    for needle in (
+        "regression-only-strategy",
+        "in addition to the bare",
+        "any repo-relative path that exists",
+    ):
+        if needle not in resident:
+            report(f"{label} resident protocol does not state: {needle}")
+            return 1
+
+    for local, packaged in SCHEMA_COPY_PAIRS:
+        if (ROOT / local).read_text(encoding="utf-8") != (
+            ROOT / packaged
+        ).read_text(encoding="utf-8"):
+            report(f"{label} schema copies diverge: {local} vs {packaged}")
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+def validate_durable_owner_vocabulary_scenario() -> int:
+    label = "durable-owner-vocabulary"
+
+    # The accepted owner forms are shape checks: a gate cannot resolve a URL or
+    # confirm an archive path is the right one. A repo-relative path is the one
+    # form it can actually check, so refusing it drew the line in the least
+    # defensible place.
+    with tempfile.TemporaryDirectory(prefix="keel-owner-vocab-") as raw_tmp:
+        repo = Path(raw_tmp) / "repo"
+        repo.mkdir()
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+        write_text(repo / "openspec/FOLLOWUP.md", "# Follow-ups\n")
+        write_text(repo / "keel/HANDOFF.md", "pointer\n")
+        write_text(repo / "keel/archive/notes/2026-07-28-example.md", "note\n")
+
+        def invalidation_start(closure: str) -> dict:
+            write_text(
+                tasks_path,
+                task_contract_fixture().replace(
+                    "## Invalidates\n\n- None.\n\n",
+                    '## Invalidates\n\n- I1: "the wording that is now wrong" '
+                    f"— somewhere in the repo. {closure}\n\n",
+                ),
+            )
+            result = run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+            )
+            return json.loads(result.stdout)
+
+        def completion(findings: str) -> dict:
+            fixture = (
+                task_contract_fixture(evidence=("M1: check exercised.",))
+                .replace("- [ ] 1.1", "- [x] 1.1")
+                .replace("      - Status: pending\n", "      - Status: pass\n")
+                .replace(
+                    "      - Acceptance check: pending\n",
+                    "      - Acceptance check: behavior proven through the public CLI.\n",
+                )
+                .replace(
+                    "      - Scope check: pending\n",
+                    "      - Scope check: writes stayed inside Touch.\n",
+                )
+                .replace(
+                    "      - Findings: pending\n", f"      - Findings: {findings}\n"
+                )
+            )
+            write_text(tasks_path, fixture)
+            result = run_keel(
+                repo, "gate", "task-complete", "--change", "demo", "--task", "1.1", "--json"
+            )
+            return json.loads(result.stdout)
+
+        def close(closure: str) -> dict:
+            write_text(
+                tasks_path,
+                task_contract_fixture(evidence=("M1: check exercised.",))
+                .replace("- [ ] 1.1", "- [x] 1.1")
+                .replace("      - Status: pending\n", "      - Status: pass\n")
+                .replace(
+                    "      - Acceptance check: pending\n",
+                    "      - Acceptance check: proven.\n",
+                )
+                .replace("      - Scope check: pending\n", "      - Scope check: inside Touch.\n")
+                .replace("      - Findings: pending\n", "      - Findings: none\n")
+                + f"\n## Expectation Coverage\n\n- E1: the expectation. {closure}\n",
+            )
+            write_text(repo / "openspec/changes/demo/proposal.md", "# Proposal\n")
+            write_text(repo / "openspec/changes/demo/design.md", "## Context\n\nfixture\n")
+            write_text(
+                repo / "openspec/changes/demo/specs/demo/spec.md",
+                "## ADDED Requirements\n",
+            )
+            result = run_keel(
+                repo, "gate", "change-close", "--change", "demo", "--action", "sync", "--json"
+            )
+            return json.loads(result.stdout)
+
+        # M1 — an existing repo path closes an entry in all three shared places.
+        ledger = "Durable owner: openspec/FOLLOWUP.md"
+        payload = invalidation_start(ledger)
+        if payload.get("status") != "pass":
+            report(f"{label} refused a repo ledger as an invalidation owner.")
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        payload = completion(f"the IDE shell contract gap. {ledger}")
+        if payload.get("status") != "pass":
+            report(f"{label} refused a repo ledger as a Findings owner.")
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        payload = close(ledger)
+        if any(
+            item.get("code") == "expectation-closure"
+            for item in payload.get("problems", [])
+        ):
+            report(f"{label} refused a repo ledger as an Expectation Coverage owner.")
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        # And a path with no file behind it is refused, distinguishably.
+        payload = invalidation_start("Durable owner: openspec/NOT-THERE.md")
+        codes = {item.get("code") for item in payload.get("problems", [])}
+        messages = " ".join(
+            item.get("message", "") for item in payload.get("problems", [])
+        )
+        if (
+            payload.get("status") != "fail"
+            or "invalidation-owner-missing" not in codes
+            or "openspec/NOT-THERE.md" not in messages
+        ):
+            report(f"{label} accepted a durable owner with no file behind it.")
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        # M2 — the pointer override is still not an owner, although it exists.
+        payload = invalidation_start("Durable owner: keel/HANDOFF.md")
+        messages = " ".join(
+            item.get("message", "") for item in payload.get("problems", [])
+        )
+        if payload.get("status") != "fail" or "HANDOFF" not in messages:
+            report(f"{label} accepted keel/HANDOFF.md as a durable owner.")
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        # A refusal names the forms it accepts, including the new one.
+        payload = invalidation_start("no closure at all")
+        messages = " ".join(
+            item.get("message", "") for item in payload.get("problems", [])
+        )
+        for expected in ("Durable owner:", "repo-relative path that exists", "Discard reason:"):
+            if expected not in messages:
+                report(f"{label} refusal does not name the accepted form: {expected}")
+                report(messages)
+                return 1
+
+        # M3 — every previously accepted form still closes.
+        for closure in (
+            "Durable owner: openspec/changes/demo/proposal.md",
+            "Durable owner: keel/archive/notes/2026-07-28-example.md",
+            "Durable owner: https://github.com/TanglmChris/keel/issues/20",
+            "Discard reason: it stands as written.",
+        ):
+            write_text(repo / "openspec/changes/demo/proposal.md", "# Proposal\n")
+            payload = invalidation_start(closure)
+            if payload.get("status") != "pass":
+                report(f"{label} dropped a previously accepted form: {closure}")
+                report(json.dumps(payload.get("problems", []), indent=2))
+                return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+def regression_tag_fixture(
+    commands: tuple[str, ...],
+    evidence: tuple[str, ...],
+    *,
+    strategy: str = "vertical-tdd",
+) -> str:
+    return (
+        task_contract_fixture(commands=commands, evidence=evidence)
+        .replace(
+            "  - Commands:\n",
+            f"  - Verification Strategy: {strategy}\n  - Commands:\n",
+        )
+        .replace("      - Status: pending\n", "      - Status: pass\n")
+        .replace(
+            "      - Acceptance check: pending\n",
+            "      - Acceptance check: behavior proven through the public CLI.\n",
+        )
+        .replace(
+            "      - Scope check: pending\n",
+            "      - Scope check: writes stayed inside Touch.\n",
+        )
+        .replace("      - Findings: pending\n", "      - Findings: none\n")
+    )
+
+
+def validate_regression_check_tag_scenario() -> int:
+    label = "regression-check-tag"
+
+    # A regression check asserts that something already green is still green, so
+    # it has no honest red. Requiring one leaves an author fabricating evidence
+    # or folding the guard into the behavior check; the tag is the third option.
+    with tempfile.TemporaryDirectory(prefix="keel-regression-tag-") as raw_tmp:
+        repo = Path(raw_tmp) / "repo"
+        repo.mkdir()
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+
+        def complete(fixture: str) -> dict:
+            write_text(tasks_path, fixture)
+            result = run_keel(
+                repo, "gate", "task-complete", "--change", "demo", "--task", "1.1", "--json"
+            )
+            return json.loads(result.stdout)
+
+        def start(fixture: str) -> dict:
+            write_text(tasks_path, fixture)
+            result = run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+            )
+            return json.loads(result.stdout)
+
+        mixed_commands = (
+            "M1: behavior reaches the public interface",
+            "M2 (regression): the existing suite stays green",
+        )
+
+        # M1 — a tagged check completes without red/green, and the untagged one
+        # still needs both.
+        payload = complete(
+            regression_tag_fixture(
+                mixed_commands,
+                (
+                    "M1: behavior exercised.",
+                    "M1.red: failed before the implementation.",
+                    "M1.green: passed after.",
+                    "M2: existing suite still green.",
+                ),
+            )
+        )
+        if payload.get("status") != "pass":
+            report(f"{label} refused a tagged regression check that needs no red.")
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+
+        # D5 — the exemption is from red-green, not from evidence.
+        payload = complete(
+            regression_tag_fixture(
+                mixed_commands,
+                (
+                    "M1: behavior exercised.",
+                    "M1.red: failed before the implementation.",
+                    "M1.green: passed after.",
+                    "M2: pending",
+                ),
+            )
+        )
+        if payload.get("status") != "fail" or not any(
+            "M2" in item.get("message", "")
+            for item in payload.get("problems", [])
+        ):
+            report(f"{label} completed a tagged check with no evidence at all.")
+            report(json.dumps(payload, indent=2))
+            return 1
+
+        # M2 — the strategy cannot be emptied out by tagging every check.
+        payload = start(
+            regression_tag_fixture(
+                (
+                    "M1 (regression): the existing suite stays green",
+                    "M2 (regression): the golden files stay byte-identical",
+                ),
+                ("M1: pending", "M2: pending"),
+            )
+        )
+        codes = {item.get("code") for item in payload.get("problems", [])}
+        if payload.get("status") != "fail" or "regression-only-strategy" not in codes:
+            report(
+                f"{label} accepted a red-green strategy whose every check is tagged."
+            )
+            report(json.dumps(payload, indent=2))
+            return 1
+
+        # M3 — an untagged check emits no tag key, so its capsule and fingerprint
+        # are byte-identical to what they were before the tag existed.
+        payload = start(
+            regression_tag_fixture(
+                ("M1: behavior reaches the public interface",),
+                ("M1: pending",),
+            )
+        )
+        entries = (
+            payload.get("contract", {})
+            .get("capsule", {})
+            .get("verification", {})
+            .get("commands", [])
+        )
+        if payload.get("status") != "pass" or [sorted(entry) for entry in entries] != [
+            ["check", "label"]
+        ]:
+            report(
+                f"{label} changed the compiled shape of an untagged check, which "
+                "moves every recorded contract fingerprint."
+            )
+            report(json.dumps(entries, indent=2))
+            return 1
+
+        # And a tagged check does declare itself in the capsule, so the exemption
+        # is a visible term of the contract rather than a silent skip.
+        payload = start(
+            regression_tag_fixture(mixed_commands, ("M1: pending", "M2: pending"))
+        )
+        tagged = next(
+            (
+                entry
+                for entry in payload.get("contract", {})
+                .get("capsule", {})
+                .get("verification", {})
+                .get("commands", [])
+                if entry.get("label") == "M2"
+            ),
+            None,
+        )
+        if not tagged or tagged.get("regression") is not True:
+            report(f"{label} did not record the regression tag in the capsule.")
+            report(json.dumps(payload.get("contract", {}), indent=2))
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+def validate_packaged_schema_derivation_scenario() -> int:
+    label = "packaged-schema-derivation"
+
+    # The helper derives the consumer-repo paths every install/uninstall/clear
+    # assertion iterates. When its root stopped existing it returned an empty
+    # list, so those loops compared nothing and reported success. Anchor it to
+    # what the installer really writes, and make emptiness a failure here.
+    try:
+        packaged_openspec_schema_install_paths(ROOT / "no-such-packaged-root")
+    except FileNotFoundError as error:
+        if "no-such-packaged-root" not in str(error):
+            report(f"{label} missing-root failure does not name the path it expected.")
+            report(str(error))
+            return 1
+    else:
+        report(
+            f"{label} returned a set for a missing packaged root instead of failing; "
+            "an absent root must not silently empty its callers' assertions."
+        )
+        return 1
+
+    derived = packaged_openspec_schema_install_paths()
+    if not derived:
+        report(
+            f"{label} derived no packaged schema paths, so every assertion that "
+            "iterates them verifies nothing."
+        )
+        return 1
+
+    with tempfile.TemporaryDirectory(prefix="keel-packaged-schema-") as raw_tmp:
+        repo = Path(raw_tmp) / "repo"
+        repo.mkdir()
+        install = run_keel(repo, "--install")
+        if install.returncode != 0:
+            report(f"{label} keel --install failed.")
+            report((install.stderr or install.stdout).strip())
+            return 1
+
+        schema_root = repo / OPENSPEC_SCHEMA_ROOT
+        installed = sorted(
+            path.relative_to(repo).as_posix()
+            for path in schema_root.rglob("*")
+            if path.is_file()
+        )
+        if installed != sorted(derived):
+            report(
+                f"{label} derived paths do not match what keel --install wrote."
+            )
+            report(f"derived:   {sorted(derived)}")
+            report(f"installed: {installed}")
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
 def validate_invalidation_authoring_surface_scenario() -> int:
     label = "invalidation-authoring-surface"
 
     # The two schema copies are the repo-local one OpenSpec resolves and the
-    # packaged one `keel --init` writes. compact-task-authoring already means to
-    # assert they agree, but its canonical root does not exist in this layout, so
-    # its rglob compares nothing; this states the pair explicitly.
+    # packaged one `keel --init` writes. This is the only check that asserts they
+    # agree: compact-task-authoring used to imply it through a projection loop
+    # rooted at trees that no longer exist, so it compared nothing and has since
+    # been removed.
     for local, packaged in SCHEMA_COPY_PAIRS:
         local_text = (ROOT / local).read_text(encoding="utf-8")
         packaged_text = (ROOT / packaged).read_text(encoding="utf-8")
@@ -4449,29 +5038,56 @@ def validate_source_repo_bootstrap_skip_scenario() -> int:
         found = managed.search(path.read_text(encoding="utf-8"))
         return found.group(0) if found else ""
 
-    own_agents = ROOT / "AGENTS.md"
-    before = block(own_agents)
-    if not before:
+    # `is_keel_source_repo` reads exactly two signals — the package name and a
+    # plugins/keel directory — so a fixture carrying both exercises the same
+    # branch. Running this against the real repository used to work and used to
+    # rewrite the .claude/ overlay markers as a side effect, which is how the
+    # marker check ended up green on that side for the wrong reason.
+    if not (ROOT / "AGENTS.md").is_file() or not block(ROOT / "AGENTS.md"):
         report("source-repo-bootstrap-skip: Keel's AGENTS.md has no managed block.")
         return 1
-    result = run_keel(ROOT, "--install", "--target", "claude")
-    if result.returncode != 0:
-        report("source-repo-bootstrap-skip: keel --install failed in Keel's repo.")
-        report((result.stderr or result.stdout).strip())
-        return 1
-    if block(own_agents) != before:
-        report(
-            "source-repo-bootstrap-skip: keel --install rewrote Keel's own "
-            "AGENTS.md managed block."
-        )
-        return 1
-    if "skip AGENTS.md" not in (result.stdout or ""):
-        report(
-            "source-repo-bootstrap-skip: the skip was silent; it must be "
-            "reported explicitly."
-        )
-        report((result.stdout or "").strip())
-        return 1
+
+    with tempfile.TemporaryDirectory(prefix="keel-source-repo-") as raw:
+        fixture = Path(raw) / "keel"
+        write_text(fixture / "package.json", json.dumps({"name": KEEL_PACKAGE_NAME}))
+        write_text(fixture / "plugins/keel/.keep", "")
+        own_agents = fixture / "AGENTS.md"
+        write_text(own_agents, (ROOT / "AGENTS.md").read_text(encoding="utf-8"))
+        before_tree = snapshot_files(fixture)
+        before = block(own_agents)
+
+        result = run_keel(fixture, "--install", "--target", "claude")
+        if result.returncode != 0:
+            report("source-repo-bootstrap-skip: keel --install failed in Keel's repo.")
+            report((result.stderr or result.stdout).strip())
+            return 1
+        if block(own_agents) != before:
+            report(
+                "source-repo-bootstrap-skip: keel --install rewrote Keel's own "
+                "AGENTS.md managed block."
+            )
+            return 1
+        if "skip AGENTS.md" not in (result.stdout or ""):
+            report(
+                "source-repo-bootstrap-skip: the skip was silent; it must be "
+                "reported explicitly."
+            )
+            report((result.stdout or "").strip())
+            return 1
+        # The original defect was the missing assertion, not only the wrong
+        # repository: name what the install must not have rewritten.
+        rewritten = [
+            name
+            for name, text in before_tree.items()
+            if (fixture / name).is_file()
+            and (fixture / name).read_text(encoding="utf-8") != text
+        ]
+        if rewritten:
+            report(
+                "source-repo-bootstrap-skip: keel --install rewrote files it "
+                "did not announce: " + ", ".join(sorted(rewritten))
+            )
+            return 1
     # A consuming project must still receive the bootstrap.
     with tempfile.TemporaryDirectory(prefix="keel-bootstrap-consumer-") as raw:
         consumer = Path(raw)
@@ -4611,6 +5227,9 @@ def validate_tracker_durable_owner_scenario() -> int:
             report((handoff.stderr or handoff.stdout).strip())
             return 1
 
+        # The archive path must now exist to own anything: a note nobody wrote
+        # owns nothing, and a path is the one owner form a gate can check.
+        write_text(repo / "keel/archive/follow-ups/x.md", "follow-up note\n")
         archived = complete("stale local note; owner keel/archive/follow-ups/x.md")
         if archived.returncode != 0:
             report(
@@ -7661,13 +8280,7 @@ def validate_expectation_alignment_real_tasks_scenario() -> int:
 
 
 def validate_compact_task_authoring_scenario() -> int:
-    source_root = (
-        ROOT / "src" / "assets" / "shared" / "openspec" / "schemas" / OPENSPEC_SCHEMA_NAME
-    )
     local_root = ROOT / "openspec" / "schemas" / OPENSPEC_SCHEMA_NAME
-    dist_root = (
-        ROOT / "dist" / "shared" / "assets" / "openspec" / "schemas" / OPENSPEC_SCHEMA_NAME
-    )
 
     which = run_openspec(ROOT, "schema", "which", OPENSPEC_SCHEMA_NAME, "--json")
     if which is None or which.returncode != 0:
@@ -7726,21 +8339,9 @@ def validate_compact_task_authoring_scenario() -> int:
             )
             return 1
 
-    for projection_root, label in ((dist_root, "dist"), (local_root, "repo-local")):
-        for source_file in sorted(source_root.rglob("*")):
-            if not source_file.is_file():
-                continue
-            relative = source_file.relative_to(source_root)
-            projected = projection_root / relative
-            if not projected.is_file() or (
-                source_file.read_text(encoding="utf-8")
-                != projected.read_text(encoding="utf-8")
-            ):
-                report(
-                    f"compact-task-authoring {label} projection diverges from "
-                    f"canonical source: {relative.as_posix()}"
-                )
-                return 1
+    # The projection loop that stood here compared against `src/assets` and
+    # `dist`, both retired, so it iterated nothing. `invalidation-authoring-surface`
+    # asserts the two copies that do exist are byte-identical.
 
     with tempfile.TemporaryDirectory(prefix="keel-compact-") as raw_tmp:
         repo = Path(raw_tmp) / "fixture"
@@ -10287,6 +10888,20 @@ def validate_thin_native_install_scenario() -> int:
             )
             return 1
 
+        # The bootstrap is the whole resident protocol a consumer gets, and the
+        # qualifier "for product files" left readers to infer what it excluded.
+        # The inference actually made was that tasks.md belongs in Touch.
+        if not re.search(r"Touch\b[^\n]*\bbound", block, re.IGNORECASE):
+            report("thin-native-install bootstrap does not state what Touch bounds.")
+            return 1
+        if not re.search(r"change'?s own dir|own change dir", block, re.IGNORECASE):
+            report(
+                "thin-native-install bootstrap does not name the record-write "
+                "exemption, so a consumer still infers that tasks.md belongs in "
+                "Touch."
+            )
+            return 1
+
         claude_text = (repo / "CLAUDE.md").read_text(encoding="utf-8")
         if claude_text.count("@AGENTS.md") != 1:
             report(
@@ -11006,7 +11621,7 @@ def validate_resident_topic_matching_scenario() -> int:
     """
     label = "resident-topic-matching"
     source = (ROOT / "assets/bootstrap/AGENTS.md").read_text(encoding="utf-8")
-    original = "Touch is the write boundary for product files;"
+    original = "Touch bounds product writes; the change's own dir is exempt."
     if original not in source:
         report(
             f"{label}: the fixture's anchor sentence is not in the bootstrap; "
@@ -12073,7 +12688,11 @@ def validate_touch_guard_surface_scenario() -> int:
                 report(f"touch-guard-surface: README lacks guard guidance: {needle}.")
                 return 1
         bootstrap = (ROOT / "assets/bootstrap/AGENTS.md").read_text(encoding="utf-8")
-        if "keel guard" not in bootstrap:
+        # The bootstrap must tell a consumer the guard exists and how to opt out;
+        # it no longer spends bytes naming `keel guard clear`, which `keel --help`
+        # and `keel guard status` carry. `--no-guard` is the flag it does name, so
+        # that one stays literal and a rename of it still fails here.
+        if "--no-guard" not in bootstrap or "guards it by default" not in bootstrap:
             report("touch-guard-surface: bootstrap does not mention the guard.")
             return 1
         registered = {name for name, _ in SCENARIOS}
@@ -12452,6 +13071,17 @@ SCENARIOS: tuple = (
     ("runner-skip-accounting", validate_runner_skip_accounting_scenario),
     ("resident-topic-matching", validate_resident_topic_matching_scenario),
     ("task-start-invalidation", validate_task_start_invalidation_scenario),
+    ("regression-check-tag", validate_regression_check_tag_scenario),
+    ("durable-owner-vocabulary", validate_durable_owner_vocabulary_scenario),
+    ("anchor-reverification-bound", validate_anchor_reverification_bound_scenario),
+    (
+        "authoring-surface-owner-and-tags",
+        validate_authoring_surface_owner_and_tags_scenario,
+    ),
+    (
+        "packaged-schema-derivation",
+        validate_packaged_schema_derivation_scenario,
+    ),
     (
         "invalidation-authoring-surface",
         validate_invalidation_authoring_surface_scenario,