@christang/keel 5.2.1 → 5.2.2

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.2 -->
 ## 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

@@ -84,7 +84,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 +127,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 +155,7 @@ function parseArgs(argv) {
     target: "claude",
     dryRun: false,
     forceTemplateUpdate: false,
+    withGitHooks: false,
     updateSource: null,
     help: false,
     version: false,
@@ -363,6 +365,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 +826,9 @@ function installerArgs(options, extra = []) {
   if (options.forceTemplateUpdate) {
     args.push("--force-template-update");
   }
+  if (options.withGitHooks) {
+    args.push("--with-git-hooks");
+  }
   return args;
 }
 
@@ -1323,10 +1332,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 +1504,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.2",
   "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.2",
   "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.2",
   "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():
@@ -310,6 +444,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 +903,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 +1145,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 +1177,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 +1189,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)

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.2.1"
-PROTOCOL_VERSION = "5.2.1"
+PACKAGE_VERSION = "5.2.2"
+PROTOCOL_VERSION = "5.2.2"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 OPENSPEC_CONFIG_PATH = Path("openspec/config.yaml")
@@ -7687,6 +7687,297 @@ def validate_native_tasks_view_scenario() -> int:
     return 0
 
 
+def validate_verification_layering_docs_scenario() -> int:
+    en = (ROOT / "README.md").read_text(encoding="utf-8")
+    for needle in (
+        "## Verification layering",
+        "inner-loop",
+        "Full gate",
+        "pre-push",
+        "change-close",
+    ):
+        if needle not in en:
+            report(
+                "verification-layering-docs: README.md lacks the fast/full "
+                f"verification split marker: {needle}"
+            )
+            return 1
+
+    zh = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8")
+    for needle in ("## 验证分层", "快速内环", "全量门禁", "pre-push", "change-close"):
+        if needle not in zh:
+            report(
+                "verification-layering-docs: README.zh-CN.md lacks the fast/full "
+                f"verification split marker: {needle}"
+            )
+            return 1
+
+    if "verification-layering-docs" not in {name for name, _ in SCENARIOS}:
+        report("verification-layering-docs: the scenario registry does not include it.")
+        return 1
+
+    report("verification-layering-docs scenario passed.")
+    return 0
+
+
+def validate_fast_check_config_scaffold_scenario() -> int:
+    with tempfile.TemporaryDirectory(prefix="keel-fastcfg-") as raw_tmp:
+        repo = Path(raw_tmp)
+        first = run_keel(repo, "--install")
+        if first.returncode != 0:
+            report("fast-check-config-scaffold: keel --install failed.")
+            report((first.stderr or first.stdout).strip())
+            return 1
+
+        config_path = repo / "keel" / "config.yaml"
+        if not config_path.is_file():
+            report("fast-check-config-scaffold: install did not scaffold keel/config.yaml.")
+            return 1
+        scaffolded = config_path.read_text(encoding="utf-8")
+        for needle in ("fast_check", "keel gate change-close", "--with-git-hooks"):
+            if needle not in scaffolded:
+                report(
+                    "fast-check-config-scaffold: scaffolded keel/config.yaml lacks the "
+                    f"fast_check guidance marker: {needle}"
+                )
+                return 1
+
+        # A project's own edits to keel/config.yaml must survive re-install.
+        edited = "fast_check: pytest -m 'not slow' -q\n"
+        config_path.write_text(edited, encoding="utf-8")
+        second = run_keel(repo, "--install")
+        if second.returncode != 0:
+            report("fast-check-config-scaffold: second keel --install failed.")
+            report((second.stderr or second.stdout).strip())
+            return 1
+        if config_path.read_text(encoding="utf-8") != edited:
+            report(
+                "fast-check-config-scaffold: re-install overwrote an existing "
+                "keel/config.yaml."
+            )
+            return 1
+
+    report("fast-check-config-scaffold scenario passed.")
+    return 0
+
+
+def validate_fast_pre_push_hooks_scenario() -> int:
+    def git(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["git", "-C", str(repo), *args], capture_output=True, text=True
+        )
+
+    def init_repo(root: Path, name: str) -> Path:
+        repo = root / name
+        repo.mkdir()
+        git(repo, "init", "-q")
+        git(repo, "config", "user.email", "t@example.com")
+        git(repo, "config", "user.name", "keel-test")
+        return repo
+
+    def declare_fast_check(repo: Path, command: str) -> None:
+        (repo / "keel").mkdir(exist_ok=True)
+        (repo / "keel" / "config.yaml").write_text(
+            f"fast_check: {command}\n", encoding="utf-8"
+        )
+
+    def hooks_path(repo: Path) -> str | None:
+        got = git(repo, "config", "--local", "--get", "core.hooksPath")
+        return got.stdout.strip() if got.returncode == 0 else None
+
+    with tempfile.TemporaryDirectory(prefix="keel-prepush-") as raw_tmp:
+        root = Path(raw_tmp)
+
+        # 1. A declared fast_check generates the hook and sets hooksPath.
+        declared = init_repo(root, "declared")
+        declare_fast_check(declared, "echo fast-check-ran")
+        res = run_keel(declared, "--install", "--with-git-hooks")
+        if res.returncode != 0:
+            report("fast-pre-push-hooks: --with-git-hooks failed with a declared fast_check.")
+            report((res.stderr or res.stdout).strip())
+            return 1
+        hook = declared / ".githooks" / "pre-push"
+        if not hook.is_file():
+            report("fast-pre-push-hooks: --with-git-hooks did not write .githooks/pre-push.")
+            return 1
+        hook_text = hook.read_text(encoding="utf-8")
+        if not hook_text.startswith("#!/bin/sh") or "echo fast-check-ran" not in hook_text:
+            report("fast-pre-push-hooks: pre-push does not run the declared fast_check under sh.")
+            report(hook_text)
+            return 1
+        if hooks_path(declared) != ".githooks":
+            report("fast-pre-push-hooks: --with-git-hooks did not set core.hooksPath to .githooks.")
+            return 1
+
+        # 2. A plain install touches neither the hook nor git config.
+        plain = init_repo(root, "plain")
+        declare_fast_check(plain, "echo plain")
+        if run_keel(plain, "--install").returncode != 0:
+            report("fast-pre-push-hooks: plain install failed.")
+            return 1
+        if (plain / ".githooks" / "pre-push").exists():
+            report("fast-pre-push-hooks: plain install wrote a pre-push hook.")
+            return 1
+        if hooks_path(plain) is not None:
+            report("fast-pre-push-hooks: plain install set core.hooksPath.")
+            return 1
+
+        # 3. Without a declared fast_check the flag refuses and writes nothing.
+        undeclared = init_repo(root, "undeclared")
+        res = run_keel(undeclared, "--install", "--with-git-hooks")
+        if res.returncode == 0:
+            report("fast-pre-push-hooks: --with-git-hooks did not refuse without a fast_check.")
+            return 1
+        if (undeclared / ".githooks" / "pre-push").exists():
+            report("fast-pre-push-hooks: a refusal still wrote a pre-push hook.")
+            return 1
+        if hooks_path(undeclared) is not None:
+            report("fast-pre-push-hooks: a refusal still set core.hooksPath.")
+            return 1
+
+        # 4a. Uninstall reverts a keel-set core.hooksPath.
+        if run_keel(declared, "--uninstall").returncode != 0:
+            report("fast-pre-push-hooks: uninstall failed.")
+            return 1
+        if hooks_path(declared) is not None:
+            report("fast-pre-push-hooks: uninstall did not unset a keel-set core.hooksPath.")
+            return 1
+
+        # 4b. Uninstall leaves a non-.githooks core.hooksPath untouched.
+        custom = init_repo(root, "custom")
+        git(custom, "config", "--local", "core.hooksPath", ".customhooks")
+        if run_keel(custom, "--uninstall").returncode != 0:
+            report("fast-pre-push-hooks: uninstall failed on a custom hooksPath repo.")
+            return 1
+        if hooks_path(custom) != ".customhooks":
+            report("fast-pre-push-hooks: uninstall clobbered a non-keel core.hooksPath.")
+            return 1
+
+    report("fast-pre-push-hooks scenario passed.")
+    return 0
+
+
+def validate_fast_pre_push_doctor_scenario() -> int:
+    def git(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["git", "-C", str(repo), *args], capture_output=True, text=True
+        )
+
+    def init_repo(root: Path, name: str) -> Path:
+        repo = root / name
+        repo.mkdir()
+        git(repo, "init", "-q")
+        git(repo, "config", "user.email", "t@example.com")
+        git(repo, "config", "user.name", "keel-test")
+        return repo
+
+    with tempfile.TemporaryDirectory(prefix="keel-prepush-doc-") as raw_tmp:
+        root = Path(raw_tmp)
+
+        # Surface active: fast_check declared and --with-git-hooks applied.
+        active = init_repo(root, "active")
+        (active / "keel").mkdir()
+        (active / "keel" / "config.yaml").write_text(
+            "fast_check: echo doc-check\n", encoding="utf-8"
+        )
+        if run_keel(active, "--install", "--with-git-hooks").returncode != 0:
+            report("fast-pre-push-doctor: install --with-git-hooks failed.")
+            return 1
+        before = git(active, "config", "--local", "--get", "core.hooksPath").stdout.strip()
+        out = run_keel(active, "--doctor").stdout
+        for needle in (
+            "Fast pre-push surface:",
+            "fast_check: ok",
+            "echo doc-check",
+            "pre-push hook: ok",
+            "core.hooksPath: ok",
+        ):
+            if needle not in out:
+                report(f"fast-pre-push-doctor: active-surface doctor output lacks: {needle}")
+                report(out)
+                return 1
+        after = git(active, "config", "--local", "--get", "core.hooksPath").stdout.strip()
+        if before != after:
+            report("fast-pre-push-doctor: doctor mutated core.hooksPath.")
+            return 1
+
+        # Surface absent: plain install, no fast_check, no hook.
+        absent = init_repo(root, "absent")
+        if run_keel(absent, "--install").returncode != 0:
+            report("fast-pre-push-doctor: plain install failed.")
+            return 1
+        out = run_keel(absent, "--doctor").stdout
+        for needle in ("fast_check: none", "pre-push hook: none", "core.hooksPath: unset"):
+            if needle not in out:
+                report(f"fast-pre-push-doctor: absent-surface doctor output lacks: {needle}")
+                report(out)
+                return 1
+
+    report("fast-pre-push-doctor scenario passed.")
+    return 0
+
+
+def validate_verify_layer_tag_scenario() -> int:
+    fixture = (
+        "# Tasks\n\n"
+        "- [ ] 1.1 Exercise the verification-layer tag\n"
+        "  - Covers:\n"
+        "    - E1: Public behavior passes.\n"
+        "  - Read:\n"
+        "    - README.md\n"
+        "  - Touch:\n"
+        "    - src/feature.js\n"
+        "  - Verify:\n"
+        "    - Strategy: evidence-first\n"
+        "    - M1 (fast): node fast.js\n"
+        "    - M2: node full.js\n"
+        "  - Autonomy boundary:\n"
+        "    - Default: hard-stop\n"
+        "    - Pre-authorized fallback: none\n"
+        "  - Stop Rules:\n"
+        "    - Stop on failure.\n"
+        "  - Evidence:\n"
+        "    - M1: pending\n"
+        "    - M2: pending\n"
+        "  - Stop if:\n"
+        "    - Requires files outside Touch.\n"
+    )
+    with tempfile.TemporaryDirectory(prefix="keel-verify-layer-") as raw_tmp:
+        repo = Path(raw_tmp)
+        write_text(repo / "openspec/changes/demo/tasks.md", fixture)
+        started = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1", "--json"
+        )
+        if started.returncode != 0:
+            report("verify-layer-tag: task-start rejected the tagged fixture.")
+            report((started.stderr or started.stdout).strip())
+            return 1
+        capsule = json.loads(started.stdout).get("contract", {}).get("capsule", {})
+        commands = capsule.get("verification", {}).get("commands", [])
+        by_label = {c.get("label"): c for c in commands}
+        if by_label.get("M1", {}).get("layer") != "fast":
+            report("verify-layer-tag: the (fast)-tagged check did not compile with layer fast.")
+            report(json.dumps(commands))
+            return 1
+        if "layer" in by_label.get("M2", {}):
+            report(
+                "verify-layer-tag: an untagged check emitted a layer field; full is "
+                "the implicit default and must stay off the capsule."
+            )
+            report(json.dumps(commands))
+            return 1
+        if (
+            by_label.get("M1", {}).get("check") != "node fast.js"
+            or by_label.get("M2", {}).get("check") != "node full.js"
+        ):
+            report("verify-layer-tag: the layer tag altered the check text.")
+            report(json.dumps(commands))
+            return 1
+
+    report("verify-layer-tag scenario passed.")
+    return 0
+
+
 def validate_native_goal_gate_order_scenario() -> int:
     with tempfile.TemporaryDirectory(prefix="keel-goal-order-") as raw_tmp:
         root = Path(raw_tmp)
