@christang/keel 5.3.6 → 5.3.7

package/assets/bootstrap/AGENTS.md

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

package/assets/openspec/schemas/keel-spec-driven/schema.yaml

@@ -108,8 +108,11 @@ artifacts:
       Accepted hidden-knowledge assumptions from risk-triggered deep
       alignment or a domain lens are critical expectations when they
       affect completion definition or execution boundaries.
-      Covers references the relevant D/F/A/Q identifiers. An unresolved Q<n>
-      without an authorized fallback blocks implementation.
+      Covers references the relevant D/F/A/Q identifiers. A Q<n> that opens a
+      Covers entry is an open question and blocks implementation without an
+      authorized fallback; the same identifier named inside an entry whose
+      subject is a fact is a citation and does not block, so a resolved question
+      can be cited beside the fact that closed it.
       A new or materially expanded dedicated skill remains non-executable until
       design or task evidence identifies authoritative sources, provenance and license
       implications, realistic positive and negative trigger cases, and

package/assets/openspec/schemas/keel-spec-driven/templates/spec.md

@@ -1,7 +1,9 @@
 ## ADDED Requirements
 
 ### Requirement: <!-- requirement name -->
-<!-- requirement text -->
+<!-- The requirement text MUST contain SHALL or MUST; validation refuses a
+     requirement without one, so keep the modal verb when filling this in. -->
+The system SHALL <!-- observable behavior -->
 
 #### Scenario: <!-- scenario name -->
 - **WHEN** <!-- condition -->

package/assets/openspec/schemas/keel-spec-driven/templates/tasks.md

@@ -11,7 +11,7 @@
 
 - [ ] 1.1 <!-- Task description -->
   - Covers:
-    - <source expectation: spec scenario as `capability / requirement or scenario heading`, hidden-knowledge assumption, domain lens requirement, or critical D<n>/F<n>/A<n>/Q<n>; an unresolved Q<n> requires an authorized fallback>
+    - <source expectation: spec scenario as `capability / requirement or scenario heading`, hidden-knowledge assumption, domain lens requirement, or critical D<n>/F<n>/A<n>/Q<n>; a Q<n> that OPENS an entry is an open question and requires an authorized fallback, while one named inside an entry about a fact is a citation and does not>
   - Touch:
     - <path>
   - Verify:
@@ -82,6 +82,36 @@
       - Findings: pending
     - Blocker: none
 
+## 3. <!-- Task Group Name -->
+
+- [ ] 3.1 <!-- Red-green example: a vertical-tdd task and the Evidence it must record -->
+  - Covers:
+    - <source expectation whose observable behavior this slice proves>
+  - Touch:
+    - <path>
+  - Verify:
+    <!-- The untagged check below is load-bearing: a red-green strategy whose
+         every check is tagged (regression) is refused as regression-only,
+         because a regression check has no honest red to record. -->
+    - Strategy: vertical-tdd
+    - M1: <public behavior check for the new behavior>
+    - M2 (regression): <check asserting behavior that is already green stays green>
+  - Evidence:
+    <!-- M1 is red-green, so it records THREE entries: the bare M1 plus M1.red
+         and M1.green. M2 is tagged regression, so it records only its bare
+         entry — it is exempt from .red/.green, not from Evidence. -->
+    - Contract: pending
+    - M1: pending
+    - M1.red: pending
+    - M1.green: pending
+    - M2: pending
+    - Review:
+      - Status: pending
+      - Acceptance check: pending
+      - Scope check: pending
+      - Findings: pending
+    - Blocker: none
+
 ## Invalidates
 
 <!-- task-start requires this section before any task of this change runs, so

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.3.6",
+  "version": "5.3.7",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.3.6",
+  "version": "5.3.7",
   "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.3.6",
+  "version": "5.3.7",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

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.7"
+PROTOCOL_VERSION = "5.3.7"
 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>",
@@ -4729,8 +4733,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 +5055,646 @@ 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
+
+
+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.
 
