@christang/keel 5.2.1 → 5.2.3

package/README.md

@@ -139,6 +139,33 @@ command at the right moment. Three things make that happen.
 So in day-to-day use you run two commands: `keel --init` once, and `keel --doctor` when you
 want to check the wiring. Everything below is the vocabulary the agent uses on your behalf.
 
+## Verification layering
+
+Keel splits verification into two layers so a slow suite never blocks your push:
+
+- **Fast inner-loop check** — seconds, run at a local pre-push and during iteration. It catches
+  obvious breakage without waiting.
+- **Full gate** — the complete or slow suite (golden byte-determinism tests, cross-platform runs),
+  run at CI or at `keel gate change-close`.
+
+A task's `Verify` checks stay fast; the slow or exhaustive layer belongs to the full gate, not the
+local pre-push. Declare your fast check once in `keel/config.yaml`:
+
+```yaml
+fast_check: npm test -- --fast   # your project's seconds-scale check
+```
+
+Then opt into a repo-local fast pre-push:
+
+```bash
+keel --install --with-git-hooks   # writes .githooks/pre-push, sets core.hooksPath (this repo only)
+keel --doctor                     # reports fast_check, the pre-push hook, and core.hooksPath
+keel --uninstall                  # reverts core.hooksPath when Keel set it
+```
+
+`--with-git-hooks` is opt-in: a plain `keel --install` never touches git config, and the override
+is repo-local and reversible.
+
 ## Domain lenses
 
 Keel's core is pure process; it ships no domain knowledge of its own. Domain guidance lives in

package/README.zh-CN.md

@@ -133,6 +133,31 @@ keel --init  →  keel context  →  /opsx:apply（选一个 task）
 所以日常使用里你真正要敲的只有两条：装配时的 `keel --init`，以及想体检时的 `keel --doctor`。
 下面列出的，是 agent 替你使用的「命令词汇表」。
 
