@christang/keel 5.54.0 → 5.56.0

package/README.md

@@ -333,6 +333,23 @@ keel lenses add web         # copy the web template into keel/lenses/web.md, the
 keel lenses add web --force # overwrite an existing lens
 ```
 
+## Re-recording a contract
+
+Changing a task's contract after work has started moves its fingerprint, and Keel reports that the
+evidence produced under the old one is stale. Sometimes that is too broad — a classification tag
+added to a check leaves its assertion untouched, and re-running a three-minute experiment for it
+buys nothing. Say so:
+
+```bash
+keel gate task-start --change <c> --task <t> --record --keep-evidence M1,M3
+```
+
+The report then names only the checks still stale, names the ones you declared unaffected, and says
+the narrowing came from your declaration. **Keel does not verify the claim** — it keeps only the
+previous fingerprint, not the capsule behind it, so it cannot compare a check's former text to its
+current one. State your reason in the task's `Reauthorizations` line, where a reviewer can disagree
+with it. Nothing about completion changes: every check still needs its Evidence.
+
 ## Pausing a change
 
 A change you have deliberately stopped — waiting on something outside the repository, or simply

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.54.0 -->
+<!-- keel:start version=5.56.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]
@@ -186,6 +187,7 @@ function parseArgs(argv) {
     base: null,
     noGuard: false,
     record: false,
+    keepEvidence: null,
     guardSubcommand: null,
     lensesSubcommand: null,
     lensName: null,
@@ -296,6 +298,20 @@ function parseArgs(argv) {
       parsed.record = true;
       continue;
     }
+    if (arg === "--keep-evidence") {
+      index += 1;
+      if (index >= argv.length) {
+        fail("--keep-evidence requires a comma-separated list of M<n> labels");
+      }
+      if (parsed.keepEvidence !== null) {
+        fail("--keep-evidence was provided more than once");
+      }
+      parsed.keepEvidence = argv[index]
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+      continue;
+    }
     if (arg === "--change" || arg === "--task") {
       index += 1;
       if (index >= argv.length) {
@@ -1179,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.",
@@ -1214,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,
       "",
@@ -1254,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.54.0",
+  "version": "5.56.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.54.0",
+  "version": "5.56.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.54.0",
+  "version": "5.56.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.54.0"
-PROTOCOL_VERSION = "5.54.0"
+PACKAGE_VERSION = "5.56.0"
+PROTOCOL_VERSION = "5.56.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())
@@ -25968,6 +25975,341 @@ def validate_paused_change_is_not_the_next_action_scenario() -> int:
     return 0
 
 
+# Issue #112 recorded four re-verifications in one session from contract
+# changes that could not affect evidence — renaming `M2:` to `M2 (regression):`
+# among them, with the assertion unchanged by a character. One of the four meant
+# breaking a testbench, re-running, and restoring it. The gate genuinely cannot
+# judge which evidence survives; what it could do is stop saying "all of it".
+def validate_evidence_survives_what_did_not_change_scenario() -> int:
+    label = "evidence-survives-what-did-not-change"
+
+    def fixture(root: Path, name: str, strategy: str = "evidence-first") -> Path:
+        repo = root / name
+        task = strategy_probe_task(
+            strategy=strategy,
+            reason="fixture; nothing here can fail first",
+            commands=(
+                "M1: the first check asserts the public behavior",
+                "M2: the second check asserts the public behavior",
+                "M3: the third check asserts the public behavior",
+            ),
+        )
+        # A recorded anchor that is not the compiled one, so --record re-records.
+        task = task.replace(
+            "    - Contract: pending",
+            "    - Contract: keel-task-capsule/v1 sha256:" + "0" * 64,
+        )
+        write_gate_fixture(repo, tasks=task)
+        return repo
+
+    def start(repo: Path, *args):
+        result = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--json", "--no-guard", *args,
+        )
+        try:
+            return json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return {"status": "unparsed", "problems": [{"message": result.stdout[:300]}]}
+
+    def said(payload: dict) -> str:
+        return " ".join(str(x) for x in (payload.get("warnings") or []))
+
+    with tempfile.TemporaryDirectory(prefix="keel-keep-evidence-") as raw:
+        root = Path(raw)
+
+        # Control: without a declaration the report covers every check.
+        blanket = start(fixture(root, "blanket"), "--record")
+        if blanket.get("status") != "pass":
+            report(
+                f"{label}: the re-record fixture did not pass; "
+                f"{problem_text(blanket)!r}."
+            )
+            return 1
+        if "stale" not in said(blanket):
+            report(
+                f"{label}: the fixture did not produce a stale-evidence "
+                f"report to narrow; {said(blanket)!r}."
+            )
+            return 1
+
+        narrowed = start(
+            fixture(root, "narrowed"), "--record", "--keep-evidence", "M1,M3"
+        )
+        if narrowed.get("status") != "pass":
+            report(
+                f"{label}: a declaration refused a valid re-record; "
+                f"{problem_text(narrowed)!r}."
+            )
+            return 1
+        spoken = said(narrowed)
+        stale_line = next(
+            (w for w in narrowed["warnings"] if "stale" in str(w)), ""
+        )
+        if "M2" not in stale_line:
+            report(
+                f"{label}: the narrowed report does not name the check that is "
+                f"still stale; {stale_line!r}."
+            )
+            return 1
+        for kept in ("M1", "M3"):
+            if kept not in stale_line:
+                report(
+                    f"{label}: the narrowed report does not name {kept} as "
+                    f"declared unaffected; {stale_line!r}."
+                )
+                return 1
+        if "declar" not in stale_line.lower():
+            report(
+                f"{label}: the narrowed report does not attribute the "
+                f"narrowing to the declaration; {stale_line!r}."
+            )
+            return 1
+
+        unknown = start(
+            fixture(root, "unknown"), "--record", "--keep-evidence", "M9"
+        )
+        if unknown.get("status") != "fail":
+            report(
+                f"{label}: a declaration naming a check the contract does not "
+                "declare was accepted; task-start returned "
+                f"{unknown.get('status')!r}."
+            )
+            return 1
+        if "M9" not in problem_text(unknown):
+            report(
+                f"{label}: the refusal does not name the label it could not "
+                f"resolve; {problem_text(unknown)!r}."
+            )
+            return 1
+
+        stray = start(fixture(root, "stray"), "--keep-evidence", "M1")
+        if stray.get("status") != "fail":
+            report(
+                f"{label}: --keep-evidence without --record was accepted, so "
+                "an author could believe they declared something nothing read."
+            )
+            return 1
+
+        # Completion is unchanged: the declaration is about the past.
+        completing = fixture(root, "completing", strategy="vertical-tdd")
+        start(completing, "--record", "--keep-evidence", "M1,M2,M3")
+        tasks_path = completing / "openspec/changes/demo/tasks.md"
+        tasks_path.write_text(
+            tasks_path.read_text(encoding="utf-8")
+            .replace("- [ ] 1.1", "- [x] 1.1")
+            .replace("    - M1: pending", "    - M1: pass. ran it.")
+            .replace("    - M2: pending", "    - M2: pass. ran it.")
+            .replace("    - M3: pending", "    - M3: pass. ran it."),
+            encoding="utf-8",
+        )
+        done = json.loads(
+            run_keel(
+                completing, "gate", "task-complete", "--change", "demo",
+                "--task", "1.1", "--json",
+            ).stdout
+        )
+        if done.get("status") != "fail":
+            report(
+                f"{label}: a declaration let a red-green task complete without "
+                "its .red/.green Evidence."
+            )
+            return 1
+        if "missing-strategy-evidence" not in problem_codes(done):
+            report(
+                f"{label}: completion stopped requiring red-green Evidence; "
+                f"{problem_codes(done)!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    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
@@ -26207,6 +26549,9 @@ SCENARIOS: tuple = (
     ("the-obligation-is-stated-early", validate_obligation_is_stated_early_scenario),
     ("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

@@ -288,6 +288,37 @@ function taskStart(repo, options) {
   // authors to — needs no manual edit. Refusal is kept only for a task with no
   // anchor at all, which is a malformed capsule rather than a reauthorization,
   // and it writes nothing, guard manifest included.
+  const declaredKeep = Array.isArray(options.keepEvidence)
+    ? options.keepEvidence
+    : [];
+  if (declaredKeep.length > 0 && !options.record) {
+    problems.push(
+      problem(
+        "keep-evidence-without-record",
+        "--keep-evidence declares which evidence a re-record leaves standing, "
+          + "and there is no re-record here. Pass --record, or drop the "
+          + "declaration so nothing reads it."
+      )
+    );
+  }
+  if (declaredKeep.length > 0 && compiled.diagnostics.length === 0) {
+    const labels = compiled.capsule.verification.commands.map(
+      (item) => item.label
+    );
+    const unknown = declaredKeep.filter((label) => !labels.includes(label));
+    if (unknown.length > 0) {
+      // Refused rather than ignored: the likeliest cause is a typo or a check
+      // that was renamed, and ignoring it would leave the author believing
+      // evidence was kept that was not.
+      problems.push(
+        problem(
+          "keep-evidence-unknown-check",
+          `--keep-evidence names ${unknown.join(", ")}, which this contract `
+            + `does not declare as a check. It declares ${labels.join(", ")}.`
+        )
+      );
+    }
+  }
   let anchorPlan = null;
   if (options.record && problems.length === 0) {
     anchorPlan = contractAnchorPlan(selection, task);
@@ -364,11 +395,30 @@ function taskStart(repo, options) {
     // call to the current agent's Review.
     const replaced = anchoredFingerprint(anchorPlan.previous);
     if (replaced && replaced !== compiled.fingerprint.value) {
+      // The gate still cannot judge which evidence survives, and this does not
+      // make it able to. What it can stop doing is saying "all of it" to an
+      // author who can see that one check's assertion did not change — because
+      // an author acting on that sentence in good faith re-runs everything,
+      // and issue #112 measured four such re-verifications in one session, one
+      // of which meant breaking a testbench and restoring it.
+      const kept = declaredKeep;
+      const labels = compiled.capsule.verification.commands.map(
+        (item) => item.label
+      );
+      const stale = labels.filter((label) => !kept.includes(label));
       result.warnings.push(
         `Re-recorded over a different contract: was sha256:${replaced}, now `
-          + `sha256:${compiled.fingerprint.value}. Execution evidence produced `
-          + "under the previous contract is stale; clear or re-verify it "
-          + "before completing this task."
+          + `sha256:${compiled.fingerprint.value}. `
+          + (kept.length > 0
+            ? `Evidence for ${stale.length > 0 ? stale.join(", ") : "no check"}`
+              + " is stale; clear or re-verify it before completing this task. "
+              + `${kept.join(", ")} ${kept.length > 1 ? "were" : "was"} `
+              + "declared unaffected by this contract change — a declaration "
+              + "Keel records and does not verify, since it retains only the "
+              + "previous fingerprint and cannot compare a check's former text "
+              + "to its current one. State the reason in Reauthorizations."
+            : "Execution evidence produced under the previous contract is "
+              + "stale; clear or re-verify it before completing this task.")
       );
     }
   }