@christang/keel 5.47.0 → 5.48.0

package/README.md

@@ -280,8 +280,10 @@ command at the right moment. Three things make that happen.
 - **The hooks.** A SessionStart hook runs the continuity projection the moment a session
   opens; a PreToolUse hook enforces the write guard on every edit. Neither needs prompting.
 
-So in day-to-day use you run two commands: `keel --init` once, and `keel --doctor` when you
-want to check the wiring. Everything below is the vocabulary the agent uses on your behalf.
+So in day-to-day use you run two commands: `keel --doctor` when you want to check the
+wiring, and `keel --init` whenever it tells you the repository is behind its install — the
+protocol version lives in your `AGENTS.md`, and updating the package does not move it.
+Everything below is the vocabulary the agent uses on your behalf.
 
 ## Verification layering
 

package/assets/bootstrap/AGENTS.md

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

@@ -983,6 +983,78 @@ function printDoctorLine(name, status, detail = "") {
   process.stdout.write(`${name}: ${status}${detail ? ` - ${detail}` : ""}\n`);
 }
 
+// The `version=` attribute of the managed marker is written by every install
+// and, until this line existed, read back by nothing that runs locally: both
+// marker parsers match `keel:start(?:\s+[^>]*)?` and throw the attributes away.
+// The one reader was the plugin's SessionStart hook, and doctor reports that
+// plugin's activation as manual on every target — so the check might simply not
+// be running, with nothing to distinguish that from agreement. Doctor is the
+// model-free fallback: the declaration comes from the working tree and the
+// running version from this process, so the comparison holds with no plugin at
+// all.
+function declaredProtocolVersion(repo) {
+  const agentsPath = path.join(repo, "AGENTS.md");
+  if (!fs.existsSync(agentsPath)) return null;
+  const match = fs
+    .readFileSync(agentsPath, "utf8")
+    .match(/<!--\s*keel:start\s+version=(\d+\.\d+\.\d+)\s*-->/);
+  return match ? match[1] : null;
+}
+
+// Numeric, not lexical: "5.9.0" precedes "5.10.0" and string order says
+// otherwise. Returns a negative number when `a` is behind `b`.
+function compareVersions(a, b) {
+  const left = a.split(".").map(Number);
+  const right = b.split(".").map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if (left[i] !== right[i]) return left[i] - right[i];
+  }
+  return 0;
+}
+
+// Printed on every run, agreeing or not. A check that is silent when it passes
+// cannot be told apart from a check that did not run, which is the failure this
+// line exists to remove — so silence is never the report.
+function printProtocolVersionDrift(repo, target) {
+  const running = PACKAGE_JSON.version;
+  const declared = declaredProtocolVersion(repo);
+  if (!declared) {
+    printDoctorLine(
+      "protocol",
+      "not comparable",
+      `this CLI is ${running}; the repository declares no protocol version in `
+        + "an AGENTS.md `keel:start` marker — run "
+        + `keel --init --target ${target} to write one`
+    );
+    return;
+  }
+  const order = compareVersions(declared, running);
+  if (order === 0) {
+    printDoctorLine(
+      "protocol",
+      "ok",
+      `repo declares ${declared}, this CLI is ${running}`
+    );
+    return;
+  }
+  // The two directions have different repairs, and the wrong repair is a no-op
+  // that reads as a failure, so the line names the direction rather than the
+  // difference. Drift never reaches the exit code: an out-of-date install is
+  // not a broken one, and a doctor that goes red on release day is a doctor
+  // people switch off.
+  printDoctorLine(
+    "protocol",
+    "warning",
+    order < 0
+      ? `repo declares ${declared}, this CLI is ${running} — the repository is `
+        + `behind its install; run keel --init --target ${target} to bring the `
+        + "protocol forward"
+      : `repo declares ${declared}, this CLI is ${running} — the install is `
+        + "behind the repository, which carries a protocol this CLI cannot "
+        + "enforce; update the Keel package"
+  );
+}
+
 function codexHome() {
   const configured = (process.env.CODEX_HOME || "").trim();
   return path.resolve(configured || path.join(os.homedir(), ".codex"));
@@ -1553,6 +1625,8 @@ function runDoctor(options) {
     );
   }
 
