@christang/keel 5.55.0 → 5.57.0

package/README.md

@@ -313,6 +313,37 @@ keel --uninstall                  # reverts core.hooksPath when Keel set it
 `--with-git-hooks` is opt-in: a plain `keel --install` never touches git config, and the override
 is repo-local and reversible.
 
+## Declaring what a red proves
+
+Red-green discipline makes you write a check that fails before the implementation exists, and
+`keel gate task-complete` refuses a task whose `M<n>.red` Evidence is missing. What it could not
+check was *why* the red failed — a red that fails because a fixture is empty, or because `PATH` was
+never cleared, is shape-perfect.
+
+A check may close by declaring the failure its red must show:
+
+```
+- M1: `npm test -- --scenario widget` asserts the widget renders. Fails with: `widget is undefined`
+```
+
+Completion then requires that literal in the check's `.red` Evidence:
+
+```
+- M1.red: fail, for the right reason. The scenario reported `widget is undefined`.
+```
+
+The clause lives inside the check text, so it is inside the contract fingerprint. That is the point:
+a signature cannot be added or rewritten after the red was observed without the anchor moving, which
+is what separates a prediction from a transcription. Keel does not judge whether the signature is a
+good one — you can declare a string that any failure prints — it holds only that you wrote it first
+and that review can see it.
+
+The clause is optional; a check without one behaves exactly as before. A declaration on a check that
+can have no red — one tagged `(regression)`, or any check under a strategy outside the red-green
+set — fails `task-start` by name rather than sitting in the contract doing nothing. So does a
+`Fails with:` marker that names no literal. To *write about* the marker in a check without declaring
+one, put it in inline code.
+
 ## Domain lenses
 
 Keel's core is pure process; it ships no domain knowledge and no decisions of its own. Alongside

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.55.0 -->
+<!-- keel:start version=5.57.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/bin/keel.js

@@ -94,7 +94,8 @@ Usage:
   keel capabilities [repo] [--target claude|codex|opencode] [--json]
   keel project [repo] --target claude|codex|opencode --event startup|resume|compaction|goal|task-view|worktree|subagent-start|subagent-stop [--authorize goal|task-view|subagent] [--expected-owner owner] [--native-complete] [--change name] [--task id] [--json]
   keel project tasks [repo] --target claude [--change name] [--json]
-  keel gate task-start|task-complete|change-close [repo] [--change name] [--task id] [--action sync|archive] [--base git-ref] [--no-guard] [--record] [--json]
+  keel gate task-start|task-complete [repo] [--change name] [--task id] [--base git-ref] [--no-guard] [--record] [--keep-evidence M1,M3] [--json]
+  keel gate change-close [repo] [--change name] --action sync|archive [--base git-ref] [--json]
   keel guard start|status|clear [repo] [--change name] [--task id] [--force] [--json]
   keel lenses list|add [name] [repo] [--force]
   keel triage [repo] [--labels <l1,l2>] [--issue <n>] [--json]
