@christang/keel 5.1.1 → 5.2.0

package/plugins/keel/skills/keel-align-expectations/SKILL.md

@@ -40,13 +40,9 @@ Accepted alignment routes to existing OpenSpec owners; create no separate alignm
 - specs own observable requirements and positive/negative/edge/failure scenarios.
 - tasks.md owns Covers, verification strategy and checks, scope, and stop boundaries that reference the accepted authority instead of duplicating chat prose.
 
-## Domain references
+## Domain lenses
 
-When the change touches a specific domain, read only the applicable reference before asking domain questions; do not load the others:
-
-- references/web.md for UI, API, routing, auth/session, persistence, or backend integration work.
-- references/hardware.md for Verilog/SystemVerilog interface, protocol, reset, or verification work.
-- references/hardware-dsl.md for hardware modeling DSL, generated RTL, or golden/equivalence work.
+When the change signals a specific domain, look in `keel/lenses/` for a lens whose `Applies when:` header matches, and read only that lens before asking domain questions; do not load unrelated lenses. When no lens matches, or the repo defines none, proceed on the domain-agnostic path. Lenses are user-authored; scaffold the bundled starting points with `keel lenses add` (web, hardware, hardware-dsl).
 
 ## Boundaries
 

package/plugins/keel/skills/keel-debug-failure/SKILL.md

@@ -12,9 +12,9 @@ Use this skill when a command or validation path fails. Keep the investigation t
 
 Read the selected OpenSpec task's Commands, Acceptance, Coupling, Candidate Boundary, Autonomy boundary, Stop Rules, Evidence, Stop if, Read, Touch, and Mode fields. When `Coupling: required`, also read design.md's Coupled Iteration Contract. Read the failed command output and any repository files needed to reproduce or explain the failure.
 
-## Domain reference
+## Domain lenses
 
-When the change's artifacts or the failing surface signal a supported domain (web, hardware, hardware-dsl), consult the matching reference's `Execution and review checks` section under `keel-align-expectations/references/` before locking a root-cause hypothesis — only the matching reference, never all of them. When no domain signal exists, load nothing.
+When the change's artifacts or the failing surface signal a domain, consult the matching lens's `Execution and review checks` section from `keel/lenses/` — the lens whose `Applies when:` header matches — before locking a root-cause hypothesis, and load only that one. When no lens matches, load nothing.
 
 ## Fuse
 

package/plugins/keel/skills/keel-review-checklist/SKILL.md

@@ -35,9 +35,9 @@ Record the current agent's judgment inside the selected task Evidence:
 
 The Review remains in tasks.md. A user-facing Report summarizes delivery but is not hidden gate state. Do not let Core or this checklist write evidence automatically.
 
-## Domain reference
+## Domain lenses
 
-When the change's artifacts or Touch extensions signal a supported domain (web, hardware, hardware-dsl), consult the matching reference's `Execution and review checks` section under `keel-align-expectations/references/` before concluding the review — only the matching reference, never all of them. When no domain signal exists, load nothing.
+When the change's artifacts or Touch extensions signal a domain, consult the matching lens's `Execution and review checks` section from `keel/lenses/` — the lens whose `Applies when:` header matches — before concluding the review, and load only that one. When no lens matches, load nothing.
 
 ## Expectation and follow-up ownership
 

package/plugins/keel/skills/keel-tdd-or-test-first/SKILL.md

@@ -24,9 +24,9 @@ Read the selected task's compiled capsule: resolved Acceptance, Verify strategy
 
 Red-green strategies (`vertical-tdd`, `regression-first`) must record concrete per-label `.red` and `.green` Evidence entries for the same check; `keel gate task-complete` rejects absent or pending entries.
 
-## Domain reference
+## Domain lenses
 
-When the change's proposal/design/specs or the task's Touch extensions signal a supported domain (web, hardware, hardware-dsl), consult the matching reference's `Execution and review checks` section under `keel-align-expectations/references/` before finalizing the strategy and the first check — only the matching reference, never all of them. When no domain signal exists, load nothing.
+When the change's proposal/design/specs or the task's Touch extensions signal a domain, consult the matching lens's `Execution and review checks` section from `keel/lenses/` — the lens whose `Applies when:` header matches — before finalizing the strategy and the first check, and load only that one. When no lens matches, load nothing.
 
 ## Coupled-task preflight
 

