@christang/keel 5.49.0 → 5.50.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.49.0 -->
+<!-- keel:start version=5.50.0 -->
 ## 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/templates/tasks.md

@@ -21,9 +21,15 @@
   - Touch:
     - <path>
   - Verify:
-    <!-- verification discipline: Strategy is one of vertical-tdd,
-         regression-first, characterization, snapshot-characterization,
-         rendered-behavior, or evidence-first. Each M<n> check must prove the
+    <!-- verification discipline: Strategy is REQUIRED and is one of
+         vertical-tdd, regression-first, characterization,
+         snapshot-characterization, rendered-behavior, or evidence-first.
+         Nothing is supplied by default, because the value an omission
+         would select is the one with no red-green requirement.
+         evidence-first additionally carries a `Reason:` entry beside
+         Strategy, stating why no meaningful red-green loop applies —
+         docs, configuration, diagnosis, or another reason nothing here
+         can fail first. No mode exempts it. Each M<n> check must prove the
          resolved Acceptance through the public interface, not build-only or
          shape-only evidence. Red-green strategies record per-label `.red` and
          `.green` Evidence entries IN ADDITION TO the bare `M<n>` entry, which
@@ -78,6 +84,7 @@
     - none
   - Verify:
     - Strategy: evidence-first
+    - Reason: <why no meaningful red-green loop applies — a diagnosis task reproduces and reports, so nothing it writes can fail first>
     - M1: <reproduction or diagnosis check with its observable evidence>
   - Evidence:
     - Contract: pending

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.49.0",
+  "version": "5.50.0",
   "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.49.0",
+  "version": "5.50.0",
   "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.49.0"
-PROTOCOL_VERSION = "5.49.0"
+PACKAGE_VERSION = "5.50.0"
+PROTOCOL_VERSION = "5.50.0"
 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
