@christang/keel 5.52.0 → 5.54.0

package/README.md

@@ -333,6 +333,29 @@ keel lenses add web         # copy the web template into keel/lenses/web.md, the
 keel lenses add web --force # overwrite an existing lens
 ```
 
+## 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.52.0 -->
+<!-- keel:start version=5.54.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/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.52.0",
+  "version": "5.54.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.52.0",
+  "version": "5.54.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.52.0",
+  "version": "5.54.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.52.0"
-PROTOCOL_VERSION = "5.52.0"
+PACKAGE_VERSION = "5.54.0"
+PROTOCOL_VERSION = "5.54.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
@@ -24945,13 +24945,20 @@ def strategy_probe_task(
         "    - README.md",
         "  - Touch:",
         "    - src/example.js",
-        f"  - {form}:",
     ]
-    if strategy is not None:
-        label = "Strategy" if form == "Verify" else "Verification Strategy"
-        lines.append(f"    - {label}: {strategy}")
-    if reason is not None:
-        lines.append(f"    - Reason: {reason}")
+    # In the expanded v3 form the strategy and its reason are task-level fields
+    # beside `Commands`, not entries inside it.
+    if form != "Verify":
+        if strategy is not None:
+            lines.append(f"  - Verification Strategy: {strategy}")
+        if reason is not None:
+            lines.append(f"  - Verification Reason: {reason}")
+    lines.append(f"  - {form}:")
+    if form == "Verify":
+        if strategy is not None:
+            lines.append(f"    - Strategy: {strategy}")
+        if reason is not None:
+            lines.append(f"    - Reason: {reason}")
     lines.extend(f"    - {entry}" for entry in commands)
     lines.extend(
         [
@@ -25516,6 +25523,451 @@ def validate_drift_names_where_to_look_scenario() -> int:
     return 0
 
 
+# Issue #112's minimal reproduction. An unfilled slot in an `M<n>` declaration
+# stopped the contract compiling, the completion path fell back to the expanded
+# v3 `Commands` field a compact task never declares, and every reference to an
+# `M<n>` was reported as naming a check the task does not declare — first, and
+# as somebody else's fault. The reporter calls it the only diagnostic in 149
+# invocations that made them edit the wrong file.
+def validate_reference_outlives_its_declaration_scenario() -> int:
+    label = "a-reference-outlives-its-declaration"
+
+    def complete(root: Path, name: str, checks, findings, form="Verify"):
+        repo = root / name
+        task = strategy_probe_task(
+            strategy="evidence-first",
+            reason="fixture; nothing here can fail first",
+            form=form,
+            commands=checks,
+        )
+        task = task.replace("- [ ] 1.1", "- [x] 1.1")
+        task = task.replace("      - Findings: none", f"      - Findings: {findings}")
+        for entry in checks:
+            lbl = entry.split(":", 1)[0].split(" ")[0]
+            task = task.replace(f"    - {lbl}: pending", f"    - {lbl}: pass. ran it.")
+        write_gate_fixture(repo, tasks=task)
+        started = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--json", "--no-guard",
+        )
+        payload = json.loads(started.stdout)
+        value = ((payload.get("contract") or {}).get("fingerprint") or {}).get(
+            "value"
+        ) or "0" * 64
+        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",
+        )
+        result = run_keel(
+            repo, "gate", "task-complete", "--change", "demo", "--task", "1.1",
+            "--json",
+        )
+        return json.loads(result.stdout)
+
+    slotted = (
+        "M1: the first check asserts the public behavior",
+        "M2: the second check runs make sta RUN=<experiment_id> and succeeds",
+    )
+    clean = (
+        "M1: the first check asserts the public behavior",
+        "M2: the second check runs the suite and succeeds",
+    )
+
+    with tempfile.TemporaryDirectory(prefix="keel-reference-") as raw:
+        root = Path(raw)
+
+        reported = complete(root, "slotted", slotted, "one. Resolved here: M2")
+        text = problem_text(reported)
+        if "<experiment_id>" not in text:
+            report(
+                f"{label}: the unfilled slot is no longer reported; {text!r}."
+            )
+            return 1
+        if "not a check this task declares" in text:
+            report(
+                f"{label}: a reference to M2 was reported as undeclared because "
+                f"M2's own declaration failed to compile; {text!r}."
+            )
+            return 1
+
+        settled = complete(root, "clean", clean, "one. Resolved here: M2")
+        if settled.get("status") != "pass":
+            report(
+                f"{label}: the same task without the slot no longer passes; "
+                f"{problem_text(settled)!r}."
+            )
+            return 1
+
+        # The set narrowed to the truth, not to everything.
+        absent = complete(root, "absent", clean, "one. Resolved here: M9")
+        if "not a check this task declares" not in problem_text(absent):
+            report(
+                f"{label}: a reference to a check the task never declared was "
+                f"accepted; {problem_text(absent)!r}."
+            )
+            return 1
+
+        legacy = complete(
+            root, "legacy", clean, "one. Resolved here: M2", form="Commands"
+        )
+        if legacy.get("status") != "pass":
+            report(
+                f"{label}: an expanded v3 task lost its declared labels; "
+                f"{problem_text(legacy)!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+# The red-green obligation is a static function of the strategy and the tags,
+# and the `Verify` block is complete at task-start while the Evidence is all
+# pending. Issue #112 hit it three times, this repository twice more: the rule
+# was first heard after the capsule was written, the task implemented, the
+# checks run, and the Evidence recorded.
+def validate_obligation_is_stated_early_scenario() -> int:
+    label = "the-obligation-is-stated-early"
+
+    def start(root: Path, name: str, strategy: str, reason=None, checks=None):
+        repo = root / name
+        write_gate_fixture(
+            repo,
+            tasks=strategy_probe_task(
+                strategy=strategy,
+                reason=reason,
+                commands=checks
+                or (
+                    "M1: the first check asserts the public behavior",
+                    "M2 (regression): the second asserts something green stays green",
+                ),
+            ),
+        )
+        result = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--json", "--no-guard",
+        )
+        return json.loads(result.stdout)
+
+    with tempfile.TemporaryDirectory(prefix="keel-obligation-") as raw:
+        root = Path(raw)
+
+        redgreen = start(root, "redgreen", "vertical-tdd")
+        if redgreen.get("status") != "pass":
+            report(
+                f"{label}: stating the obligation changed the verdict; "
+                f"{problem_text(redgreen)!r}."
+            )
+            return 1
+        warnings = " ".join(str(x) for x in (redgreen.get("warnings") or []))
+        if ".red" not in warnings or ".green" not in warnings:
+            report(
+                f"{label}: task-start did not state the red-green obligation; "
+                f"{warnings!r}."
+            )
+            return 1
+        obligation = next(
+            (w for w in redgreen["warnings"] if ".red" in str(w)), ""
+        )
+        if "M1" not in obligation:
+            report(
+                f"{label}: the obligation does not name the check that owes it; "
+                f"{obligation!r}."
+            )
+            return 1
+        if "M2" not in obligation or "regression" not in obligation:
+            report(
+                f"{label}: the obligation does not name the exempt check; "
+                f"{obligation!r}."
+            )
+            return 1
+
+        quiet = start(
+            root,
+            "quiet",
+            "evidence-first",
+            reason="fixture; nothing here can fail first",
+        )
+        quiet_warnings = " ".join(str(x) for x in (quiet.get("warnings") or []))
+        if ".red" in quiet_warnings:
+            report(
+                f"{label}: a strategy without red-green was told about it; "
+                f"{quiet_warnings!r}."
+            )
+            return 1
+
+        # A task that fails task-start for another reason still fails with its
+        # own problem: the warning is not a verdict and cannot mask one.
+        broken = start(root, "broken", "made-up-thing")
+        if broken.get("status") != "fail":
+            report(f"{label}: an unsupported strategy stopped failing.")
+            return 1
+        if "unsupported" not in problem_text(broken):
+            report(
+                f"{label}: an unsupported strategy lost its own diagnostic; "
+                f"{problem_text(broken)!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
+# Measured on issue #112's own shape: a two-check vertical-tdd task with no
+# red-green Evidence produced four problems in 827 characters, of which the
+# same 84-character rule sentence was four copies. It scales with the number
+# of checks, and the reporter estimates a third of failure output is this.
+def validate_explanation_is_printed_once_scenario() -> int:
+    label = "an-explanation-is-printed-once"
+    shared = "Tag the check `(regression)` if it asserts that something already green stays green."
+    with tempfile.TemporaryDirectory(prefix="keel-explanation-") as raw:
+        root = Path(raw)
+        repo = root / "repo"
+        task = strategy_probe_task(
+            strategy="vertical-tdd",
+            commands=(
+                "M1: the first check asserts the public behavior",
+                "M2: the second check asserts the public behavior",
+            ),
+        )
+        task = task.replace("- [ ] 1.1", "- [x] 1.1")
+        for lbl in ("M1", "M2"):
+            task = task.replace(f"    - {lbl}: pending", f"    - {lbl}: 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",
+        )
+
+        rendered = run_keel(
+            repo, "gate", "task-complete", "--change", "demo", "--task", "1.1"
+        ).stdout
+        copies = rendered.count(shared)
+        if copies != 1:
+            report(
+                f"{label}: the shared rule explanation appears {copies} times "
+                "in the rendered text; it belongs once per run."
+            )
+            return 1
+        problems = [
+            line for line in rendered.splitlines() if line.startswith("Problem:")
+        ]
+        if len(problems) != 4:
+            report(
+                f"{label}: expected the four per-label problems, got "
+                f"{len(problems)}: {problems!r}."
+            )
+            return 1
+        for needed in ("M1.red", "M1.green", "M2.red", "M2.green"):
+            if not any(needed in line for line in problems):
+                report(
+                    f"{label}: {needed} lost its own problem line; {problems!r}."
+                )
+                return 1
+        if len(rendered) >= 827:
+            report(
+                f"{label}: the rendered failure is {len(rendered)} characters, "
+                "no shorter than the 827 measured before deduplication."
+            )
+            return 1
+
+        payload = json.loads(
+            run_keel(
+                repo, "gate", "task-complete", "--change", "demo", "--task",
+                "1.1", "--json",
+            ).stdout
+        )
+        carried = [
+            entry for entry in (payload.get("problems") or [])
+            if entry.get("code") == "missing-strategy-evidence"
+        ]
+        if len(carried) != 4:
+            report(
+                f"{label}: the JSON result no longer carries all four problems; "
+                f"{len(carried)}."
+            )
+            return 1
+        if not all(shared in json.dumps(entry, ensure_ascii=False) for entry in carried):
+            report(
+                f"{label}: the JSON result was deduplicated; a consumer reading "
+                "problems individually would get a payload whose content "
+                "depends on position."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    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
+
+
 # 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
@@ -25751,6 +26203,10 @@ SCENARIOS: tuple = (
     ("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),
+    ("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),
     (
         "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

@@ -9,6 +9,7 @@ const {
   ACCEPTED_REVIEW_STATUSES,
   RED_GREEN_VERIFICATION_STRATEGIES,
   compileTaskContract,
+  declaredCommandLabels,
   field,
   isConcrete,
   isPassingReviewStatus,
@@ -21,8 +22,15 @@ const GATE_STAGES = new Set(["task-start", "task-complete", "change-close"]);
 
 class GateInputError extends Error {}
 
-function problem(code, message) {
-  return { code, message };
+// `note` is the rule behind the problem rather than the problem itself. Every
+// problem carries its own copy in the JSON result, because a consumer reading
+// problems one at a time must not get a payload whose content depends on
+// position; the text renderer prints each distinct note once, because there
+// the repetition is what crowds out the specific lines. Measured on a
+// two-check task: the same 84-character sentence four times in 827 characters,
+// and it scales with the number of checks.
+function problem(code, message, note = null) {
+  return note ? { code, message, note } : { code, message };
 }
 
 function gateResult(
@@ -212,6 +220,34 @@ function anchoredFingerprint(previous) {
 // way to acknowledge a `needs-review`, so making it one would leave a
 // legitimate split unstartable. The reader is given the other task's id and
 // compares two things, rather than being told something is wrong.
+// What completion will require, said while the Evidence is still all pending.
+// The `Verify` block is complete at task-start and the obligation is a static
+// function of the strategy and the tags, so the only reason it was first heard
+// at task-complete is that nobody said it earlier — after the capsule was
+// written, the task implemented, the checks run, and the Evidence recorded.
+// A warning, never a refusal: a task whose author has not yet decided which
+// check is a regression is not malformed, it is unfinished.
+function redGreenObligation(compiled) {
+  if (!compiled || compiled.diagnostics.length > 0) return [];
+  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 exempt = commands.filter((item) => item.regression).map((item) => item.label);
+  if (owing.length === 0) return [];
+  return [
+    `${strategy} will require concrete .red and .green Evidence at completion `
+      + `for ${owing.join(", ")}`
+      + (exempt.length > 0
+        ? `; ${exempt.join(", ")} ${exempt.length > 1 ? "are" : "is"} exempt as `
+          + "(regression)"
+        : "")
+      + ". 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.",
+  ];
+}
+
 function taskShapeWarnings(repo, selection, task, compiled) {
   if (!compiled || compiled.diagnostics.length > 0) return [];
   const strategy = compiled.capsule.verification.strategy.toLowerCase();
@@ -272,7 +308,10 @@ function taskStart(repo, options) {
     selection.change,
     [task.id],
     problems,
-    taskShapeWarnings(repo, selection, task, compiled),
+    [
+      ...redGreenObligation(compiled),
+      ...taskShapeWarnings(repo, selection, task, compiled),
+    ],
     problems.length === 0
       ? compiled
       : null
@@ -887,9 +926,13 @@ function attributeChanged(repo, task, changedList, contract, change, tasks) {
 
 function completionChecks(repo, task, contract = null, changeVerify = null, change = null) {
   const problems = [];
+  // Not the compiled capsule alone: when a check's declaration does not
+  // compile there is no capsule, and reconstructing the set from the expanded
+  // v3 `Commands` field a compact task never declares makes every reference
+  // look undeclared. The task's own declarations answer in both cases.
   const commands = contract
     ? contract.capsule.verification.commands.map((item) => item.label)
-    : commandLabels(task);
+    : declaredCommandLabels(task);
   // With no contract, the labels came from the expanded v3 `Commands` field,
   // which a compact task never declares — so their absence is a fact about the
   // fallback, not about the task. The compiler's own diagnostics are already in
@@ -926,8 +969,9 @@ function completionChecks(repo, task, contract = null, changeVerify = null, chan
             problem(
               "missing-strategy-evidence",
               `${strategy} requires concrete ${label}.${phase} Evidence for `
-                + "the same behavior check. Tag the check `(regression)` if it "
-                + "asserts that something already green stays green."
+                + "the same behavior check.",
+              "Tag the check `(regression)` if it asserts that something "
+                + "already green stays green."
             )
           );
         }
@@ -1626,6 +1670,11 @@ function renderGate(result) {
         : ""),
   ];
   for (const item of result.problems) lines.push(`Problem: ${item.message}`);
+  for (const note of [
+    ...new Set(result.problems.map((item) => item.note).filter(Boolean)),
+  ]) {
+    lines.push(`Note: ${note}`);
+  }
   for (const warning of result.warnings) lines.push(`Warning: ${warning}`);
   if (result.contract) {
     lines.push(

package/src/core/task-contract.js

@@ -229,6 +229,21 @@ function verification(task) {
   };
 }
 
+// The labels a task declares, read from the form the task itself uses. Label
+// parsing does not depend on a check being concrete, so this answers exactly
+// when the compiler cannot: a task whose `M2` declaration carries an unfilled
+// slot still declares `M2`, and a reference to it is not a reference to
+// something that does not exist.
+function declaredCommandLabels(task) {
+  const source = fieldValues(task, "Verify").length > 0
+    ? fieldValues(task, "Verify")
+    : fieldValues(task, "Commands");
+  return source
+    .map((entry) => entry.match(/^(M[1-9]\d*)(?:\s*\([^)\n]*\))?\s*:/))
+    .filter(Boolean)
+    .map((match) => match[1]);
+}
+
 function commandLabelProblems(task) {
   // A task that declared no verification form at all is reported once, by
   // requiredFieldProblems, as the one field it is missing. Its orphan Evidence
@@ -1195,6 +1210,7 @@ function loadTaskContract(repo, change, taskId) {
 
 module.exports = {
   ACCEPTED_REVIEW_STATUSES,
+  declaredCommandLabels,
   RED_GREEN_VERIFICATION_STRATEGIES,
   SUPPORTED_VERIFICATION_STRATEGIES,
   compileTaskContract,