@christang/keel 5.53.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.53.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.53.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.53.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.53.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.53.0"
-PROTOCOL_VERSION = "5.53.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
@@ -25812,6 +25812,162 @@ 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
+
+
 # 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 +26206,7 @@ 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),
     (
         "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,
       ]
     );
   }