@christang/keel 5.76.0 → 5.78.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.76.0 -->
+<!-- keel:start version=5.78.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"
@@ -1196,9 +1277,34 @@ function skillRootForTarget(target) {
   return path.join(".opencode", "skills");
 }
 
-function openspecSkillRootForTarget(target) {
+// Which OpenSpec layout a Codex repository carries (#169). OpenSpec 1.6 wrote
+// Codex's skills under `.codex/skills` and its commands as prompts in
+// CODEX_HOME; 1.13, which Keel pins, writes skills under `.agents/skills` and
+// no command files. A repository set up under 1.6 keeps its layout, and every
+// other one — a fresh repository included — gets the one the pin writes.
+function codexOpenSpecLayout(repo) {
+  const holdsOpenSpec = (root) => {
+    try {
+      return fs
+        .readdirSync(path.join(repo, root))
+        .some((entry) => entry.startsWith("openspec-"));
+    } catch {
+      return false;
+    }
+  };
+  return holdsOpenSpec(path.join(".codex", "skills"))
+    && !holdsOpenSpec(path.join(".agents", "skills"))
+    ? "legacy"
+    : "agents";
+}
+
+function openspecSkillRootForTarget(target, repo) {
   if (target === "claude") return path.join(".claude", "skills");
-  if (target === "codex") return path.join(".codex", "skills");
+  if (target === "codex") {
+    return codexOpenSpecLayout(repo) === "legacy"
+      ? path.join(".codex", "skills")
+      : path.join(".agents", "skills");
+  }
   return path.join(".opencode", "skills");
 }
 
@@ -1213,6 +1319,16 @@ function commandSurfaceForTarget(target, repo) {
       remediation: "run keel --init --target claude or openspec update --force",
     };
   }
+  if (target === "codex" && codexOpenSpecLayout(repo) === "agents") {
+    // OpenSpec 1.13 surfaces Codex's workflows as the skills counted on the
+    // line above and writes no command file, so there is nothing to count here.
+    return {
+      location: path.join(".agents", "skills"),
+      paths: [],
+      remediation: "run keel --init --target codex or openspec update --force",
+      skillsOnly: true,
+    };
+  }
   if (target === "codex") {
     const home = codexHome();
     const location = path.join(home, "prompts");
@@ -1239,13 +1355,15 @@ function commandPathForAction(target, repo, action) {
     return path.join(repo, ".claude", "commands", "opsx", `${action}.md`);
   }
   if (target === "codex") {
-    return path.join(codexHome(), "prompts", `opsx-${action}.md`);
+    return codexOpenSpecLayout(repo) === "legacy"
+      ? path.join(codexHome(), "prompts", `opsx-${action}.md`)
+      : null;
   }
   return path.join(repo, ".opencode", "commands", `opsx-${action}.md`);
 }
 
 function openspecOverlaySurfacesForTarget(target, repo) {
-  const skillRoot = openspecSkillRootForTarget(target);
+  const skillRoot = openspecSkillRootForTarget(target, repo);
   return OPENSPEC_OVERLAY_ACTIONS.flatMap((action) => {
     if (action === "propose" && target === "opencode") {
       return [];
@@ -1265,7 +1383,7 @@ function openspecOverlaySurfacesForTarget(target, repo) {
         action,
         path: commandPathForAction(target, repo, action),
       },
-    ];
+    ].filter((surface) => surface.path !== null);
   });
 }
 
@@ -1618,7 +1736,7 @@ function printTargetSurface(repo, target) {
     }
   }
 
-  const openspecSkillRoot = openspecSkillRootForTarget(target);
+  const openspecSkillRoot = openspecSkillRootForTarget(target, repo);
   const openspecSkillPaths = OPENSPEC_SKILLS.map((skill) =>
     path.join(repo, openspecSkillRoot, skill, "SKILL.md")
   );
@@ -1641,16 +1759,25 @@ function printTargetSurface(repo, target) {
   );
 
   const commands = commandSurfaceForTarget(target, repo);
-  const commandCounts = countExisting(commands.paths);
-  const commandDetail =
-    surfaceStatus(commandCounts) === "ok"
-      ? formatCount(commandCounts, commands.location)
-      : `${formatCount(commandCounts, commands.location)}; ${commands.remediation}`;
-  printDoctorLine(
-    "OpenSpec commands",
-    surfaceStatus(commandCounts),
-    commandDetail
-  );
+  if (commands.skillsOnly) {
+    printDoctorLine(
+      "OpenSpec commands",
+      "ok",
+      `none; OpenSpec 1.13 surfaces Codex's workflows as the skills under `
+        + `${commands.location}`
+    );
+  } else {
+    const commandCounts = countExisting(commands.paths);
+    const commandDetail =
+      surfaceStatus(commandCounts) === "ok"
+        ? formatCount(commandCounts, commands.location)
+        : `${formatCount(commandCounts, commands.location)}; ${commands.remediation}`;
+    printDoctorLine(
+      "OpenSpec commands",
+      surfaceStatus(commandCounts),
+      commandDetail
+    );
+  }
 
   const overlayPaths = openspecOverlaySurfacesForTarget(target, repo).map(
     (surface) => surface.path
@@ -1752,6 +1879,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");