@christang/keel 5.53.0 → 5.55.0

package/README.md

@@ -333,6 +333,46 @@ 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
+not the priority — can say so where it lives, in its own `openspec/changes/<name>/.openspec.yaml`:
+
+```yaml
+schema: keel-spec-driven
+created: 2026-09-05
+keel:
+  status: paused
+  reason: waiting on the competition brief; the priority is knowledge that needs no tooling
+  since: 2026-09-05
+```
+
+`keel context` then passes over it when inferring what to do next, and says which change it passed
+over and why — a skip you cannot see would be worse than the wrong recommendation it replaces. If
+every active change is paused, `context` reports that, with each reason, rather than reporting that
+nothing exists.
+
+This changes only what Keel *recommends*. No gate, the write guard, and completion all behave
+exactly as they would without it, and `keel context --change <paused>` still selects it — you asked
+for it by name. Keel never pauses a change on its own.
+
 ## Commands
 
 ```bash

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.53.0 -->
+<!-- keel:start version=5.55.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

@@ -186,6 +186,7 @@ function parseArgs(argv) {
     base: null,
     noGuard: false,
     record: false,
+    keepEvidence: null,
     guardSubcommand: null,
     lensesSubcommand: null,
     lensName: null,
@@ -296,6 +297,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) {

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.53.0",
+  "version": "5.55.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.53.0",
+  "version": "5.55.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.53.0"
-PROTOCOL_VERSION = "5.53.0"
+PACKAGE_VERSION = "5.55.0"
+PROTOCOL_VERSION = "5.55.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
@@ -25812,6 +25812,313 @@ def validate_explanation_is_printed_once_scenario() -> int:
     return 0
 
 
+# Issue #112's most valuable finding: a change its owner had stopped kept being
+# recommended, and the workaround was a paragraph in the project's CLAUDE.md
+# telling future sessions to ignore keel's own primary output.
+def validate_paused_change_is_not_the_next_action_scenario() -> int:
+    label = "a-paused-change-is-not-the-next-action"
+
+    def write_change(repo: Path, name: str, keel_block: str | None) -> None:
+        task = strategy_probe_task(strategy="vertical-tdd")
+        change = repo / "openspec" / "changes" / name
+        write_text(
+            change / "tasks.md",
+            "# Tasks\n\n## Invalidates\n\n- None.\n\n## Expectation Coverage\n\n"
+            "- E1:\n  - Covered by: 1.1\n\n## Tasks\n\n" + task,
+        )
+        write_text(change / "proposal.md", "# Proposal\n")
+        write_text(change / "design.md", "## Context\n\nfixture\n")
+        write_text(change / "specs/demo/spec.md", "## ADDED Requirements\n")
+        write_text(
+            change / ".openspec.yaml",
+            "schema: keel-spec-driven\ncreated: 2026-09-08\n"
+            + (keel_block or ""),
+        )
+
+    paused_block = (
+        "keel:\n"
+        "  status: paused\n"
+        "  reason: 打分寻优要等赛题，当前优先级是不依赖工具的知识沉淀\n"
+        "  since: 2026-09-05\n"
+    )
+
+    def context(repo: Path, *args):
+        result = run_keel(repo, "context", "--json", *args)
+        try:
+            return json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return {"status": "unparsed", "reasons": [result.stdout[:300]]}
+
+    def said(payload: dict) -> str:
+        return " ".join(
+            str(x) for x in
+            (payload.get("reasons") or []) + (payload.get("warnings") or [])
+        )
+
+    with tempfile.TemporaryDirectory(prefix="keel-paused-") as raw:
+        root = Path(raw)
+
+        # Without the declaration the pair is ambiguous, so the skip is what
+        # changes the answer rather than the fixture shape.
+        both = root / "both"
+        write_change(both, "alpha", None)
+        write_change(both, "beta", None)
+        if context(both).get("status") != "ambiguous":
+            report(
+                f"{label}: two unpaused changes were not ambiguous, so the "
+                "fixture does not isolate what pausing changes."
+            )
+            return 1
+
+        mixed = root / "mixed"
+        write_change(mixed, "alpha", paused_block)
+        write_change(mixed, "beta", None)
+        picked = context(mixed)
+        if picked.get("status") != "ready":
+            report(
+                f"{label}: inference did not pass over the paused change; "
+                f"{picked.get('status')!r} {said(picked)!r}."
+            )
+            return 1
+        if (picked.get("selection") or {}).get("change") != "beta":
+            report(
+                f"{label}: inference selected {picked.get('selection')!r} "
+                "rather than the change that is not paused."
+            )
+            return 1
+        spoken = said(picked)
+        if "alpha" not in spoken or "打分寻优" not in spoken:
+            report(
+                f"{label}: the paused change was skipped silently or without "
+                f"its reason; {spoken!r}."
+            )
+            return 1
+
+        allpaused = root / "allpaused"
+        write_change(allpaused, "alpha", paused_block)
+        write_change(allpaused, "beta", paused_block)
+        idle = context(allpaused)
+        if idle.get("status") != "idle":
+            report(
+                f"{label}: a repository whose every change is paused reported "
+                f"{idle.get('status')!r}."
+            )
+            return 1
+        spoken = said(idle)
+        for needed in ("alpha", "beta", "打分寻优"):
+            if needed not in spoken:
+                report(
+                    f"{label}: the all-paused report omits {needed!r}; "
+                    f"{spoken!r}."
+                )
+                return 1
+
+        explicit = context(mixed, "--change", "alpha")
+        if (explicit.get("selection") or {}).get("change") != "alpha":
+            report(
+                f"{label}: explicit selection no longer reaches a paused "
+                f"change; {explicit.get('status')!r} {said(explicit)!r}."
+            )
+            return 1
+        if "paused" not in said(explicit).lower():
+            report(
+                f"{label}: explicit selection did not report that the change "
+                f"is paused; {said(explicit)!r}."
+            )
+            return 1
+
+        # D6: a declaration Keel cannot read pauses nothing.
+        broken = root / "broken"
+        write_change(broken, "alpha", "keel:\n  status: perhaps-later\n")
+        write_change(broken, "beta", None)
+        unreadable = context(broken)
+        if unreadable.get("status") != "ambiguous":
+            report(
+                f"{label}: an unreadable declaration removed a change from "
+                f"inference; {unreadable.get('status')!r} {said(unreadable)!r}."
+            )
+            return 1
+        if "perhaps-later" not in said(unreadable):
+            report(
+                f"{label}: an unreadable declaration was not reported; "
+                f"{said(unreadable)!r}."
+            )
+            return 1
+
+        # D4: pausing is not a gate.
+        gated = run_keel(
+            mixed, "gate", "task-start", "--change", "alpha", "--task", "1.1",
+            "--json", "--no-guard",
+        )
+        ungated = run_keel(
+            both, "gate", "task-start", "--change", "alpha", "--task", "1.1",
+            "--json", "--no-guard",
+        )
+        if json.loads(gated.stdout).get("status") != json.loads(
+            ungated.stdout
+        ).get("status"):
+            report(
+                f"{label}: pausing changed a gate verdict — paused "
+                f"{json.loads(gated.stdout).get('status')!r} against unpaused "
+                f"{json.loads(ungated.stdout).get('status')!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    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
+
+
 # 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
@@ -26050,6 +26357,8 @@ SCENARIOS: tuple = (
     ("a-reference-outlives-its-declaration", validate_reference_outlives_its_declaration_scenario),
     ("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),
     (
         "authored-scenario-names-are-registered",
         validate_authored_scenario_names_scenario,

package/src/core/context.js

@@ -230,8 +230,21 @@ function resolveExplicit(repo, change, task) {
   if (task && !/^\d+(?:\.\d+)+$/.test(task)) {
     return blocked(`Invalid explicit task: ${task}`);
   }
+  // A pause is skipped by inference and never by explicit selection: the owner
+  // has said which change they mean. It is still reported, because a session
+  // resuming into a paused change should know that is what it is.
+  const declaration = pauseDeclaration(repo, change);
+  const paused = declaration && declaration.paused
+    ? [
+      `Explicitly selected change is paused: ${change} — ${declaration.reason}`
+        + (declaration.since ? ` (since ${declaration.since})` : "")
+        + ". Inference passes over it; you asked for it by name.",
+    ]
+    : [];
   if (!task) {
-    return selectionForChange(repo, change, "explicit");
+    const context = selectionForChange(repo, change, "explicit");
+    context.warnings.push(...paused);
+    return context;
   }
 
   const tasksPath = path.join(repo, "openspec", "changes", change, "tasks.md");
@@ -259,6 +272,58 @@ function activeChanges(repo) {
     .sort();
 }
 
+// A change its owner deliberately stopped. Declared where the change lives,
+// under a `keel:` key of the OpenSpec change config — namespaced because that
+// file is OpenSpec's, and a bare `status:` would be a claim on a key OpenSpec
+// may define differently. Read by inference and by nothing else: pausing says
+// what to recommend, never what is allowed, so every gate behaves identically
+// on a paused change and explicit selection still reaches it.
+//
+// A declaration that cannot be read leaves the change available and is
+// reported. The alternative failure — a change silently dropped from inference
+// because its config had a typo — is this defect pointed the other way.
+function pauseDeclaration(repo, change) {
+  const configPath = path.join(
+    repo, "openspec", "changes", change, ".openspec.yaml"
+  );
+  if (!fs.existsSync(configPath)) return null;
+  let content;
+  try {
+    content = fs.readFileSync(configPath, "utf8");
+  } catch {
+    return { unreadable: "the file could not be read" };
+  }
+  // The indented body of a top-level `keel:` key: every following line that
+  // starts with whitespace. Simpler and safer than a lookahead for the next
+  // top-level key, which has to spell "end of input" as well.
+  const block = content.match(/^keel:[ \t]*\r?\n((?:[ \t]+\S[^\n]*\r?\n?)*)/m);
+  if (!block) return null;
+  const entries = new Map();
+  for (const line of block[1].split(/\r?\n/)) {
+    const match = line.match(/^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (match) entries.set(match[1].toLowerCase(), parseScalar(match[2]));
+  }
+  if (!entries.has("status")) return null;
+  const status = String(entries.get("status") || "").toLowerCase();
+  if (status !== "paused") {
+    return { unreadable: `status: ${entries.get("status")}` };
+  }
+  return {
+    paused: true,
+    reason: entries.get("reason") || "no reason recorded",
+    since: entries.get("since") || null,
+  };
+}
+
+function pauseNote(change, declaration) {
+  return (
+    `Paused change not inferred: ${change} — ${declaration.reason}`
+    + (declaration.since ? ` (since ${declaration.since})` : "")
+    + ". Select it explicitly with `keel context --change "
+    + `${change}\` if it is what you mean.`
+  );
+}
+
 function inferContext(repo) {
   const changes = activeChanges(repo);
   if (changes.length === 0) {
@@ -270,20 +335,57 @@ function inferContext(repo) {
       ["No active OpenSpec change was found."]
     );
   }
-  const contexts = changes.map((change) => selectionForChange(repo, change, "inferred"));
+  const declarations = new Map(
+    changes.map((change) => [change, pauseDeclaration(repo, change)])
+  );
+  const unreadable = [...declarations.entries()]
+    .filter(([, declaration]) => declaration && declaration.unreadable)
+    .map(([change, declaration]) =>
+      `Keel configuration for ${change} is not a pause declaration `
+        + `(${declaration.unreadable}); the change stays available to `
+        + "inference. A pause is `keel:` with `status: paused` and a `reason:`."
+    );
+  const paused = changes.filter(
+    (change) => declarations.get(change) && declarations.get(change).paused
+  );
+  const pauseNotes = paused.map(
+    (change) => pauseNote(change, declarations.get(change))
+  );
+  const active = changes.filter((change) => !paused.includes(change));
+  if (active.length === 0) {
+    // "Nothing to do" and "everything here is deliberately on hold" are
+    // different states, and the second is the one that tells a returning
+    // session whether to un-pause something or start something new.
+    return result(
+      "idle",
+      null,
+      "none",
+      [],
+      [
+        "Every active OpenSpec change is paused.",
+        ...pauseNotes,
+        ...unreadable,
+      ]
+    );
+  }
+  const contexts = active.map((change) => selectionForChange(repo, change, "inferred"));
   const storage = contexts.filter((context) => context.storageOnly);
   const candidates = contexts.filter((context) => !context.storageOnly);
-  const warnings = storage.map(
-    (context) =>
-      `Storage-only backlog ignored during inference: ${context.selection.change}.`
-  );
+  const warnings = [
+    ...storage.map(
+      (context) =>
+        `Storage-only backlog ignored during inference: ${context.selection.change}.`
+    ),
+    ...pauseNotes,
+    ...unreadable,
+  ];
   if (candidates.length === 0) {
     return result(
       "idle",
       null,
       "none",
       storage.flatMap((context) => context.read),
-      ["No actionable OpenSpec change was found."]
+      ["No actionable OpenSpec change was found.", ...pauseNotes, ...unreadable]
     );
   }
   if (candidates.length > 1) {
@@ -297,6 +399,8 @@ function inferContext(repo) {
           + candidates
             .map((context) => context.selection?.change || context.read[0])
             .join(", "),
+        ...pauseNotes,
+        ...unreadable,
       ]
     );
   }

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.")
       );
     }
   }