@christang/keel 5.1.2 → 5.2.1

package/README.zh-CN.md

@@ -8,71 +8,59 @@
 ![Node](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen.svg)
 ![Targets](https://img.shields.io/badge/targets-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20OpenCode-blue.svg)
 
-Keel 在 [OpenSpec](https://github.com/fission-ai/openspec) 之上加一层轻量、确定性的执行纪律，
-让编码 agent 在**稳定、可校验的边界**内完成「判断 → 设计 → 执行 → review → 交接」，
-而不是中途跑偏或在会话之间丢失上下文。
-
-Keel **无状态**：每次会话都从你的 OpenSpec artifacts 和 Git 重新推导「现在该做什么」，
-绝不依赖隐藏的对话记忆、transcript 或某个存下来的「当前任务」。这让 agent 的工作可恢复、
-可审计，并且能安全地在不同 runtime 之间交接。
-
-> 这是完整中文手册。速览请看英文 [README](README.md)。
-
----
-
-## 为什么用 Keel
-
-- **确定性门禁，而不是凭感觉。** `keel gate task-start | task-complete | change-close`
-  做本地、无模型的结构检查，返回 `pass` / `fail` / `needs-review` 和真实退出码。它们从不声称
-  判断你的设计是否*正确*——只判断契约与证据是否齐备。
-- **真正的写入守卫（Claude）。** 通过的 `task-start` 会落下一次性 manifest，插件的 `PreToolUse`
-  hook 随后**确定性拒绝**任何超出任务声明 `Touch` 范围的 `Edit`/`Write`——把「请别越界」从
-  祈祷变成执法。
-- **无状态连续性。** `keel context` 每次都从 OpenSpec + Git 重建选中任务、下一步动作和最小读取
-  列表。能扛住 compaction、`/clear` 和冷启动。`keel/HANDOFF.md` 只作为可选的、经校验的覆盖存在。
-- **写代码前先对齐预期。** `keel-align-expectations` 在 specs/tasks 定稿*之前*对齐隐性假设——
-  风险触发的 deep path 一次只问一个材料性决策，并把接受的答案写回 OpenSpec。
-- **单任务原生目标执行。** 授权 agent 自动执行**恰好一个** OpenSpec task——带指纹化 capsule、
-  硬停边界，没有隐藏调度器替你选下一个任务。
-- **一套纪律，三个 runtime。** 同一协议在 Claude Code、Codex、OpenCode 上运行；执行技能与 hook
-  以原生插件分发。
-
----
-
-## 工作流程
-
-```mermaid
-flowchart LR
-    A[keel --init] --> B[keel context]
-    B --> C[proposal / design / specs / tasks]
-    C --> D[keel-align-expectations]
-    D --> E[/opsx:apply → 选一个 task/]
-    E --> F[task-start<br/>+ 写入守卫]
-    F --> G[实现 · 测试先行 · 验证]
-    G --> H[keel-review-checklist]
-    H --> I[task-complete]
-    I --> J[/opsx:sync · /opsx:archive/]
-```
+## Keel 是做什么的
 
-OpenSpec 拥有持久 artifacts（proposal、design、specs、tasks、archive）；Keel 拥有它们周围的
-*执行纪律*：模式路由、任务 capsule 契约、确定性门禁、写入守卫、连续性、review 和交接卫生。
+[OpenSpec](https://github.com/fission-ai/openspec) 给项目一套 spec 驱动的工作流：proposal、
+design、specs、tasks，以及记录改动的 archive。Claude Code（或 Codex）提供干活的 agent。
+Keel 夹在两者中间，在 agent 走完一个 OpenSpec change 的过程中盯住它别跑偏。
 
----
+放任不管时，agent 容易漂移：改了任务没提到的文件、上下文重置后丢了线索、或者没有证据就把活
+勾成完成。Keel 加的是一层轻量、可校验的约束来防止这些，而且它尽量复用你已有的能力，而不是另造
+一套。
 
-## 环境要求
+Keel 加的东西：
 
-- **Node.js `>=20.19.0`**（内置的 OpenSpec CLI 要求此版本；更低版本可能触发 `EBADENGINE`）。
+- **无状态连续性**：`keel context` 每次会话都从 OpenSpec 和 Git 重算当前任务和下一步，所以工作
+  能扛住 `/clear`、compaction 和冷启动，不依赖对话记忆。
+- **确定性门禁**：`keel gate task-start | task-complete | change-close` 做本地结构检查，返回
+  `pass` / `fail` / `needs-review` 和真实退出码。它们只检查任务契约和证据是否齐备，不判断设计对错。
+- **写入守卫（Claude）**：`task-start` 之后，`PreToolUse` hook 会拒绝任何超出任务声明改动范围的
+  文件编辑。
+- **预期对齐**：在 specs 和 tasks 定稿前，Keel 把隐性假设摆出来，只针对真正会改变行为的那些提问。
 
----
+Keel 尽量借力原生能力，而不是重造。spec 工作流就是原生 OpenSpec；执行技能、SessionStart 连续性
+hook 和写入守卫 hook 都以一个普通的 Claude Code / Codex 插件分发。`keel --init` 只往你的 repo 里
+写一小块宿主面：`AGENTS.md` bootstrap 块、OpenSpec schema，以及 `/opsx:*` 命令的 Keel overlay。
+
+## 环境要求
+
+Node.js `>=20.19.0`（内置的 OpenSpec CLI 需要）。
 
 ## 安装
 
-Keel 有两个可安装部分：**`keel` CLI**（context、gates、guard、schema、安装）和
-**`keel` 插件**（执行技能 + 运行时 hook）。
+两部分：`keel` CLI 和 `keel` 插件。
 
-### 1. `keel` CLI
+**CLI** —— 一条命令（同时装上捆绑的 OpenSpec CLI）：
 
-从 GitHub 打包后全局安装，避免与已有全局旧包在 Git 依赖准备阶段冲突，并会一并装上 OpenSpec CLI。
+```bash
+npm install -g @christang/keel
+keel --version
+```
+
+**插件** —— 执行技能和运行时 hook：
+
+```bash
+claude plugin install keel@<marketplace>   # Claude Code
+codex plugin add keel@<marketplace>        # Codex
+```
+
+> 捆绑的 OpenSpec 依赖在安装时会打印一行 opt-in 的 shell 补全提示。如果你的 npm 拦截安装脚本，
+> 这行提示会被跳过，它纯属装饰，keel 照常工作。
+
+<details>
+<summary>从 GitHub 安装最新未发布版本</summary>
+
+打包当前 `main` 并安装该 tarball（跳过 npm registry）：
 
 **Windows（PowerShell）：**
 
@@ -93,101 +81,65 @@ npm pack github:TanglmChris/keel --pack-destination "$tmp_dir"
 npm install -g "$tmp_dir"/christang-keel-*.tgz
 rm -rf "$tmp_dir"
 ```
+</details>
 
-验证版本，之后可用 `keel --update` 自更新：
-
-```bash
-keel --version
-keel --update            # 重新打包 + 重装全局 CLI
-keel --update --dry-run  # 先看将执行的 npm 命令
-```
-
-### 2. `keel` 插件（技能 + hook）
+## 怎么用
 
-执行技能（`keel-*`）和运行时 hook（SessionStart 连续性、PreToolUse 写入守卫）以原生插件分发，
-**不会**被 `keel --init` 复制进你的 repo：
-
-```bash
-claude plugin install keel@<marketplace>   # Claude Code
-codex plugin add keel@<marketplace>        # Codex
-```
-
----
-
-## 快速开始
-
-在目标项目根目录：
+在项目根目录，先设置一次：
 
 ```bash
 keel --init                 # 默认 target：claude
-keel --init --target codex
-keel --init --target opencode
+keel --init --target codex  # 或 opencode
 ```
 
-`keel --init` 会运行 OpenSpec 初始化/更新并安装 Keel 的精简宿主面。之后每次开始或恢复工作：
+`keel --init` 会跑 OpenSpec 初始化/更新，并写入 Keel 的宿主面。之后每次开始或恢复工作：
 
 ```bash
-keel context                # 或 keel context --json
+keel context                # 现在该做什么，从 OpenSpec + Git 重算
+keel --doctor               # 检查各部分是否就位
 ```
 
-它返回 `ready` / `ambiguous` / `blocked` / `idle`，附带 selection、下一动作和最小读取列表。
-随时检查完整就绪状态：
+spec 相关的活走 OpenSpec 的命令（`/opsx:propose`、`/opsx:apply`、`/opsx:sync`、`/opsx:archive`），
+Keel 的门禁在任务边界处运行。整个回路：
 
-```bash
-keel --doctor
+```
+keel --init  →  keel context  →  /opsx:apply（选一个 task）
+   →  task-start（+ 写入守卫）  →  实现并验证
+   →  task-complete  →  /opsx:sync · /opsx:archive
 ```
 
-### `--init` 会写入什么
-
-`keel --init` / `--install` 只保留**精简宿主面**——不复制技能或 hook（那些来自插件）：
-
-- `AGENTS.md` —— Keel bootstrap 块（所有 target）
-- `CLAUDE.md` —— `@AGENTS.md` import 块（Claude target）
-- `openspec/config.yaml` —— 设置 `schema: keel-spec-driven`
-- `openspec/schemas/keel-spec-driven/` —— Keel 强化过的 OpenSpec schema
-- 以及 OpenSpec 生成并叠加 Keel overlay 的 `/opsx:*` 命令面
-
-若目标 repo 里存在旧版打包的 `keel-*` skill、`keel-adapter.js` 或 `keel-gate` hook，
-`--install` 会迁移它们：与旧打包字节一致的副本被移除并提示改由原生插件提供，用户改过的副本
-原样保留并给出手动迁移警告。
-
----
-
-## 目标（Targets）
-
-| target | 初始化命令 | 命令面 |
-| --- | --- | --- |
-| Claude Code | `keel --init` | `.claude/commands/opsx/*.md` + 插件 hook（SessionStart、PreToolUse 守卫） |
-| Codex | `keel --init --target codex` | 全局 `CODEX_HOME/prompts/opsx-*.md` |
-| OpenCode | `keel --init --target opencode` | 项目内 `.opencode/commands/opsx-*.md` |
-
-一个 repo 通常固定一个 target，后续 `--install` / `--check` / `--doctor` / `--uninstall` 都用它。
-能力**按可观察证据探测，不按 target 名字假定**——无法验证的运行时行为报告为 `manual`，而非 `enforced`。
+### Full / Lite
 
----
+**Full 模式**（上面的 OpenSpec 流程）用于新功能、接口或协议变更、跨模块，或超过约 3 文件 / 100 行
+的改动。被接受的原生 `plan mode` 产物只是会话态：其中影响 scope、完成定义或执行边界的决策，必须
+在实现前固化到 `proposal/design/specs/tasks`，session plan 本身不是执行权威。
 
-## Full / Lite 模式
+**Lite 模式**用于局部小改：单点修复、小脚本、文档或补测试，不改接口、影响可局部证明；Lite 默认不
+写 OpenSpec 状态。
 
-**Full 模式**——新功能、对外接口变更、跨模块、改动超过 3 文件 / 100 行、架构或协议/状态机决策，
-或任何触及信号、reset、CDC、安全边界的硬件工作。Full 模式用 OpenSpec 走
-proposal → design → specs → tasks → archive。
+## 这些命令，agent 是怎么用起来的
 
-被接受的原生 `plan mode` 产物只是会话态：其中影响 scope、Acceptance、完成定义或执行边界的决策，
-必须在进入实现前固化到 `proposal/design/specs/tasks`；session plan 永远不是执行权威（review
-checklist 会检查这条通道）。
+下面这些命令你几乎不用手敲。Keel 的意义在于纪律会自己跑起来：`keel --init` 把它装进 agent 的
+工作流，agent 会在恰当的时刻去调用每一条命令。让这件事成立的有三样东西。
 
-**Lite 模式**——仅限局部小改：单点修复、小脚本、文档或补测试，不改对外接口、不加依赖、不引入新
-设计决策、影响面可局部证明。Lite 默认不写 OpenSpec 状态。
+- **协议**：`keel --init` 会往你 repo 的 `AGENTS.md` 写一段 bootstrap 块（在 Claude 上由
+  `CLAUDE.md` 引入）。它把 agent 要遵守的规则讲清楚：每次会话先跑 `keel context`、在任务边界处过
+  门禁、只在任务声明的写入范围内改文件。这就是 agent 知道**何时**用哪条命令的来源。
+- **技能**：`keel-*` 执行技能和 `/opsx:*` 命令 overlay 带着 agent 走「对齐 → apply → review →
+  完成」，每一步按需调用门禁。
+- **hook**：SessionStart hook 在会话打开的那一刻自动跑连续性投影；PreToolUse hook 在每次编辑时
+  执行写入守卫。两者都不需要任何提示。
 
----
+所以日常使用里你真正要敲的只有两条：装配时的 `keel --init`，以及想体检时的 `keel --doctor`。
+下面列出的，是 agent 替你使用的「命令词汇表」。
 
-## 核心命令
+## 命令参考
 
 ```bash
-# 连续性 —— 无状态地重算「现在该做什么」
+# 连续性 —— 无状态重算「现在该做什么」
 keel context [--json] [--change <c> --task <t>]
 
-# 确定性门禁（schemaVersion 1 → pass | fail | needs-review）
+# 确定性门禁 → pass | fail | needs-review
 keel gate task-start    --change <c> --task <t> --json
 keel gate task-complete --change <c> --task <t> [--base <git-ref>] --json
 keel gate change-close  --change <c> --action sync|archive --json
@@ -197,99 +149,68 @@ keel guard start --change <c> --task <t> --json
 keel guard status --json
 keel guard clear  --json
 
-# 一次性原生投影（视图，永不是权威）
-keel project --target claude --event resume --change <c> --task <t> --json
-keel project tasks [repo] --target claude [--change <c>] [--json]
+# 一次性原生投影（只读视图，永不是权威）
+keel project tasks --target claude [--change <c>] [--json]
 keel project --target codex --event compaction --json
 
 # 安装 / 维护
-keel --init | --install | --check | --doctor | --uninstall   [--target <t>] [--dry-run]
+keel --init | --install | --check | --doctor | --uninstall  [--target <t>] [--dry-run]
 keel --update [--dry-run]
 keel --version | --help
 ```
 
-退出码：`0` 通过 · `3` 确定性策略失败 · `4` 缺少语义 review · `1` 输入/解析故障。
-
-### 写入守卫（Claude target）
+退出码：`0` 通过 · `3` 策略失败 · `4` 缺少语义 review · `1` 输入/解析故障。
 
-Touch 是唯一写权限来源。通过的 `keel gate task-start` 默认写入一次性守卫 manifest
-（`keel guard start` 显式激活、`keel guard clear` 停止执法、`--no-guard` 退出默认激活）。
-守卫激活期间，插件的 `PreToolUse` hook 确定性拒绝 Touch 之外的文件编辑，并带出精确路径与恢复命令：
-
-- manifest 记录 change/task、capsule 指纹、规范化 Touch 和权威文件哈希，存于 `guard.json`；
-  失败即关闭（fail-closed）：损坏、哈希漂移、指纹不匹配或 task 已勾选时一律拒绝。
-- 守卫只覆盖文件编辑工具；`Bash` 等间接写入仍属纪律约束，仓库外的临时/scratch 路径直接放行。
+能力按可观察证据探测，不按 target 名字假定：无法验证的运行时行为报告为 `manual`，而非 `enforced`。
+一个 repo 固定一个 target，后续 `--install` / `--check` / `--doctor` / `--uninstall` 都用它。
 
-### 一次性原生投影
+### 写入守卫
 
-`keel project` 从当前 OpenSpec task 编译一次性视图（objective、Acceptance、Stop 边界、Read、Touch、
-evidence contract），永远只是投影、不是权威，也不勾选复选框：
+Touch 是唯一写权限来源。通过的 `keel gate task-start` 默认写入一次性守卫 manifest
+（`keel guard start` 显式激活、`keel guard clear` 停止执法、`--no-guard` 退出默认激活）。守卫
+激活时，`PreToolUse` hook 确定性拒绝 Touch 之外的文件编辑，并给出精确路径和恢复命令：
 
-- `keel project tasks --target claude` 把选中 change 的 tasks.md 编译成只读清单视图，由当前 agent
-  自行决定是否手动镜像到宿主任务 UI；只读、不落盘、无同步循环。
-- compaction 后手动重注入：`keel project --target codex --event compaction --json`。
+- manifest 记录 change/task、capsule 指纹、规范化 Touch 和权威文件哈希，存于 `guard.json`，
+  fail-closed：损坏、哈希漂移、指纹不匹配或 task 已勾选时一律拒绝。
+- 守卫只覆盖文件编辑工具；`Bash` 等间接写入仍受纪律约束，仓库外的临时路径直接放行。
 
----
+### 一次性投影
 
-## 对齐与纪律
+`keel project tasks --target claude` 把选中 change 的 tasks.md 编译成只读清单视图，由当前 agent
+自行决定是否手动镜像到宿主任务 UI，只读、不落盘、无同步循环。compaction 后可手动重注入：
+`keel project --target codex --event compaction --json`。
 
-- **`keel-align-expectations`**：SPEC 前的隐性知识风险用 risk-triggered deep alignment（一次一个
-  决策、给推荐答案），而不是对所有 Full change 强制问卷；先查仓库事实再问用户，接受的结论写回
-  proposal/design/specs/tasks。v5 已退役旧的 grill 问答技能，深度对齐统一由该技能承担。
-- **执行/review 阶段的领域引用**：web / hardware / hardware-dsl 三个 reference 各带一节
-  `Execution and review checks`；当变更 artifacts 或 Touch 扩展名显示对应领域信号时，
-  `keel-tdd-or-test-first`、`keel-debug-failure`、`keel-review-checklist` 会按需查阅——仍然只
-  加载匹配的那一个。
-- **Dedicated Skill Policy**：新增或实质扩展专门技能时，先研究 first-party 或其他 authoritative source
-  并记录 provenance/license 影响；用真实的 `should-trigger` 与近邻 `should-not-trigger`
-  提示验证 description，并至少通过一个 real task 验证程序性行为；以 `src/skills/<name>/SKILL.md`
-  为唯一 portable 权威，target metadata 只是 additive adapter，discovery 与激活仍由 target-native
-  runtime 负责。
+## 对齐与技能纪律
 
-`/opsx:sync`、`/opsx:archive` 的完成门禁由确定性的 `keel gate change-close` 加
-`keel-review-checklist` 承担，不再由运行时 hook 执行（该门禁在所有 target 上能力为 `manual`）。
+- **`keel-align-expectations`**：specs/tasks 定稿前用风险触发的 deep alignment（一次一个决策、给
+  推荐答案）对齐隐性假设，而不是对所有 Full change 强制问卷；先查仓库事实再问用户，接受的结论写回
+  `proposal/design/specs/tasks`。
+- **可插拔领域透镜**：keel 核心只保留机制，透镜内容由用户自己写在仓库的 `keel/lenses/*.md`。每份透镜
+  自描述——开头一行 `Applies when:` 声明触发信号，并含一节 `Execution and review checks`。当变更
+  artifacts 或 Touch 扩展名匹配某份透镜的 `Applies when:` 时，`keel-align-expectations`、
+  `keel-tdd-or-test-first`、`keel-debug-failure`、`keel-review-checklist` 按需只加载匹配的那一份，
+  没有匹配就不加载。`keel lenses list` 查看内置模板与已安装透镜；`keel lenses add web` 把内置模板
+  （web / hardware / hardware-dsl，随包放在 `assets/lenses/`）落到 `keel/lenses/` 后自行改写，
+  已存在时需 `--force` 才覆盖。
+- **专门技能政策**：新增或实质扩展技能前，先研究 first-party 或其他 authoritative source 并记录
+  provenance/license；用真实的 should-trigger 与近邻 `should-not-trigger` 用例验证 description，
+  并至少通过一个 real task；以 `src/skills/<name>/SKILL.md` 为唯一可移植权威，target metadata 只是
+  附加适配，discovery 与激活由 target-native runtime 负责。
 
----
+`/opsx:sync`、`/opsx:archive` 的完成门禁由 `keel gate change-close` 加 `keel-review-checklist`
+承担，不再由运行时 hook 执行（在所有 target 上能力为 `manual`）。
 
-## 开发与校验
+## 开发
 
-无构建步骤。`src/skills/` 是可移植技能的唯一维护源；`plugins/keel/skills/` 等分发副本必须与源
-字节一致（由校验强制）。修改后同步副本，然后运行：
+无构建步骤。`src/skills/` 是可移植技能的唯一维护源，`plugins/keel/skills/` 等分发副本必须与源
+字节一致（由校验强制）。
 
 ```bash
-npm run validate          # baseline 校验
-npm test                  # baseline + 全部场景并行（约 25s）
-
-# 单场景调试
-node scripts/run_python.js scripts/validate_plugin.py --scenario core-gates
-node scripts/run_python.js scripts/validate_plugin.py --all --jobs 4
-```
-
-`npm test` 是一条 `validate_plugin.py --all` 调用：先跑 baseline，再按内置 scenario registry
-并行跑全部场景（`--jobs N` 控制并发，默认 CPU 数），fail-loud 而非 fail-fast。新增场景只需写
-`validate_<name>_scenario()` 并加入 registry。
-
-### 目录结构
-
-```text
-bin/keel.js                # 跨平台 keel CLI
-src/core/                   # 无状态 Keel Core（context、gates、guard、goal、helper、projection）
-src/skills/                 # 可移植技能的唯一维护源（含 keel-align-expectations/references）
-plugins/keel/              # 原生插件（.claude-plugin / .codex-plugin、hooks、skills）
-assets/bootstrap/AGENTS.md  # managed bootstrap 块的唯一权威源
-assets/openspec/            # OpenSpec schema 资产
-scripts/                    # install_to_repo.py、validate_plugin.py、run_python.js
-openspec/                   # 本仓库自身的 OpenSpec 工作区
-keel/                      # 项目本地 Keel 状态（CHANGELOG、archive）
+npm test          # 一条 validate_plugin.py --all 调用：baseline + 全部场景并行（--jobs N 控制并发）
+node scripts/run_python.js scripts/validate_plugin.py --scenario core-gates   # 单场景调试
+node scripts/bump_version.js <patch|minor|major>                             # 一次改齐所有版本 pin
 ```
 
----
-
-## 文档
-
-- **[English README](README.md)** —— 速览与安装。
-- **[keel/CHANGELOG.md](keel/CHANGELOG.md)** —— 版本历史。
-
 ## License
 
-[MIT](LICENSE) © 2026 TanglmChris
+[MIT](LICENSE) © 2026 TanglmChris · 版本历史见 [keel/CHANGELOG.md](keel/CHANGELOG.md)。

package/assets/bootstrap/AGENTS.md

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

package/{plugins/keel/skills/keel-align-expectations/references → assets/lenses}/hardware-dsl.md

@@ -1,6 +1,8 @@
-# Hardware DSL alignment reference
+# Hardware DSL lens
 
-Domain lens for hardware modeling DSL work. Use during alignment when generated RTL, golden output, or model equivalence assumptions may be implicit.
+Applies when: the change touches a hardware modeling DSL, generated RTL, generated tests, golden output, or model equivalence — for example when Touch includes the DSL sources or their generated-RTL/test outputs, or the change artifacts describe regeneration, lowering, or equivalence.
+
+Domain lens for hardware modeling DSL work. Use during alignment, execution, and review when generated RTL, golden output, or model equivalence assumptions may be implicit.
 
 ## Material risk surface
 

package/{plugins/keel/skills/keel-align-expectations/references → assets/lenses}/hardware.md

@@ -1,6 +1,8 @@
-# Hardware alignment reference
+# Hardware lens
 
-Domain lens for Verilog/SystemVerilog work. Use during alignment when hardware protocol, timing, reset, or verification assumptions may be implicit.
+Applies when: the change touches Verilog/SystemVerilog interfaces, protocol, reset, clocking/CDC, valid-ready/backpressure, arbitration, CSR/register fields, or RTL verification — for example when Touch includes `.v`/`.sv`/`.vh`/`.svh` or the change artifacts describe a module interface, protocol, or testbench.
+
+Domain lens for Verilog/SystemVerilog work. Use during alignment, execution, and review when hardware protocol, timing, reset, or verification assumptions may be implicit.
 
 ## Material risk surface
 

package/{plugins/keel/skills/keel-align-expectations/references → assets/lenses}/web.md

@@ -1,6 +1,8 @@
-# Web alignment reference
+# Web lens
 
-Domain lens for web frontend/backend work. Use during alignment when UI, API, routing, persistence, or integration behavior may hide product assumptions.
+Applies when: the change touches UI, API, routing, auth/session, persistence, migrations, async/loading/error states, accessibility, or backend integration — for example when Touch includes `.tsx`/`.jsx`/`.ts`/`.js`/`.css`/`.html`/`.sql` or the change artifacts describe a route, endpoint, component, or schema.
+
+Domain lens for web frontend/backend work. Use during alignment, execution, and review when UI, API, routing, persistence, or integration behavior may hide product assumptions.
 
 ## Material risk surface
 

package/assets/openspec/schemas/keel-spec-driven/schema.yaml

@@ -99,7 +99,7 @@ artifacts:
       be covered by a slice, deferred to a durable owner, or explicitly
       discarded with rationale before the slice can be selected for execution.
       Accepted hidden-knowledge assumptions from risk-triggered deep
-      alignment or a domain reference are critical expectations when they
+      alignment or a domain lens are critical expectations when they
       affect completion definition or execution boundaries.
       Covers references the relevant D/F/A/Q identifiers. An unresolved Q<n>
       without an authorized fallback blocks implementation.
@@ -134,9 +134,15 @@ artifacts:
       outside Touch, broader design work, or an interface/security boundary
       change not covered by design.md, stop and report an Out-of-scope Need.
       Before task completion, Evidence records the current agent's semantic
-      Review with Status, Acceptance check, Scope check, and Findings. Findings
-      are `none` or name a durable OpenSpec/archive owner or discard rationale;
-      HANDOFF is never the owner.
+      Review with Status, Acceptance check, Scope check, and Findings. Status is
+      one of pass, passed, complete, completed, ok, or done. Findings
+      are `none` or carry a durable owner — a `Discard reason:`/`Discard
+      rationale:` prefix, a `keel/archive/…` path, or an existing
+      `openspec/changes/…` artifact; `keel/HANDOFF.md` is never the owner.
+      tasks.md ends with a `## Expectation Coverage` section that change-close
+      requires: one `- E<n>: <expectation> Covered by: <task ids>` line per
+      critical expectation (or a `Durable owner:` / `Discard reason:` closure),
+      or `- None.` when the change has no critical expectations.
     requires:
       - specs
       - design
@@ -152,7 +158,7 @@ apply:
     2. Select one unchecked task or a small contiguous group of unchecked tasks from tasks.md.
     3. Run the Task Authoring Gate: every relevant critical expectation must be covered by a selected slice, deferred to a durable owner, or explicitly discarded with rationale.
     4. Run the Slice Start Gate: every selected current slice must name source expectations and compile to a complete keel-task-capsule/v1 contract from its compact Covers, Touch, Verify, and Evidence fields plus any declared exceptional Mode, Read, Acceptance delta, Autonomy boundary, Coupling/Candidate Boundary, or Stop if clauses.
-    5. If a selected task lacks an execution contract, source expectations, or accepted hidden-knowledge assumptions raised by risk-triggered deep alignment or a domain reference, update OpenSpec first instead of dispatching implementation.
+    5. If a selected task lacks an execution contract, source expectations, or accepted hidden-knowledge assumptions raised by risk-triggered deep alignment or a domain lens, update OpenSpec first instead of dispatching implementation.
     6. Rough future slices may remain non-executable drafts, but they cannot be selected for implementation or marked complete.
     7. The current Keel agent remains task owner and executor. Treat any Execution recommendation as an advisory implementation note, not as a completion gate.
     8. Do not hand Keel-managed execution to another agent, subagent, or operator unless the selected task or user explicitly authorizes it. Keep task selection, implementation, verification, and failure recovery in the current agent conversation.

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

@@ -11,7 +11,7 @@
 
 - [ ] 1.1 <!-- Task description -->
   - Covers:
-    - <source expectation: spec scenario as `capability / requirement or scenario heading`, hidden-knowledge assumption, domain profile requirement, or critical D<n>/F<n>/A<n>/Q<n>; an unresolved Q<n> requires an authorized fallback>
+    - <source expectation: spec scenario as `capability / requirement or scenario heading`, hidden-knowledge assumption, domain lens requirement, or critical D<n>/F<n>/A<n>/Q<n>; an unresolved Q<n> requires an authorized fallback>
   - Touch:
     - <path>
   - Verify:
@@ -24,10 +24,11 @@
     - Strategy: <strategy>
     - M1: <public behavior check>
   - Evidence:
-    - Contract: pending task-start capsule and fingerprint
+    - Contract: pending
     - M1: pending
     - Review:
-      <!-- Findings: none, a durable OpenSpec/archive owner, or an explicit discard rationale -->
+      <!-- Status: one of pass, passed, complete, completed, ok, done -->
+      <!-- Findings: none, or carry a durable owner — a "Discard reason:"/"Discard rationale:" prefix, a keel/archive/… path, or an existing openspec/changes/… artifact; not keel/HANDOFF.md -->
       - Status: pending
       - Acceptance check: pending
       - Scope check: pending
@@ -58,7 +59,7 @@
     - Strategy: evidence-first
     - M1: <reproduction or diagnosis check with its observable evidence>
   - Evidence:
-    - Contract: pending task-start capsule and fingerprint
+    - Contract: pending
     - M1: pending
     - Review:
       - Status: pending
@@ -66,3 +67,11 @@
       - Scope check: pending
       - Findings: pending
     - Blocker: none
+
+## Expectation Coverage
+
+<!-- change-close requires this section. One line per critical expectation:
+     `- E1: the expectation Covered by: 1.1` (task ids that own it), or a
+     `Durable owner: openspec/changes/<change>/tasks.md` / `Discard reason: why`
+     closure. Use `- None.` only when the change has no critical expectations. -->
+- None.