@christang/keel 5.2.2 → 5.2.3

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.2.2 -->
+<!-- keel:start version=5.2.3 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/bin/keel.js

@@ -15,6 +15,7 @@ const {
   runGate,
 } = require("../src/core/gates");
 const {
+  isKeelSourceRepo,
   probeCapabilities,
   renderCapabilities,
 } = require("../src/core/capabilities");
@@ -1202,7 +1203,12 @@ function printTargetSurface(repo, target) {
         sourceDetail = `plugin source unreadable at ${manifestRelative}`;
       }
     }
-    printDoctorLine("native plugin source", sourceStatus, sourceDetail);
+    // Development-only check: plugins/keel/ exists only in Keel's own source
+    // repository, so in a consuming project it is permanently `missing` and
+    // there is nothing the author can do about it.
+    if (isKeelSourceRepo(repo)) {
+      printDoctorLine("native plugin source", sourceStatus, sourceDetail);
+    }
     printDoctorLine(
       "native plugin runtime",
       "manual",
@@ -1229,7 +1235,12 @@ function printTargetSurface(repo, target) {
   printDoctorLine(
     "Keel behavioral skills",
     "plugin",
-    "keel-* skills are delivered by the installed Keel plugin (see native plugin status above); install the plugin if it is missing"
+    isKeelSourceRepo(repo)
+      ? "keel-* skills are delivered by the installed Keel plugin (see native "
+        + "plugin status above); install the plugin if it is missing"
+      : "keel-* skills are delivered by the installed Keel plugin; verify it "
+        + "with the runtime's own plugin listing, since Keel cannot observe "
+        + "installation from this repository"
   );
 
   const commands = commandSurfaceForTarget(target, repo);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.2.2",
+  "version": "5.2.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.2.2",
+  "version": "5.2.3",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.2.2",
+  "version": "5.2.3",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/scripts/install_to_repo.py

@@ -432,11 +432,38 @@ def unmanaged_keel_content_warning(repo: Path, relative_path: str) -> bool:
     return False
 
 
+KEEL_PACKAGE_NAME = "@christang/keel"
+
+
+def is_keel_source_repo(repo: Path) -> bool:
+    """Whether `repo` is Keel's own source repository.
+
+    Mirrors `isKeelSourceRepo` in src/core/capabilities.js. Both signals are
+    required so a project that merely vendors a plugins/keel/ directory is not
+    misclassified as Keel's own source.
+    """
+    try:
+        manifest = json.loads((repo / "package.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if manifest.get("name") != KEEL_PACKAGE_NAME:
+        return False
+    return (repo / "plugins" / "keel").is_dir()
+
+
 def collect_actions(repo: Path, target: str) -> list[InstallAction]:
     actions: list[InstallAction] = []
     targets = target_set(target)
 
-    if not unmanaged_keel_content_warning(repo, "AGENTS.md"):
+    # Keel's own AGENTS.md carries the full protocol that the validation suite
+    # asserts on; the packaged bootstrap is the shorter consumer-facing text.
+    # Writing it here replaces the protocol and turns the repository red.
+    if is_keel_source_repo(repo):
+        print(
+            "skip AGENTS.md: Keel source repository, whose AGENTS.md carries "
+            "the full protocol; the consumer bootstrap is not written here"
+        )
+    elif not unmanaged_keel_content_warning(repo, "AGENTS.md"):
         actions.append(
             managed_file_action("AGENTS.md", PACKAGE_ROOT / BOOTSTRAP_ASSET)
         )

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.2.2"
-PROTOCOL_VERSION = "5.2.2"
+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
@@ -9110,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(
@@ -9124,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
@@ -10400,6 +10981,24 @@ SCENARIOS: tuple = (
     ("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),

package/src/core/capabilities.js

@@ -35,10 +35,33 @@ function codexHome() {
   return path.resolve(configured || path.join(os.homedir(), ".codex"));
 }
 
+// Keel's own repository ships the plugin source under plugins/keel/. A project
+// that consumes Keel never has it, and `keel --init` never creates it, so any
+// check reading that path is a development-only check. Require both signals so
+// a project that merely vendors a plugins/keel/ directory is not misread as
+// Keel's own source.
+function isKeelSourceRepo(repo) {
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(repo, "package.json"), "utf8")
+    );
+    if (manifest.name !== "@christang/keel") return false;
+  } catch {
+    return false;
+  }
+  return fs.existsSync(path.join(repo, "plugins", "keel"));
+}
+
+const PLUGIN_RUNTIME_OBSERVATION =
+  "installed/enabled/trusted/active/behavior-verified plugin states need "
+  + "native runtime evidence and remain advisory or manual until probed";
+
 function pluginObservation(repo, target) {
   if (target === "opencode") {
     return "OpenCode has no v4 native plugin surface; manual CLI compatibility only";
   }
+  // The plugin source path is meaningful only in Keel's own repository.
+  if (!isKeelSourceRepo(repo)) return PLUGIN_RUNTIME_OBSERVATION;
   const manifestRelative = path.join(
     "plugins",
     "keel",
@@ -58,11 +81,7 @@ function pluginObservation(repo, target) {
       sourceState = `plugin source unreadable at ${manifestRelative}`;
     }
   }
-  return (
-    `${sourceState}; installed/enabled/trusted/active/behavior-verified plugin `
-      + "states need native runtime evidence and remain advisory or manual "
-      + "until probed"
-  );
+  return `${sourceState}; ${PLUGIN_RUNTIME_OBSERVATION}`;
 }
 
 function targetObservation(repo, target) {
@@ -286,6 +305,7 @@ function renderCapabilities(result) {
 
 module.exports = {
   CAPABILITY_COMMANDS,
+  isKeelSourceRepo,
   probeCapabilities,
   renderCapabilities,
 };

package/src/core/gates.js

@@ -111,24 +111,36 @@ function contractAnchorPlan(selection, task) {
       ? selection.tasks[index + 1].line
       : lines.length;
   for (let cursor = task.line; cursor < end; cursor += 1) {
-    const match = lines[cursor].match(/^(\s*)-\s*Contract:\s*pending(\r?)$/);
+    const match = lines[cursor].match(/^(\s*)-\s*Contract:\s*(.*?)(\r?)$/);
     if (match) {
-      return { lines, cursor, indent: match[1], cr: match[2] };
+      return {
+        lines,
+        cursor,
+        indent: match[1],
+        previous: match[2].trim(),
+        cr: match[3],
+      };
     }
   }
   return null;
 }
 
+function anchoredFingerprint(previous) {
+  const match = previous.match(/sha-?256[\s:`]*([a-f0-9]{64})/i);
+  return match ? match[1].toLowerCase() : null;
+}
+
 function taskStart(repo, options) {
   const selection = loadSelection(repo, options);
   const task = selection.selected[0];
   const compiled = compileTaskContract(repo, selection.change, task);
   const problems = [...compiled.diagnostics];
-  // The explicit --record anchor write is refused loudly when the selected
-  // task's Evidence has no literal pending Contract line: a silent skip would
-  // hide a stale anchor and an overwrite would destroy the recorded start
-  // evidence drift detection depends on. Refusal writes nothing, guard
-  // manifest included.
+  // Recording the current fingerprint is idempotent: --record replaces the
+  // selected task's Contract anchor whatever it holds, so reauthorizing a task
+  // whose authority changed — the path the guard's own drift messages direct
+  // authors to — needs no manual edit. Refusal is kept only for a task with no
+  // anchor at all, which is a malformed capsule rather than a reauthorization,
+  // and it writes nothing, guard manifest included.
   let anchorPlan = null;
   if (options.record && problems.length === 0) {
     anchorPlan = contractAnchorPlan(selection, task);
@@ -136,9 +148,9 @@ function taskStart(repo, options) {
       problems.push(
         problem(
           "record-refused",
-          "--record requires the selected task's Evidence to contain the "
-            + 'literal line "- Contract: pending"; the anchor is already '
-            + "recorded or missing, so nothing was written."
+          "--record needs a \"- Contract:\" Evidence line on the selected "
+            + "task to anchor, and this task has none, so nothing was "
+            + 'written. Add "- Contract: pending" to its Evidence.'
         )
       );
     }
@@ -177,19 +189,38 @@ function taskStart(repo, options) {
     }
   }
   if (result.status === "pass" && anchorPlan) {
-    anchorPlan.lines[anchorPlan.cursor] =
+    const anchorLine =
       `${anchorPlan.indent}- Contract: keel-task-capsule/v1 `
       + `sha256:${compiled.fingerprint.value}${anchorPlan.cr}`;
-    fs.writeFileSync(
-      selection.tasksPath,
-      anchorPlan.lines.join("\n"),
-      "utf8"
-    );
+    const unchanged = anchorPlan.lines[anchorPlan.cursor] === anchorLine;
+    if (!unchanged) {
+      anchorPlan.lines[anchorPlan.cursor] = anchorLine;
+      fs.writeFileSync(
+        selection.tasksPath,
+        anchorPlan.lines.join("\n"),
+        "utf8"
+      );
+    }
+    const wasPending = /^pending$/i.test(anchorPlan.previous);
     result.record = {
-      status: "recorded",
+      status: unchanged ? "unchanged" : wasPending ? "recorded" : "rerecorded",
       path: `openspec/changes/${selection.change}/tasks.md`,
       line: anchorPlan.cursor + 1,
+      previous: anchorPlan.previous,
     };
+    // A re-record that lands a different fingerprint is a contract change, so
+    // any Evidence already produced under the previous one is stale. The gate
+    // cannot judge which Evidence survives; it names the change and leaves the
+    // call to the current agent's Review.
+    const replaced = anchoredFingerprint(anchorPlan.previous);
+    if (replaced && replaced !== compiled.fingerprint.value) {
+      result.warnings.push(
+        `Re-recorded over a different contract: was sha256:${replaced}, now `
+          + `sha256:${compiled.fingerprint.value}. Execution evidence produced `
+          + "under the previous contract is stale; clear or re-verify it "
+          + "before completing this task."
+      );
+    }
   }
   return result;
 }
@@ -658,7 +689,8 @@ function renderGate(result) {
   }
   if (result.record) {
     lines.push(
-      `Recorded: ${result.record.path}:${result.record.line} (Contract anchor)`
+      `Contract anchor ${result.record.status}: ${result.record.path}:`
+        + result.record.line
     );
   }
   return `${lines.join("\n")}\n`;

package/src/core/task-contract.js

@@ -10,13 +10,37 @@ const SUPPORTED_MODES = new Set([
   "plan-first",
 ]);
 
-function isConcrete(value) {
-  const normalized = String(value || "")
+const UNFILLED_TOKEN = /(<[^>]+>|\bTODO\b|\bTBD\b|\bplaceholder\b)/i;
+
+function normalizeFieldText(value) {
+  return String(value || "")
     .replace(/<!--[\s\S]*?-->/g, "")
     .replace(/^\s*-\s*/gm, "")
     .trim();
+}
+
+// Inline code spans hold documented patterns — a filename shape, or prose that
+// has to name the token forms themselves. Strip them before looking for an
+// unfilled slot, but only after the emptiness test, so a field whose whole
+// value is one code span is not mistaken for an empty field.
+function withoutInlineCode(text) {
+  return text.replace(/`[^`]*`/g, " ");
+}
+
+function isConcrete(value) {
+  const normalized = normalizeFieldText(value);
   if (!normalized || /^(?:none|pending)\.?$/i.test(normalized)) return false;
-  return !/(<[^>]+>|\bTODO\b|\bTBD\b|\bplaceholder\b)/i.test(normalized);
+  return !UNFILLED_TOKEN.test(withoutInlineCode(normalized));
+}
+
+// The unfilled token that made a field non-concrete, or null when the field is
+// empty, `none`, or `pending`. Used to explain a non-concrete field instead of
+// letting the caller infer a different schema from it.
+function unfilledToken(value) {
+  const normalized = normalizeFieldText(value);
+  if (!normalized || /^(?:none|pending)\.?$/i.test(normalized)) return null;
+  const match = withoutInlineCode(normalized).match(UNFILLED_TOKEN);
+  return match ? match[0] : null;
 }
 
 function parseTasks(content) {
@@ -245,7 +269,27 @@ function taskStartContractProblems(task) {
 }
 
 function requiredFieldProblems(task) {
-  const compact = isConcrete(field(task, "Verify"));
+  const verify = field(task, "Verify");
+  const compact = isConcrete(verify);
+  // A task that declared Verify but left an unfilled token in it is a compact
+  // v4 task with one bad token, not an expanded v3 task. Say which token, and
+  // do not report the v3 fields it never declared.
+  if (!compact) {
+    const token = unfilledToken(verify);
+    if (token) {
+      return [
+        {
+          code: "non-concrete-verify",
+          message:
+            `Verify contains the unfilled token \`${token}\`; compact v4 `
+            + "detection requires a concrete Verify. Replace or remove that "
+            + "token — the expanded v3 fields are not required. Angle "
+            + "brackets, TODO, TBD, and the word placeholder all read as "
+            + "unfilled, including inside prose.",
+        },
+      ];
+    }
+  }
   const required = compact
     ? ["Covers", "Verify", "Evidence"]
     : [
@@ -313,12 +357,8 @@ function scenarioOutcomes(content) {
   ].map((match) => normalizeText(match[1]));
 }
 
-function specAuthority(repo, change, reference) {
-  const parts = reference.split("/").map((part) => part.trim());
-  if (parts.length < 2 || parts.length > 3) return null;
-  const [capability, requirementName, scenarioName] = parts;
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(capability)) return null;
-  const candidates = [
+function specCandidatePaths(repo, change, capability) {
+  return [
     path.join(
       repo,
       "openspec",
@@ -330,6 +370,68 @@ function specAuthority(repo, change, reference) {
     ),
     path.join(repo, "openspec", "specs", capability, "spec.md"),
   ];
+}
+
+// Requirement and scenario names that contain the hierarchy separator can never
+// be referenced, whatever the author writes, so name them instead of leaving a
+// correct-looking reference unexplained.
+function separatorCollisions(repo, change, capability) {
+  const collisions = [];
+  for (const specPath of specCandidatePaths(repo, change, capability)) {
+    if (!fs.existsSync(specPath)) continue;
+    const content = fs.readFileSync(specPath, "utf8");
+    for (const pattern of [
+      /^### Requirement:\s*(.+?)\s*$/gm,
+      /^#### Scenario:\s*(.+?)\s*$/gm,
+    ]) {
+      for (const match of content.matchAll(pattern)) {
+        if (match[1].includes("/") && !collisions.includes(match[1])) {
+          collisions.push(match[1]);
+        }
+      }
+    }
+  }
+  return collisions;
+}
+
+function collisionHint(repo, change, capability) {
+  const collisions = separatorCollisions(repo, change, capability);
+  if (collisions.length === 0) return "";
+  const named = collisions.map((name) => `"${name}"`).join(", ");
+  return (
+    ` Capability ${capability} declares a name containing the / separator, `
+    + `which cannot be referenced: ${named}. Rename it in the spec, or `
+    + "reference its parent requirement instead."
+  );
+}
+
+function specAuthority(repo, change, reference) {
+  const parts = reference.split("/").map((part) => part.trim());
+  const [capability, requirementName, scenarioName] = parts;
+  const namesCapability =
+    /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(capability || "")
+    && specCandidatePaths(repo, change, capability).some((specPath) =>
+      fs.existsSync(specPath)
+    );
+  if (parts.length < 2 || parts.length > 3) {
+    // Only a reference that names a real capability is a failed spec
+    // reference; anything else is free text and stays a legacy reference.
+    if (parts.length > 3 && namesCapability) {
+      return {
+        diagnostic: {
+          code: "unresolved-covers",
+          message:
+            `Covers reference has ${parts.length} segments; the hierarchy is `
+            + "capability / requirement, or capability / requirement / "
+            + `scenario: ${reference}.`
+            + collisionHint(repo, change, capability),
+        },
+      };
+    }
+    return null;
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(capability)) return null;
+  const candidates = specCandidatePaths(repo, change, capability);
   for (const specPath of candidates) {
     if (!fs.existsSync(specPath)) continue;
     const content = fs.readFileSync(specPath, "utf8");
@@ -361,7 +463,10 @@ function specAuthority(repo, change, reference) {
             code: scenarios.length > 1 ? "ambiguous-covers" : "unresolved-covers",
             message:
               `${scenarios.length > 1 ? "Duplicated" : "Missing"} Covers `
-              + `scenario: ${reference}.`,
+              + `scenario: ${reference}.`
+              + (scenarios.length > 1
+                ? ""
+                : collisionHint(repo, change, capability)),
           },
         };
       }
@@ -383,7 +488,9 @@ function specAuthority(repo, change, reference) {
   return {
     diagnostic: {
       code: "unresolved-covers",
-      message: `Covers reference could not be resolved: ${reference}.`,
+      message:
+        `Covers reference could not be resolved: ${reference}.`
+        + collisionHint(repo, change, capability),
     },
   };
 }
@@ -657,11 +764,17 @@ function compileTaskContract(repo, change, task) {
     questionIds.length > 0
     && !isConcrete(fallback.replace(/^Pre-authorized fallback:\s*/i, ""))
   ) {
+    // Name the field and prefix this check actually reads. The previous
+    // wording said "documented design authority", which sent authors to
+    // design.md — where the answer usually already is.
     resolved.diagnostics.push(...questionIds.map((questionId) => ({
       code: "unresolved-authority",
       message:
-        `${questionId} requires documented design authority and an authorized `
-        + "fallback before implementation.",
+        `${questionId} is referenced in Covers but task ${task.id} declares no `
+        + "authorized fallback. Add an \"Autonomy boundary:\" field whose entry "
+        + "line begins \"Pre-authorized fallback:\" and states the reversible "
+        + "bound plus the evidence it requires. This check reads only that line "
+        + "on the task; prose in design.md does not satisfy it.",
     })));
   }
   const capsule = {