---
name: scope-lock
description: A1 计划范围锁定——引导用户填写项目概述 + 技术栈 + 需求索引，并按模块子目录生成 REQ 卡片（CC 据 index.md 填 req_id/title/goal/rules/constraints/acceptance 这 6 个 `{{}}` 占位，模板其余内容含输入/输出示例字段表原样复制）；末尾执行 A1 终结校验：每张 REQ 卡片 6 个占位均填真实数据、全部配置锁进 config-vars.yaml（非敏感填值、敏感凭据留占位待人工填）、build/lint/unit/e2e 命令锁进 docs/04 §零，缺则当场 AskUserQuestion 问清。
user-invocable: false
allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *)
---

**所有输出必须使用中文。**

## 执行步骤

### A / B / C. 填写项目概述 / 技术栈 / 需求清单

| 步骤 | 文件 | 编辑位置 | docs/08 子项 |
|---|---|---|---|
| A | `CLAUDE.md` | § 🎯 项目概述 | `项目概述已填写（CLAUDE.md § 🎯 项目概述）` |
| B | `docs/04-技术规范.md`（A0 模板生成） | § 零、技术栈总览 | `技术栈已确认（docs/04 § 零）` |
| C | `docs/01-需求清单/index.md` | § 模块索引（表格） | `需求清单索引已填写（docs/01-需求清单/index.md）` |

**每个填写步骤的通用流程**：输出 `[scope-lock]` 横幅指明文件 + 编辑位置 → `AskUserQuestion` 二选一（「继续」/「有疑问想先沟通」）→ 用 `Grep` 在对应位置搜 `【人工填写：` 占位（命中则打印残留行重新确认；0 命中则继续）→ 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选对应子项。

- **A**：`CLAUDE.md` § 🎯 项目概述。占位符含项目名称 / 简述 / 目标用户 / 部署方式。
- **B**：`docs/04-技术规范.md` § 零。让用户检查 / 调整默认技术栈表（删不需要的行 / 改技术 / 加条目）。
- **C**：`docs/01-需求清单/index.md`。让用户按业务列出所有模块（每行一个，如 SYS / PUR / SAL），「核心功能点」给关键词即可，CC 会拆 REQ 卡片。

### D. 生成 REQ 卡片骨架并停下等人工审阅

