@christang/keel 5.3.5 → 5.3.6

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.3.5 -->
+<!-- keel:start version=5.3.6 -->
 ## 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

@@ -1082,15 +1082,10 @@ function refreshOpenSpecSurfaceOverlay(repo, target, options = {}) {
     missing: 0,
   };
 
-  if (options.dryRun) {
-    for (const surface of surfaces) {
-      process.stdout.write(
-        `keel: would refresh OpenSpec ${surface.action} overlay in ${surface.path}\n`
-      );
-    }
-    return { status: 0, ...counts };
-  }
-
+  // A dry run and the real run classify each surface the same way, from the
+  // same read-and-compare, so the plan cannot drift from the outcome. The dry
+  // run used to list every surface without reading one, which over-reported as
+  // badly as `--check` under-reported by never reaching this step at all.
   for (const surface of surfaces) {
     if (!fs.existsSync(surface.path)) {
       counts.missing += 1;
@@ -1102,14 +1097,20 @@ function refreshOpenSpecSurfaceOverlay(repo, target, options = {}) {
       counts.current += 1;
       continue;
     }
-    fs.writeFileSync(surface.path, next, "utf8");
     counts.refreshed += 1;
+    if (options.dryRun) {
+      process.stdout.write(
+        `keel: would refresh OpenSpec ${surface.action} overlay in ${surface.path}\n`
+      );
+      continue;
+    }
+    fs.writeFileSync(surface.path, next, "utf8");
   }
 
   if (counts.refreshed > 0 || counts.current > 0) {
     process.stdout.write(
-      "keel: OpenSpec apply/archive overlay "
-        + `refreshed=${counts.refreshed} current=${counts.current} `
+      `keel: ${options.dryRun ? "would refresh " : ""}OpenSpec apply/archive `
+        + `overlay refreshed=${counts.refreshed} current=${counts.current} `
         + `missing=${counts.missing}\n`
     );
   }
@@ -1758,7 +1759,20 @@ function runAction(options) {
       return checkStatus;
     }
     process.stdout.write("\nDry-run install plan:\n");
-    return runPython(INSTALL_SCRIPT, installerArgs({ ...options, dryRun: true }));
+    const planStatus = runPython(
+      INSTALL_SCRIPT,
+      installerArgs({ ...options, dryRun: true })
+    );
+    if (planStatus !== 0) {
+      return planStatus;
+    }
+    // The overlay refresh is a Node-side step the installer's plan never sees,
+    // so without this `--check` reports an empty plan for a run that writes.
+    return refreshOpenSpecSurfaceOverlay(
+      path.resolve(options.repo || process.cwd()),
+      options.target,
+      { dryRun: true }
+    ).status;
   }
 
   if (options.action === "doctor") {

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.3.5",
+  "version": "5.3.6",
   "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.3.5",
+  "version": "5.3.6",
   "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.3.5"
-PROTOCOL_VERSION = "5.3.5"
+PACKAGE_VERSION = "5.3.6"
+PROTOCOL_VERSION = "5.3.6"
 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
@@ -3683,6 +3683,88 @@ SCHEMA_COPY_PAIRS = (
 )
 
 
+def validate_dry_run_overlay_accounting_scenario() -> int:
+    label = "dry-run-overlay-accounting"
+
+    # A dry run is relied on, so it is wrong in both directions: naming a write
+    # that will not happen trains the reader to ignore it, and omitting one
+    # breaks the promise the dry run exists to make. `--check` used to omit the
+    # overlay step entirely while `--install --dry-run` claimed every surface.
+    def overlay_lines(text: str) -> list[str]:
+        return [line for line in text.splitlines() if "overlay" in line]
+
+    def counts(text: str) -> str | None:
+        found = re.search(r"refreshed=(\d+) current=(\d+) missing=(\d+)", text)
+        return found.group(0) if found else None
+
+    with tempfile.TemporaryDirectory(prefix="keel-dry-run-overlay-") as raw_tmp:
+        repo = Path(raw_tmp) / "repo"
+        repo.mkdir()
+        # The overlay surfaces are files OpenSpec generates; install merges into
+        # them and skips the ones that are absent. Create them so this scenario
+        # exercises the classification rather than the missing branch.
+        for relative in (
+            ".claude/skills/openspec-propose/SKILL.md",
+            ".claude/skills/openspec-apply-change/SKILL.md",
+            ".claude/skills/openspec-archive-change/SKILL.md",
+            ".claude/commands/opsx/propose.md",
+            ".claude/commands/opsx/apply.md",
+            ".claude/commands/opsx/archive.md",
+        ):
+            write_text(repo / relative, "# OpenSpec surface\n\nGenerated body.\n")
+        if run_keel(repo, "--install", "--target", "claude").returncode != 0:
+            report(f"{label} could not install a fixture repository.")
+            return 1
+
+        # Nothing stale: neither dry run may name a file.
+        check = run_keel(repo, "--check", "--target", "claude")
+        if any("would refresh OpenSpec" in line and ".md" in line
+               for line in overlay_lines(check.stdout)):
+            report(f"{label} named a surface that would not change.")
+            report("\n".join(overlay_lines(check.stdout)))
+            return 1
+
+        # Make exactly one surface stale and require both dry runs to say so.
+        stale = repo / ".claude/skills/openspec-apply-change/SKILL.md"
+        if not stale.is_file():
+            report(f"{label} fixture has no overlay surface to make stale.")
+            return 1
+        original = stale.read_text(encoding="utf-8")
+        stale.write_text(
+            re.sub(r"(keel:openspec-surface-overlay version=)[0-9.]+", r"\g<1>0.0.1",
+                   original, count=1),
+            encoding="utf-8",
+        )
+
+        check = run_keel(repo, "--check", "--target", "claude")
+        dry = run_keel(repo, "--install", "--dry-run", "--target", "claude")
+        named = [line for line in overlay_lines(check.stdout) if ".md" in line]
+        if len(named) != 1 or "openspec-apply-change" not in named[0]:
+            report(f"{label} --check did not name exactly the one stale surface.")
+            report("\n".join(overlay_lines(check.stdout)) or "(no overlay output)")
+            return 1
+        if counts(check.stdout) != counts(dry.stdout):
+            report(f"{label} the two dry-run entry points disagree.")
+            report(f"--check: {counts(check.stdout)}  --install --dry-run: {counts(dry.stdout)}")
+            return 1
+        if "0.0.1" not in stale.read_text(encoding="utf-8"):
+            report(f"{label} a dry run wrote to the surface it was describing.")
+            return 1
+
+        # And the real run reports what the dry run promised.
+        real = run_keel(repo, "--install", "--target", "claude")
+        if counts(real.stdout) != counts(check.stdout):
+            report(f"{label} the real run's counts differ from the plan's.")
+            report(f"plan: {counts(check.stdout)}  real: {counts(real.stdout)}")
+            return 1
+        if "0.0.1" in stale.read_text(encoding="utf-8"):
+            report(f"{label} the real run did not refresh the stale surface.")
+            return 1
+
+    report(f"{label} scenario passed.")
+    return 0
+
+
 def validate_anchor_reverification_bound_scenario() -> int:
     label = "anchor-reverification-bound"
 
@@ -13073,6 +13155,7 @@ SCENARIOS: tuple = (
     ("task-start-invalidation", validate_task_start_invalidation_scenario),
     ("regression-check-tag", validate_regression_check_tag_scenario),
     ("durable-owner-vocabulary", validate_durable_owner_vocabulary_scenario),
+    ("dry-run-overlay-accounting", validate_dry_run_overlay_accounting_scenario),
     ("anchor-reverification-bound", validate_anchor_reverification_bound_scenario),
     (
         "authoring-surface-owner-and-tags",