@@ -3377,6 +3377,8 @@ def gate_task(
         "Covers": "\n    - E1: hook behavior",
         "Read": "\n    - openspec/changes/demo/proposal.md",
         "Touch": "\n    - src/example.js",
+        "Verification Strategy": "evidence-first",
+        "Verification Reason": "this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first",
         "Commands": "\n    - M1: npm test",
         "Acceptance": "the required command succeeds",
         "Execution recommendation": "Claude Code implementation note (advisory)",
@@ -4329,6 +4331,7 @@ def task_contract_fixture(
     touch: tuple[str, ...] = ("src/feature.js",),
     commands: tuple[str, ...] = ("M1: node test.js",),
     evidence: tuple[str, ...] = ("M1: pending",),
+    strategy: str | None = "evidence-first",
 ) -> str:
     touch_lines = "".join(f"    - {item}\n" for item in touch)
     command_lines = "".join(f"    - {item}\n" for item in commands)
@@ -4344,8 +4347,11 @@ def task_contract_fixture(
         "    - README.md\n"
         "  - Touch:\n"
         f"{touch_lines}"
-        "  - Commands:\n"
-        f"{command_lines}"
+        + (f"  - Verification Strategy: {strategy}\n" if strategy else "")
+        + (f"  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
+           if strategy == "evidence-first" else "")
+        + "  - Commands:\n"
+        + f"{command_lines}"
         "  - Acceptance:\n"
         "    - Public behavior passes.\n"
         "  - Autonomy boundary:\n"
@@ -4555,6 +4561,7 @@ def section_boundary_task(
         f"{touch}"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js reports the public behavior passing\n"
         "  - Acceptance:\n"
         "    - Public behavior passes.\n"
@@ -7091,6 +7098,7 @@ def task_capsule_expanded_fixture() -> str:
     ).replace(
         "  - Acceptance:\n",
         "  - Verification Strategy: evidence-first\n"
+        "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "  - Acceptance:\n",
     )
 
@@ -7107,6 +7115,7 @@ def task_capsule_compact_fixture() -> str:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js\n"
         "  - Autonomy boundary:\n"
         "    - Default: hard-stop\n"
@@ -7226,7 +7235,7 @@ def validate_non_concrete_verify_diagnostic_scenario() -> int:
         # 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",
+            "  - Verify:\n    - Strategy: evidence-first\n    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n    - M1: node test.js\n",
         ):
             bare = bare.replace(block, "")
         write_text(repo / "openspec/changes/bare/tasks.md", bare)
@@ -7738,7 +7747,11 @@ SPEC_TEMPLATE_RELATIVE = "schemas/keel-spec-driven/templates/spec.md"
 
 
 SLOT_FILLER = "the recorded feed status"
-SLOT_VOCABULARY = {"<strategy>": "evidence-first"}
+# The filler must be a strategy the generic task can use as written.
+# `evidence-first` no longer is: it carries a `Reason:` the generic task
+# has no slot for, and giving it one would put a line there that is wrong
+# for every other strategy the slot can take.
+SLOT_VOCABULARY = {"<strategy>": "vertical-tdd"}
 
 
 def fill_template_slots(text: str) -> str:
@@ -7815,7 +7828,7 @@ def validate_guard_scope_is_the_repository_scenario() -> int:
             "- [ ] 1.1 Exercise the guard\n"
             "  - Covers:\n    - demo-cap / The system emits a feed status\n"
             "  - Touch:\n    - src/feature.js\n"
-            "  - Verify:\n    - Strategy: evidence-first\n    - M1: node test.js\n"
+            "  - Verify:\n    - Strategy: evidence-first\n    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n    - M1: node test.js\n"
             "  - Evidence:\n    - Contract: pending\n    - M1: pending\n"
             "    - Review:\n      - Status: pending\n"
             "      - Acceptance check: pending\n      - Scope check: pending\n"
@@ -8726,7 +8739,7 @@ def validate_default_completion_attributes_writes_scenario() -> int:
             "- [ ] 1.1 Exercise task contract\n"
             "  - Covers:\n    - E1: Public behavior passes.\n"
             "  - Touch:\n    - src/declared.js\n"
-            "  - Verify:\n    - Strategy: evidence-first\n"
+            "  - Verify:\n    - Strategy: evidence-first\n    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js asserts the recorded feed status\n"
             "  - Evidence:\n    - Contract: pending\n    - M1: the suite passed\n"
             "    - Review:\n      - Status: pass\n"
@@ -8924,7 +8937,7 @@ def validate_git_paths_carry_no_escaping_scenario() -> int:
             "  - Covers:\n    - E1: Public behavior passes.\n"
             "  - Touch:\n"
             f"{touch_lines}"
-            "  - Verify:\n    - Strategy: evidence-first\n"
+            "  - Verify:\n    - Strategy: evidence-first\n    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js asserts the recorded feed status\n"
             "  - Evidence:\n    - Contract: pending\n    - M1: the suite passed\n"
             "    - Review:\n      - Status: pass\n"
@@ -9138,7 +9151,7 @@ def validate_guard_containment_is_resolved_scenario() -> int:
             "- [ ] 1.1 Exercise the guard\n"
             "  - Covers:\n    - demo-cap / The system emits a feed status\n"
             "  - Touch:\n    - src/allowed.js\n    - docs/**\n"
-            "  - Verify:\n    - Strategy: evidence-first\n"
+            "  - Verify:\n    - Strategy: evidence-first\n    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js asserts the recorded feed status\n"
             "  - Evidence:\n    - Contract: pending\n    - M1: pending\n",
         )
@@ -9268,6 +9281,7 @@ def validate_completion_requires_a_recorded_anchor_scenario() -> int:
             "    - src/feature.js\n"
             "  - Verify:\n"
             "    - Strategy: evidence-first\n"
+            "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js asserts the recorded feed status\n"
             "  - Evidence:\n"
             f"    - Contract: {contract}\n"