@@ -10104,6 +10395,11 @@ SCENARIOS: tuple = (
     ("doctor-openspec-honesty", validate_doctor_openspec_honesty_scenario),
     ("update-pack-install", validate_update_pack_install_scenario),
     ("update-default-registry", validate_update_default_registry_scenario),
+    ("verification-layering-docs", validate_verification_layering_docs_scenario),
+    ("fast-check-config-scaffold", validate_fast_check_config_scaffold_scenario),
+    ("fast-pre-push-hooks", validate_fast_pre_push_hooks_scenario),
+    ("fast-pre-push-doctor", validate_fast_pre_push_doctor_scenario),
+    ("verify-layer-tag", validate_verify_layer_tag_scenario),
     ("task-contract-core", validate_task_contract_core_scenario),
     ("task-capsule", validate_task_capsule_scenario),
     ("task-verification-strategies", validate_task_verification_strategies_scenario),

package/src/core/task-contract.js

@@ -123,10 +123,12 @@ function verification(task) {
     ? compact.filter((entry) => !/^Strategy:\s*/i.test(entry))
     : fieldValues(task, "Commands");
   const commands = commandSource.map((entry) => {
-    const match = entry.match(/^(M[1-9]\d*):\s*(.*)$/);
+    // An optional (fast)/(full) layer tag after the M<n> label marks which
+    // checks the fast inner loop runs; an untagged check is full.
+    const match = entry.match(/^(M[1-9]\d*)(?:\s*\((fast|full)\))?:\s*(.*)$/);
     return match
-      ? { label: match[1], check: normalizeText(match[2]) }
-      : { label: null, check: entry };
+      ? { label: match[1], layer: match[2] || "full", check: normalizeText(match[3]) }
+      : { label: null, layer: "full", check: entry };
   });
   return {
     compact: compact.length > 0,
@@ -678,7 +680,15 @@ function compileTaskContract(repo, change, task) {
     acceptance: [...new Set([...derivedAcceptance, ...explicitAcceptance])],
     verification: {
       strategy: taskVerification.strategy,
-      commands: taskVerification.commands.filter((entry) => entry.label),
+      // Emit the layer only when a check opts into the fast inner loop, so
+      // untagged (full) checks keep their existing capsule shape and fingerprint.
+      commands: taskVerification.commands
+        .filter((entry) => entry.label)
+        .map((entry) =>
+          entry.layer && entry.layer !== "full"
+            ? { label: entry.label, check: entry.check, layer: entry.layer }
+            : { label: entry.label, check: entry.check }
+        ),
     },
     boundaries: {
       autonomy,