@christang/keel 5.76.0 → 5.77.0

package/assets/bootstrap/AGENTS.md

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

@@ -755,6 +755,42 @@ function openspecReportedVersion(command) {
   return match ? match[0] : null;
 }
 
+// The OpenSpec that wrote this repository's surfaces: the highest
+// `generatedBy` stamp among its OpenSpec skills (#168). Every target's root is
+// read, including `.agents/skills`, where OpenSpec 1.13 writes Codex's.
+const OPENSPEC_SURFACE_ROOTS = [
+  path.join(".claude", "skills"),
+  path.join(".codex", "skills"),
+  path.join(".agents", "skills"),
+  path.join(".opencode", "skills"),
+];
+
+function surfaceGeneratorVersion(repo) {
+  let newest = null;
+  for (const root of OPENSPEC_SURFACE_ROOTS) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(path.join(repo, root));
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.startsWith("openspec-")) continue;
+      let text;
+      try {
+        text = fs.readFileSync(path.join(repo, root, entry, "SKILL.md"), "utf8");
+      } catch {
+        continue;
+      }
+      const match = text.match(/generatedBy:\s*"?(\d+\.\d+\.\d+)/);
+      if (match && (!newest || compareVersions(match[1], newest) > 0)) {
+        newest = match[1];
+      }
+    }
+  }
+  return newest;
+}
+
 // What the project declares about Keel plugin auto-update (#164). Claude reads
 // it first from `autoUpdate` on the marketplace's `extraKnownMarketplaces`
 // entry, and `keel --install --target claude` writes it. The host reports no