+## 验证分层
+
+Keel 把验证分成两层，让慢测试套件不再卡住你的 push：
+
+- **快速内环检查（fast inner-loop）** —— 秒级，在本地 pre-push 和迭代时跑，挡住明显的破坏而无需等待。
+- **全量门禁（full gate）** —— 完整或慢的套件（golden 字节确定性测试、跨平台运行），交给 CI 或
+  `keel gate change-close`。
+
+任务的 `Verify` 检查保持快；慢的或穷尽的那一层归全量门禁，不放在本地 pre-push。在 `keel/config.yaml`
+里声明一次你的快检命令：
+
+```yaml
+fast_check: npm test -- --fast   # 你项目的秒级检查
+```
+
+然后按需装一个仓内快 pre-push：
+
+```bash
+keel --install --with-git-hooks   # 写 .githooks/pre-push，设 core.hooksPath（仅本仓）
+keel --doctor                     # 报告 fast_check、pre-push hook、core.hooksPath
+keel --uninstall                  # 当 core.hooksPath 由 Keel 设置时回退
+```
+
+`--with-git-hooks` 是显式 opt-in：普通 `keel --install` 绝不碰 git config，且这个覆盖仅限本仓、可逆。
+
 ## 命令参考
 
 ```bash

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.2.1 -->
+<!-- keel:start version=5.2.3 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/assets/openspec/schemas/keel-spec-driven/templates/tasks.md

@@ -20,7 +20,11 @@
          rendered-behavior, or evidence-first. Each M<n> check must prove the
          resolved Acceptance through the public interface, not build-only or
          shape-only evidence. Red-green strategies record per-label `.red` and
-         `.green` Evidence entries for the same check before completion. -->
+         `.green` Evidence entries for the same check before completion. An M<n>
+         check may carry an optional (fast) or (full) layer tag after its label
+         (e.g. `M1 (fast): …`) marking which checks the fast inner-loop pre-push
+         runs; an untagged check is full and change-close still needs every
+         M<n>'s Evidence. -->
     - Strategy: <strategy>
     - M1: <public behavior check>
   - Evidence:

package/bin/keel.js

@@ -15,6 +15,7 @@ const {
   runGate,
 } = require("../src/core/gates");
 const {
+  isKeelSourceRepo,
   probeCapabilities,
   renderCapabilities,
 } = require("../src/core/capabilities");
@@ -84,7 +85,7 @@ Usage:
   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 --install [repo] [--target claude|codex|opencode] [--dry-run] [--force-template-update] [--with-git-hooks]
   keel --clear [repo] [--target claude|codex|opencode] [--dry-run]
   keel --uninstall [repo] [--target claude|codex|opencode] [--dry-run]
   keel --update [--dry-run] [--source npm-package-or-git-spec]
@@ -127,6 +128,7 @@ Examples:
   keel --check
   keel --doctor
   keel --install --force-template-update
+  keel --install --with-git-hooks
   keel --update
   keel --update --dry-run
   keel --clear --dry-run
@@ -154,6 +156,7 @@ function parseArgs(argv) {
     target: "claude",
     dryRun: false,
     forceTemplateUpdate: false,
+    withGitHooks: false,
     updateSource: null,
     help: false,
     version: false,
@@ -363,6 +366,10 @@ function parseArgs(argv) {
       parsed.forceTemplateUpdate = true;
       continue;
     }
+    if (arg === "--with-git-hooks") {
+      parsed.withGitHooks = true;
+      continue;
+    }
     if (arg === "--target") {
       index += 1;
       if (index >= argv.length) {
@@ -820,6 +827,9 @@ function installerArgs(options, extra = []) {
   if (options.forceTemplateUpdate) {
     args.push("--force-template-update");
   }
+  if (options.withGitHooks) {
+    args.push("--with-git-hooks");
+  }
   return args;
 }
 
@@ -1193,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",
@@ -1220,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);
@@ -1323,10 +1343,60 @@ function runDoctor(options) {
 
   printTargetSurface(repo, options.target);
   printLensSurface(repo, options.target);
+  printFastPrePushSurface(repo);
 
   return checkStatus;
 }
 
+function readFastCheck(repo) {
+  const configPath = path.join(repo, "keel", "config.yaml");
+  if (!fs.existsSync(configPath)) return null;
+  for (const line of fs.readFileSync(configPath, "utf8").split(/\r?\n/)) {
+    const stripped = line.trim();
+    if (stripped.startsWith("#")) continue;
+    const match = stripped.match(/^fast_check\s*:\s*(.+?)\s*$/);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+function gitConfigHooksPath(repo) {
+  const result = spawnSync(
+    "git",
+    ["-C", repo, "config", "--local", "--get", "core.hooksPath"],
+    { encoding: "utf8" }
+  );
+  if (result.status !== 0) return null;
+  const value = (result.stdout || "").trim();
+  return value || null;
+}
+
+function printFastPrePushSurface(repo) {
+  process.stdout.write("\nFast pre-push surface:\n");
+  const fastCheck = readFastCheck(repo);
+  printDoctorLine(
+    "fast_check",
+    fastCheck ? "ok" : "none",
+    fastCheck
+      ? `declared in keel/config.yaml: ${fastCheck}`
+      : "undeclared; add a fast_check line to keel/config.yaml"
+  );
+  const hookPresent = fs.existsSync(path.join(repo, ".githooks", "pre-push"));
+  printDoctorLine(
+    "pre-push hook",
+    hookPresent ? "ok" : "none",
+    hookPresent
+      ? ".githooks/pre-push present"
+      : "run keel --install --with-git-hooks to scaffold it"
+  );
+  const hooksPath = gitConfigHooksPath(repo);
+  printDoctorLine(
+    "core.hooksPath",
+    hooksPath === ".githooks" ? "ok" : hooksPath ? "other" : "unset",
+    hooksPath || "default (.git/hooks)"
+  );
+}
+
 const SHIPPED_LENS_DIR = path.join(PACKAGE_ROOT, "assets", "lenses");
 const EXPECTED_LENS_TEMPLATES = ["web", "hardware", "hardware-dsl"];
 
@@ -1445,6 +1515,9 @@ function runAction(options) {
   if (options.updateSource !== null && options.action !== "update") {
     fail("--source only applies to --update");
   }
+  if (options.withGitHooks && options.action !== "install") {
+    fail("--with-git-hooks only applies to --install");
+  }
 
   if (options.action === "openspec") {
     const openspec = findOpenSpecCommand();

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

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.2.1",
+  "version": "5.2.3",
   "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.1",
+  "version": "5.2.3",
   "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

@@ -6,7 +6,9 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import os
 import re
+import subprocess
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -19,6 +21,20 @@ TEMPLATE_CHECKSUM_PREFIX = "<!-- keel:content-sha256 "
 TEMPLATE_CHECKSUM_SUFFIX = " -->"
 KEEL_ROOT = Path("keel")
 HANDOFF_PATH = KEEL_ROOT / "HANDOFF.md"
+KEEL_CONFIG_PATH = KEEL_ROOT / "config.yaml"
+KEEL_CONFIG_TEMPLATE = (
+    "# Keel project configuration.\n"
+    "#\n"
+    "# fast_check (optional): your project's fast inner-loop check — a\n"
+    "# seconds-scale command run at a local pre-push (see\n"
+    "# `keel --install --with-git-hooks`) and during iteration. The full or slow\n"
+    "# suite belongs to CI or `keel gate change-close`, not the local pre-push.\n"
+    "#\n"
+    "# Example:\n"
+    "#   fast_check: npm test -- --fast\n"
+)
+GITHOOKS_DIR = ".githooks"
+PRE_PUSH_PATH = Path(GITHOOKS_DIR) / "pre-push"
 OPENSPEC_ROOT = Path("openspec")
 OPENSPEC_CONFIG_PATH = OPENSPEC_ROOT / "config.yaml"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
@@ -198,6 +214,124 @@ def openspec_config_action() -> InstallAction:
     )
 
 
+def keel_config_action() -> InstallAction:
+    return InstallAction(
+        relative_path=KEEL_CONFIG_PATH,
+        content=KEEL_CONFIG_TEMPLATE,
+        strategy="keel-config-scaffold",
+    )
+
+
+def read_fast_check(repo: Path) -> str | None:
+    """Return the project's declared fast inner-loop command, or None.
+
+    Parses keel/config.yaml with the same flat-key style Keel uses elsewhere;
+    a commented `# fast_check:` line does not count as declared.
+    """
+    config_path = repo / KEEL_CONFIG_PATH
+    if not config_path.is_file():
+        return None
+    for line in config_path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            continue
+        match = re.match(r"fast_check\s*:\s*(.+?)\s*$", stripped)
+        if match:
+            return match.group(1)
+    return None
+
+
+def is_git_repo(repo: Path) -> bool:
+    result = subprocess.run(
+        ["git", "-C", str(repo), "rev-parse", "--is-inside-work-tree"],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0 and result.stdout.strip() == "true"
+
+
+def git_config_get(repo: Path, key: str) -> str | None:
+    result = subprocess.run(
+        ["git", "-C", str(repo), "config", "--local", "--get", key],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def pre_push_hook_content(fast_check: str) -> str:
+    return (
+        "#!/bin/sh\n"
+        "# Managed by keel --install --with-git-hooks: the fast inner-loop check.\n"
+        "# The full or slow suite belongs to CI or `keel gate change-close`.\n"
+        f"exec {fast_check}\n"
+    )
+
+
+def apply_git_hooks(repo: Path, dry_run: bool) -> int:
+    if not is_git_repo(repo):
+        print(
+            "keel --install --with-git-hooks: not a git repository; run "
+            "`git init` first",
+            file=sys.stderr,
+        )
+        return 1
+    fast_check = read_fast_check(repo)
+    if fast_check is None:
+        print(
+            "keel --install --with-git-hooks: no fast_check declared in "
+            f"{KEEL_CONFIG_PATH.as_posix()}; add a `fast_check:` line, then rerun",
+            file=sys.stderr,
+        )
+        return 1
+    if dry_run:
+        print(
+            f"would write {PRE_PUSH_PATH.as_posix()} running the fast_check and "
+            f"set core.hooksPath to {GITHOOKS_DIR}"
+        )
+        return 0
+    hook_path = repo / PRE_PUSH_PATH
+    hook_path.parent.mkdir(parents=True, exist_ok=True)
+    hook_path.write_text(pre_push_hook_content(fast_check), encoding="utf-8")
+    os.chmod(hook_path, 0o755)
+    result = subprocess.run(
+        ["git", "-C", str(repo), "config", "--local", "core.hooksPath", GITHOOKS_DIR],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        print(
+            "keel --install --with-git-hooks: failed to set core.hooksPath: "
+            + (result.stderr.strip() or "git config error"),
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        f"git hooks: wrote {PRE_PUSH_PATH.as_posix()} (runs the fast_check) and "
+        f"set core.hooksPath to {GITHOOKS_DIR}"
+    )
+    return 0
+
+
+def revert_git_hooks(repo: Path, dry_run: bool) -> None:
+    """Unset core.hooksPath only when Keel is the one that set it to .githooks."""
+    if not is_git_repo(repo):
+        return
+    if git_config_get(repo, "core.hooksPath") != GITHOOKS_DIR:
+        return
+    if dry_run:
+        print(f"would unset core.hooksPath (currently {GITHOOKS_DIR})")
+        return
+    subprocess.run(
+        ["git", "-C", str(repo), "config", "--local", "--unset", "core.hooksPath"],
+        capture_output=True,
+        text=True,
+    )
+    print(f"git hooks: unset core.hooksPath (was {GITHOOKS_DIR})")
+
+
 def openspec_schema_actions() -> list[InstallAction]:
     schema_root = PACKAGE_ROOT / OPENSPEC_ASSET_ROOT / "schemas" / OPENSPEC_SCHEMA_NAME
     if not schema_root.is_dir():
@@ -298,11 +432,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)
         )
@@ -310,6 +471,7 @@ def collect_actions(repo: Path, target: str) -> list[InstallAction]:
         actions.append(managed_content_action("CLAUDE.md", CLAUDE_IMPORT_BLOCK))
 
     actions.append(openspec_config_action())
+    actions.append(keel_config_action())
     actions.extend(openspec_schema_actions())
     return actions
 
@@ -768,6 +930,9 @@ def plan_action(
     if action.strategy == "openspec-config":
         merged, kind = merge_openspec_config(existing)
         return PlannedAction(kind, action.relative_path, None if kind == "skip" else merged)
+    if action.strategy == "keel-config-scaffold":
+        # Scaffold once: never overwrite a project's own keel/config.yaml.
+        return PlannedAction("skip", action.relative_path)
 
     if existing == source_content:
         return PlannedAction("skip", action.relative_path)
@@ -1007,6 +1172,14 @@ def main() -> int:
         action="store_true",
         help="Remove managed protocol blocks and safe generated skeleton files.",
     )
+    parser.add_argument(
+        "--with-git-hooks",
+        action="store_true",
+        help=(
+            "Generate .githooks/pre-push from the declared fast_check and set "
+            "core.hooksPath (install only); refuses without a fast_check."
+        ),
+    )
     parser.add_argument(
         "--profile",
         action="append",
@@ -1031,6 +1204,7 @@ def main() -> int:
             describe_actions(actions)
             if not args.dry_run:
                 apply_actions(repo, actions)
+            revert_git_hooks(repo, args.dry_run)
             return 0
         repo.mkdir(parents=True, exist_ok=True)
         actions = plan_actions(
@@ -1042,6 +1216,8 @@ def main() -> int:
         report_handoff_status(repo)
         if not args.dry_run:
             apply_actions(repo, actions)
+        if args.with_git_hooks:
+            return apply_git_hooks(repo, args.dry_run)
         return 0
     except ValueError as exc:
         print(f"Install failed: {exc}", file=sys.stderr)