@@ -1194,6 +1195,8 @@ function keelOpenSpecOverlay(action) {
       "",
       "Keel rules below take precedence over conflicting generic OpenSpec instructions in this file.",
       "",
+      "- Invoke the OpenSpec CLI as `keel openspec …` throughout this file. The commands below are written as a bare `openspec`, which resolves only where OpenSpec is separately installed on PATH; `keel openspec` resolves either way, and `keel --doctor` reports which case this repository is.",
+      "",
       "### Expectation alignment before specs and tasks finalize",
       "",
       "- Before specs and executable tasks are finalized, run `keel-align-expectations`: quick path for complete low-risk requests, deep path when a material choice can change user-visible behavior, an external interface, acceptance, security/privacy/permission boundaries, data migration, protocol/state/timing/reset semantics, generated equivalence, irreversible cost, or a dependency commitment.",
@@ -1229,6 +1232,8 @@ function keelOpenSpecOverlay(action) {
       "",
       "Keel rules below take precedence over conflicting generic OpenSpec instructions in this file.",
       "",
+      "- Invoke the OpenSpec CLI as `keel openspec …` throughout this file. The commands below are written as a bare `openspec`, which resolves only where OpenSpec is separately installed on PATH; `keel openspec` resolves either way, and `keel --doctor` reports which case this repository is.",
+      "",
       ...syncBody,
       OPENSPEC_SURFACE_OVERLAY_END,
       "",
@@ -1269,6 +1274,8 @@ function keelOpenSpecOverlay(action) {
     "",
     "Keel rules below take precedence over conflicting generic OpenSpec instructions in this file.",
     "",
+    "- Invoke the OpenSpec CLI as `keel openspec …` throughout this file. The commands below are written as a bare `openspec`, which resolves only where OpenSpec is separately installed on PATH; `keel openspec` resolves either way, and `keel --doctor` reports which case this repository is.",
+    "",
     "### Target-native subagent gate",
     "",
     "- The current agent remains responsible for Keel ownership, task/archive decisions, scope control, and final reporting.",

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.55.0",
+  "version": "5.57.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.55.0",
+  "version": "5.57.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.55.0"
-PROTOCOL_VERSION = "5.55.0"
+PACKAGE_VERSION = "5.57.0"
+PROTOCOL_VERSION = "5.57.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
@@ -2163,7 +2163,7 @@ def validate_authoring_continuity_scenario() -> int:
             or scaffold_payload.get("status") != "ready"
             or scaffold_payload.get("selection")
             != {"source": "inferred", "change": "draft", "task": None}
-            or scaffold_payload.get("nextAction") != {"kind": "author"}
+            or scaffold_payload.get("nextAction", {}).get("kind") != "author"
         ):
             report(
                 "authoring-continuity scenario did not keep an incomplete proposal actionable."
@@ -3747,8 +3747,14 @@ def validate_stateless_continuity_scenario() -> int:
                 "change": "demo",
                 "task": "1.1",
             },
-            "nextAction": {"kind": "task-start"},
         }
+        expected_kind = "task-start"
+        if payload.get("nextAction", {}).get("kind") != expected_kind:
+            report(
+                "stateless-continuity scenario explicit selection reported "
+                f"next action {payload.get('nextAction')!r}."
+            )
+            return 1
         for key, value in expected.items():
             if payload.get(key) != value:
                 report(
@@ -3808,7 +3814,7 @@ def validate_stateless_continuity_scenario() -> int:
             inferred_payload.get("status") != "ready"
             or inferred_payload.get("selection")
             != {"source": "inferred", "change": "only", "task": "1.1"}
-            or inferred_payload.get("nextAction") != {"kind": "task-start"}
+            or inferred_payload.get("nextAction", {}).get("kind") != "task-start"
         ):
             report("stateless-continuity scenario unique inference mismatch.")
             report(inferred.stdout.strip())
@@ -3830,7 +3836,8 @@ def validate_stateless_continuity_scenario() -> int:
             or recomputed_payload.get("status") != "ready"
             or recomputed_payload.get("selection")
             != {"source": "inferred", "change": "only", "task": None}
-            or recomputed_payload.get("nextAction") != {"kind": "change-close"}
+            or recomputed_payload.get("nextAction", {}).get("kind")
+            != "change-close"
         ):
             report("stateless-continuity scenario did not recompute completed state.")
             report((recomputed.stderr or recomputed.stdout).strip())
@@ -3849,7 +3856,7 @@ def validate_stateless_continuity_scenario() -> int:
         evidence_payload = json.loads(evidence_ready.stdout)
         if (
             evidence_ready.returncode != 0
-            or evidence_payload.get("nextAction") != {"kind": "task-complete"}
+            or evidence_payload.get("nextAction", {}).get("kind") != "task-complete"
         ):
             report("stateless-continuity scenario missed evidence-ready completion.")
             report((evidence_ready.stderr or evidence_ready.stdout).strip())
@@ -3902,7 +3909,7 @@ def validate_stateless_continuity_scenario() -> int:
             or handoff_payload.get("status") != "ready"
             or handoff_payload.get("selection")
             != {"source": "handoff", "change": "beta", "task": "1.1"}
-            or handoff_payload.get("nextAction") != {"kind": "task-start"}
+            or handoff_payload.get("nextAction", {}).get("kind") != "task-start"
         ):
             report("stateless-continuity scenario did not prioritize valid HANDOFF.")
             report((handoff.stderr or handoff.stdout).strip())
@@ -4036,7 +4043,7 @@ def validate_stateless_continuity_scenario() -> int:
         discuss = run_keel(discuss_repo, "context", "--json")
         if (
             discuss.returncode != 0
-            or json.loads(discuss.stdout).get("nextAction") != {"kind": "discuss"}
+            or json.loads(discuss.stdout).get("nextAction", {}).get("kind") != "discuss"
         ):
             report("stateless-continuity scenario missed discuss transition.")
             report((discuss.stderr or discuss.stdout).strip())
@@ -4051,7 +4058,7 @@ def validate_stateless_continuity_scenario() -> int:
         author = run_keel(author_repo, "context", "--json")
         if (
             author.returncode != 0
-            or json.loads(author.stdout).get("nextAction") != {"kind": "author"}
+            or json.loads(author.stdout).get("nextAction", {}).get("kind") != "author"
         ):
             report("stateless-continuity scenario missed author transition.")
             report((author.stderr or author.stdout).strip())
@@ -4069,7 +4076,7 @@ def validate_stateless_continuity_scenario() -> int:
             idle.returncode != 0
             or idle_payload.get("status") != "idle"
             or idle_payload.get("selection") is not None
-            or idle_payload.get("nextAction") != {"kind": "none"}
+            or idle_payload.get("nextAction", {}).get("kind") != "none"
         ):
             report("stateless-continuity scenario no-work state was not idle.")
             report((idle.stderr or idle.stdout).strip())
@@ -4227,7 +4234,7 @@ def validate_stateless_continuity_scenario() -> int:
         if (
             matching.returncode != 0
             or matching_payload.get("status") != "ready"
-            or matching_payload.get("nextAction") != {"kind": "task-start"}
+            or matching_payload.get("nextAction", {}).get("kind") != "task-start"
         ):
             report("stateless-continuity scenario did not resume a matching anchor.")
             report((matching.stderr or matching.stdout).strip())
