@christang/keel 5.75.0 → 5.76.0

package/README.md

@@ -145,7 +145,7 @@ because a permission granted in conversation does not survive a context reset. D
 `keel/config.yaml` instead:
 
 ```yaml
-authorize:          # accepted names: commit, push, release, archive, continuation, issue:<owner>/<repo>
+authorize:          # accepted names: commit, push, release, archive, continuation, issue:<owner>/<repo>, protocol-refresh
   - commit
   - push
 ```
@@ -174,6 +174,15 @@ capsule and **does not enforce it**: it invokes no tracker client and cannot obs
 as it never commits on your behalf either. Closing an issue is not in scope and does not need to
 be — a pull request body carrying `Closes #<n>` does that when it lands.
 
+`protocol-refresh`, the seventh name, covers the one piece of a release that a plugin update cannot
+carry: the managed protocol block in this repository's `AGENTS.md`, which moves only when
+`keel --install` runs here. When `keel context` reports that block as older than the running Keel,
+it prints a `Protocol:` line naming the refresh command, and with this name declared the agent runs
+it before other work without asking. It never runs while a task's write guard is active, because
+the refresh writes outside that task's `Touch`, and it never commits: the diff is left for you,
+and committing it is a separate action that a declared `commit` covers like any other. On an older
+Keel whose vocabulary predates the word, the declaration authorizes nothing until corrected.
+
 Three things the declaration is not:
 
 - **Not a way past a gate.** It authorizes the action, never the proof. `keel gate task-complete`
@@ -181,7 +190,7 @@ Three things the declaration is not:
   anything.
 - **Not a trigger.** It removes a confirmation, not the step that reaches the action. Nothing
   schedules itself, and no next task is selected for you.
