@christang/keel 5.2.0 → 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.0 -->
+<!-- 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/design.md

@@ -21,7 +21,7 @@ Ordinary narrative stays unnumbered. -->
 ## Hidden Knowledge / Assumptions
 
 <!-- Accepted hidden-knowledge assumptions from risk-triggered grill or domain
-profiles. Critical assumptions use A<n>, record Basis, and name Resolve by or a
+lenses. Critical assumptions use A<n>, record Basis, and name Resolve by or a
 durable Owner. Put compressed recovery context here when future sessions need
 it; keel/HANDOFF.md should only point to durable owners. Use "None." when empty. -->
 

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

@@ -47,7 +47,7 @@ const {
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const PACKAGE_JSON = require(path.join(PACKAGE_ROOT, "package.json"));
 const INSTALL_SCRIPT = path.join(PACKAGE_ROOT, "scripts", "install_to_repo.py");
-const DEFAULT_UPDATE_SOURCE = "github:TanglmChris/keel";
+const DEFAULT_UPDATE_SOURCE = "@christang/keel";
 const VALID_TARGETS = new Set(["claude", "codex", "opencode", "both"]);
 const KEEL_SKILLS = [
   "keel-align-expectations",
@@ -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) {
@@ -378,8 +384,8 @@ function parseArgs(argv) {
     if (arg === "--profile" || arg.startsWith("--profile=")) {
       fail(
         "--profile is no longer supported: web, hardware, and hardware-dsl "
-          + "guidance is bundled with the keel-align-expectations skill as "
-          + "on-demand references"
+          + "guidance is now user-authored lenses in keel/lenses/*.md "
+          + "(scaffold with `keel lenses add`)"
       );
     }
     if (arg === "--repo") {
@@ -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.0",
+  "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.0",
+  "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.0",
+  "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,10 +1145,18 @@ 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",
-        help="Obsolete in v4; domain references are bundled with keel-align-expectations.",
+        help="Obsolete; domain guidance is now user-authored lenses in keel/lenses/*.md.",
     )
     args = parser.parse_args()
 
@@ -1019,8 +1165,8 @@ def main() -> int:
         if args.profile:
             print(
                 "Install failed: --profile is no longer supported; web, hardware, "
-                "and hardware-dsl guidance is bundled with the "
-                "keel-align-expectations skill as on-demand references",
+                "and hardware-dsl guidance is now user-authored lenses in "
+                "keel/lenses/*.md (scaffold with `keel lenses add`)",
                 file=sys.stderr,
             )
             return 1
@@ -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.0"
-PROTOCOL_VERSION = "5.2.0"
+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")
@@ -1750,23 +1750,23 @@ def validate_authoring_continuity_scenario() -> int:
     return 0
 
 
-def validate_domain_profiles_scenario() -> int:
+def validate_domain_lenses_scenario() -> int:
     plugin_skills_root = ROOT / PLUGIN_ROOT / "skills"
     if not (plugin_skills_root / "keel-align-expectations/SKILL.md").is_file():
-        report("domain-profiles scenario plugin misses the alignment skill")
+        report("domain-lenses scenario plugin misses the alignment skill")
         return 1
     lenses_root = ROOT / "assets/lenses"
     for template in ("web.md", "hardware.md", "hardware-dsl.md"):
         if not (lenses_root / template).is_file():
             report(
-                "domain-profiles scenario misses the shipped lens template: "
+                "domain-lenses scenario misses the shipped lens template: "
                 f"{template}"
             )
             return 1
     for legacy_skill in LEGACY_PROFILE_SKILLS:
         if (plugin_skills_root / legacy_skill).exists():
             report(
-                f"domain-profiles scenario plugin packages a legacy profile: {legacy_skill}"
+                f"domain-lenses scenario plugin packages a legacy profile: {legacy_skill}"
             )
             return 1
 
@@ -1776,20 +1776,20 @@ def validate_domain_profiles_scenario() -> int:
         repo.mkdir()
         install = run_keel(repo, "--install", "--target", "codex")
         if install.returncode != 0:
-            report("domain-profiles scenario default install failed:")
+            report("domain-lenses scenario default install failed:")
             report((install.stderr or install.stdout).strip())
             return 1
         if (repo / TARGET_SKILL_ROOTS["codex"]).exists():
             report(
-                "domain-profiles scenario thin install copied Keel skill trees; "
+                "domain-lenses scenario thin install copied Keel skill trees; "
                 "skills are plugin-owned in v4."
             )
             return 1
 
         rejected = run_keel(repo, "--install", "--target", "codex", "--profile", "web")
         rejected_text = (rejected.stderr or "") + (rejected.stdout or "")
-        if rejected.returncode == 0 or "bundled" not in rejected_text:
-            report("domain-profiles scenario still accepts --profile.")
+        if rejected.returncode == 0 or "keel/lenses" not in rejected_text:
+            report("domain-lenses scenario still accepts --profile.")
             report(rejected_text.strip())
             return 1
 
@@ -1801,7 +1801,7 @@ def validate_domain_profiles_scenario() -> int:
             or "Keel profiles" in doctor_text
         ):
             report(
-                "domain-profiles scenario doctor still reports profile state or "
+                "domain-lenses scenario doctor still reports profile state or "
                 "misses the native plugin surface."
             )
             report(doctor_text.strip())
@@ -1814,11 +1814,11 @@ def validate_domain_profiles_scenario() -> int:
             else ""
         )
         if uninstall.returncode != 0 or "keel:start" in agents_text:
-            report("domain-profiles scenario uninstall left the managed bootstrap.")
+            report("domain-lenses scenario uninstall left the managed bootstrap.")
             report((uninstall.stderr or uninstall.stdout).strip())
             return 1
 
-    report("domain-profiles scenario passed.")
+    report("domain-lenses scenario passed.")
     return 0
 
 
@@ -2396,6 +2396,42 @@ def validate_update_pack_install_scenario() -> int:
     return 0
 
 
+def validate_update_default_registry_scenario() -> int:
+    with tempfile.TemporaryDirectory(prefix="keel-update-default-") as raw_tmp:
+        tmp = Path(raw_tmp)
+        update = run_keel(tmp, "--update", "--dry-run")
+        if update.returncode != 0:
+            report("update-default-registry scenario keel --update --dry-run failed:")
+            report((update.stderr or update.stdout).strip())
+            return 1
+
+        pack_plan = (
+            "would run npm pack" in update.stdout
+            or "would run npm.cmd pack" in update.stdout
+        )
+        if not pack_plan:
+            report("update-default-registry scenario did not report a pack plan.")
+            report(update.stdout.strip())
+            return 1
+        if "@christang/keel" not in update.stdout:
+            report(
+                "update-default-registry scenario default source is not the "
+                "published registry package @christang/keel."
+            )
+            report(update.stdout.strip())
+            return 1
+        if "github:" in update.stdout:
+            report(
+                "update-default-registry scenario default source is a git-type "
+                "spec; self-update must default to the registry package."
+            )
+            report(update.stdout.strip())
+            return 1
+
+    report("update-default-registry scenario passed.")
+    return 0
+
+
 def run_keel_hook(repo: Path, event: dict) -> subprocess.CompletedProcess[str]:
     env = dict(os.environ)
     env["KEEL_CLI"] = str(ROOT / "bin/keel.js")
@@ -2642,7 +2678,7 @@ def validate_cli_scenario() -> int:
         if (
             update.returncode != 0
             or not pack_plan
-            or "github:TanglmChris/keel" not in update.stdout
+            or "@christang/keel" not in update.stdout
             or not install_plan
         ):
             report("cli scenario keel --update did not report global CLI update plan.")
@@ -5184,6 +5220,107 @@ def validate_core_gates_scenario() -> int:
     return 0
 
 
+def validate_scope_rename_attribution_scenario() -> int:
+    rename_task = (
+        "# Tasks\n\n"
+        "- [ ] 1.1 Complete behavior\n"
+        "  - Owner: keel-agent\n"
+        "  - Mode: implementation\n"
+        "  - Covers:\n"
+        "    - E1: public behavior\n"
+        "  - Read:\n"
+        "    - README.md\n"
+        "  - Touch:\n"
+        "    - src/renamed-from.js\n"
+        "    - src/renamed-to.js\n"
+        "    - openspec/changes/demo/tasks.md\n"
+        "  - Commands:\n"
+        "    - M1: node test.js\n"
+        "  - Acceptance:\n"
+        "    - Public behavior passes.\n"
+        "  - Autonomy boundary:\n"
+        "    - Default: hard-stop\n"
+        "    - Pre-authorized fallback: none\n"
+        "  - Coupling: none\n"
+        "  - Candidate Boundary:\n"
+        "    - One complete candidate reaches M1.\n"
+        "  - Stop Rules:\n"
+        "    - Stop on final assertion failure.\n"
+        "  - Evidence:\n"
+        "    - M1: passed\n"
+        "    - Review:\n"
+        "      - Status: pass\n"
+        "      - Acceptance check: public behavior reviewed\n"
+        "      - Scope check: Touch reviewed semantically\n"
+        "      - Findings: none\n"
+        "    - Blocker: none\n"
+        "  - Stop if:\n"
+        "    - Requires files outside Touch.\n"
+        "  - Report:\n"
+        "    - Summary\n"
+    )
+    with tempfile.TemporaryDirectory(prefix="keel-scope-rename-") as raw_tmp:
+        repo = Path(raw_tmp)
+        write_text(repo / "openspec/changes/demo/tasks.md", rename_task)
+        write_text(repo / "src/renamed-from.js", "module.exports = 1;\n")
+        write_text(repo / "README.md", "readme\n")
+        for args in (
+            ["init", "--quiet"],
+            ["config", "user.email", "keel@example.invalid"],
+            ["config", "user.name", "Keel Fixture"],
+            ["add", "."],
+            ["commit", "--quiet", "-m", "baseline"],
+        ):
+            result = subprocess.run(
+                ["git", *args], cwd=repo, capture_output=True, text=True
+            )
+            if result.returncode != 0:
+                report("scope-rename scenario git setup failed:")
+                report((result.stderr or result.stdout).strip())
+                return 1
+        # A staged rename whose old and new paths are both in Touch must not be a
+        # false outside-Touch failure (git reports it as one `old -> new` entry).
+        moved = subprocess.run(
+            ["git", "mv", "src/renamed-from.js", "src/renamed-to.js"],
+            cwd=repo,
+            capture_output=True,
+            text=True,
+        )
+        if moved.returncode != 0:
+            report("scope-rename scenario git mv failed:")
+            report((moved.stderr or moved.stdout).strip())
+            return 1
+        completed = run_keel(
+            repo,
+            "gate",
+            "task-complete",
+            "--change",
+            "demo",
+            "--task",
+            "1.1",
+            "--base",
+            "HEAD",
+            "--json",
+        )
+        payload = json.loads(completed.stdout or "{}")
+        outside = " ".join(
+            problem.get("message", "") for problem in payload.get("problems", [])
+        )
+        if (
+            completed.returncode != 0
+            or payload.get("status") != "pass"
+            or "outside" in outside.lower()
+        ):
+            report(
+                "scope-rename scenario reported a false outside-touch failure for a "
+                "git mv rename whose old and new paths are both in Touch."
+            )
+            report((completed.stderr or completed.stdout).strip())
+            return 1
+    report("scope-rename scenario passed.")
+    return 0
+
+
 def validate_target_capability_adapters_scenario() -> int:
     capability_keys = (
         "continuity.start",
@@ -7550,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)
@@ -9950,6 +10378,7 @@ def validate_doctor_openspec_honesty_scenario() -> int:
 SCENARIOS: tuple = (
     ("stateless-continuity", validate_stateless_continuity_scenario),
     ("core-gates", validate_core_gates_scenario),
+    ("scope-rename-attribution", validate_scope_rename_attribution_scenario),
     ("target-capability-adapters", validate_target_capability_adapters_scenario),
     ("native-runtime-projection", validate_native_runtime_projection_scenario),
     ("target-surface", validate_target_surface_scenario),
@@ -9957,7 +10386,7 @@ SCENARIOS: tuple = (
     ("expectation-slice-gates", validate_expectation_slice_gates_scenario),
     ("expectation-completion-gates", validate_expectation_completion_gates_scenario),
     ("authoring-continuity", validate_authoring_continuity_scenario),
-    ("domain-profiles", validate_domain_profiles_scenario),
+    ("domain-lenses", validate_domain_lenses_scenario),
     ("skill-portability-policy", validate_skill_portability_policy_scenario),
     ("version-alignment", validate_version_alignment_scenario),
     ("openspec-surface-overlay", validate_openspec_surface_overlay_scenario),
@@ -9965,6 +10394,12 @@ SCENARIOS: tuple = (
     ("cli", validate_cli_scenario),
     ("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/gates.js

@@ -237,7 +237,16 @@ function gitPaths(repo) {
   return status.stdout
     .split(/\r?\n/)
     .filter(Boolean)
-    .map((line) => line.slice(3).trim().replace(/\\/g, "/"));
+    .flatMap((line) => {
+      // A staged rename/copy is one porcelain line, `R  old -> new`; attribute
+      // both endpoints so a rename whose old and new paths are in Touch is not
+      // a false outside-Touch failure. Every other line carries one path.
+      const entry = line.slice(3).trim().replace(/\\/g, "/");
+      const arrow = entry.indexOf(" -> ");
+      return arrow === -1
+        ? [entry]
+        : [entry.slice(0, arrow), entry.slice(arrow + 4)];
+    });
 }
 
 function touchEntries(task, contract = null) {

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,