@christang/keel 5.3.6 → 5.3.8

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.3.6"
-PROTOCOL_VERSION = "5.3.6"
+PACKAGE_VERSION = "5.3.8"
+PROTOCOL_VERSION = "5.3.8"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 # Mirrors KEEL_PACKAGE_NAME in scripts/install_to_repo.py, one of the two
@@ -1307,7 +1307,11 @@ def validate_expectation_slice_gates_scenario() -> int:
         "Covers:",
         "source expectation",
         "D<n>/F<n>/A<n>/Q<n>",
-        "unresolved Q<n>",
+        # The rule is no longer "an unresolved Q<n> requires a fallback"
+        # unconditionally: the identifier blocks only where it opens the entry,
+        # so a resolved question can be cited beside the fact that closed it.
+        "OPENS an entry",
+        "requires an authorized fallback",
     ]
     design_template_snippets = [
         "D<n>",
@@ -3505,6 +3509,11 @@ def task_contract_fixture(
         "  - Stop Rules:\n"
         "    - Stop on failure.\n"
         "  - Evidence:\n"
+        # Emitted unconditionally rather than through `evidence`, which callers
+        # override to control the M-entries. Completion requires a recorded
+        # fingerprint, and `--record` rewrites this line in place, so a caller
+        # that customizes its evidence must not be able to drop the anchor.
+        "    - Contract: pending\n"
         f"{evidence_lines}"
         "    - Review:\n"
         "      - Status: pending\n"
@@ -3541,7 +3550,7 @@ def invalidation_repo(root: Path, name: str, section: str | None) -> Path:
     # A real Contract anchor, so the missing-section case can prove that a
     # failing authoring gate leaves the anchor untouched rather than merely
     # failing earlier for want of one.
-    body = task_contract_fixture(evidence=("Contract: pending", "M1: pending"))
+    body = task_contract_fixture()
     body = body.replace(INVALIDATES_NONE, "" if section is None else section)
     write_text(repo / "openspec/changes/demo/tasks.md", body)
     return repo
@@ -3777,7 +3786,7 @@ def validate_anchor_reverification_bound_scenario() -> int:
         repo = Path(raw_tmp) / "repo"
         repo.mkdir()
         live = repo / "openspec/changes/demo/tasks.md"
-        write_text(live, task_contract_fixture(evidence=("Contract: pending", "M1: pending")))
+        write_text(live, task_contract_fixture())
 
         recorded = run_keel(
             repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
@@ -3989,6 +3998,7 @@ def validate_durable_owner_vocabulary_scenario() -> int:
                 )
             )
             write_text(tasks_path, fixture)
+            record_contract_anchor(repo, "demo")
             result = run_keel(
                 repo, "gate", "task-complete", "--change", "demo", "--task", "1.1", "--json"
             )
@@ -4134,6 +4144,7 @@ def validate_regression_check_tag_scenario() -> int:
 
         def complete(fixture: str) -> dict:
             write_text(tasks_path, fixture)
+            record_contract_anchor(repo, "demo")
             result = run_keel(
                 repo, "gate", "task-complete", "--change", "demo", "--task", "1.1", "--json"
             )
@@ -4650,12 +4661,39 @@ def task_capsule_compact_fixture() -> str:
         "  - Stop Rules:\n"
         "    - Stop on failure.\n"
         "  - Evidence:\n"
+        # Completion requires a recorded fingerprint here, so the anchor line
+        # must exist for `--record` to rewrite in place. See
+        # record_contract_anchor.
+        "    - Contract: pending\n"
         "    - M1: pending\n"
         "  - Stop if:\n"
         "    - Requires files outside Touch.\n"
     )
 
 