@@ -9428,6 +9442,7 @@ def _anchor_fixture(
         f"    - {touch}\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js asserts the recorded feed status\n"
         "  - Evidence:\n"
         f"    - Contract: {contract}\n"
@@ -9718,6 +9733,7 @@ def validate_task_body_ends_at_heading_scenario() -> int:
             "    - src/feature.js\n"
             "  - Verify:\n"
             "    - Strategy: evidence-first\n"
+            "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js asserts the recorded feed status\n"
             "  - Evidence:\n"
             f"    - Contract: {contract}\n"
@@ -9835,9 +9851,17 @@ def validate_task_body_ends_at_heading_scenario() -> int:
         # 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.
+        #
+        # Moved once, deliberately, when `evidence-first` began requiring a
+        # stated reason: this fixture gained a `Verification Reason:` field, so
+        # its own capsule changed. What did not change is the capsule of a task
+        # that states no reason — the `reason` key is emitted only when there is
+        # one, and a vertical-tdd task compiles to the identical block and the
+        # identical fingerprint before and after, measured both ways. So no
+        # existing anchor drifted; this fixture is simply a different task now.
         pinned = {
-            "1.1": "2f723a8778160a2d51cd91e34255bf19f2c654fa23cdcd7b013915727a541d17",
-            "2.1": "5e0481362b06992d0317c91d34bbd5d6746fb9c1fee47566060f61fbba7cbf05",
+            "1.1": "11110c1cdde55df1008c6a2bd9f6bde2bffa286a34ae93addb9cf66fc1e5b90f",
+            "2.1": "62f7dfaec87e0614dae7e4935ce1749554f141a23518b094632eb8423e96d54c",
         }
         plain = (
             "# Tasks\n\n"
@@ -10093,6 +10117,7 @@ def validate_task_complete_selection_requires_a_started_task_scenario() -> int:
             "    - src/feature.js\n"
             "  - Verify:\n"
             "    - Strategy: evidence-first\n"
+            "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js\n"
             "  - Evidence:\n"
             f"    - Contract: {contract}\n"
@@ -10228,7 +10253,11 @@ def validate_absent_verification_form_is_one_problem_scenario() -> int:
         "    - src/feature.js\n"
     )
     evidence = "  - Evidence:\n    - M1: pending\n"
-    commands = "  - Commands:\n    - M1: node test.js\n"
+    commands = (
+        "  - Verification Strategy: evidence-first\n"
+        "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
+        "  - Commands:\n    - M1: node test.js\n"
+    )
 
     with tempfile.TemporaryDirectory(prefix="keel-absent-verification-") as raw:
         repo = Path(raw)
@@ -10563,7 +10592,7 @@ def validate_unusable_contract_names_only_its_cause_scenario() -> int:
         # 6. Suppression must not hide a task that genuinely declares no
         #    verification form. The refusal names the compact field to add.
         noform = clean.replace(
-            "  - Verify:\n    - Strategy: evidence-first\n    - M1: node test.js\n",
+            "  - Verify:\n    - Strategy: evidence-first\n    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n    - M1: node test.js\n",
             "",
         )
         write_text(repo / "openspec/changes/noform/tasks.md", noform)
@@ -10855,6 +10884,8 @@ def tracker_owner_tasks(findings: str, closure: str) -> str:
         "    - README.md\n"
         "  - Touch:\n"
         "    - src/feature.js\n"
+        "  - Verification Strategy: evidence-first\n"
+        "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "  - Commands:\n"
         "    - M1: node test.js\n"
         "  - Acceptance:\n"
@@ -11255,6 +11286,8 @@ def review_extent_tasks(review: str, blocker: str = "none") -> str:
         "    - README.md\n"
         "  - Touch:\n"
         "    - src/feature.js\n"
+        "  - Verification Strategy: evidence-first\n"
+        "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "  - Commands:\n"
         "    - M1: node test.js\n"
         "  - Acceptance:\n"
@@ -11524,6 +11557,8 @@ def reauthorizations_tasks(reauthorizations: str, blocker: str = "none") -> str:
         "    - README.md\n"
         "  - Touch:\n"
         "    - src/feature.js\n"
+        "  - Verification Strategy: evidence-first\n"
+        "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "  - Commands:\n"
         "    - M1: node test.js\n"
         "  - Acceptance:\n"
@@ -12655,6 +12690,8 @@ def validate_core_gates_scenario() -> int:
             "  - Touch:\n"
             "    - src/feature.js\n"
             "    - openspec/changes/demo/tasks.md\n"
+            "  - Verification Strategy: evidence-first\n"
+            "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "  - Commands:\n"
             "    - M1: node test.js\n"
             "  - Acceptance:\n"
@@ -12805,6 +12842,8 @@ def validate_core_gates_scenario() -> int:
                 "  - Touch:\n"
                 "    - src/feature.js\n"
                 "    - openspec/changes/demo/tasks.md\n"
+                "  - Verification Strategy: evidence-first\n"
+                "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
                 "  - Commands:\n"
                 "    - M1: node test.js\n"
                 "  - Acceptance:\n"
@@ -13298,6 +13337,8 @@ def validate_core_gates_scenario() -> int:
                 "  - Touch:\n"
                 + touch
                 + "    - openspec/changes/demo/tasks.md\n"
+                "  - Verification Strategy: evidence-first\n"
+                "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
                 "  - Commands:\n"
                 "    - M1: node test.js\n"
                 "  - Acceptance:\n"
@@ -13519,6 +13560,8 @@ def validate_core_gates_scenario() -> int:
                 "    - README.md\n"
                 "  - Touch:\n"
                 "    - src/feature.js\n"
+                "  - Verification Strategy: evidence-first\n"
+                "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
                 "  - Commands:\n"
                 "    - M1: node test.js\n"
                 "  - Acceptance:\n"
@@ -13689,6 +13732,8 @@ def validate_scope_rename_attribution_scenario() -> int:
         "    - src/renamed-from.js\n"
         "    - src/renamed-to.js\n"
         "    - openspec/changes/demo/tasks.md\n"
+        "  - Verification Strategy: evidence-first\n"
+        "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "  - Commands:\n"
         "    - M1: node test.js\n"
         "  - Acceptance:\n"
@@ -15865,6 +15910,8 @@ def validate_native_runtime_projection_scenario() -> int:
             "    - README.md\n"
             "  - Touch:\n"
             "    - src/feature.js\n"
+            "  - Verification Strategy: evidence-first\n"
+            "  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "  - Commands:\n"
             "    - M1: node test.js\n"
             "  - Acceptance:\n"
@@ -16457,7 +16504,7 @@ def _goal_task_block(
     title: str = "Deliver one bounded behavior",
     checked: bool = False,
     acceptance: tuple[str, ...] = ("Observable result is proven by M1.",),
-    strategy: str | None = None,
+    strategy: str | None = "evidence-first",
     filled: bool = False,
     blocker: str = "none",
     redgreen: bool = False,
@@ -16476,6 +16523,8 @@ def _goal_task_block(
     ]
     if strategy:
         lines.append("  - Verification Strategy: %s" % strategy)
+        if strategy == "evidence-first":
+            lines.append("  - Verification Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first")
     lines.append("  - Commands:")
     lines.append("    - M1: node test.js")
     lines.append("  - Acceptance:")
@@ -17101,6 +17150,7 @@ def standing_authorization_task(boundary: str = "") -> str:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js proves the public behavior\n"
         + boundary
         + "  - Evidence:\n"
@@ -18096,6 +18146,7 @@ def validate_delegation_never_weakens_scenario() -> int:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js proves the public behavior\n"
         "  - Evidence:\n"
         "    - Contract: pending\n"
@@ -18369,6 +18420,7 @@ def validate_delegation_goal_budget_scenario() -> int:
             + padding
             + "  - Verify:\n"
             "    - Strategy: evidence-first\n"
+            "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js proves the public behavior\n"
             "  - Evidence:\n"
             "    - Contract: pending\n"
@@ -18938,6 +18990,7 @@ def validate_triage_admits_only_a_start_scenario() -> int:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js proves the public behavior\n"
         "  - Evidence:\n"
         "    - Contract: pending\n"
@@ -19200,6 +19253,7 @@ def validate_precedent_never_weakens_scenario() -> int:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js proves the public behavior\n"
         "  - Evidence:\n"
         "    - Contract: pending\n"
@@ -19323,6 +19377,7 @@ def validate_standing_authorization_never_weakens_scenario() -> int:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js proves the public behavior\n"
         "  - Evidence:\n"
         "    - Contract: pending\n"
@@ -19481,6 +19536,7 @@ def validate_continuation_authorization_scenario() -> int:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js proves the public behavior\n"
         "  - Evidence:\n"
         "    - Contract: pending\n"
@@ -19925,6 +19981,7 @@ def validate_verify_layer_tag_scenario() -> int:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1 (fast): node fast.js\n"
         "    - M2: node full.js\n"
         "  - Autonomy boundary:\n"
@@ -21334,6 +21391,7 @@ def guard_task_fixture(checked: bool = False) -> str:
         "    - docs/**\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js\n"
         "  - Evidence:\n"
         "    - M1: pending\n"
@@ -21433,6 +21491,7 @@ def record_layer_tasks(checked: bool = False, touch: str = "src/feature.js") ->
         f"    - {touch}\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js\n"
         "  - Evidence:\n"
         "    - M1: pending\n"
@@ -21450,6 +21509,7 @@ def mode_fixture_tasks(mode: str, touch: str) -> str:
         f"    - {touch}\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: git rev-parse HEAD resolves and git log reports one commit\n"
         "  - Evidence:\n"
         "    - Contract: pending\n"
@@ -21571,6 +21631,7 @@ def sibling_scope_tasks(sibling_checked: bool, sibling_touch: str) -> str:
             + "".join(f"    - {entry}\n" for entry in touch.split(","))
             + "  - Verify:\n"
             "    - Strategy: evidence-first\n"
+            "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js\n"
             "  - Evidence:\n"
             "    - M1: verified\n"
@@ -22182,6 +22243,7 @@ def validate_touch_write_guard_scenario() -> int:
             "    - src/other.js\n"
             "  - Verify:\n"
             "    - Strategy: evidence-first\n"
+            "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js\n"
             "  - Evidence:\n"
             "    - M1: pending\n"
@@ -22272,6 +22334,7 @@ def compaction_task_fixture() -> str:
         "    - src/feature.js\n"
         "  - Verify:\n"
         "    - Strategy: evidence-first\n"
+        "    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
         "    - M1: node test.js\n"
         "  - Evidence:\n"
         "    - Contract: sha256:"
@@ -23569,7 +23632,7 @@ def validate_declared_paths_are_read_whole_scenario() -> int:
             "- [x] 1.1 Exercise the declared-path readers\n"
             "  - Covers:\n    - E1: Public behavior passes.\n"
             "  - Touch:\n    - src/declared.js\n"
-            "  - Verify:\n    - Strategy: evidence-first\n"
+            "  - Verify:\n    - Strategy: evidence-first\n    - Reason: this is a gate fixture; it exercises contract structure and has no executable behavior that can fail first\n"
             "    - M1: node test.js asserts the recorded feed status\n"
             "  - Evidence:\n"
             "    - Contract: keel-task-capsule/v1 sha256:"
@@ -24861,6 +24924,304 @@ def validate_output_survives_the_pipe_scenario() -> int:
     return 0
 
 
+# A helper the strategy scenarios share. The task body is written out rather
+# than reusing `change_verify_task` because these scenarios need to omit fields
+# that helper always emits.
+def strategy_probe_task(
+    *,
+    strategy: str | None,
+    reason: str | None = None,
+    mode: str = "implementation",
+    form: str = "Verify",
+    commands: tuple[str, ...] = ("M1: node test.js asserts the public behavior",),
+) -> str:
+    lines = [
+        "- [ ] 1.1 Strategy probe",
+        "  - Owner: claude",
+        f"  - Mode: {mode}",
+        "  - Covers:",
+        "    - E1: the task proves its own behavior",
+        "  - Read:",
+        "    - README.md",
+        "  - Touch:",
+        "    - src/example.js",
+        f"  - {form}:",
+    ]
+    if strategy is not None:
+        label = "Strategy" if form == "Verify" else "Verification Strategy"
+        lines.append(f"    - {label}: {strategy}")
+    if reason is not None:
+        lines.append(f"    - Reason: {reason}")
+    lines.extend(f"    - {entry}" for entry in commands)
+    lines.extend(
+        [
+            "  - Acceptance:",
+            "    - Public behavior passes.",
+            "  - Autonomy boundary:",
+            "    - Default: hard-stop",
+            "    - Pre-authorized fallback: none",
+            "  - Stop Rules:",
+            "    - Stop on failure.",
+            "  - Evidence:",
+            "    - Contract: pending",
+        ]
+    )
+    lines.extend(
+        f"    - {entry.split(':', 1)[0].split(' ')[0]}: pending" for entry in commands
+    )
+    lines.extend(
+        [
+            "    - Review:",
+            "      - Status: pass",
+            "      - Acceptance check: behavior proven.",
+            "      - Scope check: writes stayed inside Touch.",
+            "      - Findings: none",
+            "    - Blocker: none",
+            "  - Stop if:",
+            "    - Requires files outside Touch.",
+        ]
+    )
+    return "\n".join(lines) + "\n"
+
+
+def strategy_probe_start(root: Path, name: str, task: str) -> dict:
+    repo = root / name
+    write_gate_fixture(repo, tasks=task)
+    result = run_keel(
+        repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+    )
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return {"status": "unparsed", "problems": [{"message": result.stdout[:400]}]}
+
+
+def problem_text(payload: dict) -> str:
+    return " ".join(
+        str(entry.get("message", "")) for entry in (payload.get("problems") or [])
+    )
+
+
+def problem_codes(payload: dict) -> list[str]:
+    return [str(entry.get("code", "")) for entry in (payload.get("problems") or [])]
+
+
+# The strategy was the one capsule field the compiler supplied from a value no
+# spec documents as a default — and it supplied the weakest of the six, so
+# omitting the line was how a task opted out of red-green.
+def validate_strategy_is_declared_scenario() -> int:
+    label = "a-strategy-is-declared"
+    with tempfile.TemporaryDirectory(prefix="keel-strategy-") as raw:
+        root = Path(raw)
+
+        missing = strategy_probe_start(
+            root, "missing", strategy_probe_task(strategy=None)
+        )
+        if missing.get("status") != "fail":
+            report(
+                f"{label}: a task declaring Verify with no Strategy was not "
+                f"refused; task-start returned {missing.get('status')!r}."
+            )
+            return 1
+        text = problem_text(missing)
+        for needed in ("vertical-tdd", "evidence-first", "strategy"):
+            if needed not in text:
+                report(
+                    f"{label}: the refusal for a missing strategy omits "
+                    f"{needed!r}; got {text!r}."
+                )
+                return 1
+        # The failure this change exists to remove: reporting the task as using
+        # a strategy it never named.
+        if "unsupported" in text:
+            report(
+                f"{label}: a missing strategy was reported as an unsupported "
+                f"one, which sends the reader looking for a typo; got {text!r}."
+            )
+            return 1
+        if "missing-verification-strategy" not in problem_codes(missing):
+            report(
+                f"{label}: the refusal for a missing strategy carries no "
+                f"missing-verification-strategy code; got "
+                f"{problem_codes(missing)!r}."
+            )
+            return 1
+
+        legacy = strategy_probe_start(
+            root,
+            "legacy",
+            strategy_probe_task(strategy=None, form="Commands"),
+        )
+        if legacy.get("status") != "fail":
+            report(
+                f"{label}: an expanded v3 task declaring Commands with no "
+                "Verification Strategy was not refused; task-start returned "
+                f"{legacy.get('status')!r}."
+            )
+            return 1
+
+        for strategy in (
+            "vertical-tdd",
+            "regression-first",
+            "characterization",
+            "snapshot-characterization",
+            "rendered-behavior",
+        ):
+            declared = strategy_probe_start(
+                root, f"ok-{strategy}", strategy_probe_task(strategy=strategy)
+            )
+            if declared.get("status") != "pass":
+                report(
+                    f"{label}: a task declaring {strategy} was refused; "
+                    f"{problem_text(declared)!r}."
+                )
+                return 1
+
+        unsupported = strategy_probe_start(
+            root, "unsupported", strategy_probe_task(strategy="made-up-thing")
+        )
+        if unsupported.get("status") != "fail":
+            report(
+                f"{label}: an unsupported strategy was not refused; task-start "
+                f"returned {unsupported.get('status')!r}."
+            )
+            return 1
+        if "unsupported" not in problem_text(unsupported):
+            report(
+                f"{label}: an unsupported strategy lost its own diagnostic; "
+                f"got {problem_text(unsupported)!r}."
+            )
+            return 1
+
+        # A task declaring no verification form at all is already reported once,
+        # as the one field it is missing. Restating it as a missing strategy is
+        # the cascade this repository has removed before.
+        formless = strategy_probe_start(
+            root,
+            "formless",
+            strategy_probe_task(strategy=None).replace("  - Verify:\n", ""),
+        )
+        codes = problem_codes(formless)
+        if "missing-verification-strategy" in codes:
+            report(
+                f"{label}: a task declaring no verification form was also told "
+                f"its strategy is missing; codes {codes!r}."
+            )
+            return 1
+        if codes != ["missing-verification-form"]:
+            report(
+                f"{label}: a task declaring no verification form should be "
+                f"reported once, as that; got codes {codes!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+# `evidence-first` is scoped by an absence — work that cannot use a meaningful
+# red-green loop — and an absence is exactly the claim that has to be stated to
+# be reviewable. The gate checks the reason is there and is a sentence; whether
+# it is true belongs to the Review, the same contract `Discard reason:` has.
+def validate_weakest_strategy_states_its_reason_scenario() -> int:
+    label = "the-weakest-strategy-states-its-reason"
+    with tempfile.TemporaryDirectory(prefix="keel-reason-") as raw:
+        root = Path(raw)
+
+        silent = strategy_probe_start(
+            root, "silent", strategy_probe_task(strategy="evidence-first")
+        )
+        if silent.get("status") != "fail":
+            report(
+                f"{label}: an evidence-first task stating no reason was not "
+                f"refused; task-start returned {silent.get('status')!r}."
+            )
+            return 1
+        if "reason" not in problem_text(silent).lower():
+            report(
+                f"{label}: the refusal does not name the reason as what is "
+                f"missing; got {problem_text(silent)!r}."
+            )
+            return 1
+
+        for slot in ("TODO", "<why>"):
+            empty = strategy_probe_start(
+                root,
+                f"slot-{slot.strip('<>')}",
+                strategy_probe_task(strategy="evidence-first", reason=slot),
+            )
+            if empty.get("status") != "fail":
+                report(
+                    f"{label}: an evidence-first task whose reason is {slot!r} "
+                    f"was accepted; task-start returned {empty.get('status')!r}."
+                )
+                return 1
+
+        stated = strategy_probe_start(
+            root,
+            "stated",
+            strategy_probe_task(
+                strategy="evidence-first",
+                reason="this task only moves documentation; there is no "
+                "executable behavior that can fail first.",
+            ),
+        )
+        if stated.get("status") != "pass":
+            report(
+                f"{label}: an evidence-first task stating a reason was refused; "
+                f"{problem_text(stated)!r}."
+            )
+            return 1
+        verification = (
+            (stated.get("contract") or {})
+            .get("capsule", {})
+            .get("verification", {})
+        )
+        if "documentation" not in str(verification.get("reason", "")):
+            report(
+                f"{label}: the compiled capsule does not carry the stated "
+                f"reason in its verification block; got {verification!r}."
+            )
+            return 1
+        # D5: the reason is a field, not a check. A reason that took an M<n>
+        # label would be a check the author never wrote.
+        labels = [entry.get("label") for entry in verification.get("commands", [])]
+        if labels != ["M1"]:
+            report(
+                f"{label}: the reason was parsed as a check; the compiled "
+                f"checks are {labels!r}."
+            )
+            return 1
+
+        # D3: no exemption. A mode the same author writes would be a second
+        # escape hatch, and the first one is what this change closes.
+        diagnostic = strategy_probe_start(
+            root,
+            "diagnose-only",
+            strategy_probe_task(strategy="evidence-first", mode="diagnose-only"),
+        )
+        if diagnostic.get("status") != "fail":
+            report(
+                f"{label}: a diagnose-only task skipped the reason; task-start "
+                f"returned {diagnostic.get('status')!r}."
+            )
+            return 1
+
+        # D4: the requirement reaches only the strategy it is about.
+        redgreen = strategy_probe_start(
+            root, "redgreen", strategy_probe_task(strategy="vertical-tdd")
+        )
+        if redgreen.get("status") != "pass":
+            report(
+                f"{label}: a vertical-tdd task was asked for a reason; "
+                f"{problem_text(redgreen)!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
 # A scenario name, as the registry spells one. Two registered names carry no
 # hyphen — `cli` and `uninstall` — so requiring one would leave exactly those
 # two unchecked, and allowing single words was measured to add no false
@@ -25092,6 +25453,8 @@ SCENARIOS: tuple = (
     ("doctor-openspec-honesty", validate_doctor_openspec_honesty_scenario),
     ("the-marker-version-is-read", validate_marker_version_is_read_scenario),
     ("output-survives-the-pipe", validate_output_survives_the_pipe_scenario),
+    ("a-strategy-is-declared", validate_strategy_is_declared_scenario),
+    ("the-weakest-strategy-states-its-reason", validate_weakest_strategy_states_its_reason_scenario),
     (
         "authored-scenario-names-are-registered",
         validate_authored_scenario_names_scenario,

package/src/core/task-contract.js

@@ -175,8 +175,16 @@ function isPassingReviewStatus(value) {
 function verification(task) {
   const compact = fieldValues(task, "Verify");
   const strategyEntry = compact.find((entry) => /^Strategy:\s*/i.test(entry));
+  // `evidence-first` is the one strategy scoped by an absence — work that
+  // cannot use a meaningful red-green loop — so the task states why. It is a
+  // field beside `Strategy:`, not a check: everything else under `Verify` is a
+  // command, and a reason that took an `M<n>` label would be a check the author
+  // never wrote and evidence nobody can record.
+  const reasonEntry = compact.find((entry) => /^Reason:\s*/i.test(entry));
+  const isVerificationField = (entry) =>
+    /^Strategy:\s*/i.test(entry) || /^Reason:\s*/i.test(entry);
   const commandSource = compact.length > 0
-    ? compact.filter((entry) => !/^Strategy:\s*/i.test(entry))
+    ? compact.filter((entry) => !isVerificationField(entry))
     : fieldValues(task, "Commands");
   const commands = commandSource.map((entry) => {
     // An optional tag set after the M<n> label. `fast`/`full` marks which checks
@@ -202,11 +210,21 @@ function verification(task) {
   });
   return {
     compact: compact.length > 0,
+    // No default. The strategy is not among the defaults the capsule inherits,
+    // and the value this once fell back to — `evidence-first` — is the one
+    // strategy with no red-green requirement, so omitting the line was how a
+    // task opted out of red-green with nothing on screen saying so. An absent
+    // strategy is now reported rather than chosen.
     strategy: normalizeText(
       strategyEntry
         ? strategyEntry.replace(/^Strategy:\s*/i, "")
         : field(task, "Verification Strategy")
-    ) || "evidence-first",
+    ),
+    reason: normalizeText(
+      reasonEntry
+        ? reasonEntry.replace(/^Reason:\s*/i, "")
+        : field(task, "Verification Reason")
+    ),
     commands,
   };
 }
@@ -920,7 +938,24 @@ function compileTaskContract(repo, change, task) {
       });
     }
   }
-  if (
+  // A task that declared no verification form at all is reported once, by
+  // requiredFieldProblems, as the one field it is missing. Telling it its
+  // strategy is missing too is the cascade that buries the actionable line.
+  const declaredVerificationForm =
+    fieldValues(task, "Verify").length > 0
+    || fieldValues(task, "Commands").length > 0;
+  if (!taskVerification.strategy) {
+    if (declaredVerificationForm) {
+      resolved.diagnostics.push({
+        code: "missing-verification-strategy",
+        message:
+          "Verification strategy is missing; a task that declares checks "
+          + "declares the strategy that governs them, because none is "
+          + "supplied by default. Supported: "
+          + `${SUPPORTED_VERIFICATION_STRATEGIES.join(", ")}.`,
+      });
+    }
+  } else if (
     !SUPPORTED_VERIFICATION_STRATEGIES.includes(
       taskVerification.strategy.toLowerCase()
     )
@@ -931,6 +966,22 @@ function compileTaskContract(repo, change, task) {
         `Verification strategy is unsupported: ${taskVerification.strategy}; `
         + `supported: ${SUPPORTED_VERIFICATION_STRATEGIES.join(", ")}.`,
     });
+  } else if (
+    taskVerification.strategy.toLowerCase() === "evidence-first"
+    && !isConcrete(taskVerification.reason)
+  ) {
+    // Presence and concreteness, never truth — the contract `Discard reason:`
+    // already has. No mode exempts a task from stating it: an exemption keyed
+    // on a field the same author writes is a second escape hatch.
+    resolved.diagnostics.push({
+      code: "missing-evidence-first-reason",
+      message:
+        "evidence-first states why a meaningful red-green loop does not "
+        + "apply. Add a `Reason:` entry beside `Strategy:` saying what makes "
+        + "this task non-behavioral — docs, configuration, diagnosis, or "
+        + "another reason nothing here can fail first. A red-green strategy "
+        + "needs no reason.",
+    });
   }
   const couplingMode = normalizeText(field(task, "Coupling")).toLowerCase()
     || "none";
@@ -1048,6 +1099,10 @@ function compileTaskContract(repo, change, task) {
     acceptance: [...new Set([...derivedAcceptance, ...explicitAcceptance])],
     verification: {
       strategy: taskVerification.strategy,
+      // Emitted only when the strategy is the one that requires it, so every
+      // other task keeps the capsule shape and fingerprint it had before the
+      // field existed.
+      ...(taskVerification.reason ? { reason: taskVerification.reason } : {}),
       // Emit a tag only when the check opts out of a default, so an untagged
       // check keeps the capsule shape and fingerprint it had before either tag
       // existed. `layer` appears only for `fast`, `regression` only when true.