@christang/keel 5.47.0 → 5.49.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.49.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,
@@ -2160,4 +2234,11 @@ function main() {
   return runAction(options);
 }
 
-process.exit(main());
+// Not `process.exit()`: stdout to a pipe is asynchronous, and exiting discards
+// whatever the operating system has not yet accepted. Nothing is lost while the
+// payload fits the pipe buffer, which is why this was invisible at the 64KB
+// default — and under the memory pressure that shrinks buffers to a page or
+// two, a consumer receives a valid prefix of an incomplete document with no
+// error and no change of exit code. Setting the code instead lets the event
+// loop drain the write and end the process on its own.
+process.exitCode = main();

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.49.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.49.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.49.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.49.0"
+PROTOCOL_VERSION = "5.49.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,270 @@ 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
+
+
+# `process.exit()` discards whatever Node has not flushed, and stdout to a pipe
+# is asynchronous. Whether anything is lost depends only on whether the payload
+# fit the pipe buffer — so at the 64KB default nothing is ever lost, and under
+# the memory pressure that shrinks buffers to a page or two, output is lost
+# silently. Waiting for that condition is not a test; this scenario creates it.
+def validate_output_survives_the_pipe_scenario() -> int:
+    label = "output-survives-the-pipe"
+    F_SETPIPE_SZ = 1031
+    try:
+        import fcntl
+        import time
+    except ImportError:
+        return skip_scenario(
+            label,
+            "fcntl is unavailable, so the pipe buffer cannot be shrunk and the "
+            "truncation cannot be forced rather than waited for",
+        )
+
+    def goal_task(acceptance_padding: int) -> str:
+        huge = ("Acceptance " + ("A" * acceptance_padding) + " is proven by M1.",)
+        return _goal_tasks_file(
+            [_goal_task_block(acceptance=huge, strategy="vertical-tdd")]
+        )
+
+    goal_args = (
+        "project", "goal",
+        "--target", "codex",
+        "--change", "sample-change", "--task", "1.1", "--json",
+    )
+
+    with tempfile.TemporaryDirectory(prefix="keel-pipe-") as raw:
+        root = Path(raw)
+        repo = root / "repo"
+        write_text(repo / "openspec/changes/sample-change/proposal.md", "# P\n")
+        write_text(
+            repo / "openspec/changes/sample-change/design.md",
+            "## Context\n\nfixture\n",
+        )
+        write_text(
+            repo / "openspec/changes/sample-change/specs/demo/spec.md",
+            "## ADDED Requirements\n",
+        )
+        write_text(
+            repo / "openspec/changes/sample-change/tasks.md", goal_task(4200)
+        )
+
+        # The reference length: the same invocation with nowhere to lose bytes.
+        redirected = run_keel(repo, *goal_args)
+        if redirected.returncode != 0:
+            report(
+                f"{label}: the fixture did not produce a goal projection to "
+                f"measure against; keel exited {redirected.returncode}."
+            )
+            report((redirected.stderr or redirected.stdout).strip()[:400])
+            return 1
+        expected = redirected.stdout.encode("utf-8")
+        if len(expected) <= 4096:
+            report(
+                f"{label}: the fixture projection is {len(expected)} bytes, "
+                "which fits the shrunken pipe, so the condition this scenario "
+                "exists to force would not arise."
+            )
+            return 1
+
+        read_fd, write_fd = os.pipe()
+        try:
+            fcntl.fcntl(write_fd, F_SETPIPE_SZ, 4096)
+        except OSError as error:
+            os.close(read_fd)
+            os.close(write_fd)
+            return skip_scenario(
+                label,
+                "this platform refused F_SETPIPE_SZ "
+                f"({error}), so the pipe buffer cannot be shrunk",
+            )
+
+        child = subprocess.Popen(
+            ["node", str(ROOT / "bin" / "keel.js"), *goal_args],
+            cwd=repo,
+            stdout=write_fd,
+            stderr=subprocess.DEVNULL,
+        )
+        os.close(write_fd)
+        # Nothing is read for a moment, so the buffer fills and the rest of the
+        # write is left pending. A child that discards its pending write on exit
+        # is finished by now, having lost everything past the buffer; a child
+        # that lets the event loop drain is blocked on the write and finishes
+        # once the loop below starts reading. Reading immediately would drain
+        # fast enough to let the broken form through, which is the race this
+        # scenario exists to remove — so the pause is the forcing condition, and
+        # the child is waited for after the read rather than before it.
+        time.sleep(1.0)
+        received = b""
+        while True:
+            chunk = os.read(read_fd, 65536)
+            if not chunk:
+                break
+            received += chunk
+        os.close(read_fd)
+        child.wait(timeout=60)
+
+        if received != expected:
+            report(
+                f"{label}: {len(received)} of {len(expected)} bytes survived a "
+                "4096-byte pipe. Output written for a program to read is being "
+                "discarded at process exit, with no error and no exit-code "
+                "change — the consumer receives a valid prefix of an "
+                "incomplete document."
+            )
+            return 1
+        try:
+            json.loads(received.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            report(f"{label}: the payload that survived does not parse: {error}.")
+            return 1
+
+        # D3: the one behavioral difference a reader would worry about.
+        ok = run_keel(repo, "--version")
+        if ok.returncode != 0:
+            report(f"{label}: a successful command returned {ok.returncode}.")
+            return 1
+        refused = run_keel(
+            repo, "gate", "task-start", "--change", "no-such-change", "--task", "1.1"
+        )
+        if refused.returncode != 1:
+            report(
+                f"{label}: a refused gate returned {refused.returncode}, not 1."
+            )
+            return 1
+        invalid = run_keel(repo, "--not-a-flag")
+        if invalid.returncode != 2:
+            report(
+                f"{label}: an invalid argument returned {invalid.returncode}, "
+                "not 2."
+            )
+            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
@@ -24826,6 +25090,8 @@ 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),
+    ("output-survives-the-pipe", validate_output_survives_the_pipe_scenario),
     (
         "authored-scenario-names-are-registered",
         validate_authored_scenario_names_scenario,