@christang/keel 5.2.2 → 5.2.4

package/assets/bootstrap/AGENTS.md

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

@@ -15,6 +15,7 @@ const {
   runGate,
 } = require("../src/core/gates");
 const {
+  isKeelSourceRepo,
   probeCapabilities,
   renderCapabilities,
 } = require("../src/core/capabilities");
@@ -1202,7 +1203,12 @@ function printTargetSurface(repo, target) {
         sourceDetail = `plugin source unreadable at ${manifestRelative}`;
       }
     }
-    printDoctorLine("native plugin source", sourceStatus, sourceDetail);
+    // Development-only check: plugins/keel/ exists only in Keel's own source
+    // repository, so in a consuming project it is permanently `missing` and
+    // there is nothing the author can do about it.
+    if (isKeelSourceRepo(repo)) {
+      printDoctorLine("native plugin source", sourceStatus, sourceDetail);
+    }
     printDoctorLine(
       "native plugin runtime",
       "manual",
@@ -1229,7 +1235,12 @@ function printTargetSurface(repo, target) {
   printDoctorLine(
     "Keel behavioral skills",
     "plugin",
-    "keel-* skills are delivered by the installed Keel plugin (see native plugin status above); install the plugin if it is missing"
+    isKeelSourceRepo(repo)
+      ? "keel-* skills are delivered by the installed Keel plugin (see native "
+        + "plugin status above); install the plugin if it is missing"
+      : "keel-* skills are delivered by the installed Keel plugin; verify it "
+        + "with the runtime's own plugin listing, since Keel cannot observe "
+        + "installation from this repository"
   );
 
   const commands = commandSurfaceForTarget(target, repo);
@@ -1333,10 +1344,28 @@ function runDoctor(options) {
   printTargetSurface(repo, options.target);
   printLensSurface(repo, options.target);
   printFastPrePushSurface(repo);
+  printSourceRepoCliResolution(repo);
 
   return checkStatus;
 }
 
+// Only meaningful in Keel's own repository: a bare `keel` resolves to the
+// installed package, so gate commands verify the released CLI rather than the
+// working tree. The failure mode is a silently stale result, not an error, so
+// it is worth stating rather than leaving to be discovered.
+function printSourceRepoCliResolution(repo) {
+  if (!isKeelSourceRepo(repo)) return;
+  process.stdout.write("\nKeel source repository:\n");
+  printDoctorLine(
+    "gate CLI resolution",
+    "advisory",
+    "a bare `keel` runs the installed package, so gate results will not "
+      + "reflect uncommitted changes to gate, contract, or capability code; "
+      + "run `node bin/keel.js gate <stage> . --change <c> --task <t>` "
+      + "instead — the repository argument is required"
+  );
+}
+
 function readFastCheck(repo) {
   const configPath = path.join(repo, "keel", "config.yaml");
   if (!fs.existsSync(configPath)) return null;

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.2.2",
+  "version": "5.2.4",
   "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.2.2",
+  "version": "5.2.4",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/scripts/install_to_repo.py

@@ -33,6 +33,14 @@ KEEL_CONFIG_TEMPLATE = (
     "# Example:\n"
     "#   fast_check: npm test -- --fast\n"
 )
+KEEL_GITIGNORE_PATH = KEEL_ROOT / ".gitignore"
+KEEL_GITIGNORE_TEMPLATE = (
+    "# Keel local state. keel/ otherwise holds project content that belongs in\n"
+    "# version control (config.yaml, CHANGELOG.md, archive/); the write-guard\n"
+    "# manifest is per-clone session state that a gate run writes and\n"
+    "# `keel guard clear` removes.\n"
+    "guard.json\n"
+)
 GITHOOKS_DIR = ".githooks"
 PRE_PUSH_PATH = Path(GITHOOKS_DIR) / "pre-push"
 OPENSPEC_ROOT = Path("openspec")
@@ -222,6 +230,14 @@ def keel_config_action() -> InstallAction:
     )
 
 
+def keel_gitignore_action() -> InstallAction:
+    return InstallAction(
+        relative_path=KEEL_GITIGNORE_PATH,
+        content=KEEL_GITIGNORE_TEMPLATE,
+        strategy="keel-config-scaffold",
+    )
+
+
 def read_fast_check(repo: Path) -> str | None:
     """Return the project's declared fast inner-loop command, or None.
 
@@ -432,11 +448,38 @@ def unmanaged_keel_content_warning(repo: Path, relative_path: str) -> bool:
     return False
 
 
+KEEL_PACKAGE_NAME = "@christang/keel"
+
+
+def is_keel_source_repo(repo: Path) -> bool:
+    """Whether `repo` is Keel's own source repository.
+
+    Mirrors `isKeelSourceRepo` in src/core/capabilities.js. Both signals are
+    required so a project that merely vendors a plugins/keel/ directory is not
+    misclassified as Keel's own source.
+    """
+    try:
+        manifest = json.loads((repo / "package.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if manifest.get("name") != KEEL_PACKAGE_NAME:
+        return False
+    return (repo / "plugins" / "keel").is_dir()
+
+
 def collect_actions(repo: Path, target: str) -> list[InstallAction]:
     actions: list[InstallAction] = []
     targets = target_set(target)
 
-    if not unmanaged_keel_content_warning(repo, "AGENTS.md"):
+    # Keel's own AGENTS.md carries the full protocol that the validation suite
+    # asserts on; the packaged bootstrap is the shorter consumer-facing text.
+    # Writing it here replaces the protocol and turns the repository red.
+    if is_keel_source_repo(repo):
+        print(
+            "skip AGENTS.md: Keel source repository, whose AGENTS.md carries "
+            "the full protocol; the consumer bootstrap is not written here"
+        )
+    elif not unmanaged_keel_content_warning(repo, "AGENTS.md"):
         actions.append(
             managed_file_action("AGENTS.md", PACKAGE_ROOT / BOOTSTRAP_ASSET)
         )
@@ -445,6 +488,7 @@ def collect_actions(repo: Path, target: str) -> list[InstallAction]:
 
     actions.append(openspec_config_action())
     actions.append(keel_config_action())
+    actions.append(keel_gitignore_action())
     actions.extend(openspec_schema_actions())
     return actions