@@ -774,6 +810,30 @@ function pluginAutoUpdateDeclaration(repo) {
     entry = undefined;
   }
   if (entry && entry.autoUpdate === true) {
+    // A declaration in a file Git does not track exists in this checkout only:
+    // every other clone of the project starts with auto-update off (#168).
+    const inWorkTree = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd: repo,
+      encoding: "utf8",
+    });
+    const tracked = spawnSync(
+      "git",
+      ["ls-files", "--error-unmatch", ".claude/settings.json"],
+      { cwd: repo, encoding: "utf8" }
+    );
+    if (
+      !inWorkTree.error
+      && inWorkTree.status === 0
+      && String(inWorkTree.stdout).trim() === "true"
+      && tracked.status !== 0
+    ) {
+      return [
+        "warning",
+        ".claude/settings.json declares keel-marketplace autoUpdate: true, "
+          + "but Git does not track the file, so only this checkout declares "
+          + "it; commit it with `git add .claude/settings.json`",
+      ];
+    }
     return [
       "ok",
       `.claude/settings.json declares keel-marketplace autoUpdate: true; ${observation}`,
@@ -1066,7 +1126,25 @@ function runProjectInit(options) {
     fs.mkdirSync(repo, { recursive: true });
   }
 
-  const openspecTools = openspecToolsForTarget(options.target);
+  // Never downgrade (#168): surfaces a newer OpenSpec wrote keep their
+  // content. The protocol and Keel's overlays still move; only OpenSpec's own
+  // `--force` rewrite is skipped, and the reason is printed.
+  const surfaces = surfaceGeneratorVersion(repo);
+  const resolvedCommand = findOpenSpecCommand();
+  const resolved = resolvedCommand ? openspecReportedVersion(resolvedCommand) : null;
+  const keepSurfaces = Boolean(
+    surfaces && resolved && compareVersions(surfaces, resolved) > 0
+  );
+  if (keepSurfaces) {
+    process.stdout.write(
+      `keel: OpenSpec surfaces were written by OpenSpec ${surfaces}, newer `
+        + `than the ${resolved} Keel runs; skipped \`openspec init --force\` `
+        + "and `openspec update --force`, which would downgrade them (#168). "
+        + "The protocol and Keel's overlays are still refreshed.\n"
+    );
+  }
+
+  const openspecTools = keepSurfaces ? null : openspecToolsForTarget(options.target);
   if (openspecTools) {
     const initStatus = runOpenSpec(
       ["init", "--tools", openspecTools, "--force"],
@@ -1088,6 +1166,8 @@ function runProjectInit(options) {
     if (updateStatus !== 0) {
       return updateStatus;
     }
+  }
+  if (openspecTools || keepSurfaces) {
     return refreshOpenSpecSurfaceOverlay(repo, options.target, {
       dryRun: options.dryRun,
     }).status;
@@ -1164,8 +1244,9 @@ function printProtocolVersionDrift(repo, target) {
     "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"
+        + `behind its install; run keel --install --target ${target} to bring `
+        + "the protocol forward; it leaves OpenSpec's surfaces as they are "
+        + "(#168)"
       : `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"
@@ -1752,6 +1833,22 @@ function runDoctor(options) {
     );
   }
 
+  const surfaces = surfaceGeneratorVersion(repo);
+  const running = openspec ? openspecReportedVersion(openspec) : null;
+  if (surfaces && running) {
+    const newer = compareVersions(surfaces, running) > 0;
+    printDoctorLine(
+      "OpenSpec surfaces",
+      newer ? "warning" : "ok",
+      newer
+        ? `written by OpenSpec ${surfaces}, newer than the OpenSpec Keel runs `
+          + `(${running}); keel --init leaves them unrewritten rather than `
+          + `downgrading them, and keel --install --target ${options.target} `
+          + "refreshes the protocol without touching them"
+        : `written by OpenSpec ${surfaces}; Keel runs ${running}`
+    );
+  }
+
   printProtocolVersionDrift(repo, options.target);
 
   process.stdout.write("\nProject status:\n");

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@christang/keel",
-  "version": "5.76.0",
+  "version": "5.77.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@christang/keel",
-      "version": "5.76.0",
+      "version": "5.77.0",
       "license": "MIT",
       "dependencies": {
         "@fission-ai/openspec": "^1.4.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.76.0",
+  "version": "5.77.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.76.0",
+  "version": "5.77.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.76.0",
+  "version": "5.77.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

@@ -38,8 +38,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.76.0"
-PROTOCOL_VERSION = "5.76.0"
+PACKAGE_VERSION = "5.77.0"
+PROTOCOL_VERSION = "5.77.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
@@ -16337,6 +16337,114 @@ def validate_context_names_the_protocol_refresh_scenario() -> int:
     return 0
 
 
+# Issue #168: 5.74.0's shrinkwrap pinned OpenSpec 1.6.0 for every install, and
+# `keel --init` ran `openspec update --force` over surfaces 1.13.2 had written,
+# deleting ~1000 lines in a consumer while doctor said `openspec: ok`.
+DOWNGRADE_LABEL = "init-never-downgrades-openspec"
+DOWNGRADE_SENTINEL = "keel-downgrade-sentinel: this line exists only in the planted surface"
+
+
+def _restamp_surfaces(repo: Path, version: str) -> Path:
+    """Stamp every OpenSpec skill `generatedBy: version` and plant a sentinel."""
+    skills = sorted((repo / ".claude/skills").glob("openspec-*/SKILL.md"))
+    for skill in skills:
+        text = skill.read_text(encoding="utf-8")
+        skill.write_text(
+            re.sub(r'generatedBy: "[^"]*"', f'generatedBy: "{version}"', text),
+            encoding="utf-8",
+        )
+    target = repo / ".claude/skills/openspec-propose/SKILL.md"
+    head, sep, body = target.read_text(encoding="utf-8").partition("\n---\n")
+    target.write_text(head + sep + DOWNGRADE_SENTINEL + "\n" + body, encoding="utf-8")
+    return target
+
+
+def _downgrade_m1(tmp: Path) -> str | None:
+    repo = tmp / "newer"
+    repo.mkdir()
+    run_keel(repo, "--init", "--target", "claude")
+    planted = _restamp_surfaces(repo, "99.0.0")
+    again = run_keel(repo, "--init", "--target", "claude")
+    output = (again.stdout or "") + (again.stderr or "")
+    if DOWNGRADE_SENTINEL not in planted.read_text(encoding="utf-8"):
+        return (
+            "M1 keel --init rewrote OpenSpec surfaces written by a newer OpenSpec "
+            "(99.0.0): the planted sentinel is gone."
+        )
+    if "99.0.0" not in output or "skip" not in output.lower():
+        return (
+            "M1 keel --init kept the surfaces but did not say it skipped the rewrite "
+            f"of OpenSpec surfaces written by a newer OpenSpec: {output[-600:]!r}"
+        )
+    return None
+
+
+def _downgrade_m2(tmp: Path) -> str | None:
+    repo = tmp / "doctor-newer"
+    repo.mkdir()
+    run_keel(repo, "--init", "--target", "claude")
+    _restamp_surfaces(repo, "99.0.0")
+    running = run_keel(repo, "openspec", "--version").stdout.strip()
+    doctor = run_keel(repo, "--doctor").stdout or ""
+    lines = [l for l in doctor.splitlines() if l.startswith("OpenSpec surfaces:")]
+    if len(lines) != 1 or not lines[0].startswith("OpenSpec surfaces: warning"):
+        return f"M2 doctor printed no OpenSpec surfaces warning for 99.0.0 surfaces: {lines!r}"
+    for needle in ("99.0.0", running, "keel --install --target claude"):
+        if needle not in lines[0]:
+            return f"M2 doctor printed no OpenSpec surfaces warning carrying {needle!r}: {lines[0]!r}"
+    return None
+
+
+def _downgrade_m3(tmp: Path) -> str | None:
+    repo = tmp / "older"
+    repo.mkdir()
+    run_keel(repo, "--init", "--target", "claude")
+    planted = _restamp_surfaces(repo, "1.0.0")
+    run_keel(repo, "--init", "--target", "claude")
+    if DOWNGRADE_SENTINEL in planted.read_text(encoding="utf-8"):
+        return (
+            "M3 keel --init skipped the OpenSpec refresh for surfaces older than "
+            "the OpenSpec it runs (1.0.0); only newer surfaces are protected."
+        )
+    return None
+
+
+def _downgrade_m4(tmp: Path) -> str | None:
+    repo = tmp / "git"
+    repo.mkdir()
+    git = ["git", "-c", "user.name=keel", "-c", "user.email=keel@example.invalid"]
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+    run_keel(repo, "--install", "--target", "claude")
+
+    def line() -> str:
+        doctor = run_keel(repo, "--doctor", "--target", "claude").stdout or ""
+        return next((l for l in doctor.splitlines() if l.startswith("plugin auto-update:")), "")
+
+    untracked = line()
+    if not untracked.startswith("plugin auto-update: warning") or "git add .claude/settings.json" not in untracked:
+        return f"M4 doctor did not say .claude/settings.json is untracked: {untracked!r}"
+    subprocess.run([*git, "add", ".claude/settings.json"], cwd=repo, check=True)
+    subprocess.run([*git, "commit", "-q", "-m", "declare"], cwd=repo, check=True)
+    tracked = line()
+    if not tracked.startswith("plugin auto-update: ok"):
+        return f"M4 doctor did not say .claude/settings.json is untracked only while it was: {tracked!r}"
+    return None
+
+
+def validate_init_never_downgrades_openspec_scenario() -> int:
+    with tempfile.TemporaryDirectory(
+        prefix="keel-downgrade-", ignore_cleanup_errors=True
+    ) as raw:
+        tmp = Path(raw)
+        for check in (_downgrade_m1, _downgrade_m2, _downgrade_m3, _downgrade_m4):
+            problem = check(tmp)
+            if problem:
+                report(f"{DOWNGRADE_LABEL} {problem}")
+                return 1
+    report(f"{DOWNGRADE_LABEL} scenario passed.")
+    return 0
+
+
 def validate_native_plugin_marketplaces_scenario() -> int:
     codex = shutil.which("codex")
     claude = claude_cli()
@@ -26150,7 +26258,15 @@ def validate_marker_version_is_read_scenario() -> int:
                 f"older protocol did not warn; got {line!r}."
             )
             return 1
-        for needed in ("5.14.0", PACKAGE_VERSION, "keel --init"):
+        # #168: `keel --init` also runs OpenSpec's `--force` rewrite, which is
+        # what downgraded a consumer's surfaces. The protocol refresh is install.
+        if "keel --init" in line:
+            report(
+                "the-marker-version-is-read scenario: a repository behind its "
+                f"install was told to run keel --init; got {line!r}."
+            )
+            return 1
+        for needed in ("5.14.0", PACKAGE_VERSION, "keel --install"):
             if needed not in line:
                 report(
                     "the-marker-version-is-read scenario: the behind-repository "
@@ -31314,6 +31430,7 @@ SCENARIOS: tuple = (
     ("plugin-runs-its-own-cli", validate_plugin_runs_its_own_cli_scenario),
     ("init-declares-plugin-auto-update", validate_init_declares_plugin_auto_update_scenario),
     ("context-names-the-protocol-refresh", validate_context_names_the_protocol_refresh_scenario),
+    ("init-never-downgrades-openspec", validate_init_never_downgrades_openspec_scenario),
     ("native-plugin-marketplaces", validate_native_plugin_marketplaces_scenario),
     ("native-plugin-install-matrix", validate_native_plugin_install_matrix_scenario),
     ("native-goal-projection", validate_native_goal_projection_scenario),