+def record_contract_anchor(repo: Path, change: str, task: str = "1.1") -> bool:
+    """Run `task-start --record` so a fixture can reach completion.
+
+    Completion refuses a task whose `Contract` anchor holds no compiled
+    fingerprint (issue #30), so a scenario that only wanted to exercise
+    task-complete still has to start the task first. That is the real loop, not
+    a workaround: a task that was never started is not a task being completed.
+    """
+    result = run_keel(
+        repo,
+        "gate",
+        "task-start",
+        "--change",
+        change,
+        "--task",
+        task,
+        "--record",
+        "--no-guard",
+        "--json",
+    )
+    return result.returncode == 0
+
+
 def validate_non_concrete_verify_diagnostic_scenario() -> int:
     """A compact v4 task whose Verify carries an unfilled token must be told so.
 
@@ -4729,8 +4767,10 @@ def validate_non_concrete_verify_diagnostic_scenario() -> int:
             )
             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.
+        # A task with no Verify at all must not be reported as carrying a token
+        # it never wrote. What it is reported as instead — one missing
+        # verification form rather than the expanded v3 set — belongs to the
+        # absent-verification-form-is-one-problem scenario.
         bare = task_capsule_compact_fixture()
         for block in (
             "  - Verify:\n    - Strategy: evidence-first\n    - M1: node test.js\n",
@@ -5049,6 +5089,957 @@ def validate_unresolved_authority_names_field_scenario() -> int:
     return 0
 
 
+SPEC_TEMPLATE_RELATIVE = "schemas/keel-spec-driven/templates/spec.md"
+
+
+SLOT_FILLER = "the recorded feed status"
+SLOT_VOCABULARY = {"<strategy>": "evidence-first"}
+
+
+def fill_template_slots(text: str, comments: str = "strip") -> str:
+    """Fill a shipped template's author-facing slots the way an author would.
+
+    Deliberately mechanical, so a slot added to the template later is handled
+    without touching the scenario: what is asserted is the template's structure
+    rather than a hand-maintained copy of it.
+
+    The two templates use HTML comments for different jobs, so the caller says
+    which. In the spec template a comment *is* the slot — the requirement name
+    and body are both comments — so it is replaced. In the tasks template
+    comments are instructions to the author sitting on their own lines, and the
+    slots are angle-bracket runs, so the comments are stripped.
+    """
+    if comments == "replace":
+        text = re.sub(r"<!--[\s\S]*?-->", SLOT_FILLER, text)
+    else:
+        # An own-line comment is an instruction to the author, so it goes. A
+        # comment with text before it on the line is that line's slot — a task
+        # title, a group name — and stripping it leaves a task line the parser
+        # cannot read, so it is filled like any other slot.
+        text = re.sub(r"^[ \t]*<!--[\s\S]*?-->[ \t]*\r?\n", "", text, flags=re.M)
+        text = re.sub(r"<!--[\s\S]*?-->", SLOT_FILLER, text)
+    # A slot whose value comes from a fixed vocabulary needs a member of it, so
+    # those are named. Everything else takes the generic filler.
+    for slot, value in SLOT_VOCABULARY.items():
+        text = text.replace(slot, value)
+    # Innermost-first to a fixed point: a slot may quote an identifier shape such
+    # as `Q<n>`, and the inner brackets would otherwise block the outer match and
+    # leave the whole slot unfilled.
+    while True:
+        collapsed = re.sub(r"<[^<>\n]*>", SLOT_FILLER, text)
+        if collapsed == text:
+            return text
+        text = collapsed
+
+
+def validate_completion_requires_a_recorded_anchor_scenario() -> int:
+    """Issue #30: an unrecorded anchor made the drift guarantee conditional.
+
+    `anchoredFingerprint` returns null for a non-digest value and completion
+    then skipped the comparison entirely, so a task with `Contract: pending`
+    passed with zero problems. It could be implemented against one contract,
+    have its Touch or Verify rewritten mid-flight, and complete clean — purely
+    by never running `task-start --record`. 5.3.7 closed the inference path;
+    this closes the explicitly named one.
+    """
+    header = "# Tasks\n\n## Invalidates\n\n- None.\n\n"
+
+    def task(contract: str) -> str:
+        return (
+            "- [ ] 1.1 Exercise task contract\n"
+            "  - Covers:\n"
+            "    - E1: Public behavior passes.\n"
+            "  - Touch:\n"
+            "    - src/feature.js\n"
+            "  - Verify:\n"
+            "    - Strategy: evidence-first\n"
+            "    - M1: node test.js asserts the recorded feed status\n"
+            "  - Evidence:\n"
+            f"    - Contract: {contract}\n"
+            "    - M1: the suite passed\n"
+            "    - Review:\n"
+            "      - Status: pass\n"
+            "      - Acceptance check: behavior asserted at the interface\n"
+            "      - Scope check: only Touch files changed\n"
+            "      - Findings: none\n"
+            "    - Blocker: none\n"
+        )
+
+    with tempfile.TemporaryDirectory(prefix="keel-anchor-required-") as raw:
+        repo = Path(raw)
+        write_text(repo / "openspec/changes/unrecorded/tasks.md", header + task("pending"))
+
+        def gate(change: str, stage: str) -> dict:
+            return json.loads(
+                run_keel(
+                    repo,
+                    "gate",
+                    stage,
+                    "--change",
+                    change,
+                    "--task",
+                    "1.1",
+                    "--json",
+                ).stdout
+            )
+
+        payload = gate("unrecorded", "task-complete")
+        if payload.get("status") == "pass":
+            report(
+                "completion-requires-a-recorded-anchor: an explicitly named task "
+                "with `Contract: pending` passed task-complete, so the "
+                "fingerprint comparison still compares nothing."
+            )
+            return 1
+        named = [
+            problem.get("message", "")
+            for problem in payload.get("problems", [])
+            if problem.get("code") == "missing-contract-anchor"
+        ]
+        if not named:
+            report(
+                "completion-requires-a-recorded-anchor: the task did not pass, "
+                "but no missing-contract-anchor diagnostic explained why."
+            )
+            for problem in payload.get("problems", []):
+                report(f"  {problem.get('code')}: {problem.get('message')}")
+            return 1
+        for needle in ("Contract", "--record"):
+            if needle not in named[0]:
+                report(
+                    "completion-requires-a-recorded-anchor: the diagnostic did "
+                    f"not name {needle}."
+                )
+                report(named[0])
+                return 1
+        # Doing what the diagnostic asks must clear it. The fingerprint is the
+        # one this task actually compiles to, so the anchor comparison that
+        # follows is a real comparison rather than a shape check.
+        started = gate("unrecorded", "task-start")
+        fingerprint = started.get("contract", {}).get("fingerprint", {}).get("value")
+        if not fingerprint:
+            report(
+                "completion-requires-a-recorded-anchor: task-start returned no "
+                "fingerprint to record."
+            )
+            return 1
+        if any(
+            problem.get("code") == "missing-contract-anchor"
+            for problem in started.get("problems", [])
+        ):
+            report(
+                "completion-requires-a-recorded-anchor: task-start reported the "
+                "missing anchor, but it runs before one can exist."
+            )
+            return 1
+        write_text(
+            repo / "openspec/changes/recorded/tasks.md",
+            header + task(f"keel-task-capsule/v1 sha256:{fingerprint}"),
+        )
+        recorded = gate("recorded", "task-complete")
+        if recorded.get("status") != "pass":
+            report(
+                "completion-requires-a-recorded-anchor: recording the anchor did "
+                "not clear the refusal."
+            )
+            for problem in recorded.get("problems", []):
+                report(f"  {problem.get('code')}: {problem.get('message')}")
+            return 1
+    if "completion-requires-a-recorded-anchor" not in {name for name, _ in SCENARIOS}:
+        report(
+            "completion-requires-a-recorded-anchor: the scenario registry does "
+            "not include it."
+        )
+        return 1
+    report("completion-requires-a-recorded-anchor scenario passed.")
+    return 0
+
+
+def validate_task_body_ends_at_heading_scenario() -> int:
+    """Issue #29: a change-level section was read as the last task's Evidence.
+
+    parseTasks gave a task every line up to the next task or EOF, and a `##`
+    heading did not stop it, so `## Invalidates` and `## Expectation Coverage`
+    landed in whichever field was open last. That made the two checks look
+    contradictory: `invalidation-phrase` requires the searchable wording in
+    double quotes, while the concreteness test rejects an angle-bracket slot
+    outside inline code, so an entry quoting wording that carries one could
+    satisfy neither. They were never in conflict — the parser only made them
+    appear so.
+    """
+    slot = "<" + "n" + ">"
+    header = "# Tasks\n\n"
+
+    def task(number: str, contract: str) -> str:
+        return (
+            f"- [ ] {number} Exercise task contract\n"
+            "  - Covers:\n"
+            "    - E1: Public behavior passes.\n"
+            "  - Touch:\n"
+            "    - src/feature.js\n"
+            "  - Verify:\n"
+            "    - Strategy: evidence-first\n"
+            "    - M1: node test.js asserts the recorded feed status\n"
+            "  - Evidence:\n"
+            f"    - Contract: {contract}\n"
+            "    - M1: the suite passed\n"
+            "    - Review:\n"
+            "      - Status: pass\n"
+            "      - Acceptance check: behavior asserted at the interface\n"
+            "      - Scope check: only Touch files changed\n"
+            "      - Findings: none\n"
+            "    - Blocker: none\n"
+        )
+
+    # The entry quotes stale wording carrying an unfilled slot, which is exactly
+    # what issue #16 asks an invalidation to quote. A stray Contract line sits
+    # in the trailing section to prove the anchor search stops at the heading.
+    sections = (
+        "\n## Invalidates\n\n"
+        f'- I1: "an unresolved Q{slot} without an authorized fallback blocks '
+        'implementation" — the schema prose. Updated by: 1.1\n'
+        "    - Contract: keel-task-capsule/v1 sha256:" + "b" * 64 + "\n"
+        "\n## Expectation Coverage\n\n"
+        f"- E1: Every Q{slot} reference resolves Covered by: 1.1\n"
+    )
+    body = header + task("1.1", "pending") + "\n## 2. Second group\n\n" + task(
+        "2.1", "pending"
+    )
+
+    with tempfile.TemporaryDirectory(prefix="keel-task-extent-") as raw:
+        repo = Path(raw)
+        write_text(repo / "openspec/changes/demo/tasks.md", body + sections)
+        started = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "2.1", "--json"
+        )
+        payload = json.loads(started.stdout)
+        problems = payload.get("problems", [])
+        if payload.get("status") != "pass":
+            report(
+                "task-body-ends-at-heading: the last task did not pass task-start "
+                "with a trailing section quoting an unfilled slot."
+            )
+            for problem in problems:
+                report(f"  {problem.get('code')}: {problem.get('message')}")
+            return 1
+        # The same run proves the phrase check is satisfied: an entry the phrase
+        # check rejected would have produced invalidation-phrase above.
+        malformed = body + (
+            "\n## Invalidates\n\n"
+            "- I1: the schema prose is stale. Updated by: 1.1\n"
+        )
+        write_text(repo / "openspec/changes/unquoted/tasks.md", malformed)
+        unquoted = json.loads(
+            run_keel(
+                repo,
+                "gate",
+                "task-start",
+                "--change",
+                "unquoted",
+                "--task",
+                "2.1",
+                "--json",
+            ).stdout
+        )
+        if not any(
+            problem.get("code") == "invalidation-phrase"
+            for problem in unquoted.get("problems", [])
+        ):
+            report(
+                "task-body-ends-at-heading: an unquoted invalidation entry was "
+                "accepted, so the phrase check is no longer being satisfied by "
+                "the quoted one."
+            )
+            return 1
+        # A group heading must not be appended to the preceding task's field.
+        first = json.loads(
+            run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+            ).stdout
+        )
+        evidence = json.dumps(first)
+        if "Second group" in evidence:
+            report(
+                "task-body-ends-at-heading: the group heading leaked into the "
+                "preceding task's fields."
+            )
+            return 1
+        # --record must anchor the last task's own Contract line, not the stray
+        # one planted in the trailing section.
+        recorded = run_keel(
+            repo,
+            "gate",
+            "task-start",
+            "--change",
+            "demo",
+            "--task",
+            "2.1",
+            "--record",
+            "--json",
+        )
+        if recorded.returncode != 0:
+            report("task-body-ends-at-heading: --record failed on the last task.")
+            report((recorded.stdout or recorded.stderr).strip())
+            return 1
+        written = (repo / "openspec/changes/demo/tasks.md").read_text(
+            encoding="utf-8"
+        )
+        after_heading = written.split("## Invalidates", 1)[1]
+        if "b" * 64 not in after_heading:
+            report(
+                "task-body-ends-at-heading: --record overwrote the Contract line "
+                "planted inside the trailing section."
+            )
+            return 1
+        # The extent change must move no fingerprint: an anchor that shifted
+        # would drift every live change in every consumer repo at once. Pinned
+        # rather than merely measured, so a future extent change cannot move one
+        # silently. A deliberate capsule-shape change will fail here too — that
+        # is the point; it should be looked at, not absorbed.
+        pinned = {
+            "1.1": "2f723a8778160a2d51cd91e34255bf19f2c654fa23cdcd7b013915727a541d17",
+            "2.1": "5e0481362b06992d0317c91d34bbd5d6746fb9c1fee47566060f61fbba7cbf05",
+        }
+        plain = (
+            "# Tasks\n\n"
+            + task("1.1", "pending")
+            + "\n## 2. Second group\n\n"
+            + task("2.1", "pending")
+            + '\n## Invalidates\n\n- I1: "the schema prose is stale here" — the '
+            "schema. Updated by: 1.1\n\n## Expectation Coverage\n\n"
+            "- E1: Covered by: 1.1\n"
+        )
+        write_text(repo / "openspec/changes/pinned/tasks.md", plain)
+        for task_id, expected in pinned.items():
+            payload = json.loads(
+                run_keel(
+                    repo,
+                    "gate",
+                    "task-start",
+                    "--change",
+                    "pinned",
+                    "--task",
+                    task_id,
+                    "--json",
+                ).stdout
+            )
+            actual = (
+                payload.get("contract", {}).get("fingerprint", {}).get("value")
+            )
+            if actual != expected:
+                report(
+                    "task-body-ends-at-heading: the compiled fingerprint for "
+                    f"task {task_id} moved. Expected {expected}, got {actual}. "
+                    "An extent or capsule-shape change that moves an anchor "
+                    "drifts every live change in every consumer repo."
+                )
+                return 1
+    if "task-body-ends-at-heading" not in {name for name, _ in SCENARIOS}:
+        report(
+            "task-body-ends-at-heading: the scenario registry does not include it."
+        )
+        return 1
+    report("task-body-ends-at-heading scenario passed.")
+    return 0
+
+
+TASKS_TEMPLATE_RELATIVE = "schemas/keel-spec-driven/templates/tasks.md"
+
+
+def validate_tasks_template_red_green_example_scenario() -> int:
+    """Issue #28 items 2 and 3: the red-green shape was described, never shown.
+
+    The template's prose has said since 5.3.4 that the `.red`/`.green` entries
+    come in addition to the bare `M<n>` entry, but it showed only the flat form.
+    The reporter tried annotated labels, was refused, landed on the flat form,
+    and was refused again for the missing bare entry. One worked example closes
+    both attempts — and it is asserted by gating it, so it cannot drift from the
+    rule it illustrates.
+    """
+    shipped = ROOT / "openspec" / TASKS_TEMPLATE_RELATIVE
+    packaged = ROOT / "assets" / "openspec" / TASKS_TEMPLATE_RELATIVE
+    for path in (shipped, packaged):
+        if not path.is_file():
+            report(f"tasks-template-red-green-example: missing template {path}.")
+            return 1
+    if shipped.read_bytes() != packaged.read_bytes():
+        report(
+            "tasks-template-red-green-example: the two shipped copies of the "
+            "tasks template have diverged."
+        )
+        return 1
+
+    source = shipped.read_text(encoding="utf-8")
+    red_green = [
+        block
+        for block in re.split(r"^## ", source, flags=re.MULTILINE)
+        if re.search(r"^\s*-\s*Strategy:\s*(vertical-tdd|regression-first)", block, re.M)
+    ]
+    if not red_green:
+        report(
+            "tasks-template-red-green-example: the template defines no task "
+            "group with a red-green strategy, so it still only describes one."
+        )
+        return 1
+    group = red_green[0]
+    untagged = re.findall(r"^\s*-\s*(M[1-9]\d*):\s*(?!pending)", group, re.M)
+    tagged = re.findall(r"^\s*-\s*(M[1-9]\d*)\s*\([^)]*regression[^)]*\):", group, re.M)
+    if not untagged:
+        report(
+            "tasks-template-red-green-example: the red-green group has no "
+            "untagged check, which task-start refuses as regression-only."
+        )
+        return 1
+    if not tagged:
+        report(
+            "tasks-template-red-green-example: the red-green group shows no "
+            "(regression)-tagged check, so the exemption is still unillustrated."
+        )
+        return 1
+    label = untagged[0]
+    for suffix in ("", ".red", ".green"):
+        if not re.search(rf"^\s*-\s*{label}{re.escape(suffix)}:", group, re.M):
+            report(
+                "tasks-template-red-green-example: the untagged check is missing "
+                f"its `{label}{suffix}` Evidence entry."
+            )
+            return 1
+    for suffix in (".red", ".green"):
+        if re.search(rf"^\s*-\s*{tagged[0]}{re.escape(suffix)}:", group, re.M):
+            report(
+                "tasks-template-red-green-example: the (regression)-tagged check "
+                f"carries a `{suffix}` entry it is exempt from."
+            )
+            return 1
+
+    # Gating the filled template is what keeps the example from drifting from
+    # the rule it illustrates.
+    filled = fill_template_slots(source)
+    with tempfile.TemporaryDirectory(prefix="keel-tasks-template-") as raw:
+        repo = Path(raw)
+        write_text(repo / "openspec/changes/from-template/tasks.md", filled)
+        ids = re.findall(r"^\s*-\s*\[[ xX]\]\s+(\d+(?:\.\d+)+)\s", filled, re.M)
+        if not ids:
+            report(
+                "tasks-template-red-green-example: the filled template defines "
+                "no task the gate can read."
+            )
+            return 1
+        for task_id in ids:
+            result = run_keel(
+                repo,
+                "gate",
+                "task-start",
+                "--change",
+                "from-template",
+                "--task",
+                task_id,
+                "--json",
+            )
+            payload = json.loads(result.stdout)
+            if payload.get("status") != "pass":
+                report(
+                    "tasks-template-red-green-example: task "
+                    f"{task_id} written from the shipped template did not pass "
+                    "task-start."
+                )
+                for problem in payload.get("problems", []):
+                    report(f"  {problem.get('code')}: {problem.get('message')}")
+                return 1
+    if "tasks-template-red-green-example" not in {name for name, _ in SCENARIOS}:
+        report(
+            "tasks-template-red-green-example: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("tasks-template-red-green-example scenario passed.")
+    return 0
+
+
+def validate_spec_template_validates_scenario() -> int:
+    """Issue #28 item 7: following the spec template guaranteed a first failure.
+
+    The template's requirement body is a comment with no modal verb, and
+    `openspec validate` requires SHALL or MUST, so the reporter's 16 requirements
+    produced 16 errors. Asserted by running the filled template through the
+    validator rather than by matching the template's prose, because a template
+    that only mentions the requirement in a comment would satisfy the latter.
+    """
+    shipped = ROOT / "openspec" / SPEC_TEMPLATE_RELATIVE
+    packaged = ROOT / "assets" / "openspec" / SPEC_TEMPLATE_RELATIVE
+    for path in (shipped, packaged):
+        if not path.is_file():
+            report(f"spec-template-validates: missing shipped template {path}.")
+            return 1
+    if shipped.read_bytes() != packaged.read_bytes():
+        report(
+            "spec-template-validates: the two shipped copies of the spec "
+            "template have diverged."
+        )
+        return 1
+    if run_openspec(ROOT, "--version") is None:
+        report("spec-template-validates skipped: the openspec CLI is not on PATH.")
+        return 0
+
+    filled = fill_template_slots(
+        shipped.read_text(encoding="utf-8"), comments="replace"
+    )
+    with tempfile.TemporaryDirectory(prefix="keel-spec-template-") as raw:
+        repo = Path(raw)
+        write_text(repo / "openspec/project.md", "# Project\n\nA fixture.\n")
+        change = repo / "openspec/changes/from-template"
+        write_text(
+            change / "proposal.md",
+            "# from-template\n\n## Why\n\nExercise the shipped spec template.\n"
+            "\n## What Changes\n\n- One requirement written from the template.\n",
+        )
+        write_text(change / "specs/demo-capability/spec.md", filled)
+        result = run_openspec(repo, "validate", "from-template")
+        if result is None:
+            report(
+                "spec-template-validates skipped: the openspec CLI vanished "
+                "mid-scenario."
+            )
+            return 0
+        if result.returncode != 0:
+            report(
+                "spec-template-validates: a requirement written from the "
+                "shipped template did not validate."
+            )
+            report((result.stdout or result.stderr).strip())
+            return 1
+    if "spec-template-validates" not in {name for name, _ in SCENARIOS}:
+        report("spec-template-validates: the scenario registry does not include it.")
+        return 1
+    report("spec-template-validates scenario passed.")
+    return 0
+
+
+def validate_task_complete_selection_requires_a_started_task_scenario() -> int:
+    """Issue #28 item 6: the no-arg default reported another task's problems.
+
+    The documented order is gate-then-checkbox, so first-unchecked is the right
+    inference and stays. The hazard is narrower: inferring a task that never
+    started, then printing its readiness problems under a selection heading the
+    author reads as their own task's failure. A task that has started records a
+    fingerprint in its Evidence `Contract` anchor, so that anchor is what makes
+    the inference safe.
+    """
+    header = "# Tasks\n\n## Invalidates\n\n- None.\n\n"
+
+    def task(number: str, checked: bool, contract: str) -> str:
+        box = "x" if checked else " "
+        return (
+            f"- [{box}] {number} Exercise task contract\n"
+            "  - Covers:\n"
+            "    - E1: Public behavior passes.\n"
+            "  - Touch:\n"
+            "    - src/feature.js\n"
+            "  - Verify:\n"
+            "    - Strategy: evidence-first\n"
+            "    - M1: node test.js\n"
+            "  - Evidence:\n"
+            f"    - Contract: {contract}\n"
+            "    - M1: the suite passed\n"
+            "    - Review:\n"
+            "      - Status: pass\n"
+            "      - Acceptance check: behavior asserted at the interface\n"
+            "      - Scope check: only Touch files changed\n"
+            "      - Findings: none\n"
+            "    - Blocker: none\n"
+        )
+
+    digest = "a" * 64
+    anchored = f"keel-task-capsule/v1 sha256:{digest}"
+    with tempfile.TemporaryDirectory(prefix="keel-complete-selection-") as raw:
+        repo = Path(raw)
+
+        def gate(change: str, stage: str) -> dict:
+            result = run_keel(
+                repo, "gate", stage, "--change", change, "--json"
+            )
+            return json.loads(result.stdout)
+
+        # 1.1 is finished; 1.2 has never started, so its anchor is still pending.
+        write_text(
+            repo / "openspec/changes/unstarted/tasks.md",
+            header
+            + task("1.1", True, anchored)
+            + "\n"
+            + task("1.2", False, "pending"),
+        )
+        payload = gate("unstarted", "task-complete")
+        codes = {problem.get("code") for problem in payload.get("problems", [])}
+        if "ambiguous-completion-selection" not in codes:
+            report(
+                "task-complete-selection-requires-a-started-task: no-arg "
+                "task-complete did not refuse on selection for a task that "
+                "records no start fingerprint."
+            )
+            report(json.dumps(payload.get("problems", []), indent=2))
+            return 1
+        message = next(
+            problem.get("message", "")
+            for problem in payload.get("problems", [])
+            if problem.get("code") == "ambiguous-completion-selection"
+        )
+        for needle in ("1.2", "1.1", "--task"):
+            if needle not in message:
+                report(
+                    "task-complete-selection-requires-a-started-task: the "
+                    f"refusal did not name {needle}."
+                )
+                report(message)
+                return 1
+        # The same shape, once 1.2 has recorded its start fingerprint.
+        write_text(
+            repo / "openspec/changes/started/tasks.md",
+            header
+            + task("1.1", True, anchored)
+            + "\n"
+            + task("1.2", False, anchored),
+        )
+        started = gate("started", "task-complete")
+        started_codes = {
+            problem.get("code") for problem in started.get("problems", [])
+        }
+        if "ambiguous-completion-selection" in started_codes:
+            report(
+                "task-complete-selection-requires-a-started-task: a task that "
+                "recorded its start fingerprint was still refused on selection."
+            )
+            return 1
+        if started.get("selection", {}).get("tasks") != ["1.2"]:
+            report(
+                "task-complete-selection-requires-a-started-task: the started "
+                "task was not the inferred selection."
+            )
+            report(json.dumps(started.get("selection", {}), indent=2))
+            return 1
+        # task-start keeps the plain first-unchecked default: selecting a task
+        # that has not started is exactly its job.
+        start = gate("unstarted", "task-start")
+        if start.get("selection", {}).get("tasks") != ["1.2"]:
+            report(
+                "task-complete-selection-requires-a-started-task: no-arg "
+                "task-start no longer selects the first unchecked task."
+            )
+            report(json.dumps(start.get("selection", {}), indent=2))
+            return 1
+        start_codes = {problem.get("code") for problem in start.get("problems", [])}
+        if "ambiguous-completion-selection" in start_codes:
+            report(
+                "task-complete-selection-requires-a-started-task: the selection "
+                "refusal leaked into task-start."
+            )
+            return 1
+    if "task-complete-selection-requires-a-started-task" not in {
+        name for name, _ in SCENARIOS
+    }:
+        report(
+            "task-complete-selection-requires-a-started-task: the scenario "
+            "registry does not include it."
+        )
+        return 1
+    report("task-complete-selection-requires-a-started-task scenario passed.")
+    return 0
+
+
+def validate_absent_verification_form_is_one_problem_scenario() -> int:
+    """Issue #28 item 4: the cascade reported a schema the author never chose.
+
+    Compact detection read only `isConcrete(Verify)`, so a task that simply had
+    no verification field was reported as an expanded v3 task missing nine
+    fields. Seven of them either resolve to a documented default, derive from
+    other authority, are consumed nowhere, or belong to the coupling contract —
+    leaving the one actionable line last.
+    """
+    defaulted = (
+        "Owner",
+        "Mode",
+        "Read",
+        "Acceptance",
+        "Report",
+        "Candidate Boundary",
+        "Stop Rules",
+    )
+    header = "# Tasks\n\n## Invalidates\n\n- None.\n\n"
+    body = (
+        "- [ ] 1.1 Exercise task contract\n"
+        "  - Covers:\n"
+        "    - E1: Public behavior passes.\n"
+        "  - Touch:\n"
+        "    - src/feature.js\n"
+    )
+    evidence = "  - Evidence:\n    - M1: pending\n"
+    commands = "  - Commands:\n    - M1: node test.js\n"
+
+    with tempfile.TemporaryDirectory(prefix="keel-absent-verification-") as raw:
+        repo = Path(raw)
+
+        def problems_for(change: str, content: str) -> list:
+            write_text(repo / f"openspec/changes/{change}/tasks.md", content)
+            result = run_keel(
+                repo,
+                "gate",
+                "task-start",
+                "--change",
+                change,
+                "--task",
+                "1.1",
+                "--json",
+            )
+            return json.loads(result.stdout).get("problems", [])
+
+        # M1 — neither verification form declared.
+        none_declared = problems_for("noform", header + body + evidence)
+        naming = [
+            problem
+            for problem in none_declared
+            if "Verify" in problem.get("message", "")
+        ]
+        if len(naming) != 1:
+            report(
+                "absent-verification-form-is-one-problem: expected exactly one "
+                f"diagnostic naming Verify, found {len(naming)}."
+            )
+            for problem in none_declared:
+                report(f"  {problem.get('code')}: {problem.get('message')}")
+            return 1
+        leaked = sorted(
+            name
+            for problem in none_declared
+            if problem.get("code") == "missing-field"
+            for name in defaulted
+            if problem.get("message", "").startswith(f"{name} must be concrete")
+        )
+        if leaked:
+            report(
+                "absent-verification-form-is-one-problem: fields with documented "
+                f"defaults were still required: {', '.join(leaked)}."
+            )
+            return 1
+
+        # M2 — a genuine expanded v3 task that omits every defaulted field.
+        expanded = problems_for("expanded", header + body + commands + evidence)
+        if expanded:
+            report(
+                "absent-verification-form-is-one-problem: an expanded task "
+                "declaring Commands, Covers, Touch and Evidence did not pass."
+            )
+            for problem in expanded:
+                report(f"  {problem.get('code')}: {problem.get('message')}")
+            return 1
+        # Removing Commands from that same task must still fail.
+        if not problems_for("expanded-no-commands", header + body + evidence):
+            report(
+                "absent-verification-form-is-one-problem: removing Commands "
+                "from the expanded task left it passing."
+            )
+            return 1
+        # Candidate Boundary is the coupling contract's to require.
+        coupled = problems_for(
+            "coupled",
+            header
+            + body
+            + "  - Coupling: required\n"
+            + commands
+            + evidence,
+        )
+        if not any(
+            "Candidate Boundary" in problem.get("message", "") for problem in coupled
+        ):
+            report(
+                "absent-verification-form-is-one-problem: Coupling required did "
+                "not require a Candidate Boundary."
+            )
+            for problem in coupled:
+                report(f"  {problem.get('code')}: {problem.get('message')}")
+            return 1
+    if "absent-verification-form-is-one-problem" not in {
+        name for name, _ in SCENARIOS
+    }:
+        report(
+            "absent-verification-form-is-one-problem: the scenario registry does "
+            "not include it."
+        )
+        return 1
+    report("absent-verification-form-is-one-problem scenario passed.")
+    return 0
+
+
+def validate_non_concrete_check_names_token_scenario() -> int:
+    """Issue #28 item 5: the check diagnostic must name the slot it matched.
+
+    `unfilledToken` already identifies the matched token and `Verify` already
+    reports it. The per-check message said only that the check "must define a
+    concrete public check", which describes the consequence rather than the
+    cause, so the reporter had to guess which of several inline slots was the
+    problem.
+    """
+    slot = "<" + "url" + ">"
+    with tempfile.TemporaryDirectory(prefix="keel-check-token-") as raw:
+        repo = Path(raw)
+        base = task_capsule_compact_fixture().replace(
+            "    - M1: node test.js\n",
+            "    - M1: node test.js\n"
+            f"    - M2: run the fetch script against {slot} and assert the "
+            "recorded status\n",
+        ).replace("    - M1: pending\n", "    - M1: pending\n    - M2: pending\n")
+        write_text(repo / "openspec/changes/tokened/tasks.md", base)
+
+        def check_messages(change: str) -> list:
+            result = run_keel(
+                repo,
+                "gate",
+                "task-start",
+                "--change",
+                change,
+                "--task",
+                "1.1",
+                "--json",
+            )
+            payload = json.loads(result.stdout)
+            return [
+                problem.get("message", "")
+                for problem in payload.get("problems", [])
+                if problem.get("code") == "missing-command-check"
+            ]
+
+        tokened = check_messages("tokened")
+        if not tokened:
+            report(
+                "non-concrete-check-names-token: a check carrying a bare "
+                "unfilled slot produced no missing-command-check diagnostic."
+            )
+            return 1
+        if slot not in tokened[0]:
+            report(
+                "non-concrete-check-names-token: the diagnostic did not name "
+                f"the {slot} slot it matched."
+            )
+            report(tokened[0])
+            return 1
+        # Replacing exactly what the diagnostic names must clear it.
+        fixed = base.replace(slot, "`https://example.test/feed`")
+        write_text(repo / "openspec/changes/fixed/tasks.md", fixed)
+        if check_messages("fixed"):
+            report(
+                "non-concrete-check-names-token: replacing the named slot did "
+                "not clear the diagnostic."
+            )
+            return 1
+        # An empty check has no token to name, so the unqualified wording is
+        # still the honest one there.
+        empty = base.replace(
+            f"    - M2: run the fetch script against {slot} and assert the "
+            "recorded status\n",
+            "    - M2: pending\n",
+        )
+        write_text(repo / "openspec/changes/empty/tasks.md", empty)
+        bare = check_messages("empty")
+        if not bare:
+            report(
+                "non-concrete-check-names-token: a pending check produced no "
+                "missing-command-check diagnostic."
+            )
+            return 1
+        if "must define a concrete public check" not in bare[0]:
+            report(
+                "non-concrete-check-names-token: a pending check lost the "
+                "unqualified wording."
+            )
+            report(bare[0])
+            return 1
+    if "non-concrete-check-names-token" not in {name for name, _ in SCENARIOS}:
+        report(
+            "non-concrete-check-names-token: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("non-concrete-check-names-token scenario passed.")
+    return 0
+
+
+def validate_covers_question_reference_scope_scenario() -> int:
+    """Issue #28 item 9: citing a resolved question must not re-open it.
+
+    The question scan used to run over the whole Covers field, so a task that
+    named `Q1` beside the fact that closed it was told to declare a fallback for
+    a question it does not carry. The reporter's only available fix was to
+    delete the reference, which makes traceability worse.
+
+    Both sides are asserted. A scenario that only checked the newly passing
+    shape would also be satisfied by deleting the check outright.
+    """
+    with tempfile.TemporaryDirectory(prefix="keel-covers-question-") as raw:
+        repo = Path(raw)
+        base = task_capsule_compact_fixture()
+        # Still in scope: the question is the subject of its entry.
+        subject = base.replace(
+            "    - E1: Public behavior passes.\n",
+            "    - Q1: Should the widget retry on timeout?\n",
+        )
+        write_text(repo / "openspec/changes/subject/tasks.md", subject)
+        # Out of scope: the entry's subject is the fact, and the resolved
+        # question is named as the supporting detail that points at it.
+        detail = base.replace(
+            "    - E1: Public behavior passes.\n",
+            "    - F13 (Q1 resolved: the widget retries twice, then stops)\n",
+        )
+        write_text(repo / "openspec/changes/detail/tasks.md", detail)
+
+        def authority_messages(change: str) -> list:
+            result = run_keel(
+                repo,
+                "gate",
+                "task-start",
+                "--change",
+                change,
+                "--task",
+                "1.1",
+                "--json",
+            )
+            payload = json.loads(result.stdout)
+            return [
+                problem.get("message", "")
+                for problem in payload.get("problems", [])
+                if problem.get("code") == "unresolved-authority"
+            ]
+
+        blocking = authority_messages("subject")
+        if not blocking:
+            report(
+                "covers-question-reference-scope: a question that opens its "
+                "Covers entry produced no unresolved-authority diagnostic, so "
+                "the check no longer refuses anything."
+            )
+            return 1
+        if "Q1" not in blocking[0]:
+            report(
+                "covers-question-reference-scope: the diagnostic did not name "
+                "the question it read."
+            )
+            report(blocking[0])
+            return 1
+        citing = authority_messages("detail")
+        if citing:
+            report(
+                "covers-question-reference-scope: naming a resolved question as "
+                "supporting detail still demands a fallback for it."
+            )
+            report(citing[0])
+            return 1
+    if "covers-question-reference-scope" not in {name for name, _ in SCENARIOS}:
+        report(
+            "covers-question-reference-scope: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("covers-question-reference-scope scenario passed.")
+    return 0
+
+
 def validate_dev_only_plugin_source_scoping_scenario() -> int:
     """Issue #6: plugins/keel/ exists only in Keel's own repository.
 
