@christang/keel 5.3.4 → 5.3.6

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.3.4 -->
+<!-- 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.4",
+  "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.4",
+  "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.4",
+  "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,10 +37,13 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.3.4"
-PROTOCOL_VERSION = "5.3.4"
+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
+# signals is_keel_source_repo reads.
+KEEL_PACKAGE_NAME = "@christang/keel"
 OPENSPEC_CONFIG_PATH = Path("openspec/config.yaml")
 OPENSPEC_SCHEMA_ROOT = Path("openspec/schemas") / OPENSPEC_SCHEMA_NAME
 OPENSPEC_SURFACE_OVERLAY_START = (
@@ -417,6 +420,17 @@ def validate_npm_package(errors: list[str]) -> None:
 # Path expressions rooted at a tree the retirement check above requires to be
 # absent. `src/core` and `src/skills` are live, so only the retired `src`
 # children are listed.
+# Keel subcommands that write. A scenario may point read-only ones at the
+# repository root; these need a fixture.
+MUTATING_KEEL_COMMANDS = (
+    "--install",
+    "--init",
+    "--uninstall",
+    "--clear",
+    "--update",
+    "--with-git-hooks",
+)
+
 RETIRED_PATH_EXPRESSIONS = (
     r'ROOT\s*/\s*"dist"',
     r'ROOT\s*/\s*"src"\s*/\s*"assets"',
@@ -458,6 +472,29 @@ def validate_paths(errors: list[str]) -> None:
                 f"retired custom distribution path must be removed: {retired}"
             )
 
+    validator_source = (ROOT / "scripts" / "validate_plugin.py").read_text(
+        encoding="utf-8"
+    )
+
+    # A scenario that writes to the repository it validates can satisfy the very
+    # condition another check asserts, and a check whose input its own run
+    # produces cannot fail. Reads against ROOT are fine and common; writes are
+    # not. Keyed on the mutating subcommand rather than on ROOT itself, so
+    # `--version`, `--doctor`, and the gates stay legal.
+    for line_number, line in enumerate(validator_source.splitlines(), start=1):
+        invocation = re.search(r"run_(?:keel|install)\(\s*ROOT\s*,([^)]*)", line)
+        if not invocation:
+            continue
+        if any(
+            re.search(rf'"{command}"', invocation.group(1))
+            for command in MUTATING_KEEL_COMMANDS
+        ):
+            errors.append(
+                "a scenario must not run a mutating Keel command against the "
+                "repository it validates; build a fixture instead: "
+                f"scripts/validate_plugin.py:{line_number}: {line.strip()}"
+            )
+
     # Every Keel marker that carries a version is a shipped claim about which
     # version this is. Derive the set from the markers that exist rather than a
     # fixed list, because a fixed list is the next thing to fall behind — which
@@ -484,9 +521,6 @@ def validate_paths(errors: list[str]) -> None:
     # directory yields no error, so the check reports success forever. Naming a
     # retired tree in a string literal is fine — that is how the checks above
     # state what must not exist; building a Path into one is not.
-    validator_source = (ROOT / "scripts" / "validate_plugin.py").read_text(
-        encoding="utf-8"
-    )
     for line_number, line in enumerate(validator_source.splitlines(), start=1):
         if any(re.search(pattern, line) for pattern in RETIRED_PATH_EXPRESSIONS):
             errors.append(
@@ -3649,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"
 
@@ -5004,29 +5120,56 @@ def validate_source_repo_bootstrap_skip_scenario() -> int:
         found = managed.search(path.read_text(encoding="utf-8"))
         return found.group(0) if found else ""
 
-    own_agents = ROOT / "AGENTS.md"
-    before = block(own_agents)
-    if not before:
+    # `is_keel_source_repo` reads exactly two signals — the package name and a
+    # plugins/keel directory — so a fixture carrying both exercises the same
+    # branch. Running this against the real repository used to work and used to
+    # rewrite the .claude/ overlay markers as a side effect, which is how the
+    # marker check ended up green on that side for the wrong reason.
+    if not (ROOT / "AGENTS.md").is_file() or not block(ROOT / "AGENTS.md"):
         report("source-repo-bootstrap-skip: Keel's AGENTS.md has no managed block.")
         return 1
-    result = run_keel(ROOT, "--install", "--target", "claude")
-    if result.returncode != 0:
-        report("source-repo-bootstrap-skip: keel --install failed in Keel's repo.")
-        report((result.stderr or result.stdout).strip())
-        return 1
-    if block(own_agents) != before:
-        report(
-            "source-repo-bootstrap-skip: keel --install rewrote Keel's own "
-            "AGENTS.md managed block."
-        )
-        return 1
-    if "skip AGENTS.md" not in (result.stdout or ""):
-        report(
-            "source-repo-bootstrap-skip: the skip was silent; it must be "
-            "reported explicitly."
-        )
-        report((result.stdout or "").strip())
-        return 1
+
+    with tempfile.TemporaryDirectory(prefix="keel-source-repo-") as raw:
+        fixture = Path(raw) / "keel"
+        write_text(fixture / "package.json", json.dumps({"name": KEEL_PACKAGE_NAME}))
+        write_text(fixture / "plugins/keel/.keep", "")
+        own_agents = fixture / "AGENTS.md"
+        write_text(own_agents, (ROOT / "AGENTS.md").read_text(encoding="utf-8"))
+        before_tree = snapshot_files(fixture)
+        before = block(own_agents)
+
+        result = run_keel(fixture, "--install", "--target", "claude")
+        if result.returncode != 0:
+            report("source-repo-bootstrap-skip: keel --install failed in Keel's repo.")
+            report((result.stderr or result.stdout).strip())
+            return 1
+        if block(own_agents) != before:
+            report(
+                "source-repo-bootstrap-skip: keel --install rewrote Keel's own "
+                "AGENTS.md managed block."
+            )
+            return 1
+        if "skip AGENTS.md" not in (result.stdout or ""):
+            report(
+                "source-repo-bootstrap-skip: the skip was silent; it must be "
+                "reported explicitly."
+            )
+            report((result.stdout or "").strip())
+            return 1
+        # The original defect was the missing assertion, not only the wrong
+        # repository: name what the install must not have rewritten.
+        rewritten = [
+            name
+            for name, text in before_tree.items()
+            if (fixture / name).is_file()
+            and (fixture / name).read_text(encoding="utf-8") != text
+        ]
+        if rewritten:
+            report(
+                "source-repo-bootstrap-skip: keel --install rewrote files it "
+                "did not announce: " + ", ".join(sorted(rewritten))
+            )
+            return 1
     # A consuming project must still receive the bootstrap.
     with tempfile.TemporaryDirectory(prefix="keel-bootstrap-consumer-") as raw:
         consumer = Path(raw)
@@ -13012,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",