@christang/keel 5.76.0 → 5.78.0

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.78.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.78.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.78.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.78.0"
+PROTOCOL_VERSION = "5.78.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
@@ -1242,13 +1242,12 @@ def validate_target_surface_scenario() -> int:
             report((codex_init.stderr or codex_init.stdout).strip())
             return 1
         codex_doctor = run_keel(codex_repo, "--doctor", "--target", "codex", env=env)
-        codex_prompt_dir = str(codex_home / "prompts")
         if (
             codex_doctor.returncode != 0
             or "OpenSpec commands: ok" not in codex_doctor.stdout
-            or posix_paths(codex_prompt_dir) not in posix_paths(codex_doctor.stdout)
+            or "OpenSpec 1.13 surfaces Codex's workflows" not in codex_doctor.stdout
             or "OpenSpec action skills: ok" not in codex_doctor.stdout
-            or ".codex/skills" not in posix_paths(codex_doctor.stdout)
+            or ".agents/skills" not in posix_paths(codex_doctor.stdout)
             or "bootstrap: ok" not in codex_doctor.stdout
             or "native plugin runtime: manual" not in codex_doctor.stdout
             or "Target capabilities (codex):" not in codex_doctor.stdout
@@ -1265,16 +1264,15 @@ def validate_target_surface_scenario() -> int:
             report("target-surface scenario Codex init created Claude-only paths.")
             return 1
 
-        for prompt in (codex_home / "prompts").glob("opsx-*.md"):
-            prompt.unlink()
+        # OpenSpec 1.13 writes Codex's workflows as skills only (#169), so the
+        # surface that can go missing is a skill.
+        shutil.rmtree(codex_repo / ".agents/skills/openspec-propose")
         codex_missing = run_keel(codex_repo, "--doctor", "--target", "codex", env=env)
         if (
             codex_missing.returncode != 0
-            or "OpenSpec commands: missing" not in codex_missing.stdout
-            or "keel --init --target codex" not in codex_missing.stdout
-            or "openspec update --force" not in codex_missing.stdout
+            or "OpenSpec action skills: missing" not in codex_missing.stdout
         ):
-            report("target-surface scenario Codex doctor did not report missing prompts.")
+            report("target-surface scenario Codex doctor did not report a missing skill.")
             report((codex_missing.stderr or codex_missing.stdout).strip())
             return 1
 
@@ -2649,15 +2647,11 @@ def openspec_overlay_files(
         }
     if target == "codex":
         assert codex_home is not None
+        # OpenSpec 1.13, which Keel pins, writes Codex's workflows as skills
+        # under `.agents/skills` and no command files (#169).
         return {
-            "apply": [
-                repo / ".codex/skills/openspec-apply-change/SKILL.md",
-                codex_home / "prompts/opsx-apply.md",
-            ],
-            "archive": [
-                repo / ".codex/skills/openspec-archive-change/SKILL.md",
-                codex_home / "prompts/opsx-archive.md",
-            ],
+            "apply": [repo / ".agents/skills/openspec-apply-change/SKILL.md"],
+            "archive": [repo / ".agents/skills/openspec-archive-change/SKILL.md"],
         }
     return {
         "apply": [
@@ -2777,8 +2771,7 @@ def expected_overlay_surfaces(
             surfaces.append(repo / f".claude/commands/opsx/{action}.md")
         elif target == "codex":
             assert codex_home is not None
-            surfaces.append(repo / f".codex/skills/{skill}/SKILL.md")
-            surfaces.append(codex_home / f"prompts/opsx-{action}.md")
+            surfaces.append(repo / f".agents/skills/{skill}/SKILL.md")
         else:
             surfaces.append(repo / f".opencode/skills/{skill}/SKILL.md")
             surfaces.append(repo / f".opencode/commands/opsx-{action}.md")
@@ -3022,7 +3015,7 @@ def validate_sync_surface_overlay_scenario() -> int:
                 ".claude/skills/openspec-sync-specs/SKILL.md",
             ],
             "codex": [
-                ".codex/skills/openspec-sync-specs/SKILL.md",
+                ".agents/skills/openspec-sync-specs/SKILL.md",
             ],
         }
 
@@ -3236,13 +3229,12 @@ def validate_openspec_surface_overlay_scenario() -> int:
         if (
             codex_doctor.returncode != 0
             or "Keel apply/archive/sync overlay: ok" not in codex_doctor.stdout
-            or str(codex_home / "prompts") not in codex_doctor.stdout
         ):
             report("openspec-surface-overlay scenario Codex doctor missed overlay health.")
             report((codex_doctor.stderr or codex_doctor.stdout).strip())
             return 1
 
-        codex_apply_prompt = codex_home / "prompts/opsx-apply.md"
+        codex_apply_prompt = codex_repo / ".agents/skills/openspec-apply-change/SKILL.md"
         original_prompt = codex_apply_prompt.read_text(encoding="utf-8")
         outdated_prompt = re.sub(
             r"<!--\s*keel:openspec-surface-overlay(?:\s+[^>]*)?\s*-->"
@@ -3269,6 +3261,33 @@ def validate_openspec_surface_overlay_scenario() -> int:
             report("openspec-surface-overlay scenario Codex install did not refresh overlay idempotently.")
             return 1
 
+        # M6 — a repository set up under OpenSpec 1.6 keeps its layout: skills
+        # under `.codex/skills` and commands as CODEX_HOME prompts (#169).
+        legacy_repo = tmp / "codex-legacy"
+        legacy_home = tmp / "codex-legacy-home"
+        legacy_env = os.environ.copy()
+        legacy_env["CODEX_HOME"] = str(legacy_home)
+        legacy_surfaces = []
+        for action, skill in OVERLAY_ACTION_SKILLS.items():
+            for surface in (
+                legacy_repo / f".codex/skills/{skill}/SKILL.md",
+                legacy_home / f"prompts/opsx-{action}.md",
+            ):
+                write_text(surface, f"---\nname: {skill}\n---\n\n# {action}\n")
+                legacy_surfaces.append(surface)
+        run_keel(legacy_repo, "--install", "--target", "codex", env=legacy_env)
+        lost = [
+            str(surface)
+            for surface in legacy_surfaces
+            if surface.read_text(encoding="utf-8").count(OPENSPEC_SURFACE_OVERLAY_START) != 1
+        ]
+        if lost:
+            report(
+                "openspec-surface-overlay scenario 1.6-layout Codex surfaces lost "
+                f"their overlay: {lost!r}"
+            )
+            return 1
+
         opencode_repo = tmp / "opencode"
         opencode_repo.mkdir()
         opencode_init = run_keel(opencode_repo, "--init", "--target", "opencode")
@@ -16337,6 +16356,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()
@@ -16509,8 +16636,7 @@ def validate_authoring_alignment_overlay_scenario() -> int:
             report((codex_init.stderr or codex_init.stdout).strip())
             return 1
         codex_surfaces = (
-            codex_repo / ".codex/skills/openspec-propose/SKILL.md",
-            codex_home / "prompts/opsx-propose.md",
+            codex_repo / ".agents/skills/openspec-propose/SKILL.md",
         )
         for surface in codex_surfaces:
             content = surface.read_text(encoding="utf-8")
@@ -16540,7 +16666,7 @@ def validate_authoring_alignment_overlay_scenario() -> int:
                 return 1
 
         apply_skill = (
-            codex_repo / ".codex/skills/openspec-apply-change/SKILL.md"
+            codex_repo / ".agents/skills/openspec-apply-change/SKILL.md"
         ).read_text(encoding="utf-8")
         if (
             "rerun `keel-align-expectations`" not in apply_skill
@@ -26150,7 +26276,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 +31448,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),

package/src/core/context.js

@@ -741,9 +741,10 @@ function stampedProtocol(repo) {
 
 // The target the installer left behind. `CLAUDE.md` carries the managed
 // import only on the Claude target, and only OpenCode writes project commands
-// under `.opencode/`. A Codex install writes neither — its OpenSpec commands
-// are global prompts under CODEX_HOME — so a managed `AGENTS.md` with neither
-// surface beside it is what a Codex install leaves.
+// under `.opencode/`. A Codex install writes neither: OpenSpec 1.13 puts its
+// skills under `.agents/skills`, and 1.6 put its commands in CODEX_HOME, so a
+// managed `AGENTS.md` with neither surface beside it is what a Codex install
+// leaves.
 function installedTarget(repo) {
   try {
     if (/<!--\s*keel:start/.test(fs.readFileSync(path.join(repo, "CLAUDE.md"), "utf8"))) {