package/scripts/bump_version.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+"use strict";
+
+// One-shot version bump across every place Keel pins its version.
+//
+// The Keel validation suite requires the same version in package.json,
+// package-lock.json, both native plugin manifests, the validator constants,
+// the protocol docs, and the changelog. This script updates all of them
+// together so a release never ships half-aligned.
+//
+// Usage:
+//   node scripts/bump_version.js <patch|minor|major|explicit-version>
+//
+// After running: fill in the CHANGELOG entry, then `npm test`, commit,
+// tag `vX.Y.Z`, push, and publish a GitHub Release.
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const PKG_PATH = path.join(ROOT, "package.json");
+const LOCK_PATH = path.join(ROOT, "package-lock.json");
+const CHANGELOG_PATH = path.join(ROOT, "keel", "CHANGELOG.md");
+const CHANGELOG_HEADER = "# Keel Changelog\n\n";
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+function fail(message) {
+  process.stderr.write(`bump-version: ${message}\n`);
+  process.exit(1);
+}
+
+function resolveNewVersion(current, target) {
+  if (target === "patch" || target === "minor" || target === "major") {
+    const [, major, minor, patch] = current.match(SEMVER_RE).map(Number);
+    if (target === "major") return `${major + 1}.0.0`;
+    if (target === "minor") return `${major}.${minor + 1}.0`;
+    return `${major}.${minor}.${patch + 1}`;
+  }
+  if (!SEMVER_RE.test(target)) {
+    fail(`not a patch|minor|major keyword or an X.Y.Z version: ${target}`);
+  }
+  return target;
+}
+
+function writeJson(filePath, data) {
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function bumpPackageFiles(newVersion) {
+  const pkg = JSON.parse(fs.readFileSync(PKG_PATH, "utf8"));
+  pkg.version = newVersion;
+  writeJson(PKG_PATH, pkg);
+  process.stdout.write("  updated package.json\n");
+
+  const lock = JSON.parse(fs.readFileSync(LOCK_PATH, "utf8"));
+  lock.version = newVersion;
+  if (lock.packages && lock.packages[""]) {
+    lock.packages[""].version = newVersion;
+  }
+  writeJson(LOCK_PATH, lock);
+  process.stdout.write("  updated package-lock.json\n");
+}
+
+function replaceInFile(relPath, replacements) {
+  const filePath = path.join(ROOT, relPath);
+  let content = fs.readFileSync(filePath, "utf8");
+  for (const [from, to] of replacements) {
+    if (!content.includes(from)) {
+      fail(`expected to find ${JSON.stringify(from)} in ${relPath}`);
+    }
+    content = content.split(from).join(to);
+  }
+  fs.writeFileSync(filePath, content);
+  process.stdout.write(`  updated ${relPath}\n`);
+}
+
+function prependChangelogEntry(newVersion) {
+  let content = fs.readFileSync(CHANGELOG_PATH, "utf8");
+  if (content.includes(`## ${newVersion} `) || content.includes(`## ${newVersion}\n`)) {
+    process.stdout.write(`  keel/CHANGELOG.md already has a ${newVersion} entry\n`);
+    return;
+  }
+  if (!content.startsWith(CHANGELOG_HEADER)) {
+    fail("keel/CHANGELOG.md does not start with the expected header");
+  }
+  const entry =
+    `## ${newVersion} - TODO: summarize this release\n\n` +
+    "- TODO: describe the change.\n" +
+    "- Version alignment: the npm package, both native plugin manifests, " +
+    `protocol docs, and this changelog share Keel ${newVersion}; the OpenSpec ` +
+    "dependency pin stays `^1.4.1`.\n\n";
+  content = CHANGELOG_HEADER + entry + content.slice(CHANGELOG_HEADER.length);
+  fs.writeFileSync(CHANGELOG_PATH, content);
+  process.stdout.write("  updated keel/CHANGELOG.md (fill in the TODO lines)\n");
+}
+
+function main() {
+  const target = process.argv[2];
+  if (!target) {
+    fail("usage: node scripts/bump_version.js <patch|minor|major|explicit-version>");
+  }
+
+  const oldVersion = JSON.parse(fs.readFileSync(PKG_PATH, "utf8")).version;
+  if (!SEMVER_RE.test(oldVersion)) {
+    fail(`current package.json version is not X.Y.Z: ${oldVersion}`);
+  }
+  const newVersion = resolveNewVersion(oldVersion, target);
+  process.stdout.write(`Bumping ${oldVersion} -> ${newVersion}\n`);
+
+  bumpPackageFiles(newVersion);
+  replaceInFile("plugins/keel/.claude-plugin/plugin.json", [
+    [`"version": "${oldVersion}"`, `"version": "${newVersion}"`],
+  ]);
+  replaceInFile("plugins/keel/.codex-plugin/plugin.json", [
+    [`"version": "${oldVersion}"`, `"version": "${newVersion}"`],
+  ]);
+  replaceInFile("scripts/validate_plugin.py", [
+    [`PACKAGE_VERSION = "${oldVersion}"`, `PACKAGE_VERSION = "${newVersion}"`],
+    [`PROTOCOL_VERSION = "${oldVersion}"`, `PROTOCOL_VERSION = "${newVersion}"`],
+  ]);
+  replaceInFile("AGENTS.md", [
+    [`v${oldVersion}`, `v${newVersion}`],
+    [`version=${oldVersion}`, `version=${newVersion}`],
+  ]);
+  replaceInFile("assets/bootstrap/AGENTS.md", [
+    [`version=${oldVersion}`, `version=${newVersion}`],
+  ]);
+  prependChangelogEntry(newVersion);
+
+  process.stdout.write(
+    `\nDone. Next:\n` +
+      `  1. Edit keel/CHANGELOG.md ${newVersion} entry.\n` +
+      `  2. npm test\n` +
+      `  3. git commit -am "${newVersion}"\n` +
+      `  4. git tag v${newVersion} && git push --follow-tags && git push origin v${newVersion}\n` +
+      `  5. gh release create v${newVersion} --title v${newVersion} --notes "..."\n`
+  );
+}
+
+main();

package/scripts/install_to_repo.py

@@ -51,23 +51,11 @@ KEEL_HOOK_NAME = "keel-gate"
 KEEL_HOOK_ROOT = Path(".claude") / "hooks" / KEEL_HOOK_NAME
 SUPPORTED_TARGETS = ("claude", "codex", "opencode")
 AGENT_PROTOCOL_TARGETS = {"codex", "opencode"}
-TARGET_SKILL_ROOTS = {
-    "claude": Path(".claude") / "skills",
-    "codex": Path(".agents") / "skills",
-    "opencode": Path(".opencode") / "skills",
-}
 TARGET_ADAPTER_PATHS = {
     "claude": Path(".claude") / "keel" / "keel-adapter.js",
     "codex": Path(".agents") / "keel" / "keel-adapter.js",
     "opencode": Path(".opencode") / "keel" / "keel-adapter.js",
 }
-CORE_KEEL_SKILLS = {
-    "keel-align-expectations",
-    "keel-debug-failure",
-    "keel-handoff",
-    "keel-review-checklist",
-    "keel-tdd-or-test-first",
-}
 HANDOFF_FIELDS = {"schema", "owner", "action", "reason"}
 HANDOFF_ACTIONS = {
     "discuss",
@@ -158,10 +146,6 @@ def target_set(target: str) -> set[str]:
     return set(target_names(target))
 
 
-def core_skill_names() -> set[str]:
-    return set(CORE_KEEL_SKILLS)
-
-
 def file_action(relative_path: str, source_path: Path) -> InstallAction:
     if not source_path.is_file():
         raise ValueError(f"missing packaged asset: {source_path}")
@@ -233,31 +217,6 @@ def openspec_schema_actions() -> list[InstallAction]:
     return actions
 
 
-def skill_actions(target: str) -> list[InstallAction]:
-    actions: list[InstallAction] = []
-    selected_skill_names = core_skill_names()
-    for target_name in target_names(target):
-        skill_destination_root = TARGET_SKILL_ROOTS[target_name]
-        skills_root = dist_asset(target_name, "skills")
-        if skills_root.is_dir():
-            for skill in sorted(skills_root.iterdir()):
-                if not skill.is_dir():
-                    continue
-                if skill.name not in selected_skill_names:
-                    continue
-                for skill_file in sorted(skill.rglob("*")):
-                    if not skill_file.is_file():
-                        continue
-                    relative_file = skill_file.relative_to(skill).as_posix()
-                    actions.append(
-                        file_action(
-                            (skill_destination_root / skill.name / relative_file).as_posix(),
-                            skill_file,
-                        )
-                    )
-    return actions
-
-
 def agent_actions(target: str) -> list[InstallAction]:
     actions: list[InstallAction] = []
     if "claude" not in target_set(target):
@@ -945,35 +904,6 @@ def rmdir_if_empty_action(relative_dir: str) -> PlannedAction:
     return PlannedAction("rmdir", Path(relative_dir))
 
 
-def plan_uninstall_skill_actions(repo: Path, target: str) -> list[PlannedAction]:
-    actions: list[PlannedAction] = []
-    for target_name in target_names(target):
-        skill_root = TARGET_SKILL_ROOTS[target_name]
-        target_actions = skill_actions(target_name)
-        for action in target_actions:
-            if action.source_path is None:
-                continue
-            actions.append(
-                plan_uninstall_packaged_file(
-                    repo,
-                    action.relative_path.as_posix(),
-                    action.source_path,
-                )
-            )
-
-        skill_dirs: set[Path] = set()
-        for action in target_actions:
-            parent = action.relative_path.parent
-            while parent != skill_root:
-                skill_dirs.add(parent)
-                parent = parent.parent
-        for skill_dir in sorted(skill_dirs, key=lambda path: len(path.parts), reverse=True):
-            actions.append(rmdir_if_empty_action(skill_dir.as_posix()))
-        actions.append(rmdir_if_empty_action(skill_root.as_posix()))
-        actions.append(rmdir_if_empty_action(skill_root.parent.as_posix()))
-    return actions
-
-
 def plan_uninstall_agent_actions(repo: Path, target: str) -> list[PlannedAction]:
     actions: list[PlannedAction] = []
     if "claude" not in target_set(target):

package/scripts/run_python.js

@@ -1,63 +1,63 @@
-#!/usr/bin/env node
-"use strict";
-
-const { spawnSync } = require("child_process");
-
-function pythonCandidates() {
-  if (process.env.KEEL_PYTHON) {
-    return [{ command: process.env.KEEL_PYTHON, prefixArgs: [] }];
-  }
-
-  if (process.platform === "win32") {
-    return [
-      { command: "py", prefixArgs: ["-3"] },
-      { command: "python", prefixArgs: [] },
-      { command: "python3", prefixArgs: [] },
-    ];
-  }
-
-  return [
-    { command: "python3", prefixArgs: [] },
-    { command: "python", prefixArgs: [] },
-  ];
-}
-
-function commandExists(candidate) {
-  const result = spawnSync(
-    candidate.command,
-    [...candidate.prefixArgs, "--version"],
-    { encoding: "utf8" }
-  );
-  return !result.error && result.status === 0;
-}
-
-function main() {
-  const args = process.argv.slice(2);
-  if (args.length === 0) {
-    process.stderr.write("run_python: expected a Python script path.\n");
-    return 2;
-  }
-
-  const candidate = pythonCandidates().find(commandExists);
-  if (!candidate) {
-    process.stderr.write(
-      "run_python: could not find Python. Install python3/python or set KEEL_PYTHON.\n"
-    );
-    return 127;
-  }
-
-  const result = spawnSync(
-    candidate.command,
-    [...candidate.prefixArgs, ...args],
-    { stdio: "inherit" }
-  );
-
-  if (result.error) {
-    process.stderr.write(`run_python: ${result.error.message}\n`);
-    return 127;
-  }
-
-  return result.status ?? 1;
-}
-
-process.exit(main());
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+
+function pythonCandidates() {
+  if (process.env.KEEL_PYTHON) {
+    return [{ command: process.env.KEEL_PYTHON, prefixArgs: [] }];
+  }
+
+  if (process.platform === "win32") {
+    return [
+      { command: "py", prefixArgs: ["-3"] },
+      { command: "python", prefixArgs: [] },
+      { command: "python3", prefixArgs: [] },
+    ];
+  }
+
+  return [
+    { command: "python3", prefixArgs: [] },
+    { command: "python", prefixArgs: [] },
+  ];
+}
+
+function commandExists(candidate) {
+  const result = spawnSync(
+    candidate.command,
+    [...candidate.prefixArgs, "--version"],
+    { encoding: "utf8" }
+  );
+  return !result.error && result.status === 0;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    process.stderr.write("run_python: expected a Python script path.\n");
+    return 2;
+  }
+
+  const candidate = pythonCandidates().find(commandExists);
+  if (!candidate) {
+    process.stderr.write(
+      "run_python: could not find Python. Install python3/python or set KEEL_PYTHON.\n"
+    );
+    return 127;
+  }
+
+  const result = spawnSync(
+    candidate.command,
+    [...candidate.prefixArgs, ...args],
+    { stdio: "inherit" }
+  );
+
+  if (result.error) {
+    process.stderr.write(`run_python: ${result.error.message}\n`);
+    return 127;
+  }
+
+  return result.status ?? 1;
+}
+
+process.exit(main());