@christang/keel 5.1.1 → 5.2.0

package/bin/keel.js

@@ -56,11 +56,6 @@ const KEEL_SKILLS = [
   "keel-review-checklist",
   "keel-tdd-or-test-first",
 ];
-const ALIGNMENT_REFERENCES = [
-  "references/web.md",
-  "references/hardware.md",
-  "references/hardware-dsl.md",
-];
 const OPENSPEC_COMMAND_IDS = ["propose", "explore", "apply", "sync", "archive"];
 const OPENSPEC_SKILLS = [
   "openspec-propose",
@@ -86,6 +81,8 @@ Usage:
   keel project tasks [repo] --target claude [--change name] [--json]
   keel gate task-start|task-complete|change-close [repo] [--change name] [--task id] [--action sync|archive] [--base git-ref] [--no-guard] [--record] [--json]
   keel guard start|status|clear [repo] [--change name] [--task id] [--force] [--json]
+  keel lenses list|add [name] [repo] [--force]
+  keel openspec [args...]
   keel --init [repo] [--target claude|codex|opencode] [--dry-run] [--force-template-update]
   keel --install [repo] [--target claude|codex|opencode] [--dry-run] [--force-template-update]
   keel --clear [repo] [--target claude|codex|opencode] [--dry-run]
@@ -105,9 +102,7 @@ Defaults:
 Project layout:
   continuity is recomputed from OpenSpec on every invocation.
   keel/HANDOFF.md is an optional keel-handoff/v1 pointer override.
-  Claude skills are installed under .claude/skills/keel-*.
-  Codex skills are installed under .agents/skills/keel-*.
-  OpenCode skills are installed under .opencode/skills/keel-*.
+  keel-* behavioral skills are delivered by the installed Keel plugin, not by the CLI.
   repeat keel --install to refresh project protocol files.
 
 Examples:
@@ -121,6 +116,9 @@ Examples:
   keel guard start --change my-change --task 1.1 --json
   keel guard status --json
   keel guard clear --json
+  keel lenses list
+  keel lenses add web
+  keel lenses add web --force
   keel --init
   keel --install
   keel --install --target codex
@@ -169,6 +167,9 @@ function parseArgs(argv) {
     noGuard: false,
     record: false,
     guardSubcommand: null,
+    lensesSubcommand: null,
+    lensName: null,
+    openspecArgs: [],
     force: false,
     projectionEvent: null,
     authorizations: [],
@@ -207,6 +208,15 @@ function parseArgs(argv) {
       parsed.action = "guard";
       continue;
     }
+    if (arg === "lenses" && parsed.action === null && parsed.repo === null) {
+      parsed.action = "lenses";
+      continue;
+    }
+    if (arg === "openspec" && parsed.action === null && parsed.repo === null) {
+      parsed.action = "openspec";
+      parsed.openspecArgs = argv.slice(index + 1);
+      break;
+    }
     if (arg === "--force") {
       parsed.force = true;
       continue;
@@ -423,6 +433,18 @@ function parseArgs(argv) {
       parsed.projectSubcommand = arg;
       continue;
     }
+    if (parsed.action === "lenses" && parsed.lensesSubcommand === null) {
+      parsed.lensesSubcommand = arg;
+      continue;
+    }
+    if (
+      parsed.action === "lenses"
+      && parsed.lensesSubcommand === "add"
+      && parsed.lensName === null
+    ) {
+      parsed.lensName = arg;
+      continue;
+    }
     if (parsed.repo !== null) {
       fail("repo path was provided more than once");
     }
@@ -486,8 +508,25 @@ function parseArgs(argv) {
   if (parsed.action !== "guard" && parsed.guardSubcommand !== null) {
     fail("guard subcommands apply only to keel guard");
   }
-  if (parsed.force && parsed.action !== "guard") {
-    fail("--force applies only to keel guard start");
+  if (
+    parsed.force
+    && parsed.action !== "guard"
+    && !(parsed.action === "lenses" && parsed.lensesSubcommand === "add")
+  ) {
+    fail("--force applies only to keel guard start or keel lenses add");
+  }
+  if (parsed.action === "lenses") {
+    if (!["list", "add"].includes(parsed.lensesSubcommand || "")) {
+      fail("lenses requires list or add");
+    }
+    if (parsed.lensesSubcommand === "add" && !parsed.lensName) {
+      fail("keel lenses add requires a lens name");
+    }
+    if (parsed.lensesSubcommand === "list" && parsed.lensName) {
+      fail("keel lenses list does not take a lens name");
+    }
+  } else if (parsed.lensesSubcommand !== null || parsed.lensName !== null) {
+    fail("lens subcommands apply only to keel lenses");
   }
   if (parsed.noGuard && parsed.action !== "gate") {
     fail("--no-guard applies only to keel gate task-start");
@@ -983,6 +1022,7 @@ function keelOpenSpecOverlay(action) {
           "- The current agent reviews all subagent output, command evidence, and diffs before marking any task complete.",
           "- When implementation exposes a material expectation, acceptance boundary, or user-owned decision absent from durable authority, stop before implementing that choice, rerun `keel-align-expectations`, and reauthor the affected proposal/design/spec/task authority first.",
           "- A discovered repository fact that does not change accepted behavior or scope may be recorded and execution continues inside the existing task boundary without a product interview.",
+          "- Invoke OpenSpec through `keel openspec` (for example `keel openspec validate`); a bare `openspec` command may not be on PATH.",
         ]
       : [
           "- The current agent owns final sync/archive decisions and must verify task evidence, follow-up ownership, and completion gates before proceeding.",
@@ -990,6 +1030,9 @@ function keelOpenSpecOverlay(action) {
           "- Target-native subagents may help with bounded assessment or evidence production only; they cannot archive, sync, change acceptance, or bypass completion gates.",
           "- The current agent reviews any subagent report before running `openspec-sync-specs`, `/opsx:sync`, or `/opsx:archive`.",
           "- Do not treat generic OpenSpec archive delegation language as authority to transfer Keel ownership.",
+          "- Invoke OpenSpec through `keel openspec` (for example `keel openspec validate`); a bare `openspec` command may not be on PATH.",
+          "- When `/opsx:sync` has already promoted the change's spec delta, run the archive with `--skip-specs` so the promoted delta is not re-applied; archive is not idempotent over an already-synced delta.",
+          "- After archiving, run `keel guard clear` to drop the change's guard manifest; the read-only gate never clears it for you.",
         ];
 
   const lines = [
@@ -1174,6 +1217,12 @@ function printTargetSurface(repo, target) {
     formatCount(openspecSkillCounts, openspecSkillRoot)
   );
 
+  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"
+  );
+
   const commands = commandSurfaceForTarget(target, repo);
   const commandCounts = countExisting(commands.paths);
   const commandDetail =
@@ -1226,11 +1275,27 @@ function runDoctor(options) {
   );
 
   const openspec = findOpenSpecCommand();
-  printDoctorLine(
-    "openspec",
-    openspec ? "ok" : "missing",
-    openspec || "reinstall keel so npm installs its OpenSpec dependency"
-  );
+  if (!openspec) {
+    printDoctorLine(
+      "openspec",
+      "missing",
+      "reinstall keel so npm installs its OpenSpec dependency"
+    );
+  } else {
+    const bareOpenSpecOnPath =
+      !path.isAbsolute(openspec)
+      || runCommand("openspec", ["--version"], {
+        stdio: "ignore",
+        silentNotFound: true,
+      }) === 0;
+    printDoctorLine(
+      "openspec",
+      bareOpenSpecOnPath ? "ok" : "warning",
+      bareOpenSpecOnPath
+        ? openspec
+        : `${openspec} is keel-resolvable but bare \`openspec\` is not on PATH — use \`keel openspec\``
+    );
+  }
 
   process.stdout.write("\nProject status:\n");
   const checkStatus = runPython(
@@ -1257,15 +1322,142 @@ function runDoctor(options) {
   }
 
   printTargetSurface(repo, options.target);
+  printLensSurface(repo, options.target);
 
   return checkStatus;
 }
 
+const SHIPPED_LENS_DIR = path.join(PACKAGE_ROOT, "assets", "lenses");
+const EXPECTED_LENS_TEMPLATES = ["web", "hardware", "hardware-dsl"];
+
+function targetSkillsDir(repo, target) {
+  if (target === "codex") return path.join(repo, ".agents", "skills");
+  if (target === "opencode") return path.join(repo, ".opencode", "skills");
+  return path.join(repo, ".claude", "skills");
+}
+
+function legacyProfileSkills(repo, target) {
+  try {
+    return fs
+      .readdirSync(targetSkillsDir(repo, target), { withFileTypes: true })
+      .filter(
+        (entry) => entry.isDirectory() && /^keel-profile-/.test(entry.name)
+      )
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    return [];
+  }
+}
+
+function printLensSurface(repo, target) {
+  process.stdout.write("\nDomain lens surface:\n");
+  const shipped = lensNames(SHIPPED_LENS_DIR);
+  const missing = EXPECTED_LENS_TEMPLATES.filter(
+    (name) => !shipped.includes(name)
+  );
+  printDoctorLine(
+    "lens templates",
+    missing.length === 0 ? "ok" : "incomplete",
+    missing.length === 0
+      ? `shipped: ${EXPECTED_LENS_TEMPLATES.join(", ")}; scaffold with keel lenses add`
+      : `missing template(s): ${missing.join(", ")}`
+  );
+  const installed = lensNames(path.join(repo, "keel", "lenses"));
+  printDoctorLine(
+    "installed lenses",
+    installed.length > 0 ? "ok" : "none",
+    installed.length > 0
+      ? `keel/lenses/: ${installed.join(", ")}`
+      : "no user lenses yet; keel lenses add scaffolds one"
+  );
+  const legacy = legacyProfileSkills(repo, target);
+  if (legacy.length > 0) {
+    printDoctorLine(
+      "legacy profiles",
+      "migrate",
+      `found ${legacy.join(", ")}; v3 keel-profile-* skills are replaced by `
+        + "pluggable lenses (keel lenses add). Left untouched; not active state."
+    );
+  }
+}
+
+function lensNames(dir) {
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((name) => name.endsWith(".md"))
+      .map((name) => name.slice(0, -3))
+      .sort();
+  } catch (error) {
+    return [];
+  }
+}
+
+function runLensesList(repo) {
+  const shipped = lensNames(SHIPPED_LENS_DIR);
+  const installed = lensNames(path.join(repo, "keel", "lenses"));
+  process.stdout.write("Shipped lens templates (assets/lenses/):\n");
+  if (shipped.length === 0) {
+    process.stdout.write("  (none)\n");
+  } else {
+    for (const name of shipped) {
+      const mark = installed.includes(name) ? " (installed)" : "";
+      process.stdout.write(`  ${name}${mark}\n`);
+    }
+  }
+  process.stdout.write("\nInstalled lenses (keel/lenses/):\n");
+  if (installed.length === 0) {
+    process.stdout.write("  (none) — run keel lenses add <name>\n");
+  } else {
+    for (const name of installed) {
+      const mark = shipped.includes(name) ? "" : " (custom)";
+      process.stdout.write(`  ${name}${mark}\n`);
+    }
+  }
+  return 0;
+}
+
+function runLensesAdd(repo, name, force) {
+  const source = path.join(SHIPPED_LENS_DIR, `${name}.md`);
+  if (!fs.existsSync(source)) {
+    const available = lensNames(SHIPPED_LENS_DIR).join(", ") || "(none)";
+    fail(`unknown lens template: ${name}; shipped templates: ${available}`);
+  }
+  const destDir = path.join(repo, "keel", "lenses");
+  const dest = path.join(destDir, `${name}.md`);
+  if (fs.existsSync(dest) && !force) {
+    process.stderr.write(
+      `keel: keel/lenses/${name}.md already exists; pass --force to overwrite\n`
+    );
+    return 3;
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.copyFileSync(source, dest);
+  process.stdout.write(
+    `keel: wrote keel/lenses/${name}.md from the ${name} template; `
+      + "edit it to fit this repository\n"
+  );
+  return 0;
+}
+
 function runAction(options) {
   if (options.updateSource !== null && options.action !== "update") {
     fail("--source only applies to --update");
   }
 
+  if (options.action === "openspec") {
+    const openspec = findOpenSpecCommand();
+    if (!openspec) {
+      process.stderr.write(
+        "keel: openspec is not resolvable; reinstall keel so npm installs "
+          + "its OpenSpec dependency\n"
+      );
+      return 1;
+    }
+    return runCommand(openspec, options.openspecArgs, { stdio: "inherit" });
+  }
+
   if (options.action === "context") {
     if (options.dryRun || options.forceTemplateUpdate || options.updateSource) {
       fail("context does not accept install or update options");
@@ -1351,6 +1543,17 @@ function runAction(options) {
       : 3;
   }
 
+  if (options.action === "lenses") {
+    if (options.dryRun || options.forceTemplateUpdate || options.updateSource) {
+      fail("lenses does not accept install or update options");
+    }
+    const repo = path.resolve(options.repo || process.cwd());
+    if (options.lensesSubcommand === "list") {
+      return runLensesList(repo);
+    }
+    return runLensesAdd(repo, options.lensName, options.force);
+  }
+
   if (options.action === "capabilities") {
     if (options.dryRun || options.forceTemplateUpdate || options.updateSource) {
       fail("capabilities does not accept install or update options");

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.1.1",
+  "version": "5.2.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.1.1",
+  "version": "5.2.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/hooks/hooks.json

@@ -1,30 +1,30 @@
-{
-  "description": "Keel plugin hooks: non-blocking SessionStart projection and the manifest-gated PreToolUse write guard, both backed by the shared keel CLI contract.",
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/session-start.js"],
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write|NotebookEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node",
-            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/pretooluse-guard.js"],
-            "timeout": 10
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "description": "Keel plugin hooks: non-blocking SessionStart projection and the manifest-gated PreToolUse write guard, both backed by the shared keel CLI contract.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/session-start.js"],
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/pretooluse-guard.js"],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}