@@ -5230,6 +6221,7 @@ def tracker_owner_tasks(findings: str, closure: str) -> str:
         "  - Stop Rules:\n"
         "    - Stop on failure.\n"
         "  - Evidence:\n"
+        "    - Contract: pending\n"
         "    - M1: passed\n"
         "    - Review:\n"
         "      - Status: pass\n"
@@ -5264,6 +6256,7 @@ def validate_tracker_durable_owner_scenario() -> int:
 
         def complete(findings: str, closure: str = "Covered by: 1.1"):
             write_text(tasks, tracker_owner_tasks(findings, closure))
+            record_contract_anchor(repo, "demo")
             return run_keel(
                 repo, "gate", "task-complete",
                 "--change", "demo", "--task", "1.1", "--json",
@@ -5685,6 +6678,7 @@ def validate_task_capsule_scenario() -> int:
             repo / "openspec/changes/demo/tasks.md",
             completion_task,
         )
+        record_contract_anchor(repo, "demo")
         completed = run_keel(
             repo,
             "gate",
@@ -6379,6 +7373,10 @@ def validate_core_gates_scenario() -> int:
                 "  - Stop Rules:\n"
                 "    - Stop on final assertion failure.\n"
                 "  - Evidence:\n"
+                # Read at call time, so every variant below carries the anchor
+                # recorded once for this fixture. Evidence is not in the capsule,
+                # so one fingerprint is correct for all of them.
+                f"    - Contract: {completion_anchor}\n"
                 f"    - M1: {evidence}\n"
                 "    - Review:\n"
                 f"      - Status: {review_status}\n"
@@ -6392,6 +7390,19 @@ def validate_core_gates_scenario() -> int:
                 "    - Summary\n"
             )
 
