@christang/keel 5.1.1 → 5.2.0

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.1 -->
+<!-- keel:start version=5.2.0 -->
 ## 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