+  printProtocolVersionDrift(repo, options.target);
+
   process.stdout.write("\nProject status:\n");
   const checkStatus = runPython(
     INSTALL_SCRIPT,

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.47.0",
+  "version": "5.48.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.47.0",
+  "version": "5.48.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.47.0"
-PROTOCOL_VERSION = "5.47.0"
+PACKAGE_VERSION = "5.48.0"
+PROTOCOL_VERSION = "5.48.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
@@ -24597,6 +24597,129 @@ def validate_doctor_openspec_honesty_scenario() -> int:
     return 0
 
 
+# The marker's `version=` attribute is written by the installer and, before this
+# scenario, read back by nothing that runs locally: both marker parsers match
+# `keel:start(?:\s+[^>]*)?` and discard the attributes. The only reader was the
+# plugin's SessionStart hook, whose activation doctor itself reports as manual.
+def validate_marker_version_is_read_scenario() -> int:
+    def doctor_protocol_line(repo: Path) -> tuple[str, int]:
+        result = run_keel(repo, "--doctor")
+        line = next(
+            (
+                entry
+                for entry in result.stdout.splitlines()
+                if entry.startswith("protocol:")
+            ),
+            "",
+        )
+        return line, result.returncode
+
+    def write_repo(root: Path, name: str, marker: str | None) -> Path:
+        repo = root / name
+        repo.mkdir()
+        body = "# Agents\n\nSession Start.\n"
+        (repo / "AGENTS.md").write_text(
+            f"{marker}\n{body}" if marker is not None else body,
+            encoding="utf-8",
+        )
+        return repo
+
+    with tempfile.TemporaryDirectory(prefix="keel-marker-version-") as raw:
+        root = Path(raw)
+
+        behind = write_repo(root, "behind", "<!-- keel:start version=5.14.0 -->")
+        line, behind_code = doctor_protocol_line(behind)
+        if not line.startswith("protocol: warning"):
+            report(
+                "the-marker-version-is-read scenario: a repository declaring an "
+                f"older protocol did not warn; got {line!r}."
+            )
+            return 1
+        for needed in ("5.14.0", PACKAGE_VERSION, "keel --init"):
+            if needed not in line:
+                report(
+                    "the-marker-version-is-read scenario: the behind-repository "
+                    f"warning omits {needed!r}; got {line!r}."
+                )
+                return 1
+        if "repository" not in line:
+            report(
+                "the-marker-version-is-read scenario: the warning does not name "
+                f"the repository as the term that is behind; got {line!r}."
+            )
+            return 1
+
+        ahead = write_repo(root, "ahead", "<!-- keel:start version=9.99.0 -->")
+        line, _ = doctor_protocol_line(ahead)
+        if not line.startswith("protocol: warning"):
+            report(
+                "the-marker-version-is-read scenario: a repository declaring a "
+                f"newer protocol did not warn; got {line!r}."
+            )
+            return 1
+        for needed in ("9.99.0", PACKAGE_VERSION, "install"):
+            if needed not in line:
+                report(
+                    "the-marker-version-is-read scenario: the ahead-repository "
+                    f"warning omits {needed!r}; got {line!r}."
+                )
+                return 1
+        if "keel --init" in line:
+            report(
+                "the-marker-version-is-read scenario: a repository ahead of its "
+                f"install was told to re-run keel --init; got {line!r}."
+            )
+            return 1
+
+        agreed = write_repo(
+            root, "agreed", f"<!-- keel:start version={PACKAGE_VERSION} -->"
+        )
+        line, agreed_code = doctor_protocol_line(agreed)
+        if not line.startswith("protocol: ok"):
+            report(
+                "the-marker-version-is-read scenario: agreeing versions did not "
+                f"report ok; got {line!r}."
+            )
+            return 1
+        if line.count(PACKAGE_VERSION) < 2:
+            report(
+                "the-marker-version-is-read scenario: the agreeing line does not "
+                f"print both versions; got {line!r}."
+            )
+            return 1
+
+        # D2: drift is a warning and nothing else. A line that could turn a
+        # pipeline red on release day is a line users switch off.
+        if behind_code != agreed_code:
+            report(
+                "the-marker-version-is-read scenario: drift changed doctor's "
+                f"exit code ({behind_code} vs {agreed_code})."
+            )
+            return 1
+
+        for name, marker in (
+            ("undeclared", None),
+            ("attributeless", "<!-- keel:start -->"),
+        ):
+            repo = write_repo(root, name, marker)
+            line, _ = doctor_protocol_line(repo)
+            if not line.startswith("protocol: not comparable"):
+                report(
+                    f"the-marker-version-is-read scenario: the {name} repository "
+                    f"did not report `not comparable`; got {line!r}."
+                )
+                return 1
+            if "declares" not in line:
+                report(
+                    f"the-marker-version-is-read scenario: the {name} repository "
+                    f"was not told which term is missing; got {line!r}."
+                )
+                return 1
+
+    report("the-marker-version-is-read 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
@@ -24826,6 +24949,7 @@ SCENARIOS: tuple = (
     ),
     ("cli", validate_cli_scenario),
     ("doctor-openspec-honesty", validate_doctor_openspec_honesty_scenario),
+    ("the-marker-version-is-read", validate_marker_version_is_read_scenario),
     (
         "authored-scenario-names-are-registered",
         validate_authored_scenario_names_scenario,