@christang/keel 5.2.1 → 5.2.3

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.2.1"
-PROTOCOL_VERSION = "5.2.1"
+PACKAGE_VERSION = "5.2.3"
+PROTOCOL_VERSION = "5.2.3"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 OPENSPEC_CONFIG_PATH = Path("openspec/config.yaml")
@@ -3713,6 +3713,520 @@ def task_capsule_compact_fixture() -> str:
     )
 
 
+def validate_non_concrete_verify_diagnostic_scenario() -> int:
+    """A compact v4 task whose Verify carries an unfilled token must be told so.
+
+    Regression for issue #7 example 1: the compact/expanded decision reads
+    isConcrete(Verify), so one unfilled token used to select the expanded v3
+    required-field set and report fields the author never declared.
+    """
+    v3_only_fields = (
+        "Owner",
+        "Read",
+        "Commands",
+        "Acceptance",
+        "Candidate Boundary",
+        "Report",
+    )
+    with tempfile.TemporaryDirectory(prefix="keel-non-concrete-verify-") as raw_tmp:
+        repo = Path(raw_tmp)
+        # A bare token in prose. The reporter's own case wrote it inside an
+        # inline code span, which the inline-code-is-concrete scenario now
+        # covers as legitimately filled; what must still be reported is a token
+        # standing unfenced in the text.
+        task = task_capsule_compact_fixture().replace(
+            "    - M1: node test.js\n",
+            "    - M1: node test.js writes ledger/scan-log/<date>.md\n",
+        )
+        write_text(repo / "openspec/changes/demo/tasks.md", task)
+        started = run_keel(
+            repo,
+            "gate",
+            "task-start",
+            "--change",
+            "demo",
+            "--task",
+            "1.1",
+            "--json",
+        )
+        payload = json.loads(started.stdout)
+        problems = payload.get("problems", [])
+        codes = {problem.get("code") for problem in problems}
+        if "non-concrete-verify" not in codes:
+            report(
+                "non-concrete-verify-diagnostic: an unfilled token in Verify did "
+                "not produce the non-concrete-verify diagnostic."
+            )
+            report(started.stdout.strip())
+            return 1
+        named = [
+            problem
+            for problem in problems
+            if problem.get("code") == "non-concrete-verify"
+            and "<date>" in problem.get("message", "")
+        ]
+        if not named:
+            report(
+                "non-concrete-verify-diagnostic: the diagnostic did not name the "
+                "matched token."
+            )
+            report(started.stdout.strip())
+            return 1
+        leaked = sorted(
+            field
+            for problem in problems
+            if problem.get("code") == "missing-field"
+            for field in v3_only_fields
+            if problem.get("message", "").startswith(f"{field} must be concrete")
+        )
+        if leaked:
+            report(
+                "non-concrete-verify-diagnostic: expanded v3 fields were still "
+                f"reported as missing: {', '.join(leaked)}."
+            )
+            report(started.stdout.strip())
+            return 1
+        # A task with no Verify at all is a genuine expanded v3 task and must
+        # keep its existing required-field diagnostics.
+        bare = task_capsule_compact_fixture()
+        for block in (
+            "  - Verify:\n    - Strategy: evidence-first\n    - M1: node test.js\n",
+        ):
+            bare = bare.replace(block, "")
+        write_text(repo / "openspec/changes/bare/tasks.md", bare)
+        bare_started = run_keel(
+            repo,
+            "gate",
+            "task-start",
+            "--change",
+            "bare",
+            "--task",
+            "1.1",
+            "--json",
+        )
+        bare_payload = json.loads(bare_started.stdout)
+        bare_codes = {
+            problem.get("code") for problem in bare_payload.get("problems", [])
+        }
+        if "non-concrete-verify" in bare_codes:
+            report(
+                "non-concrete-verify-diagnostic: a task with no Verify was "
+                "reported as carrying an unfilled token."
+            )
+            report(bare_started.stdout.strip())
+            return 1
+    if "non-concrete-verify-diagnostic" not in {name for name, _ in SCENARIOS}:
+        report(
+            "non-concrete-verify-diagnostic: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("non-concrete-verify-diagnostic scenario passed.")
+    return 0
+
+
+def validate_inline_code_is_concrete_scenario() -> int:
+    """Unfilled-token forms inside inline code spans are documented patterns.
+
+    Regression for issue #7 example 1: the reporter's Verify wrote a filename
+    pattern inside backticks and it was still judged unfilled. The exemption
+    covers every token form, not only angle brackets, because prose naming the
+    keywords is equally common — see
+    keel/archive/follow-ups/2026-07-27-unfilled-token-keywords.md.
+    """
+    fenced_m1 = (
+        "    - M1: node test.js writes `ledger/scan-log/<date>.md`, skips a "
+        "`TODO` marker, and leaves `TBD` rows alone\n"
+    )
+    bare_m1 = "    - M1: node test.js writes ledger/scan-log/<date>.md\n"
+    with tempfile.TemporaryDirectory(prefix="keel-inline-code-") as raw_tmp:
+        repo = Path(raw_tmp)
+        write_text(
+            repo / "openspec/changes/fenced/tasks.md",
+            task_capsule_compact_fixture().replace(
+                "    - M1: node test.js\n", fenced_m1
+            ),
+        )
+        fenced = run_keel(
+            repo, "gate", "task-start", "--change", "fenced", "--task", "1.1", "--json"
+        )
+        if fenced.returncode != 0:
+            report(
+                "inline-code-is-concrete: token forms inside inline code spans "
+                "were still judged unfilled."
+            )
+            report((fenced.stdout or fenced.stderr).strip())
+            return 1
+        # The same token outside inline code must still be caught, otherwise the
+        # exemption has swallowed the check it is narrowing.
+        write_text(
+            repo / "openspec/changes/bare/tasks.md",
+            task_capsule_compact_fixture().replace(
+                "    - M1: node test.js\n", bare_m1
+            ),
+        )
+        bare = run_keel(
+            repo, "gate", "task-start", "--change", "bare", "--task", "1.1", "--json"
+        )
+        bare_codes = {
+            problem.get("code")
+            for problem in json.loads(bare.stdout).get("problems", [])
+        }
+        if "non-concrete-verify" not in bare_codes:
+            report(
+                "inline-code-is-concrete: a bare token outside inline code was "
+                "no longer reported as unfilled."
+            )
+            report(bare.stdout.strip())
+            return 1
+        # Stripping runs after the emptiness test, so a field that is entirely
+        # one code span must not read as empty.
+        write_text(
+            repo / "openspec/changes/whole/tasks.md",
+            task_capsule_compact_fixture()
+            .replace("    - M1: node test.js\n", "    - M1: `node test.js`\n")
+            .replace("    - src/feature.js\n", "    - `src/feature.js`\n"),
+        )
+        whole = run_keel(
+            repo, "gate", "task-start", "--change", "whole", "--task", "1.1", "--json"
+        )
+        if whole.returncode != 0:
+            report(
+                "inline-code-is-concrete: a field whose whole value is one "
+                "inline code span was judged empty."
+            )
+            report((whole.stdout or whole.stderr).strip())
+            return 1
+    if "inline-code-is-concrete" not in {name for name, _ in SCENARIOS}:
+        report("inline-code-is-concrete: the scenario registry does not include it.")
+        return 1
+    report("inline-code-is-concrete scenario passed.")
+    return 0
+
+
+def validate_covers_separator_collision_scenario() -> int:
+    """Issue #7 example 2: a requirement name containing the hierarchy separator.
+
+    Both spellings the reporter tried must fail loudly and say why. Keeping the
+    slash over-segments the reference, which used to compile to an unlinked
+    legacy-task-reference and PASS; removing it resolves nothing and used to
+    give a generic message.
+    """
+    collide = "Continue or downgrade or switch/window criteria"
+
+    def spec(requirement: str) -> str:
+        return (
+            "# cap\n\n## Purpose\nDemo.\n\n"
+            f"### Requirement: {requirement}\nText.\n\n"
+            "#### Scenario: Criteria cover three outcomes\n"
+            "- **WHEN** a thing\n- **THEN** another\n"
+        )
+
+    def tasks(reference: str) -> str:
+        return task_capsule_compact_fixture().replace(
+            "    - E1: Public behavior passes.\n", f"    - {reference}\n"
+        )
+
+    with tempfile.TemporaryDirectory(prefix="keel-covers-collision-") as raw_tmp:
+        repo = Path(raw_tmp)
+        write_text(repo / "openspec/specs/collide-cap/spec.md", spec(collide))
+        write_text(repo / "openspec/specs/clean-cap/spec.md", spec("Plain name"))
+
+        def start(change: str, reference: str):
+            write_text(repo / f"openspec/changes/{change}/tasks.md", tasks(reference))
+            result = run_keel(
+                repo, "gate", "task-start", "--change", change, "--task", "1.1",
+                "--json",
+            )
+            return json.loads(result.stdout)
+
+        # The reporter's correct spelling: over-segmented, capability is real.
+        kept = start(
+            "kept",
+            f"collide-cap / {collide} / Criteria cover three outcomes",
+        )
+        kept_messages = " ".join(
+            problem.get("message", "") for problem in kept.get("problems", [])
+        )
+        kept_kinds = {
+            entry.get("kind")
+            for entry in kept.get("contract", {})
+            .get("capsule", {})
+            .get("authority", [])
+        }
+        if kept.get("status") != "fail" or "legacy-task-reference" in kept_kinds:
+            report(
+                "covers-separator-collision: an over-segmented reference to a "
+                "real capability still degraded to a free-text reference."
+            )
+            report(json.dumps(kept.get("problems"), ensure_ascii=False))
+            return 1
+        if collide not in kept_messages or "separator" not in kept_messages:
+            report(
+                "covers-separator-collision: the over-segmented diagnostic did "
+                "not name the colliding requirement."
+            )
+            report(kept_messages)
+            return 1
+        # The reporter's fallback spelling: resolves to nothing.
+        trimmed = start(
+            "trimmed",
+            "collide-cap / Continue or downgrade or switchwindow criteria"
+            " / Criteria cover three outcomes",
+        )
+        trimmed_messages = " ".join(
+            problem.get("message", "") for problem in trimmed.get("problems", [])
+        )
+        if collide not in trimmed_messages:
+            report(
+                "covers-separator-collision: the unresolved diagnostic did not "
+                "name the colliding requirement."
+            )
+            report(trimmed_messages)
+            return 1
+        # A capability with no collision keeps the plain wording.
+        plain = start(
+            "plain", "clean-cap / No such requirement / No such scenario"
+        )
+        plain_messages = " ".join(
+            problem.get("message", "") for problem in plain.get("problems", [])
+        )
+        if "separator" in plain_messages:
+            report(
+                "covers-separator-collision: a capability with no colliding "
+                "name still received the separator hint."
+            )
+            report(plain_messages)
+            return 1
+        # Free text that merely contains slashes is not a spec reference.
+        free = start("free", "E1: writes a/b/c and passes")
+        free_kinds = {
+            entry.get("kind")
+            for entry in free.get("contract", {})
+            .get("capsule", {})
+            .get("authority", [])
+        }
+        if free.get("status") != "pass" or free_kinds != {"legacy-task-reference"}:
+            report(
+                "covers-separator-collision: free text containing slashes was "
+                "no longer accepted as a legacy reference."
+            )
+            report(json.dumps(free.get("problems"), ensure_ascii=False))
+            return 1
+    if "covers-separator-collision" not in {name for name, _ in SCENARIOS}:
+        report(
+            "covers-separator-collision: the scenario registry does not include it."
+        )
+        return 1
+    report("covers-separator-collision scenario passed.")
+    return 0
+
+
+def validate_unresolved_authority_names_field_scenario() -> int:
+    """Issue #7 example 3: the diagnostic must name what it actually reads.
+
+    The check reads only the task's `Pre-authorized fallback:` line. The old
+    wording said "documented design authority", which sent authors to design.md
+    where the answer usually already was.
+    """
+    with tempfile.TemporaryDirectory(prefix="keel-unresolved-authority-") as raw:
+        repo = Path(raw)
+        # design.md documents Q1 and an authorized fallback in prose, which is
+        # exactly the state the reporter was in when the message misdirected.
+        write_text(
+            repo / "openspec/changes/demo/design.md",
+            "## Questions\n\nQ1 — Should the widget retry on timeout?\n\n"
+            "Authorized fallback: retry twice with backoff, then stop.\n",
+        )
+        without = task_capsule_compact_fixture().replace(
+            "    - E1: Public behavior passes.\n", "    - Q1\n"
+        )
+        write_text(repo / "openspec/changes/demo/tasks.md", without)
+        result = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+        )
+        payload = json.loads(result.stdout)
+        messages = [
+            problem.get("message", "")
+            for problem in payload.get("problems", [])
+            if problem.get("code") == "unresolved-authority"
+        ]
+        if not messages:
+            report(
+                "unresolved-authority-names-field: a Q reference with no "
+                "authorized fallback produced no unresolved-authority diagnostic."
+            )
+            report(result.stdout.strip())
+            return 1
+        message = messages[0]
+        required = ("Autonomy boundary:", "Pre-authorized fallback:", "design.md")
+        missing = [needle for needle in required if needle not in message]
+        if missing:
+            report(
+                "unresolved-authority-names-field: the diagnostic omitted "
+                f"{', '.join(missing)}."
+            )
+            report(message)
+            return 1
+        if "documented design authority" in message:
+            report(
+                "unresolved-authority-names-field: the diagnostic still points "
+                "at design.md as the thing to add."
+            )
+            report(message)
+            return 1
+        # Doing literally what the message asks must clear it.
+        with_fallback = without.replace(
+            "    - Pre-authorized fallback: none\n",
+            "    - Pre-authorized fallback: retry twice with backoff then stop;"
+            " evidence is the retry log\n",
+        )
+        write_text(repo / "openspec/changes/fixed/tasks.md", with_fallback)
+        write_text(
+            repo / "openspec/changes/fixed/design.md",
+            "## Questions\n\nQ1 — Should the widget retry on timeout?\n",
+        )
+        fixed = run_keel(
+            repo, "gate", "task-start", "--change", "fixed", "--task", "1.1", "--json"
+        )
+        if fixed.returncode != 0:
+            report(
+                "unresolved-authority-names-field: following the diagnostic did "
+                "not clear it."
+            )
+            report((fixed.stdout or fixed.stderr).strip())
+            return 1
+    if "unresolved-authority-names-field" not in {name for name, _ in SCENARIOS}:
+        report(
+            "unresolved-authority-names-field: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("unresolved-authority-names-field scenario passed.")
+    return 0
+
+
+def validate_dev_only_plugin_source_scoping_scenario() -> int:
+    """Issue #6: plugins/keel/ exists only in Keel's own repository.
+
+    In a consuming project the source check is permanently `missing` and the
+    next line told the author to install a plugin they had just installed.
+    """
+    with tempfile.TemporaryDirectory(prefix="keel-dev-only-scope-") as raw:
+        consumer = Path(raw)
+        init = run_keel(consumer, "--init", "--target", "claude")
+        if init.returncode != 0:
+            report("dev-only-plugin-source-scoping: keel --init failed.")
+            report((init.stderr or init.stdout).strip())
+            return 1
+        doctor = run_keel(consumer, "--doctor")
+        out = doctor.stdout or ""
+        if "native plugin source" in out:
+            report(
+                "dev-only-plugin-source-scoping: a consuming project was still "
+                "shown the development-only plugin source check."
+            )
+            report(out)
+            return 1
+        if "install the plugin if it is missing" in out:
+            report(
+                "dev-only-plugin-source-scoping: a consuming project was still "
+                "told to install an already-installed plugin."
+            )
+            report(out)
+            return 1
+        if "plugin source" in out:
+            report(
+                "dev-only-plugin-source-scoping: the plugin source clause "
+                "leaked into a consuming project's capability lines."
+            )
+            report(out)
+            return 1
+        # Keel's own repository must keep the check, which is where it means
+        # something: the manifest and the CLI have to agree before release.
+        own = run_keel(ROOT, "--doctor")
+        if "native plugin source" not in (own.stdout or ""):
+            report(
+                "dev-only-plugin-source-scoping: Keel's own repository lost the "
+                "plugin source check."
+            )
+            report((own.stdout or own.stderr).strip())
+            return 1
+    if "dev-only-plugin-source-scoping" not in {name for name, _ in SCENARIOS}:
+        report(
+            "dev-only-plugin-source-scoping: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("dev-only-plugin-source-scoping scenario passed.")
+    return 0
+
+
+def validate_source_repo_bootstrap_skip_scenario() -> int:
+    """Issue #9: `keel --install` must not overwrite Keel's own AGENTS.md.
+
+    Keel's repository AGENTS.md carries the full protocol that four scenarios
+    assert on; the packaged asset is the shorter consumer bootstrap. Writing it
+    here drops those sections and turns the repository red.
+    """
+    managed = re.compile(
+        r"<!--\s*keel:start.*?<!--\s*keel:end\s*-->", re.DOTALL
+    )
+
+    def block(path: Path) -> str:
+        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:
+        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
+    # A consuming project must still receive the bootstrap.
+    with tempfile.TemporaryDirectory(prefix="keel-bootstrap-consumer-") as raw:
+        consumer = Path(raw)
+        installed = run_keel(consumer, "--install", "--target", "claude")
+        if installed.returncode != 0:
+            report(
+                "source-repo-bootstrap-skip: keel --install failed in a "
+                "consuming project."
+            )
+            report((installed.stderr or installed.stdout).strip())
+            return 1
+        asset_block = block(ROOT / "assets/bootstrap/AGENTS.md")
+        if block(consumer / "AGENTS.md") != asset_block:
+            report(
+                "source-repo-bootstrap-skip: a consuming project did not "
+                "receive the packaged bootstrap block."
+            )
+            return 1
+    if "source-repo-bootstrap-skip" not in {name for name, _ in SCENARIOS}:
+        report(
+            "source-repo-bootstrap-skip: the scenario registry does not include it."
+        )
+        return 1
+    report("source-repo-bootstrap-skip scenario passed.")
+    return 0
+
+
 def validate_task_capsule_scenario() -> int:
     with tempfile.TemporaryDirectory(prefix="keel-task-capsule-") as raw_tmp:
         repo = Path(raw_tmp)
@@ -4887,14 +5401,19 @@ def validate_core_gates_scenario() -> int:
         (completion_repo / "openspec/changes/other/proposal.md").unlink()
         (completion_repo / "openspec/specs/demo-spec/spec.md").unlink()
 
-        # Explicit --record replaces exactly the selected task's literal
-        # pending Contract anchor; a non-pending or missing anchor refuses
-        # loudly writing nothing; without the flag the gate stays read-only.
+        # Explicit --record replaces the selected task's Contract anchor
+        # whatever it currently holds, so reauthorizing a task whose authority
+        # changed needs no manual edit; a no-op re-record writes nothing, only
+        # a missing anchor refuses, and without the flag the gate stays
+        # read-only.
         record_repo = root / "record-anchor"
         record_repo.mkdir()
         record_tasks = record_repo / "openspec/changes/demo/tasks.md"
 
-        def record_task(anchor: str) -> str:
+        def record_task(anchor: str, extra_touch: bool = False) -> str:
+            touch = "    - src/feature.js\n"
+            if extra_touch:
+                touch += "    - src/extra.js\n"
             return (
                 "# Tasks\n\n"
                 "- [ ] 1.1 Record behavior\n"
@@ -4905,8 +5424,8 @@ def validate_core_gates_scenario() -> int:
                 "  - Read:\n"
                 "    - README.md\n"
                 "  - Touch:\n"
-                "    - src/feature.js\n"
-                "    - openspec/changes/demo/tasks.md\n"
+                + touch
+                + "    - openspec/changes/demo/tasks.md\n"
                 "  - Commands:\n"
                 "    - M1: node test.js\n"
                 "  - Acceptance:\n"
@@ -4951,8 +5470,15 @@ def validate_core_gates_scenario() -> int:
             report("core-gates scenario --record on a pending anchor failed.")
             report((recorded.stderr or recorded.stdout).strip())
             return 1
+        recorded_result = json.loads(recorded.stdout)
+        if recorded_result.get("record", {}).get("status") != "recorded":
+            report(
+                "core-gates scenario --record over a pending anchor must "
+                "report the outcome as recorded."
+            )
+            return 1
         fingerprint = (
-            json.loads(recorded.stdout)
+            recorded_result
             .get("contract", {})
             .get("fingerprint", {})
             .get("value", "")
@@ -4993,23 +5519,67 @@ def validate_core_gates_scenario() -> int:
             )
             return 1
 
-        before_refusal = record_tasks.read_bytes()
+        before_noop = record_tasks.read_bytes()
+        noop = run_keel(
+            record_repo, "gate", "task-start",
+            "--change", "demo", "--task", "1.1", "--no-guard", "--record",
+            "--json",
+        )
+        noop_result = json.loads(noop.stdout) if noop.stdout else {}
+        if (
+            noop.returncode != 0
+            or noop_result.get("record", {}).get("status") != "unchanged"
+            or noop_result.get("warnings")
+            or record_tasks.read_bytes() != before_noop
+        ):
+            report(
+                "core-gates scenario --record over an anchor that already "
+                "carries the compiled fingerprint must report unchanged, "
+                "warn about nothing, and write nothing."
+            )
+            report((noop.stderr or noop.stdout).strip())
+            return 1
+
+        # Reauthorization: the task authority changes, so the recorded anchor
+        # is now stale and --record must replace it rather than refuse.
+        anchor_line = f"keel-task-capsule/v1 sha256:{fingerprint}"
+        write_text(record_tasks, record_task(anchor_line, extra_touch=True))
+        before_rerecord = record_tasks.read_text(encoding="utf-8").splitlines()
         rerecord = run_keel(
             record_repo, "gate", "task-start",
             "--change", "demo", "--task", "1.1", "--no-guard", "--record",
             "--json",
         )
+        rerecord_result = json.loads(rerecord.stdout) if rerecord.stdout else {}
+        new_fingerprint = (
+            rerecord_result.get("contract", {}).get("fingerprint", {}).get("value", "")
+        )
+        after_rerecord = record_tasks.read_text(encoding="utf-8").splitlines()
+        rerecord_changed = [
+            (old, new)
+            for old, new in zip(before_rerecord, after_rerecord)
+            if old != new
+        ]
         if (
-            rerecord.returncode != 3
+            rerecord.returncode != 0
+            or rerecord_result.get("record", {}).get("status") != "rerecorded"
+            or fingerprint not in rerecord_result.get("record", {}).get("previous", "")
+            or not new_fingerprint
+            or new_fingerprint == fingerprint
+            or len(before_rerecord) != len(after_rerecord)
+            or len(rerecord_changed) != 1
+            or rerecord_changed[0][1]
+            != f"    - Contract: keel-task-capsule/v1 sha256:{new_fingerprint}"
             or not any(
-                problem.get("code") == "record-refused"
-                for problem in json.loads(rerecord.stdout).get("problems", [])
+                fingerprint in warning
+                for warning in rerecord_result.get("warnings", [])
             )
-            or record_tasks.read_bytes() != before_refusal
         ):
             report(
-                "core-gates scenario --record on an already-recorded anchor "
-                "must refuse deterministically and write nothing."
+                "core-gates scenario --record over a stale recorded anchor "
+                "must replace exactly that line with the new fingerprint, "
+                "report the outcome as rerecorded with the replaced value, "
+                "and warn naming the fingerprint it replaced."
             )
             report((rerecord.stderr or rerecord.stdout).strip())
             return 1
@@ -7687,6 +8257,297 @@ def validate_native_tasks_view_scenario() -> int:
     return 0
 
 
+def validate_verification_layering_docs_scenario() -> int:
+    en = (ROOT / "README.md").read_text(encoding="utf-8")
+    for needle in (
+        "## Verification layering",
+        "inner-loop",
+        "Full gate",
+        "pre-push",
+        "change-close",
+    ):
+        if needle not in en:
+            report(
+                "verification-layering-docs: README.md lacks the fast/full "
+                f"verification split marker: {needle}"
+            )
+            return 1
+
+    zh = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8")
+    for needle in ("## 验证分层", "快速内环", "全量门禁", "pre-push", "change-close"):
+        if needle not in zh:
+            report(
+                "verification-layering-docs: README.zh-CN.md lacks the fast/full "
+                f"verification split marker: {needle}"
+            )
+            return 1
+
+    if "verification-layering-docs" not in {name for name, _ in SCENARIOS}:
+        report("verification-layering-docs: the scenario registry does not include it.")
+        return 1
+
+    report("verification-layering-docs scenario passed.")
+    return 0
+
+
+def validate_fast_check_config_scaffold_scenario() -> int:
+    with tempfile.TemporaryDirectory(prefix="keel-fastcfg-") as raw_tmp:
+        repo = Path(raw_tmp)
+        first = run_keel(repo, "--install")
+        if first.returncode != 0:
+            report("fast-check-config-scaffold: keel --install failed.")
+            report((first.stderr or first.stdout).strip())
+            return 1
+
+        config_path = repo / "keel" / "config.yaml"
+        if not config_path.is_file():
+            report("fast-check-config-scaffold: install did not scaffold keel/config.yaml.")
+            return 1
+        scaffolded = config_path.read_text(encoding="utf-8")
+        for needle in ("fast_check", "keel gate change-close", "--with-git-hooks"):
+            if needle not in scaffolded:
+                report(
+                    "fast-check-config-scaffold: scaffolded keel/config.yaml lacks the "
+                    f"fast_check guidance marker: {needle}"
+                )
+                return 1
+
+        # A project's own edits to keel/config.yaml must survive re-install.
+        edited = "fast_check: pytest -m 'not slow' -q\n"
+        config_path.write_text(edited, encoding="utf-8")
+        second = run_keel(repo, "--install")
+        if second.returncode != 0:
+            report("fast-check-config-scaffold: second keel --install failed.")
+            report((second.stderr or second.stdout).strip())
+            return 1
+        if config_path.read_text(encoding="utf-8") != edited:
+            report(
+                "fast-check-config-scaffold: re-install overwrote an existing "
+                "keel/config.yaml."
+            )
+            return 1
+
+    report("fast-check-config-scaffold scenario passed.")
+    return 0
+
+
+def validate_fast_pre_push_hooks_scenario() -> int:
+    def git(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["git", "-C", str(repo), *args], capture_output=True, text=True
+        )
+
+    def init_repo(root: Path, name: str) -> Path:
+        repo = root / name
+        repo.mkdir()
+        git(repo, "init", "-q")
+        git(repo, "config", "user.email", "t@example.com")
+        git(repo, "config", "user.name", "keel-test")
+        return repo
+
+    def declare_fast_check(repo: Path, command: str) -> None:
+        (repo / "keel").mkdir(exist_ok=True)
+        (repo / "keel" / "config.yaml").write_text(
+            f"fast_check: {command}\n", encoding="utf-8"
+        )
+
+    def hooks_path(repo: Path) -> str | None:
+        got = git(repo, "config", "--local", "--get", "core.hooksPath")
+        return got.stdout.strip() if got.returncode == 0 else None
+
+    with tempfile.TemporaryDirectory(prefix="keel-prepush-") as raw_tmp:
+        root = Path(raw_tmp)
+
+        # 1. A declared fast_check generates the hook and sets hooksPath.
+        declared = init_repo(root, "declared")
+        declare_fast_check(declared, "echo fast-check-ran")
+        res = run_keel(declared, "--install", "--with-git-hooks")
+        if res.returncode != 0:
+            report("fast-pre-push-hooks: --with-git-hooks failed with a declared fast_check.")
+            report((res.stderr or res.stdout).strip())
+            return 1
+        hook = declared / ".githooks" / "pre-push"
+        if not hook.is_file():
+            report("fast-pre-push-hooks: --with-git-hooks did not write .githooks/pre-push.")
+            return 1
+        hook_text = hook.read_text(encoding="utf-8")
+        if not hook_text.startswith("#!/bin/sh") or "echo fast-check-ran" not in hook_text:
+            report("fast-pre-push-hooks: pre-push does not run the declared fast_check under sh.")
+            report(hook_text)
+            return 1
+        if hooks_path(declared) != ".githooks":
+            report("fast-pre-push-hooks: --with-git-hooks did not set core.hooksPath to .githooks.")
+            return 1
+
+        # 2. A plain install touches neither the hook nor git config.
+        plain = init_repo(root, "plain")
+        declare_fast_check(plain, "echo plain")
+        if run_keel(plain, "--install").returncode != 0:
+            report("fast-pre-push-hooks: plain install failed.")
+            return 1
+        if (plain / ".githooks" / "pre-push").exists():
+            report("fast-pre-push-hooks: plain install wrote a pre-push hook.")
+            return 1
+        if hooks_path(plain) is not None:
+            report("fast-pre-push-hooks: plain install set core.hooksPath.")
+            return 1
+
+        # 3. Without a declared fast_check the flag refuses and writes nothing.
+        undeclared = init_repo(root, "undeclared")
+        res = run_keel(undeclared, "--install", "--with-git-hooks")
+        if res.returncode == 0:
+            report("fast-pre-push-hooks: --with-git-hooks did not refuse without a fast_check.")
+            return 1
+        if (undeclared / ".githooks" / "pre-push").exists():
+            report("fast-pre-push-hooks: a refusal still wrote a pre-push hook.")
+            return 1
+        if hooks_path(undeclared) is not None:
+            report("fast-pre-push-hooks: a refusal still set core.hooksPath.")
+            return 1
+
+        # 4a. Uninstall reverts a keel-set core.hooksPath.
+        if run_keel(declared, "--uninstall").returncode != 0:
+            report("fast-pre-push-hooks: uninstall failed.")
+            return 1
+        if hooks_path(declared) is not None:
+            report("fast-pre-push-hooks: uninstall did not unset a keel-set core.hooksPath.")
+            return 1
+
+        # 4b. Uninstall leaves a non-.githooks core.hooksPath untouched.
+        custom = init_repo(root, "custom")
+        git(custom, "config", "--local", "core.hooksPath", ".customhooks")
+        if run_keel(custom, "--uninstall").returncode != 0:
+            report("fast-pre-push-hooks: uninstall failed on a custom hooksPath repo.")
+            return 1
+        if hooks_path(custom) != ".customhooks":
+            report("fast-pre-push-hooks: uninstall clobbered a non-keel core.hooksPath.")
+            return 1
+
+    report("fast-pre-push-hooks scenario passed.")
+    return 0
+
+
+def validate_fast_pre_push_doctor_scenario() -> int:
+    def git(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["git", "-C", str(repo), *args], capture_output=True, text=True
+        )
+
+    def init_repo(root: Path, name: str) -> Path:
+        repo = root / name
+        repo.mkdir()
+        git(repo, "init", "-q")
+        git(repo, "config", "user.email", "t@example.com")
+        git(repo, "config", "user.name", "keel-test")
+        return repo
+
+    with tempfile.TemporaryDirectory(prefix="keel-prepush-doc-") as raw_tmp:
+        root = Path(raw_tmp)
+
+        # Surface active: fast_check declared and --with-git-hooks applied.
+        active = init_repo(root, "active")
+        (active / "keel").mkdir()
+        (active / "keel" / "config.yaml").write_text(
+            "fast_check: echo doc-check\n", encoding="utf-8"
+        )
+        if run_keel(active, "--install", "--with-git-hooks").returncode != 0:
+            report("fast-pre-push-doctor: install --with-git-hooks failed.")
+            return 1
+        before = git(active, "config", "--local", "--get", "core.hooksPath").stdout.strip()
+        out = run_keel(active, "--doctor").stdout
+        for needle in (
+            "Fast pre-push surface:",
+            "fast_check: ok",
+            "echo doc-check",
+            "pre-push hook: ok",
+            "core.hooksPath: ok",
+        ):
+            if needle not in out:
+                report(f"fast-pre-push-doctor: active-surface doctor output lacks: {needle}")
+                report(out)
+                return 1
+        after = git(active, "config", "--local", "--get", "core.hooksPath").stdout.strip()
+        if before != after:
+            report("fast-pre-push-doctor: doctor mutated core.hooksPath.")
+            return 1
+
+        # Surface absent: plain install, no fast_check, no hook.
+        absent = init_repo(root, "absent")
+        if run_keel(absent, "--install").returncode != 0:
+            report("fast-pre-push-doctor: plain install failed.")
+            return 1
+        out = run_keel(absent, "--doctor").stdout
+        for needle in ("fast_check: none", "pre-push hook: none", "core.hooksPath: unset"):
+            if needle not in out:
+                report(f"fast-pre-push-doctor: absent-surface doctor output lacks: {needle}")
+                report(out)
+                return 1
+
+    report("fast-pre-push-doctor scenario passed.")
+    return 0
+
+
+def validate_verify_layer_tag_scenario() -> int:
+    fixture = (
+        "# Tasks\n\n"
+        "- [ ] 1.1 Exercise the verification-layer tag\n"
+        "  - Covers:\n"
+        "    - E1: Public behavior passes.\n"
+        "  - Read:\n"
+        "    - README.md\n"
+        "  - Touch:\n"
+        "    - src/feature.js\n"
+        "  - Verify:\n"
+        "    - Strategy: evidence-first\n"
+        "    - M1 (fast): node fast.js\n"
+        "    - M2: node full.js\n"
+        "  - Autonomy boundary:\n"
+        "    - Default: hard-stop\n"
+        "    - Pre-authorized fallback: none\n"
+        "  - Stop Rules:\n"
+        "    - Stop on failure.\n"
+        "  - Evidence:\n"
+        "    - M1: pending\n"
+        "    - M2: pending\n"
+        "  - Stop if:\n"
+        "    - Requires files outside Touch.\n"
+    )
+    with tempfile.TemporaryDirectory(prefix="keel-verify-layer-") as raw_tmp:
+        repo = Path(raw_tmp)
+        write_text(repo / "openspec/changes/demo/tasks.md", fixture)
+        started = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+        )
+        if started.returncode != 0:
+            report("verify-layer-tag: task-start rejected the tagged fixture.")
+            report((started.stderr or started.stdout).strip())
+            return 1
+        capsule = json.loads(started.stdout).get("contract", {}).get("capsule", {})
+        commands = capsule.get("verification", {}).get("commands", [])
+        by_label = {c.get("label"): c for c in commands}
+        if by_label.get("M1", {}).get("layer") != "fast":
+            report("verify-layer-tag: the (fast)-tagged check did not compile with layer fast.")
+            report(json.dumps(commands))
+            return 1
+        if "layer" in by_label.get("M2", {}):
+            report(
+                "verify-layer-tag: an untagged check emitted a layer field; full is "
+                "the implicit default and must stay off the capsule."
+            )
+            report(json.dumps(commands))
+            return 1
+        if (
+            by_label.get("M1", {}).get("check") != "node fast.js"
+            or by_label.get("M2", {}).get("check") != "node full.js"
+        ):
+            report("verify-layer-tag: the layer tag altered the check text.")
+            report(json.dumps(commands))
+            return 1
+
+    report("verify-layer-tag scenario passed.")
+    return 0
+
+
 def validate_native_goal_gate_order_scenario() -> int:
     with tempfile.TemporaryDirectory(prefix="keel-goal-order-") as raw_tmp:
         root = Path(raw_tmp)
@@ -8819,12 +9680,16 @@ def validate_thin_native_install_scenario() -> int:
             report(uncertain_text.strip())
             return 1
 
-        # --- Case E: doctor reports the missing native plugin with remediation ---
+        # --- Case E: doctor reports the native plugin runtime with remediation ---
+        # These repos consume Keel, so the runtime line and its install
+        # remediation must appear, while the plugin *source* check must not:
+        # plugins/keel/ exists only in Keel's own repository and `keel --init`
+        # never creates it, so reporting it here is a permanent unactionable
+        # `missing`. See the dev-only-plugin-source-scoping scenario.
         doctor = run_keel(repo, "--doctor")
         doctor_text = (doctor.stdout or "") + (doctor.stderr or "")
         if (
-            "native plugin source" not in doctor_text
-            or "native plugin runtime" not in doctor_text
+            "native plugin runtime" not in doctor_text
             or "keel@<marketplace>" not in doctor_text
         ):
             report(
@@ -8833,14 +9698,21 @@ def validate_thin_native_install_scenario() -> int:
             )
             report(doctor_text.strip())
             return 1
+        if "native plugin source" in doctor_text:
+            report(
+                "thin-native-install doctor reported the development-only "
+                "plugin source check in a consuming project."
+            )
+            report(doctor_text.strip())
+            return 1
         missing_repo = tmp / "no-plugin"
         missing_repo.mkdir()
         missing_doctor = run_keel(missing_repo, "--doctor")
         missing_text = (missing_doctor.stdout or "") + (missing_doctor.stderr or "")
-        if "plugin source absent" not in missing_text:
+        if "plugin source" in missing_text:
             report(
-                "thin-native-install doctor does not diagnose an absent native "
-                "plugin source."
+                "thin-native-install doctor diagnosed a plugin source outside "
+                "Keel's own repository."
             )
             report(missing_text.strip())
             return 1
@@ -10104,6 +10976,29 @@ SCENARIOS: tuple = (
     ("doctor-openspec-honesty", validate_doctor_openspec_honesty_scenario),
     ("update-pack-install", validate_update_pack_install_scenario),
     ("update-default-registry", validate_update_default_registry_scenario),
+    ("verification-layering-docs", validate_verification_layering_docs_scenario),
+    ("fast-check-config-scaffold", validate_fast_check_config_scaffold_scenario),
+    ("fast-pre-push-hooks", validate_fast_pre_push_hooks_scenario),
+    ("fast-pre-push-doctor", validate_fast_pre_push_doctor_scenario),
+    ("verify-layer-tag", validate_verify_layer_tag_scenario),
+    (
+        "non-concrete-verify-diagnostic",
+        validate_non_concrete_verify_diagnostic_scenario,
+    ),
+    ("inline-code-is-concrete", validate_inline_code_is_concrete_scenario),
+    ("covers-separator-collision", validate_covers_separator_collision_scenario),
+    (
+        "unresolved-authority-names-field",
+        validate_unresolved_authority_names_field_scenario,
+    ),
+    (
+        "dev-only-plugin-source-scoping",
+        validate_dev_only_plugin_source_scoping_scenario,
+    ),
+    (
+        "source-repo-bootstrap-skip",
+        validate_source_repo_bootstrap_skip_scenario,
+    ),
     ("task-contract-core", validate_task_contract_core_scenario),
     ("task-capsule", validate_task_capsule_scenario),
     ("task-verification-strategies", validate_task_verification_strategies_scenario),