@@ -4315,7 +4322,7 @@ def validate_stateless_continuity_scenario() -> int:
             or matching_handoff_payload.get("status") != "ready"
             or matching_handoff_payload.get("selection")
             != {"source": "handoff", "change": "demo", "task": "1.1"}
-            or matching_handoff_payload.get("nextAction") != {"kind": "task-start"}
+            or matching_handoff_payload.get("nextAction", {}).get("kind") != "task-start"
         ):
             report("stateless-continuity scenario did not resume a matching HANDOFF anchor.")
             report((matching_handoff.stderr or matching_handoff.stdout).strip())
@@ -25013,6 +25020,306 @@ def problem_codes(payload: dict) -> list[str]:
     return [str(entry.get("code", "")) for entry in (payload.get("problems") or [])]
 
 
+
+# Red-green forces the expensive half — a check that fails before the
+# implementation exists — and enforces that a `.red` line is present. Nothing
+# checked that the red failed *because of the thing under test*. Issue #116
+# measured two reds in one session that were shape-perfect and failed for an
+# unrelated reason: one where the fixture had not cleared PATH so the check
+# passed, one where the fixture contained no wording the checker would refuse.
+# The declaration is what a gate can hold: written into the check, so it is in
+# the fingerprint, and therefore written before the run rather than after it.
+def validate_red_declares_what_it_proves_scenario() -> int:
+    label = "a-red-declares-what-it-proves"
+    signature = "openspec: not found"
+    declared = (
+        f"M1: node test.js asserts the public behavior. Fails with: `{signature}`",
+    )
+    plain = ("M1: node test.js asserts the public behavior",)
+    with tempfile.TemporaryDirectory(prefix="keel-failswith-") as raw:
+        root = Path(raw)
+
+        def start(name: str, **kwargs) -> dict:
+            return strategy_probe_start(
+                root, name, strategy_probe_task(**kwargs)
+            )
+
+        def commands_of(payload: dict) -> list[dict]:
+            contract = payload.get("contract") or {}
+            capsule = contract.get("capsule") or {}
+            return ((capsule.get("verification") or {}).get("commands") or [])
+
+        def fingerprint_of(payload: dict) -> str:
+            return str((payload.get("contract") or {}).get("fingerprint") or "")
+
+        # A declared signature compiles and is carried as its own field, so the
+        # gate can read it without re-parsing the author's prose.
+        with_signature = start(
+            "declared", strategy="vertical-tdd", commands=declared
+        )
+        if with_signature.get("status") != "pass":
+            report(
+                f"{label}: a check declaring a failure signature was refused; "
+                f"got {with_signature.get('status')!r} "
+                f"{problem_text(with_signature)!r}."
+            )
+            return 1
+        compiled = commands_of(with_signature)
+        if len(compiled) != 1 or compiled[0].get("failsWith") != signature:
+            report(
+                f"{label}: the compiled check does not carry the declared "
+                f"failure signature; got {compiled!r}."
+            )
+            return 1
+        # The clause is part of the check the author wrote, so it stays in
+        # `check` as well; the field is what the gate reads, not a replacement
+        # for the text.
+        if "Fails with:" not in str(compiled[0].get("check", "")):
+            report(
+                f"{label}: compiling the signature stripped it out of the "
+                f"check text the author wrote; got {compiled[0]!r}."
+            )
+            return 1
+
+        # In the fingerprint for free, which is what makes the declaration a
+        # prediction rather than a transcription: it cannot be retrofitted to
+        # whatever the run happened to print without the anchor moving.
+        edited = start(
+            "edited",
+            strategy="vertical-tdd",
+            commands=(
+                "M1: node test.js asserts the public behavior. "
+                "Fails with: `a different failure entirely`",
+            ),
+        )
+        without = start("without", strategy="vertical-tdd", commands=plain)
+        prints = {
+            "declared": fingerprint_of(with_signature),
+            "edited": fingerprint_of(edited),
+            "without": fingerprint_of(without),
+        }
+        if not all(prints.values()):
+            report(f"{label}: a probe reported no fingerprint; got {prints!r}.")
+            return 1
+        if prints["declared"] == prints["edited"]:
+            report(
+                f"{label}: editing only the declared failure signature left "
+                f"the fingerprint unmoved at {prints['declared']!r}, so a "
+                "signature could be rewritten after the red was recorded."
+            )
+            return 1
+        if prints["declared"] == prints["without"]:
+            report(
+                f"{label}: declaring a signature left the fingerprint "
+                f"unmoved at {prints['without']!r}."
+            )
+            return 1
+
+        # A declaration that can produce no red is refused rather than left to
+        # sit in the contract doing nothing, which reads to its author as a
+        # check being enforced.
+        for name, kwargs in (
+            (
+                "regression",
+                dict(
+                    strategy="vertical-tdd",
+                    commands=(
+                        "M1: node test.js asserts the public behavior",
+                        "M2 (regression): the suite stays green. "
+                        f"Fails with: `{signature}`",
+                    ),
+                ),
+            ),
+            (
+                "no-red-strategy",
+                dict(
+                    strategy="evidence-first",
+                    reason="the artifact is inspected after it is written.",
+                    commands=declared,
+                ),
+            ),
+        ):
+            payload = start(name, **kwargs)
+            if payload.get("status") != "fail":
+                report(
+                    f"{label}: a failure signature on a check with no red "
+                    f"({name}) was accepted; got {payload.get('status')!r}."
+                )
+                return 1
+            text = problem_text(payload)
+            expected_label = "M2" if name == "regression" else "M1"
+            if expected_label not in text or "red" not in text:
+                report(
+                    f"{label}: the refusal for {name} does not name the check "
+                    f"and say it records no red; got {text!r}."
+                )
+                return 1
+            if "signature-without-red" not in problem_codes(payload):
+                report(
+                    f"{label}: the refusal for {name} carries no "
+                    f"signature-without-red code; got "
+                    f"{problem_codes(payload)!r}."
+                )
+                return 1
+
+        # A marker that names no literal is the shape of a typo. Ignoring it
+        # leaves the author believing a signature is enforced when none parsed.
+        for name, check in (
+            ("bare", "M1: node test.js asserts the behavior. Fails with:"),
+            (
+                "unquoted",
+                "M1: node test.js asserts the behavior. Fails with: not found",
+            ),
+            (
+                "not-closing",
+                "M1: node test.js asserts it. Fails with: `not found` "
+                "and then keeps going.",
+            ),
+        ):
+            payload = start(name, strategy="vertical-tdd", commands=(check,))
+            if payload.get("status") != "fail":
+                report(
+                    f"{label}: a malformed signature marker ({name}) compiled "
+                    f"as if nothing were declared; got "
+                    f"{payload.get('status')!r}."
+                )
+                return 1
+            if "malformed-failure-signature" not in problem_codes(payload):
+                report(
+                    f"{label}: the refusal for {name} carries no "
+                    f"malformed-failure-signature code; got "
+                    f"{problem_codes(payload)!r}."
+                )
+                return 1
+
+        # The escape is the one this repository already established for quoted
+        # material: a check that describes this rule has to be able to name it.
+        quoted = start(
+            "quoted",
+            strategy="vertical-tdd",
+            commands=(
+                "M1: a `Fails with:` marker with no literal is refused by name",
+            ),
+        )
+        if quoted.get("status") != "pass":
+            report(
+                f"{label}: a marker written inside inline code was read as a "
+                f"declaration; got {quoted.get('status')!r} "
+                f"{problem_text(quoted)!r}."
+            )
+            return 1
+        if commands_of(quoted)[0].get("failsWith") is not None:
+            report(
+                f"{label}: a marker inside inline code compiled to a failure "
+                f"signature; got {commands_of(quoted)!r}."
+            )
+            return 1
+
+        # The obligation is stated where the author is deciding — before the
+        # failing check is written — rather than discovered once it has run.
+        warnings = " ".join(str(w) for w in (with_signature.get("warnings") or []))
+        if signature not in warnings or "M1" not in warnings:
+            report(
+                f"{label}: the task-start obligation does not name which "
+                f"checks declared a failure signature; got {warnings!r}."
+            )
+            return 1
+        undeclared = " ".join(str(w) for w in (without.get("warnings") or []))
+        if "declared no failure signature" not in undeclared:
+            report(
+                f"{label}: the obligation does not say that a check owing a "
+                f"red declared no signature; got {undeclared!r}."
+            )
+            return 1
+
+        # Completion is where the declaration becomes a criterion.
+        repo = root / "completion"
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+
+        def complete(check: str, red: str) -> dict:
+            write_gate_fixture(
+                repo,
+                tasks=strategy_probe_task(
+                    strategy="vertical-tdd", commands=(check,)
+                ).replace(
+                    "    - M1: pending\n",
+                    f"    - M1: the check ran.\n"
+                    f"    - M1.red: {red}\n"
+                    "    - M1.green: it passed after the implementation.\n",
+                ),
+            )
+            record_contract_anchor(repo, "demo")
+            result = run_keel(
+                repo,
+                "gate",
+                "task-complete",
+                "--change",
+                "demo",
+                "--task",
+                "1.1",
+                "--json",
+            )
+            try:
+                return json.loads(result.stdout)
+            except json.JSONDecodeError:
+                return {
+                    "status": "unparsed",
+                    "problems": [{"message": result.stdout[:400]}],
+                }
+
+        declared_check = declared[0]
+        mismatched = complete(
+            declared_check, "it failed before the implementation existed."
+        )
+        if mismatched.get("status") != "fail":
+            report(
+                f"{label}: task-complete accepted a red that does not show "
+                f"the declared failure; got {mismatched.get('status')!r}."
+            )
+            return 1
+        text = problem_text(mismatched)
+        if "M1" not in text or signature not in text:
+            report(
+                f"{label}: the refusal names neither the check nor the string "
+                f"it did not find; got {text!r}."
+            )
+            return 1
+        if "red-missing-declared-failure" not in problem_codes(mismatched):
+            report(
+                f"{label}: the refusal carries no "
+                f"red-missing-declared-failure code; got "
+                f"{problem_codes(mismatched)!r}."
+            )
+            return 1
+
+        matched = complete(
+            declared_check,
+            f"it failed with `{signature}` before the implementation existed.",
+        )
+        if matched.get("status") != "pass":
+            report(
+                f"{label}: a red showing the declared failure was refused; "
+                f"got {matched.get('status')!r} {problem_text(matched)!r}."
+            )
+            return 1
+
+        # D3: the undeclared case is unchanged, asserted against the same
+        # fixture with the clause removed and the same weak red that the
+        # declared check was refused for.
+        undeclared_task = complete(
+            plain[0], "it failed before the implementation existed."
+        )
+        if undeclared_task.get("status") != "pass":
+            report(
+                f"{label}: a red-green task declaring no signature stopped "
+                f"completing; got {undeclared_task.get('status')!r} "
+                f"{problem_text(undeclared_task)!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
 # 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.
@@ -26119,6 +26426,190 @@ def validate_evidence_survives_what_did_not_change_scenario() -> int:
     return 0
 
 
+# `keel context` exists to answer "what now" and answered with a noun. Issue
+# #112: `Next action: change-close` followed by `keel gate change-close
+# --change x` failing on the argument that stage requires — a wrong attempt
+# Keel had everything in the same result to prevent.
+def validate_next_action_is_a_command_scenario() -> int:
+    label = "the-next-action-is-a-command"
+
+    def repo_with(root: Path, name: str, *, checked: bool, evidence: bool):
+        repo = root / name
+        task = strategy_probe_task(
+            strategy="evidence-first",
+            reason="fixture; nothing here can fail first",
+        )
+        if checked:
+            task = task.replace("- [ ] 1.1", "- [x] 1.1")
+        if evidence:
+            task = task.replace("    - M1: pending", "    - M1: pass. ran it.")
+        write_gate_fixture(repo, tasks=task)
+        started = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--json", "--no-guard",
+        )
+        value = json.loads(started.stdout)["contract"]["fingerprint"]["value"]
+        tasks_path = repo / "openspec/changes/demo/tasks.md"
+        tasks_path.write_text(
+            tasks_path.read_text(encoding="utf-8").replace(
+                "    - Contract: pending",
+                f"    - Contract: keel-task-capsule/v1 sha256:{value}",
+            ),
+            encoding="utf-8",
+        )
+        return repo
+
+    def context(repo: Path):
+        text = run_keel(repo, "context", "--change", "demo").stdout
+        payload = json.loads(
+            run_keel(repo, "context", "--change", "demo", "--json").stdout
+        )
+        return text, payload
+
+    with tempfile.TemporaryDirectory(prefix="keel-next-command-") as raw:
+        root = Path(raw)
+
+        pending = repo_with(root, "pending", checked=False, evidence=False)
+        text, payload = context(pending)
+        command = (payload.get("nextAction") or {}).get("command")
+        if not command:
+            report(
+                f"{label}: the next action carries no command; "
+                f"{payload.get('nextAction')!r}."
+            )
+            return 1
+        for needed in ("task-start", "--change demo", "--task 1.1"):
+            if needed not in command:
+                report(
+                    f"{label}: the reported command omits {needed!r}; "
+                    f"{command!r}."
+                )
+                return 1
+        if command not in text:
+            report(
+                f"{label}: the text surface does not carry the same command as "
+                f"--json; {command!r} not in {text!r}."
+            )
+            return 1
+
+        done = repo_with(root, "done", checked=False, evidence=True)
+        _, payload = context(done)
+        if "task-complete" not in str((payload.get("nextAction") or {}).get("command")):
+            report(
+                f"{label}: a task with completion evidence did not report the "
+                f"task-complete invocation; {payload.get('nextAction')!r}."
+            )
+            return 1
+
+        closing = repo_with(root, "closing", checked=True, evidence=True)
+        _, payload = context(closing)
+        close_command = str((payload.get("nextAction") or {}).get("command") or "")
+        if "change-close" not in close_command:
+            report(
+                f"{label}: a change whose tasks are complete did not report the "
+                f"change-close invocation; {payload.get('nextAction')!r}."
+            )
+            return 1
+        if "--action" not in close_command:
+            report(
+                f"{label}: the change-close command omits the argument that "
+                f"stage requires; {close_command!r}."
+            )
+            return 1
+        # Running exactly what was printed must not hit the input error the
+        # report describes.
+        printed = close_command.split()
+        if printed and printed[0] == "keel":
+            printed = printed[1:]
+        ran = run_keel(closing, *printed)
+        if "requires --action" in (ran.stdout + ran.stderr):
+            report(
+                f"{label}: the reported command still fails on the argument it "
+                f"was supposed to supply; {(ran.stdout + ran.stderr)[:200]!r}."
+            )
+            return 1
+
+        idle = root / "idle"
+        write_text(idle / "README.md", "# fixture\n")
+        payload = json.loads(run_keel(idle, "context", "--json").stdout)
+        if (payload.get("nextAction") or {}).get("command"):
+            report(
+                f"{label}: an action with nothing to run reported a command; "
+                f"{payload.get('nextAction')!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+# `keel --init` writes OpenSpec's command and skill surfaces, whose text says
+# `openspec new change "<name>"`. With only the Keel package installed globally
+# a bare `openspec` is not on PATH, which `keel --doctor` reports and names the
+# working invocation for. Those files belong to OpenSpec and Keel appends a
+# block rather than editing their body — so the block is where Keel says it.
+def validate_overlay_names_the_invocation_scenario() -> int:
+    label = "the-overlay-names-the-invocation"
+    start = "<!-- keel:openspec-surface-overlay"
+    end = "<!-- keel:openspec-surface-overlay:end -->"
+    with tempfile.TemporaryDirectory(prefix="keel-overlay-invocation-") as raw:
+        repo = Path(raw)
+        # The surfaces OpenSpec writes, as OpenSpec writes them: the overlay is
+        # merged into files that already exist, and their body is the text this
+        # scenario asserts Keel does not touch.
+        upstream = 'Run `openspec new change "<name>"` to begin.\n'
+        for action in ("propose", "apply", "sync", "archive"):
+            write_text(repo / f".claude/commands/opsx/{action}.md", upstream)
+        for skill in (
+            "openspec-propose",
+            "openspec-apply-change",
+            "openspec-sync-specs",
+            "openspec-archive-change",
+        ):
+            write_text(repo / f".claude/skills/{skill}/SKILL.md", upstream)
+        installed = run_keel(repo, "--install", "--target", "claude")
+        if installed.returncode != 0:
+            report(
+                f"{label}: the fixture install failed; "
+                f"{(installed.stderr or installed.stdout).strip()[:300]}"
+            )
+            return 1
+
+        carrying = [
+            path
+            for path in sorted(repo.rglob("*.md"))
+            if start in path.read_text(encoding="utf-8", errors="replace")
+        ]
+        if not carrying:
+            report(f"{label}: the install wrote no file carrying an overlay.")
+            return 1
+        for path in carrying:
+            content = path.read_text(encoding="utf-8")
+            block = content[content.index(start):content.index(end) + len(end)]
+            for needed in ("keel openspec", "keel --doctor"):
+                if needed not in block:
+                    report(
+                        f"{label}: the overlay in {path.name} does not name "
+                        f"{needed!r}."
+                    )
+                    return 1
+            # The boundary: everything outside the block is OpenSpec's.
+            outside = (
+                content[: content.index(start)]
+                + content[content.index(end) + len(end):]
+            )
+            if start in outside or "keel openspec" in outside:
+                report(
+                    f"{label}: {path.name} carries Keel invocation text outside "
+                    "the overlay block, so the OpenSpec-authored body was "
+                    "edited."
+                )
+                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
@@ -26351,6 +26842,7 @@ SCENARIOS: tuple = (
     ("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),
+    ("a-red-declares-what-it-proves", validate_red_declares_what_it_proves_scenario),
     ("the-weakest-strategy-states-its-reason", validate_weakest_strategy_states_its_reason_scenario),
     ("a-quoted-marker-is-not-a-disposition", validate_quoted_marker_is_not_a_disposition_scenario),
     ("drift-names-where-to-look", validate_drift_names_where_to_look_scenario),
@@ -26359,6 +26851,8 @@ SCENARIOS: tuple = (
     ("an-explanation-is-printed-once", validate_explanation_is_printed_once_scenario),
     ("a-paused-change-is-not-the-next-action", validate_paused_change_is_not_the_next_action_scenario),
     ("evidence-survives-what-did-not-change", validate_evidence_survives_what_did_not_change_scenario),
+    ("the-next-action-is-a-command", validate_next_action_is_a_command_scenario),
+    ("the-overlay-names-the-invocation", validate_overlay_names_the_invocation_scenario),
     (
         "authored-scenario-names-are-registered",
         validate_authored_scenario_names_scenario,

package/src/core/context.js

@@ -29,12 +29,34 @@ function taskRecords(tasksPath) {
   }));
 }
 
+// The invocation the action's name stands for. Everything it needs is in the
+// same result, and the failure it prevents is the one issue #112 reports: an
+// action name followed by an attempt that fails on an argument Keel knew was
+// required. Change and task are named explicitly rather than left to
+// inference, because a reader may run the printed line later or elsewhere,
+// where inference would answer about a different repository state.
+function nextActionCommand(kind, selection) {
+  if (!selection || !selection.change) return null;
+  const scope = `--change ${selection.change}`;
+  if (kind === "task-start" || kind === "task-complete") {
+    if (!selection.task) return null;
+    return `keel gate ${kind} ${scope} --task ${selection.task}`;
+  }
+  if (kind === "change-close") {
+    // `--action` is not optional for this stage, so a command printed without
+    // it is a command that fails.
+    return `keel gate change-close ${scope} --action archive`;
+  }
+  return null;
+}
+
 function result(status, selection, nextAction, read, reasons = [], contract = null) {
+  const command = nextActionCommand(nextAction, selection);
   const context = {
     schemaVersion: 1,
     status,
     selection,
-    nextAction: { kind: nextAction },
+    nextAction: command ? { kind: nextAction, command } : { kind: nextAction },
     read,
     reasons,
     warnings: [],
@@ -679,6 +701,9 @@ function renderContext(result) {
     `Keel context: ${result.status}`,
     `Next action: ${result.nextAction.kind}`,
   ];
+  if (result.nextAction.command) {
+    lines.push(`Run: ${result.nextAction.command}`);
+  }
   if (result.selection) {
     lines.push(
       `Selection: ${result.selection.change}`

package/src/core/gates.js

@@ -232,9 +232,24 @@ function redGreenObligation(compiled) {
   const strategy = compiled.capsule.verification.strategy.toLowerCase();
   if (!RED_GREEN_VERIFICATION_STRATEGIES.has(strategy)) return [];
   const commands = compiled.capsule.verification.commands;
-  const owing = commands.filter((item) => !item.regression).map((item) => item.label);
+  const owingChecks = commands.filter((item) => !item.regression);
+  const owing = owingChecks.map((item) => item.label);
   const exempt = commands.filter((item) => item.regression).map((item) => item.label);
   if (owing.length === 0) return [];
+  // What a red proves is only checkable if it was written down before the red
+  // was run, so the moment to say so is here — the author is about to write the
+  // failing check — and not at completion, where any signature is a
+  // transcription of whatever already failed (issue #116).
+  const signed = owingChecks.filter((item) => item.failsWith);
+  const unsigned = owingChecks.filter((item) => !item.failsWith).map((item) => item.label);
+  const signatures = signed.length > 0
+    ? ` ${signed.map((item) => `${item.label} must fail with \`${item.failsWith}\``).join("; ")}.`
+      + (unsigned.length > 0
+        ? ` ${unsigned.join(", ")} declared no failure signature.`
+        : "")
+    : ` ${owing.join(", ")} declared no failure signature — close the check with `
+      + "`Fails with:` and the literal its red should print, and the red that "
+      + "gets recorded has to be the one you predicted.";
   return [
     `${strategy} will require concrete .red and .green Evidence at completion `
       + `for ${owing.join(", ")}`
@@ -244,7 +259,8 @@ function redGreenObligation(compiled) {
         : "")
       + ". Tag a check `(regression)` now if it asserts that something already "
       + "green stays green, rather than discovering the obligation once the "
-      + "checks have been run.",
+      + "checks have been run."
+      + signatures,
   ];
 }
 
@@ -1011,8 +1027,34 @@ function completionChecks(repo, task, contract = null, changeVerify = null, chan
         .filter((entry) => entry.regression)
         .map((entry) => entry.label)
     );
+    // A check may declare the failure its red must show. Enforced against the
+    // recorded `.red`, which is where the shape check stopped: a red that
+    // failed for an unrelated reason satisfied the presence check exactly as
+    // well as one that failed for the right reason (issue #116). Keel does not
+    // judge whether the declared string is a good one — what it holds is that
+    // the string is in the contract, so it was written before the run.
+    const declaredFailure = new Map(
+      (contract ? contract.capsule.verification.commands : [])
+        .filter((entry) => entry.failsWith)
+        .map((entry) => [entry.label, entry.failsWith])
+    );
     for (const label of commands) {
       if (exempt.has(label)) continue;
+      const expected = declaredFailure.get(label);
+      const recorded = evidenceValue(task, `${label}.red`);
+      if (expected && isConcrete(recorded) && !String(recorded).includes(expected)) {
+        problems.push(
+          problem(
+            "red-missing-declared-failure",
+            `${label} declares that its red fails with \`${expected}\`, and `
+              + `the recorded ${label}.red Evidence does not contain that `
+              + "string. Record the failure output the red actually printed, "
+              + "or correct the declaration — which moves the contract "
+              + "fingerprint, because a signature edited after the red was "
+              + "observed is a transcription of it.",
+          )
+        );
+      }
       for (const phase of ["red", "green"]) {
         if (!isConcrete(evidenceValue(task, `${label}.${phase}`))) {
           problems.push(

package/src/core/task-contract.js

@@ -153,6 +153,31 @@ const RED_GREEN_VERIFICATION_STRATEGIES = new Set([
 // Tags an M<n> check may carry after its label, as a comma-separated set.
 const COMMAND_TAGS = new Set(["fast", "full", "regression"]);
 
+// A check may end by declaring the failure its red is expected to show, so that
+// what the red proves is written down before the red is run. The clause closes
+// the check: `Fails with:` followed by one inline-code literal and nothing more.
+// End-anchored on purpose — a check that describes this rule mentions the marker
+// mid-sentence, and a mention is not a declaration.
+const FAILURE_SIGNATURE = /\bFails with:[ \t]*`([^`\n]+)`[ \t]*$/i;
+const FAILURE_MARKER = /\bFails with:/i;
+
+// Classify a check's `Fails with:` marker. `signature` is the declared literal;
+// `malformed` marks a marker that is present and is not a closing clause — a
+// typo shape, and ignoring it would leave the author believing a signature is
+// enforced when none was parsed. A marker written inside inline code is quoted
+// material rather than a declaration, the meaning inline code already carries
+// here, which is what lets this file's own tasks name the marker.
+function failureSignature(check) {
+  const text = String(check || "");
+  const match = text.match(FAILURE_SIGNATURE);
+  if (match) return { signature: match[1].trim(), malformed: false };
+  const remainder = withoutInlineCode(text);
+  return {
+    signature: null,
+    malformed: FAILURE_MARKER.test(remainder),
+  };
+}
+
 // Single source of truth for the accepted completion Review `Status`
 // vocabulary. Consumed by both the completion gate (src/core/gates.js) and the
 // context "already reviewed" probe (src/core/context.js) so the two never
@@ -193,19 +218,39 @@ function verification(task) {
     // therefore exempt from the red-green evidence requirement. A check may
     // carry both, so the tag is a comma-separated set rather than one word.
     const match = entry.match(/^(M[1-9]\d*)(?:\s*\(([^)\n]*)\))?:\s*(.*)$/);
-    if (!match) return { label: null, layer: "full", regression: false, check: entry };
+    if (!match) {
+      return {
+        label: null,
+        layer: "full",
+        regression: false,
+        check: entry,
+        failsWith: null,
+        malformedSignature: false,
+      };
+    }
     const tags = (match[2] || "")
       .split(",")
       .map((tag) => tag.trim().toLowerCase())
       .filter(Boolean);
     if (tags.some((tag) => !COMMAND_TAGS.has(tag))) {
-      return { label: null, layer: "full", regression: false, check: entry };
+      return {
+        label: null,
+        layer: "full",
+        regression: false,
+        check: entry,
+        failsWith: null,
+        malformedSignature: false,
+      };
     }
+    const check = normalizeText(match[3]);
+    const failure = failureSignature(check);
     return {
       label: match[1],
       layer: tags.includes("fast") ? "fast" : "full",
       regression: tags.includes("regression"),
-      check: normalizeText(match[3]),
+      check,
+      failsWith: failure.signature,
+      malformedSignature: failure.malformed,
     };
   });
   return {
@@ -367,7 +412,60 @@ function taskStartContractProblems(task) {
       ...regressionOnlyProblems(task),
     ];
   }
-  return [...commandLabelProblems(task), ...regressionOnlyProblems(task)];
+  return [
+    ...commandLabelProblems(task),
+    ...regressionOnlyProblems(task),
+    ...failureSignatureProblems(task),
+  ];
+}
+
+// A declared failure signature describes the check's red. A `(regression)` check
+// is exempt from red-green and a strategy outside the red-green set records no
+// `.red` at all, so in both cases the declaration describes evidence that will
+// never exist. Refused rather than left sitting in the contract: a declaration
+// doing nothing reads to its author as a check being enforced.
+function failureSignatureProblems(task) {
+  const parsed = verification(task);
+  const strategy = parsed.strategy.toLowerCase();
+  const redGreen = RED_GREEN_VERIFICATION_STRATEGIES.has(strategy);
+  const problems = [];
+  for (const entry of parsed.commands) {
+    if (!entry.label) continue;
+    if (entry.malformedSignature) {
+      problems.push({
+        code: "malformed-failure-signature",
+        message:
+          `${entry.label} carries a \`Fails with:\` marker that does not close `
+          + "the check with a literal. Write the failure signature as one "
+          + "inline-code literal at the end of the check, or fence the marker "
+          + "in inline code when the check is describing it rather than "
+          + "declaring one.",
+      });
+      continue;
+    }
+    if (!entry.failsWith) continue;
+    if (!redGreen) {
+      problems.push({
+        code: "signature-without-red",
+        message:
+          `${entry.label} declares the failure its red must show, but `
+          + `\`${parsed.strategy}\` records no red for the signature to `
+          + "describe. Name a red-green strategy, or drop the clause.",
+      });
+      continue;
+    }
+    if (entry.regression) {
+      problems.push({
+        code: "signature-without-red",
+        message:
+          `${entry.label} declares the failure its red must show, but it is `
+          + "tagged `(regression)` and so records no red for the signature to "
+          + "describe. Untag the check if it proves new behavior, or drop the "
+          + "clause.",
+      });
+    }
+  }
+  return problems;
 }
 
 // A red-green strategy whose every check is exempt from red-green is that
@@ -1127,6 +1225,10 @@ function compileTaskContract(repo, change, task) {
           const emitted = { label: entry.label, check: entry.check };
           if (entry.layer && entry.layer !== "full") emitted.layer = entry.layer;
           if (entry.regression) emitted.regression = true;
+          // The clause stays in `check` — it is text the author wrote — and the
+          // field is what the gate reads. Emitted only when declared, so every
+          // check without one keeps the capsule shape and fingerprint it had.
+          if (entry.failsWith) emitted.failsWith = entry.failsWith;
           return emitted;
         }),
     },