+        completion_anchor = "pending"
+        write_text(completion_tasks, completion_task("pending", "pass"))
+        if not record_contract_anchor(completion_repo, "demo"):
+            report("core-gates scenario could not record the completion anchor.")
+            return 1
+        recorded_line = re.search(
+            r"-\s*Contract:\s*(.+)", completion_tasks.read_text(encoding="utf-8")
+        )
+        if not recorded_line:
+            report("core-gates scenario found no recorded Contract anchor.")
+            return 1
+        completion_anchor = recorded_line.group(1).strip()
+
         write_text(completion_tasks, completion_task("pending", "pass"))
         missing_evidence = run_keel(
             completion_repo,
@@ -7194,6 +8205,7 @@ def validate_scope_rename_attribution_scenario() -> int:
         "  - Stop Rules:\n"
         "    - Stop on final assertion failure.\n"
         "  - Evidence:\n"
+        "    - Contract: pending\n"
         "    - M1: passed\n"
         "    - Review:\n"
         "      - Status: pass\n"
@@ -7237,6 +8249,7 @@ def validate_scope_rename_attribution_scenario() -> int:
             report("scope-rename scenario git mv failed:")
             report((moved.stderr or moved.stdout).strip())
             return 1
+        record_contract_anchor(repo, "demo")
         completed = run_keel(
             repo,
             "gate",
@@ -8598,6 +9611,7 @@ def validate_task_verification_strategies_scenario() -> int:
 
         def run_completion(fixture: str) -> subprocess.CompletedProcess[str]:
             write_text(tasks_path, fixture)
+            record_contract_anchor(repo, "demo")
             return run_keel(
                 repo,
                 "gate",
@@ -9337,6 +10351,7 @@ def _goal_task_block(
             "  - Stop Rules:",
             "    - stop on failure",
             "  - Evidence:",
+            "    - Contract: pending",
         ]
     )
     if filled:
@@ -10040,6 +11055,7 @@ def validate_native_goal_gate_order_scenario() -> int:
 
         # 4. With evidence and a passing Review recorded, task-complete passes.
         write_text(tasks_path, _goal_tasks_file([_goal_task_block(filled=True)]))
+        record_contract_anchor(repo, "sample-change")
         completed = run_keel(
             repo, "gate", "task-complete",
             "--change", "sample-change", "--task", "1.1", "--json",
@@ -10603,6 +11619,7 @@ def validate_single_task_goal_real_tasks_scenario() -> int:
                     [_goal_task_block(strategy=strategy, filled=True, redgreen=redgreen)]
                 ),
             )
+            record_contract_anchor(repo, "sample-change")
             done = run_keel(
                 repo, "gate", "task-complete",
                 "--change", "sample-change", "--task", "1.1", "--json", env=env,
@@ -10898,6 +11915,7 @@ def _single_task_matrix_target(target: str, root: Path) -> int:
             ]
         ),
     )
