@christang/keel 5.57.0 → 5.59.0

package/assets/bootstrap/AGENTS.md

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

@@ -671,16 +671,33 @@ function npmCommand() {
   return process.platform === "win32" ? "npm.cmd" : "npm";
 }
 
+// npm hoists: installed as a dependency, Keel's OpenSpec bin lands in the
+// consumer project's `node_modules/.bin`, and Keel's own package root has no
+// `node_modules` at all. Searching only the package root worked in exactly one
+// layout — a checkout of this repository, where Keel is the direct consumer —
+// which is why every scenario stayed green while `keel openspec` failed on a
+// plain install (issue #129). Walk outward the way Node resolves a module:
+// nearest wins, so a project pinning its own OpenSpec is honored over one
+// further up. The `.bin` entry is the published contract between npm and a
+// consumer; resolving through the dependency's internal bin path instead would
+// bind Keel to a path that belongs to the dependency.
+function openspecBinNames() {
+  return process.platform === "win32"
+    ? ["openspec.cmd", "openspec.exe", "openspec"]
+    : ["openspec"];
+}
+
 function openspecCandidates() {
-  const localBin = path.join(
-    PACKAGE_ROOT,
-    "node_modules",
-    ".bin",
-    process.platform === "win32" ? "openspec.cmd" : "openspec"
-  );
   const candidates = [];
-  if (fs.existsSync(localBin)) {
-    candidates.push(localBin);
+  let directory = PACKAGE_ROOT;
+  for (;;) {
+    for (const name of openspecBinNames()) {
+      const candidate = path.join(directory, "node_modules", ".bin", name);
+      if (fs.existsSync(candidate)) candidates.push(candidate);
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
   }
   candidates.push(process.platform === "win32" ? "openspec.cmd" : "openspec");
   candidates.push("openspec");
@@ -765,6 +782,39 @@ function declaredOpenSpecVersion(repo) {
   return { state: "none", version: null };
 }
 
+// "Not installed" and "installed and Keel cannot reach it" need different
+// advice: reinstalling is the only remedy for the first and cannot help with the
+// second, and issue #129 measured a whole class of installs being sent to it.
+// The package directory is the evidence — it is present whenever npm placed the
+// dependency, whatever happened to its `.bin` entry.
+function installedOpenSpecPackage() {
+  let directory = PACKAGE_ROOT;
+  for (;;) {
+    const candidate = path.join(
+      directory,
+      "node_modules",
+      "@fission-ai",
+      "openspec",
+      "package.json"
+    );
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+// The remedy for an openspec Keel could not run, split by whether npm has
+// already done the thing the other branch would ask for.
+function unresolvedOpenSpecAdvice() {
+  const installed = installedOpenSpecPackage();
+  return installed
+    ? `the OpenSpec dependency is installed at ${path.dirname(installed)} but `
+      + "Keel could not run it — check that its node_modules/.bin entry exists "
+      + "and is executable; reinstalling will not change this"
+    : "reinstall keel so npm installs its OpenSpec dependency";
+}
+
 function findOpenSpecCommand() {
   for (const command of openspecCandidates()) {
     const status = runCommand(command, ["--version"], {
@@ -1606,8 +1656,8 @@ function runDoctor(options) {
   if (!openspec) {
     printDoctorLine(
       "openspec",
-      "missing",
-      "reinstall keel so npm installs its OpenSpec dependency"
+      installedOpenSpecPackage() ? "problem" : "missing",
+      unresolvedOpenSpecAdvice()
     );
   } else {
     const bareOpenSpecOnPath =
@@ -1967,8 +2017,7 @@ function runAction(options) {
     const openspec = findOpenSpecCommand();
     if (!openspec) {
       process.stderr.write(
-        "keel: openspec is not resolvable; reinstall keel so npm installs "
-          + "its OpenSpec dependency\n"
+        `keel: openspec is not resolvable; ${unresolvedOpenSpecAdvice()}\n`
       );
       return 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.57.0",
+  "version": "5.59.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.57.0",
+  "version": "5.59.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.57.0",
+  "version": "5.59.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.57.0"
-PROTOCOL_VERSION = "5.57.0"
+PACKAGE_VERSION = "5.59.0"
+PROTOCOL_VERSION = "5.59.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
@@ -24623,6 +24623,186 @@ def validate_validation_runner_scenario() -> int:
 
 # The one ordered scenario registry: --scenario dispatch, the --all runner,
 # and registration assertions all read this list and nothing else.
+
+# 170 scenarios and every release gate ran green while `keel openspec` did not
+# resolve on a plain `npm install` (issue #129). The cause is a layout, not a
+# behavior: npm hoists, so the OpenSpec bin lands in the consumer project's
+# `node_modules/.bin` while the lookup only searched Keel's own package root —
+# which is where it sits in a checkout of this repository, and nowhere else.
+# So the assertion has to build the other layout rather than test harder in this
+# one. Built from the package's own files instead of the registry: what is under
+# test is where a file sits, and a suite that reaches the network fails for
+# reasons that have nothing to do with this code.
+def validate_dependency_resolves_where_npm_put_it_scenario() -> int:
+    label = "the-dependency-resolves-where-npm-put-it"
+
+    def write_openspec_stub(bin_dir: Path, version: str) -> None:
+        bin_dir.mkdir(parents=True, exist_ok=True)
+        if os.name == "nt":
+            (bin_dir / "openspec.cmd").write_text(
+                f"@echo off\necho {version}\n", encoding="utf-8"
+            )
+            return
+        stub = bin_dir / "openspec"
+        stub.write_text(f"#!/bin/sh\necho {version}\n", encoding="utf-8")
+        stub.chmod(0o755)
+
+    def install_keel(package_root: Path) -> None:
+        # The published `files` set, copied rather than packed: the tarball's
+        # contents are what npm unpacks, and `npm pack` would add a network-free
+        # but slow round trip through tar for no additional assertion.
+        package_root.mkdir(parents=True, exist_ok=True)
+        for entry in ("bin", "scripts", "src", "assets", "plugins"):
+            source = ROOT / entry
+            if source.exists():
+                shutil.copytree(source, package_root / entry, dirs_exist_ok=True)
+        shutil.copy2(ROOT / "package.json", package_root / "package.json")
+
+    # PATH without any openspec, so what resolves came from the layout and not
+    # from the machine running the suite.
+    def clean_env(extra_path: Path | None = None) -> dict[str, str]:
+        env = dict(os.environ)
+        entries = [
+            entry
+            for entry in env.get("PATH", "").split(os.pathsep)
+            if entry and not (Path(entry) / "openspec").exists()
+        ]
+        if extra_path is not None:
+            entries.insert(0, str(extra_path))
+        env["PATH"] = os.pathsep.join(entries)
+        return env
+
+    def run_installed(
+        package_root: Path, cwd: Path, *args: str, env: dict[str, str] | None = None
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["node", str(package_root / "bin" / "keel.js"), *args],
+            cwd=cwd,
+            env=env if env is not None else clean_env(),
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            check=False,
+        )
+
+    def doctor_openspec_line(result: subprocess.CompletedProcess[str]) -> str:
+        return next(
+            (
+                line
+                for line in result.stdout.splitlines()
+                if line.startswith("openspec:")
+            ),
+            "",
+        )
+
+    with tempfile.TemporaryDirectory(prefix="keel-hoisted-") as raw:
+        root = Path(raw)
+
+        # The layout npm actually produces: Keel unpacked under the consumer's
+        # node_modules with no node_modules of its own, the dependency's bin
+        # hoisted beside it.
+        project = root / "project"
+        package_root = project / "node_modules/@christang/keel"
+        install_keel(package_root)
+        write_openspec_stub(project / "node_modules/.bin", "1.12.0")
+        if (package_root / "node_modules").exists():
+            report(
+                f"{label}: the fixture gave Keel a node_modules of its own, "
+                "which is the one layout the defect does not appear in."
+            )
+            return 1
+
+        proxied = run_installed(package_root, project, "openspec", "--version")
+        if proxied.returncode != 0:
+            report(
+                f"{label}: `keel openspec` failed against the hoisted "
+                f"dependency; exit {proxied.returncode}, stderr "
+                f"{proxied.stderr.strip()!r}."
+            )
+            return 1
+        if "1.12.0" not in proxied.stdout:
+            report(
+                f"{label}: `keel openspec` exited 0 without running the "
+                f"hoisted dependency; stdout {proxied.stdout.strip()!r}."
+            )
+            return 1
+
+        hoisted_doctor = doctor_openspec_line(
+            run_installed(package_root, project, "--doctor")
+        )
+        if hoisted_doctor.startswith("openspec: missing"):
+            report(
+                f"{label}: doctor reported an installed dependency as missing; "
+                f"got {hoisted_doctor!r}."
+            )
+            return 1
+
+        # Nearest wins, so a project pinning its own OpenSpec is honored over
+        # one further up the tree.
+        nested = root / "outer/project"
+        nested_package = nested / "node_modules/@christang/keel"
+        install_keel(nested_package)
+        write_openspec_stub(root / "outer/node_modules/.bin", "9.9.9")
+        write_openspec_stub(nested / "node_modules/.bin", "1.12.0")
+        nearest = run_installed(nested_package, nested, "openspec", "--version")
+        if "1.12.0" not in nearest.stdout:
+            report(
+                f"{label}: the farther OpenSpec won over the nearer one; got "
+                f"{nearest.stdout.strip()!r}."
+            )
+            return 1
+
+        # The one case where advising a reinstall is correct.
+        bare = root / "bare"
+        bare_package = bare / "node_modules/@christang/keel"
+        install_keel(bare_package)
+        absent = doctor_openspec_line(
+            run_installed(bare_package, bare, "--doctor")
+        )
+        if not absent.startswith("openspec: missing"):
+            report(
+                f"{label}: doctor did not report a genuinely absent dependency "
+                f"as missing; got {absent!r}."
+            )
+            return 1
+        if "reinstall" not in absent:
+            report(
+                f"{label}: doctor stopped advising a reinstall in the one case "
+                f"where it is the right advice; got {absent!r}."
+            )
+            return 1
+
+        # Installed and unreachable: the package is where npm puts it, its bin
+        # entry is not. Sending this reader to reinstall is what issue #129
+        # measured, and it is the one action that cannot help.
+        broken = root / "broken"
+        broken_package = broken / "node_modules/@christang/keel"
+        install_keel(broken_package)
+        write_text(
+            broken / "node_modules/@fission-ai/openspec/package.json",
+            '{"name": "@fission-ai/openspec", "version": "1.12.0"}\n',
+        )
+        unreachable = doctor_openspec_line(
+            run_installed(broken_package, broken, "--doctor")
+        )
+        if "reinstall" in unreachable and "will not change this" not in unreachable:
+            report(
+                f"{label}: doctor advised reinstalling for a dependency that "
+                f"is already installed; got {unreachable!r}."
+            )
+            return 1
+        if "installed" not in unreachable:
+            report(
+                f"{label}: doctor did not distinguish an installed but "
+                f"unreachable dependency from an absent one; got "
+                f"{unreachable!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
 def validate_doctor_openspec_honesty_scenario() -> int:
     cli = (ROOT / "bin/keel.js").read_text(encoding="utf-8")
     if "is not on PATH" not in cli:
@@ -26426,6 +26606,215 @@ def validate_evidence_survives_what_did_not_change_scenario() -> int:
     return 0
 
 
+# 5.55.0 built the way out of a blanket "all of it is stale" and signed it
+# nowhere a reader would look: issue #134 grepped the installed package and
+# found `--keep-evidence` only in its own two refusals, so the population told
+# it exists is exactly the population already using it. One use in 67 task
+# capsules, against a median re-verification of 256 s. Every exit that tells an
+# author their evidence is stale now names it — and none of them names which
+# checks it would apply to, because the gate keeps only the previous
+# fingerprint and cannot know.
+def validate_staleness_report_names_its_exception_scenario() -> int:
+    label = "a-staleness-report-names-its-exception"
+    flag = "--keep-evidence"
+
+    def fixture(root: Path, name: str) -> Path:
+        repo = root / name
+        task = strategy_probe_task(
+            strategy="evidence-first",
+            reason="fixture; nothing here can fail first",
+            commands=(
+                "M1: the first check asserts the public behavior",
+                "M2: the second check asserts the public behavior",
+                "M3: the third check asserts the public behavior",
+            ),
+        )
+        # A recorded anchor that is not the compiled one, so every exit fires.
+        task = task.replace(
+            "    - Contract: pending",
+            "    - Contract: keel-task-capsule/v1 sha256:" + "0" * 64,
+        )
+        write_gate_fixture(repo, tasks=task)
+        return repo
+
+    def keel_json(repo: Path, *args) -> dict:
+        result = run_keel(repo, *args)
+        try:
+            return json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return {"status": "unparsed", "problems": [
+                {"code": "unparsed", "message": result.stdout[:300]}
+            ]}
+
+    def message_for(payload: dict, code: str) -> str:
+        for entry in payload.get("problems") or []:
+            if str(entry.get("code", "")) == code:
+                return str(entry.get("message", ""))
+        return ""
+
+    # The suggestion has to carry the flag's own contract, not just its name:
+    # when it applies, and that the claim is the author's to defend.
+    def states_the_condition(text: str) -> bool:
+        return "assertion" in text.lower()
+
+    def sends_the_reason_home(text: str) -> bool:
+        return "Reauthorizations" in text
+
+    def names_a_check(text: str) -> str:
+        return next((m for m in ("M1", "M2", "M3") if m in text), "")
+
+    with tempfile.TemporaryDirectory(prefix="keel-names-exception-") as raw:
+        root = Path(raw)
+
+        # Exit 1 of 3 — `task-start --record` with no declaration. This is the
+        # branch issue #134 names, and the only one whose reader is mid-record.
+        blanket = keel_json(
+            fixture(root, "blanket"), "gate", "task-start", "--change", "demo",
+            "--task", "1.1", "--json", "--no-guard", "--record",
+        )
+        if blanket.get("status") != "pass":
+            report(
+                f"{label}: the re-record fixture did not pass, so no "
+                f"stale-evidence report was produced; {problem_text(blanket)!r}."
+            )
+            return 1
+        warned = " ".join(str(x) for x in (blanket.get("warnings") or []))
+        if flag not in warned:
+            report(
+                f"{label}: the blanket stale-evidence report does not name "
+                f"{flag}, so an author who has not already used it re-verifies "
+                f"everything; {warned!r}."
+            )
+            return 1
+        if not states_the_condition(warned):
+            report(
+                f"{label}: the blanket report names {flag} without saying when "
+                f"it applies — that the check's assertion did not move; "
+                f"{warned!r}."
+            )
+            return 1
+        if not sends_the_reason_home(warned):
+            report(
+                f"{label}: the blanket report names {flag} without saying the "
+                f"reason belongs in Reauthorizations, where it can be "
+                f"disagreed with; {warned!r}."
+            )
+            return 1
+        named = names_a_check(warned)
+        if named:
+            report(
+                f"{label}: the blanket report names {named} while suggesting "
+                f"{flag}. The gate keeps only the previous fingerprint and "
+                f"cannot know which checks are unaffected; {warned!r}."
+            )
+            return 1
+
+        # Exit 2 of 3 — `task-complete`'s contract-drift refusal, which already
+        # prints the command the flag belongs to.
+        completing = fixture(root, "completing")
+        done = keel_json(
+            completing, "gate", "task-complete", "--change", "demo",
+            "--task", "1.1", "--json",
+        )
+        drift = message_for(done, "contract-drift")
+        if not drift:
+            report(
+                f"{label}: the drifted fixture did not produce a "
+                f"contract-drift refusal; {problem_codes(done)!r}."
+            )
+            return 1
+        if "keel gate task-start --record" not in drift:
+            report(
+                f"{label}: the contract-drift refusal stopped naming the "
+                f"reauthorization command, which is what makes the flag "
+                f"belong in it; {drift!r}."
+            )
+            return 1
+        if flag not in drift:
+            report(
+                f"{label}: the contract-drift refusal does not name {flag} "
+                f"even though it names the command that accepts it; {drift!r}."
+            )
+            return 1
+        if not states_the_condition(drift):
+            report(
+                f"{label}: the contract-drift refusal names {flag} without "
+                f"saying when it applies; {drift!r}."
+            )
+            return 1
+        named = names_a_check(drift)
+        if named:
+            report(
+                f"{label}: the contract-drift refusal names {named} while "
+                f"suggesting {flag}; {drift!r}."
+            )
+            return 1
+
+        # Exit 3 of 3 — the context drift hard-stop, which already says to
+        # re-run task-start and record the new anchor.
+        blocked = keel_json(fixture(root, "blocked"), "context", "--json")
+        reasons = " ".join(str(x) for x in (blocked.get("reasons") or []))
+        if blocked.get("status") != "blocked":
+            report(
+                f"{label}: the drifted fixture did not block context, so the "
+                f"drift hard-stop did not fire; {blocked.get('status')!r}."
+            )
+            return 1
+        if "drift" not in reasons.lower():
+            report(
+                f"{label}: context blocked for something other than the "
+                f"contract drift this fixture builds; {reasons!r}."
+            )
+            return 1
+        if flag not in reasons:
+            report(
+                f"{label}: the context drift hard-stop does not name {flag} "
+                f"even though it tells the reader to re-record the anchor; "
+                f"{reasons!r}."
+            )
+            return 1
+        if not states_the_condition(reasons):
+            report(
+                f"{label}: the context drift hard-stop names {flag} without "
+                f"saying when it applies; {reasons!r}."
+            )
+            return 1
+        named = names_a_check(reasons)
+        if named:
+            report(
+                f"{label}: the context drift hard-stop names {named} while "
+                f"suggesting {flag}; {reasons!r}."
+            )
+            return 1
+
+        # The already-narrowed report does not repeat the suggestion. Absence
+        # is also what a broken narrowing produces, so the positive control
+        # runs first: the branch has to be alive before its silence means
+        # anything.
+        narrowed = keel_json(
+            fixture(root, "narrowed"), "gate", "task-start", "--change", "demo",
+            "--task", "1.1", "--json", "--no-guard", "--record",
+            "--keep-evidence", "M1,M3",
+        )
+        narrowed_said = " ".join(str(x) for x in (narrowed.get("warnings") or []))
+        if "declared unaffected" not in narrowed_said:
+            report(
+                f"{label}: the narrowed branch did not report a declaration, "
+                f"so its silence about {flag} proves nothing; "
+                f"{narrowed_said!r}."
+            )
+            return 1
+        if flag in narrowed_said:
+            report(
+                f"{label}: the narrowed report suggests {flag} to a reader who "
+                f"just used it; {narrowed_said!r}."
+            )
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
 # `keel context` exists to answer "what now" and answered with a noun. Issue
 # #112: `Next action: change-close` followed by `keel gate change-close
 # --change x` failing on the argument that stage requires — a wrong attempt
@@ -26839,6 +27228,10 @@ SCENARIOS: tuple = (
     ),
     ("cli", validate_cli_scenario),
     ("doctor-openspec-honesty", validate_doctor_openspec_honesty_scenario),
+    (
+        "the-dependency-resolves-where-npm-put-it",
+        validate_dependency_resolves_where_npm_put_it_scenario,
+    ),
     ("the-marker-version-is-read", validate_marker_version_is_read_scenario),
     ("output-survives-the-pipe", validate_output_survives_the_pipe_scenario),
     ("a-strategy-is-declared", validate_strategy_is_declared_scenario),
@@ -26851,6 +27244,10 @@ SCENARIOS: tuple = (
     ("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),
     ("evidence-survives-what-did-not-change", validate_evidence_survives_what_did_not_change_scenario),
+    (
+        "a-staleness-report-names-its-exception",
+        validate_staleness_report_names_its_exception_scenario,
+    ),
     ("the-next-action-is-a-command", validate_next_action_is_a_command_scenario),
     ("the-overlay-names-the-invocation", validate_overlay_names_the_invocation_scenario),
     (

package/src/core/context.js

@@ -129,7 +129,10 @@ function driftSearchSet(contract) {
     `${where} Evidence, Review, and the task checkbox are not covered — `
     + "editing them does not move it. Reauthorize by re-running "
     + "`keel gate task-start` and recording the new anchor, after confirming "
-    + "the change to the authority above was intended."
+    + "the change to the authority above was intended. If a check's assertion "
+    + "did not move, add `--keep-evidence <check>` to that re-record; Keel "
+    + "records that claim and does not verify it, so state the reason in "
+    + "Reauthorizations."
   );
 }
 

package/src/core/gates.js

@@ -147,7 +147,10 @@ function contractDriftProblem(recorded, contract) {
       + "implemented under is not the authority it is being judged against. "
       + "Reauthorize with `keel gate task-start --record`, which rewrites the "
       + "anchor in place; execution evidence produced under the previous "
-      + "contract is stale and has to be cleared or re-verified first."
+      + "contract is stale and has to be cleared or re-verified first. If a "
+      + "check's assertion did not move, add `--keep-evidence <check>` to that "
+      + "re-record; Keel records that claim and does not verify it, so state "
+      + "the reason in Reauthorizations."
   );
 }
 
@@ -434,7 +437,11 @@ function taskStart(repo, options) {
               + "previous fingerprint and cannot compare a check's former text "
               + "to its current one. State the reason in Reauthorizations."
             : "Execution evidence produced under the previous contract is "
-              + "stale; clear or re-verify it before completing this task.")
+              + "stale; clear or re-verify it before completing this task. "
+              + "If a check's assertion did not move, re-record with "
+              + "`--keep-evidence <check>` to say so; Keel records that claim "
+              + "and does not verify it, so state the reason in "
+              + "Reauthorizations.")
       );
     }
   }