-- **Not open-ended.** The six names above are the whole vocabulary. An unrecognized entry is
+- **Not open-ended.** The seven names above are the whole vocabulary. An unrecognized entry is
   reported with the accepted names and the declaration authorizes nothing until you fix it — a
   typo never becomes a silent grant.
 

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.75.0 -->
+<!-- keel:start version=5.76.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/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@christang/keel",
-  "version": "5.75.0",
+  "version": "5.76.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@christang/keel",
-      "version": "5.75.0",
+      "version": "5.76.0",
       "license": "MIT",
       "dependencies": {
         "@fission-ai/openspec": "^1.4.1"

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.75.0",
+  "version": "5.76.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.75.0",
+  "version": "5.76.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

@@ -38,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.75.0"
-PROTOCOL_VERSION = "5.75.0"
+PACKAGE_VERSION = "5.76.0"
+PROTOCOL_VERSION = "5.76.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
@@ -16222,6 +16222,121 @@ def validate_init_declares_plugin_auto_update_scenario() -> int:
     return 0
 
 
+# Issue #164: the managed protocol block is the one piece of a release that a
+# plugin update cannot carry, so `keel context` names its refresh, and a
+# standing `protocol-refresh` lets the agent run it without asking.
+PROTOCOL_REFRESH_LABEL = "context-names-the-protocol-refresh"
+
+
+def _installed_repo(tmp: Path, name: str, target: str, stamp: str) -> Path:
+    repo = tmp / name
+    repo.mkdir()
+    installed = run_keel(repo, "--install", "--target", target)
+    if installed.returncode != 0:
+        raise RuntimeError((installed.stderr or installed.stdout).strip())
+    agents = repo / "AGENTS.md"
+    text = agents.read_text(encoding="utf-8")
+    agents.write_text(
+        re.sub(r"<!-- keel:start version=[0-9.]+ -->", f"<!-- keel:start version={stamp} -->", text, count=1),
+        encoding="utf-8",
+    )
+    return repo
+
+
+def _protocol_lines(repo: Path) -> list[str]:
+    result = run_keel(repo, "context")
+    return [line for line in (result.stdout or "").splitlines() if line.startswith("Protocol:")]
+
+
+def _protocol_json(repo: Path):
+    result = run_keel(repo, "context", "--json")
+    try:
+        return json.loads(result.stdout).get("protocol")
+    except ValueError:
+        return "unparseable"
+
+
+def _protocol_refresh_m1(tmp: Path) -> str | None:
+    repo = _installed_repo(tmp, "older", "claude", "5.0.0")
+    lines = _protocol_lines(repo)
+    if len(lines) != 1:
+        return f"M1 context printed no Protocol line for a 5.0.0 stamp under Keel {PACKAGE_VERSION}: {lines!r}"
+    line = lines[0]
+    for needle in ("5.0.0", PACKAGE_VERSION, "keel --install --target claude", "ask"):
+        if needle not in line:
+            return f"M1 context printed no Protocol line carrying {needle!r}: {line!r}"
+    found = _protocol_json(repo)
+    if not isinstance(found, dict) or found.get("stamped") != "5.0.0":
+        return f"M1 context printed no Protocol line in its JSON result: protocol is {found!r}"
+    return None
+
+
+def _protocol_refresh_m2(tmp: Path) -> str | None:
+    repo = _installed_repo(tmp, "authorized", "claude", "5.0.0")
+    write_text(repo / "keel/config.yaml", "authorize:\n  - protocol-refresh\n")
+    lines = _protocol_lines(repo)
+    if len(lines) != 1 or "standing-authorized" not in lines[0]:
+        return f"M2 context did not read protocol-refresh as authorized: {lines!r}"
+    doctor = run_keel(repo, "--doctor").stdout or ""
+    if "protocol-refresh: authorized" not in doctor or "commit: not authorized" not in doctor:
+        return (
+            "M2 doctor did not read protocol-refresh as authorized alone: "
+            + repr([l for l in doctor.splitlines() if "authoriz" in l])
+        )
+    return None
+
+
+def _protocol_refresh_m3(tmp: Path) -> str | None:
+    repo = _installed_repo(tmp, "guarded", "claude", "5.0.0")
+    write_text(repo / "keel/config.yaml", "authorize:\n  - protocol-refresh\n")
+    write_text(repo / "keel/guard.json", "{}\n")
+    lines = _protocol_lines(repo)
+    if len(lines) != 1 or "deferred" not in lines[0] or "write guard" not in lines[0]:
+        return f"M3 the refresh was not deferred while a write guard is active: {lines!r}"
+    return None
+
+
+def _protocol_refresh_m4(tmp: Path) -> str | None:
+    repo = _installed_repo(tmp, "newer", "claude", "99.0.0")
+    for where, target in (("a 99.0.0 stamp", repo), ("Keel's own source repository", ROOT)):
+        lines = _protocol_lines(target)
+        found = _protocol_json(target)
+        if lines or found is not None:
+            return (
+                f"M4 context offered a refresh for a protocol that is not older ({where}): "
+                f"{lines!r}, json {found!r}"
+            )
+    return None
+
+
+def _protocol_refresh_m5(tmp: Path) -> str | None:
+    repo = _installed_repo(tmp, "codex", "codex", "5.0.0")
+    lines = _protocol_lines(repo)
+    if len(lines) != 1 or "keel --install --target codex" not in lines[0]:
+        return f"M5 context named the wrong target for a Codex repository: {lines!r}"
+    return None
+
+
+def validate_context_names_the_protocol_refresh_scenario() -> int:
+    with tempfile.TemporaryDirectory(
+        prefix="keel-protocol-refresh-", ignore_cleanup_errors=True
+    ) as raw:
+        tmp = Path(raw)
+        for check in (
+            _protocol_refresh_m1,
+            _protocol_refresh_m2,
+            _protocol_refresh_m3,
+            _protocol_refresh_m4,
+            _protocol_refresh_m5,
+        ):
+            problem = check(tmp)
+            if problem:
+                report(f"{PROTOCOL_REFRESH_LABEL} {problem}")
+                return 1
+    report(f"{PROTOCOL_REFRESH_LABEL} scenario passed.")
+    return 0
+
+
 def validate_native_plugin_marketplaces_scenario() -> int:
     codex = shutil.which("codex")
     claude = claude_cli()
@@ -17925,6 +18040,7 @@ STANDING_AUTHORIZATION_ACTIONS = (
     "release",
     "archive",
     "continuation",
+    "protocol-refresh",
 )
 
 
@@ -20824,25 +20940,52 @@ def validate_continuation_docs_scenario() -> int:
 
     readme = (ROOT / "README.md").read_text(encoding="utf-8")
     for needle in (
-        "accepted names: commit, push, release, archive, continuation, "
-        "issue:<owner>/<repo>",
         "next unchecked task of the same change",
         "the stop that re-asks for an approval already given",
-        "The six names above are the whole vocabulary.",
     ):
         if needle not in readme:
             report(f"{label}: README.md lacks: {needle}")
             return 1
+    # The seventh name (#164). Each surface that spells the vocabulary out has
+    # to spell all of it: a reader copies from the list they are shown.
+    for needle in (
+        "accepted names: commit, push, release, archive, continuation, "
+        "issue:<owner>/<repo>, protocol-refresh",
+        "The seven names above are the whole vocabulary.",
+        "`protocol-refresh`, the seventh name",
+    ):
+        if needle not in readme:
+            report(f"{label}: README.md lacks: protocol-refresh, as {needle!r}")
+            return 1
 
     config_text = (ROOT / "keel/config.yaml").read_text(encoding="utf-8")
-    if "commit, push, release, archive,\n# continuation, issue:<owner>/<repo>" not in config_text:
+    if "commit, push, release, archive,\n# continuation, issue:<owner>/<repo>, protocol-refresh" not in config_text:
         report(
-            f"{label}: keel/config.yaml's comment does not name the six-name "
-            "vocabulary."
+            f"{label}: keel/config.yaml's comment lacks: protocol-refresh in the "
+            "seven-name vocabulary."
         )
         return 1
 
     agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+    # M2 — the rule an agent follows when `keel context` names a refresh. The
+    # consumer bootstrap has no room for it (its byte budget is spent), and
+    # needs none: it opens with `keel context`, whose `Protocol:` line states
+    # the same rule in whichever state applies.
+    session = agents.split("## Session Start", 1)[-1].split("\n## ", 1)[0]
+    for needle in ("`protocol-refresh`", "write guard", "uncommitted"):
+        if needle not in session:
+            report(
+                f"{label}: AGENTS.md Session Start does not carry the "
+                f"protocol-refresh rule; it lacks {needle!r}."
+            )
+            return 1
+    bootstrap = (ROOT / "assets/bootstrap/AGENTS.md").read_text(encoding="utf-8")
+    if "Start every session with `keel context`" not in bootstrap:
+        report(
+            f"{label}: the bootstrap does not carry the protocol-refresh rule's "
+            "route to a consumer: it no longer opens with `keel context`."
+        )
+        return 1
     parts = agents.split("## Execution boundary", 1)
     if len(parts) != 2:
         report(f"{label}: AGENTS.md lost its Execution boundary section.")
@@ -31170,6 +31313,7 @@ SCENARIOS: tuple = (
     ("runtime-version-drift", validate_runtime_version_drift_scenario),
     ("plugin-runs-its-own-cli", validate_plugin_runs_its_own_cli_scenario),
     ("init-declares-plugin-auto-update", validate_init_declares_plugin_auto_update_scenario),
+    ("context-names-the-protocol-refresh", validate_context_names_the_protocol_refresh_scenario),
     ("native-plugin-marketplaces", validate_native_plugin_marketplaces_scenario),
     ("native-plugin-install-matrix", validate_native_plugin_install_matrix_scenario),
     ("native-goal-projection", validate_native_goal_projection_scenario),

package/src/core/config.js

@@ -14,6 +14,10 @@ const STANDING_AUTHORIZATION_ACTIONS = [
   "archive",
   "continuation",
   "issue",
+  // Running the refresh `keel context` names while the managed protocol is
+  // older than the running Keel (#164). It acts on this checkout, so it takes
+  // no scope, and it never covers committing what the refresh wrote.
+  "protocol-refresh",
 ];
 
 // The actions whose credential reaches further than the checkout the

package/src/core/context.js

@@ -18,6 +18,7 @@ const {
   readExecutorTier,
   readMergeDeclaration,
 } = require("./config");
+const { isKeelSourceRepo } = require("./capabilities");
 
 const NEXT_ACTIONS = new Set([
   "discuss",
@@ -712,6 +713,9 @@ function resolveContext(repo, options) {
   context.executorTier = executor.tier;
   if (executor.unknown.length > 0) context.warnings.push(executor.message);
 
+  const protocol = protocolRefresh(repo, keelVersion(), authorization);
+  if (protocol) context.protocol = protocol;
+
   // Set here rather than by the caller, so every consumer of the projection —
   // text, JSON, and any host reading it — carries the version without having
   // to know to add it.
@@ -719,6 +723,79 @@ function resolveContext(repo, options) {
   return context;
 }
 
+// The managed block is the one piece of a release a plugin update cannot
+// carry: it lives in each repository and moves only when `keel --install`
+// runs there (#164). The stamp is read in the SessionStart hook's order.
+function stampedProtocol(repo) {
+  for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+    try {
+      const text = fs.readFileSync(path.join(repo, name), "utf8");
+      const match = text.match(/<!--\s*keel:start\s+version=(\d+\.\d+\.\d+)\s*-->/);
+      if (match) return { version: match[1], file: name };
+    } catch {
+      // Absent is not older.
+    }
+  }
+  return null;
+}
+
+// The target the installer left behind. `CLAUDE.md` carries the managed
+// import only on the Claude target, and only OpenCode writes project commands
+// under `.opencode/`. A Codex install writes neither — its OpenSpec commands
+// are global prompts under CODEX_HOME — so a managed `AGENTS.md` with neither
+// surface beside it is what a Codex install leaves.
+function installedTarget(repo) {
+  try {
+    if (/<!--\s*keel:start/.test(fs.readFileSync(path.join(repo, "CLAUDE.md"), "utf8"))) {
+      return "claude";
+    }
+  } catch {
+    // No CLAUDE.md: not the Claude target.
+  }
+  if (fs.existsSync(path.join(repo, ".opencode", "commands"))) return "opencode";
+  return "codex";
+}
+
+// Numeric X.Y.Z order. Only a strictly older stamp is a refresh: a newer one
+// means the CLI is the stale side, which the SessionStart drift line reports.
+function olderThan(stamped, running) {
+  const a = stamped.split(".").map(Number);
+  const b = String(running).split(".").map(Number);
+  if (b.length !== 3 || b.some(Number.isNaN)) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) return a[i] < b[i];
+  }
+  return false;
+}
+
+function protocolRefresh(repo, running, authorization) {
+  if (isKeelSourceRepo(repo)) return null;
+  const stamped = stampedProtocol(repo);
+  if (!stamped || !olderThan(stamped.version, running)) return null;
+  return {
+    stamped: stamped.version,
+    keel: running,
+    file: stamped.file,
+    command: `keel --install --target ${installedTarget(repo)}`,
+    authorized: authorization.scopes.has("protocol-refresh"),
+    deferred: fs.existsSync(path.join(repo, "keel", "guard.json")),
+  };
+}
+
+function renderProtocol(protocol) {
+  const head = `Protocol: ${protocol.file} is stamped ${protocol.stamped}, older than `
+    + `Keel ${protocol.keel}; refresh with \`${protocol.command}\``;
+  if (protocol.deferred) {
+    return `${head} — deferred while a task's write guard is active, because `
+      + "the refresh writes outside the task's Touch";
+  }
+  return protocol.authorized
+    ? `${head} — standing-authorized (authorize: protocol-refresh); run it `
+      + "before other work and leave the diff for the owner to commit"
+    : `${head} — ask before running it; keel/config.yaml does not `
+      + "standing-authorize protocol-refresh";
+}
+
 // The version comparison has to survive a runtime too old to contain it. The
 // SessionStart check shipped in 5.9.0, so a plugin older than that carries no
 // check at all, and its silence is indistinguishable from three versions
@@ -779,6 +856,7 @@ function renderContext(result) {
         + "Review changes with it"
     );
   }
+  if (result.protocol) lines.push(renderProtocol(result.protocol));
   for (const reason of result.reasons) lines.push(`Reason: ${reason}`);
   for (const warning of result.warnings) lines.push(`Warning: ${warning}`);
   return `${lines.join("\n")}\n`;