1. 读 `index.md` 解析模块索引；读两个模板 `${CLAUDE_SKILL_DIR}/templates/_module-template.md`、`${CLAUDE_SKILL_DIR}/templates/req-card-template.md` 作为卡片结构参照。
2. **每模块/每 REQ 直接 `Write`**：对每个模块先 `mkdir -p "docs/01-需求清单/<MOD>-<模块名>"`，再照模板结构 `Write`，`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 按 `index.md` 实际值替换：
   - **模块头** `_module.md`：据 `index.md` 填 `module_code` / `module_name` / `module_brief`；`依赖模块: TBD(A5 自动补)` / `涉及表: TBD(A3 自动补)` 两行原样保留。
   - **每个 REQ** `<REQ-MOD-NNN>.md`：**照模板原样 `Write`**，只把 `{{req_id}}` / `{{title}}` / `{{goal}}` / `{{rules}}` / `{{constraints}}` / `{{acceptance}}` 这 6 个占位替换为据 `index.md` 推断的真实值；模板其余内容（`输入` / `输出` 示例字段表、`依赖表: TBD(A3 自动补)` / `依赖接口: TBD(A5 自动补)` 两行）**原样复制不动**；模板顶部 HTML 引导注释**不写进产物**。
3. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选（A1 子项）：
   - `  - [ ] REQ 卡片骨架已生成（docs/01-需求清单/<module>/REQ-*.md，业务内容留待人工填写）`
4. 打印「请人工填写 REQ 卡片」横幅并提示用户填完后回来继续：

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [scope-lock] REQ 卡片骨架已生成

   - 产出: docs/01-需求清单/<module>/{_module.md, REQ-*.md}
   - 6 个占位已填真实值；输入/输出字段表为模板示例内容(如需可自行调整)。
   - 审阅后选「继续」进 A1 校验.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

用 `AskUserQuestion` 确认「REQ 卡片已生成（6 个占位已填真实值），确认进入 A1 校验吗？」，给「继续」和「有疑问想先沟通」两个选项。

- 选「继续」→ 进入步骤 E。
- 选「有疑问想先沟通」→ 回答用户问题后，再确认一次。

### E. A1 校验

#### E.1 占位校验（每张 REQ 卡片）

卡片正文是模板原样复制，只有 6 个 `{{}}` 标量由 CC 填——本步只校验这 6 个占位填全填真。

1. 用 `Glob` 列出所有 `docs/01-需求清单/<module>/REQ-*.md`。
2. 对每张卡片用 `Read` + `Grep` 校验：
   - **无 `{{` 残留**：不得残留任何 `{{` 占位（命中即说明 6 个标量未全部替换）。
   - **6 个标量为真实值**：`req_id` / `title` / `goal` / `rules` / `constraints` / `acceptance` 均据 `index.md` 填为真实内容，非空、非回显占位名。
   - 输入/输出字段表为模板原样复制内容，**不在此校验**。
3. 任一卡片不通过：打印不通过的卡片路径 + 具体缺口行，用 `AskUserQuestion` 引导用户当场补齐，修订后重跑 E.1，直到全部通过。

#### E.2 全部配置锁进 config-vars.yaml（含敏感凭据，单一文件，随项目提交）

1. 据 `docs/04` § 零 + REQ 卡片盘点配置.
2. `Read` 模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml` → `Write` `config-vars.yaml`: 非敏感字段（包名 / 端口 / 前端包名 / 初始账号等）CC 据上下文填默认值, 无技术栈整节删, 不可推断留 `【人工填写】`; 敏感字段（`database.password` / `admin_init.password` / `secrets.*` 等真实凭据）CC **不臆造**, 一律留 `【人工填写：<说明>】` 占位待人工填（本地 MySQL 无密码时，用户可把 `database.password` 明确填成 `''`）。
3. `AskUserQuestion` 让用户确认非敏感项齐全, 并提示敏感凭据需用户**自己在 config-vars.yaml 填真实值**（`database.password` 可为显式空串）.

#### E.3 build / lint / unit / e2e 命令锁进 docs/04 § 零

1. 用 `Read` 读 `docs/04-技术规范.md` § 零技术栈表，确定本项目涉及的每个 stack（如后端、前端，可能多个）。
2. 对**每个 stack**，用 `AskUserQuestion`（如默认值可推断则展示默认值让用户确认/覆盖）收集四类命令：
   - **build**（构建命令，如 `mvn package` / `npm run build`）
   - **lint**（静态检查命令，如 `npm run lint`）
   - **unit**（单元测试命令，如 `mvn test` / `npm run test:unit`）
   - **e2e**（端到端测试命令，如 `npm run test:e2e`；无则显式记 `无`）
3. 把确认后的命令写入 `docs/04-技术规范.md` § 零（若 § 零无「命令」小节则用 `Edit` 新增一个「命令清单」小节，按 stack 分组列出 build/lint/unit/e2e 四行）。这些命令是 Coding 阶段 `coding.mjs` 的 tdd / test-gate 读取来源，必须在此锁全。

#### E.4 全部通过后勾选 A1 顶层并自动进入 A2

三项检查（E.1 / E.2 / E.3）全部通过后：

1. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 `- [ ] A1 范围锁定 — scope-lock` 顶层项。
2. 打印 A1 完成横幅：

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [scope-lock] ✅ A1 范围锁定完成（终结校验通过）

 产出 & 锁定：
   ✓ CLAUDE.md § 🎯 项目概述
   ✓ docs/04 § 零 技术栈 + build/lint/unit/e2e 命令
   ✓ docs/01-需求清单/index.md 模块索引
   ✓ docs/01-需求清单/<module>/_module.md 模块头
   ✓ docs/01-需求清单/<module>/REQ-*.md 6 个占位已填真实值（字段表为模板示例）
   ✓ config-vars.yaml 配置已锁（非敏感已填；DB 凭据 / 密钥占位待人工填，plan-start 把关）

 自动进入 A2：skeleton-gen
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

3. 立即调用 `Skill(skeleton-gen)` 进入 A2。

## 参考

- `CLAUDE.md`
- `docs/04-技术规范.md`
- `docs/01-需求清单/index.md`
- `docs/01-需求清单/<module>/_module.md`
- `docs/01-需求清单/<module>/REQ-*.md`
- `config-vars.yaml`
- `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml`
- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md`
- `${CLAUDE_SKILL_DIR}/templates/_module-template.md`