+    record_contract_anchor(repo, "sample-change")
     done = run_keel(repo, "gate", "task-complete", "--change", "sample-change", "--task", "1.1", "--json", env=env)
     if done.returncode != 0:
         report("native-single-task-matrix %s could not complete with evidence." % target)
@@ -13106,6 +14124,32 @@ SCENARIOS: tuple = (
         "unresolved-authority-names-field",
         validate_unresolved_authority_names_field_scenario,
     ),
+    (
+        "covers-question-reference-scope",
+        validate_covers_question_reference_scope_scenario,
+    ),
+    (
+        "non-concrete-check-names-token",
+        validate_non_concrete_check_names_token_scenario,
+    ),
+    (
+        "absent-verification-form-is-one-problem",
+        validate_absent_verification_form_is_one_problem_scenario,
+    ),
+    (
+        "task-complete-selection-requires-a-started-task",
+        validate_task_complete_selection_requires_a_started_task_scenario,
+    ),
+    ("task-body-ends-at-heading", validate_task_body_ends_at_heading_scenario),
+    (
+        "completion-requires-a-recorded-anchor",
+        validate_completion_requires_a_recorded_anchor_scenario,
+    ),
+    ("spec-template-validates", validate_spec_template_validates_scenario),
+    (
+        "tasks-template-red-green-example",
+        validate_tasks_template_red_green_example_scenario,
+    ),
     (
         "dev-only-plugin-source-scoping",
         validate_dev_only_plugin_source_scoping_scenario,