@@ -13106,6 +13752,27 @@ 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,
+    ),
+    ("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,

package/src/core/gates.js

@@ -103,6 +103,32 @@ function loadSelection(repo, options, requireTask = true) {
   return { change, tasksPath, content, tasks, selected: [selected] };
 }
 
+// The documented order is gate-then-checkbox, so first-unchecked is the right
+// inference for task-start and stays. The hazard is narrower: completing without
+// an explicit task infers a task that has not started, then reports its
+// readiness problems under a selection heading the author reads as the failure
+// of the task they just finished. A task that has started records a fingerprint
+// in its Evidence `Contract` anchor, so that anchor is what makes the inference
+// safe — and without one there is nothing for completion to compare against.
+function unstartedInferenceProblem(selection) {
+  const task = selection.selected[0];
+  const plan = contractAnchorPlan(selection, task);
+  if (plan && anchoredFingerprint(plan.previous)) return null;
+  const checked = [...selection.tasks].filter((item) => item.checked).pop();
+  return problem(
+    "ambiguous-completion-selection",
+    `task-complete inferred ${selection.change}#${task.id}, the first unchecked `
+      + "task, but that task records no start fingerprint in its Evidence "
+      + "`Contract` anchor, so it has not started and there is nothing to "
+      + `compare. ${
+        checked
+          ? `The most recently checked task is ${checked.id}. `
+          : ""
+      }Name the task you mean with \`--task\`, or run \`task-start --record\` `
+      + "first."
+  );
+}
+
 function contractAnchorPlan(selection, task) {
   const lines = selection.content.split("\n");
   const index = selection.tasks.findIndex((item) => item.id === task.id);
@@ -559,6 +585,20 @@ function completionChecks(repo, task, contract = null) {
 function taskComplete(repo, options) {
   const selection = loadSelection(repo, options);
   const task = selection.selected[0];
+  if (!options.task) {
+    const ambiguous = unstartedInferenceProblem(selection);
+    if (ambiguous) {
+      return gateResult(
+        "task-complete",
+        "fail",
+        selection.change,
+        [task.id],
+        [ambiguous],
+        [],
+        null
+      );
+    }
+  }
   const contract = compileTaskContract(repo, selection.change, task);
   const usableContract = contract.diagnostics.length === 0 ? contract : null;
   const checks = completionChecks(repo, task, usableContract);

package/src/core/task-contract.js

@@ -192,6 +192,16 @@ function verification(task) {
 }
 
 function commandLabelProblems(task) {
+  // A task that declared no verification form at all is reported once, by
+  // requiredFieldProblems, as the one field it is missing. Its orphan Evidence
+  // labels are a consequence of that same absence, and restating them here is
+  // the cascade that buries the actionable line.
+  if (
+    fieldValues(task, "Verify").length === 0
+    && fieldValues(task, "Commands").length === 0
+  ) {
+    return [];
+  }
   const problems = [];
   const seen = new Set();
   const labels = [];
@@ -222,9 +232,18 @@ function commandLabelProblems(task) {
     seen.add(command[1]);
     labels.push(command[1]);
     if (!isConcrete(command[2])) {
+      // Name the matched slot, the way the Verify diagnostic already does. The
+      // unqualified wording described the consequence, so an author with
+      // several slots in one check had to guess which one was read.
+      const token = unfilledToken(command[2]);
       problems.push({
         code: "missing-command-check",
-        message: `${command[1]} must define a concrete public check.`,
+        message: token
+          ? `${command[1]} carries the unfilled slot \`${token}\`, so it does `
+            + "not define a concrete public check. Replace that slot with the "
+            + "value the check actually runs against, or fence it in inline "
+            + "code when it is a documented pattern rather than a slot."
+          : `${command[1]} must define a concrete public check.`,
       });
     }
   }
@@ -343,38 +362,44 @@ function requiredFieldProblems(task) {
         },
       ];
     }
-  }
-  const required = compact
-    ? ["Covers", "Verify", "Evidence"]
-    : [
-        "Owner",
-        "Mode",
-        "Covers",
-        "Read",
-        "Commands",
-        "Acceptance",
-        "Candidate Boundary",
-        "Stop Rules",
-        "Evidence",
-        "Report",
+    // Neither verification form declared. That is a compact v4 task missing one
+    // field, not an expanded v3 task missing nine — and listing the v3 set here
+    // reported a schema this author never chose.
+    if (!isConcrete(field(task, "Commands"))) {
+      return [
+        {
+          code: "missing-verification-form",
+          message:
+            "The task declares no verification form. Add a `Verify` field with "
+            + "a `Strategy:` entry and one `M<n>:` check per behavior the task "
+            + "proves. The expanded v3 `Commands` field is the other accepted "
+            + "form; the remaining v3 fields are not required.",
+        },
+        // The rest of the compact set is still reported, so a near-empty task
+        // learns everything it is missing. Only the v3 cascade is replaced.
+        ...missingFieldProblems(task, ["Covers", "Evidence"]),
       ];
-  const problems = required
+    }
+  }
+  // The expanded set is the compact set with `Commands` in place of `Verify`.
+  // Owner, Mode, Read, and Acceptance resolve to documented defaults or derive
+  // from Covers, Report is consumed nowhere, and Candidate Boundary and Stop
+  // Rules belong to couplingProblems, which requires them when the coupling
+  // contract does. Requiring them here reported fields that were already in
+  // effect.
+  return missingFieldProblems(
+    task,
+    compact ? ["Covers", "Verify", "Evidence"] : ["Covers", "Commands", "Evidence"]
+  );
+}
+
+function missingFieldProblems(task, names) {
+  return names
     .filter((name) => !isConcrete(field(task, name)))
     .map((name) => ({
       code: "missing-field",
       message: `${name} must be concrete.`,
     }));
-  if (
-    !compact
-    && !isConcrete(field(task, "Autonomy boundary"))
-    && !isConcrete(field(task, "Stop if"))
-  ) {
-    problems.push({
-      code: "missing-boundary",
-      message: "Stop if or Autonomy boundary must be concrete.",
-    });
-  }
-  return problems;
 }
 
 function canonical(value) {
@@ -808,8 +833,18 @@ function compileTaskContract(repo, change, task) {
   if (!autonomy.some((item) => /^Pre-authorized fallback:/i.test(item))) {
     autonomy.push("Pre-authorized fallback: none");
   }
+  // A question is unresolved authority when it is the subject of its Covers
+  // entry. Scanning the whole field also matched a resolved question named as
+  // supporting detail beside the fact that closed it, and the only fix
+  // available to the author was deleting the reference — so the check punished
+  // the traceability it exists to protect.
   const questionIds = [
-    ...new Set(field(task, "Covers").match(/\bQ\d+\b/g) || []),
+    ...new Set(
+      normalizedValues(task, "Covers", { ordered: true })
+        .map((entry) => entry.match(/^(Q\d+)\b/))
+        .filter(Boolean)
+        .map((match) => match[1])
+    ),
   ];
   const fallback = autonomy.find((item) =>
     /^Pre-authorized fallback:/i.test(item)