---
name: scope-lock
description: A1 计划范围锁定——引导用户填写项目概述 + 技术栈 + 需求索引，并按模块子目录生成 REQ 卡片骨架（CC 推断 req_id/title/goal/rules/constraints/acceptance；输入/输出 字段表为结构化 6 列表单由人工逐行填真实数据）；末尾执行 A1 终结校验：每张 REQ 卡片字段含真实数据、配置字段名锁进 config-vars.yaml（非敏感填值 + secrets_ref 键名引用 .env.local）、build/lint/unit/e2e 命令锁进 docs/04 §零，缺则当场 AskUserQuestion 问清。
user-invocable: false
allowed-tools: Read Write Edit Grep Glob Skill AskUserQuestion Bash(mkdir *) Bash(node *) Bash(rm *)
---

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

## 执行步骤

### 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. 用 `Grep` 校验 `docs/01-需求清单/index.md` 无 `【人工填写：` 残留；有则回步骤 C。
2. 用 `Read` 读 `index.md` 解析模块索引。
3. **每模块/每 REQ 渲染**：`Write` vars.json → `mkdir -p` → `node render.mjs`。`<MOD>` / `<模块名>` / `<REQ-MOD-NNN>` 按 `index.md` 实际值替换。

   ```bash
   # 模块头：先 Write docs/01-需求清单/<MOD>-<模块名>/_module.vars.json，内容形如
   #   {"module_code":"<MOD>","module_name":"<模块名>","module_brief":"<module_brief>"}
   mkdir -p "docs/01-需求清单/<MOD>-<模块名>"
   node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \
     "${CLAUDE_SKILL_DIR}/templates/_module-template.md" \
     "docs/01-需求清单/<MOD>-<模块名>/_module.vars.json" \
     "docs/01-需求清单/<MOD>-<模块名>/_module.md"

   # 每个 REQ：先 Write 该 REQ 的 vars JSON，内容形如
   #   {"req_id":"<REQ-MOD-NNN>","title":"<title>","goal":"<goal>","rules":"<rules>","constraints":"<constraints>","acceptance":"<acceptance>"}
   node "${CLAUDE_PLUGIN_ROOT}/lib/render.mjs" \
     "${CLAUDE_SKILL_DIR}/templates/req-card-template.md" \
     "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.vars.json" \
     "docs/01-需求清单/<MOD>-<模块名>/<REQ-MOD-NNN>.md"
   ```
4. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选（A1 子项）：
   - `  - [ ] REQ 卡片骨架已生成（docs/01-需求清单/<module>/REQ-*.md，业务内容留待人工填写）`
5. 打印「请人工填写 REQ 卡片」横幅并提示用户填完后回来继续（不停止，下一步是 A1 终结校验）：

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

   - 产出: docs/01-需求清单/<module>/{_module.md, REQ-*.md}
   - 请逐张填真实字段表, 完成后选「继续」进 A1 终结校验.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

用 `AskUserQuestion` 确认「所有 REQ 卡片的结构化字段都填成真实数据了吗？」，给「继续」和「有疑问想先沟通」两个选项。

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

### E. A1 终结校验（硬闸：全部通过才勾选 A1 顶层）

E.1/E.2/E.3 全过后才勾 A1 顶层。

#### E.1 真实数据校验（每张 REQ 卡片）

1. 用 `Glob` 列出所有 `docs/01-需求清单/<module>/REQ-*.md`。
2. 对每张卡片用 `Read` + `Grep` 校验：
   - **无模板默认占位**：卡片内**不得**出现 `【示例行，替换为真实字段】` 或 `<示例值>`（用 `Grep` 搜这两个字面量，命中即视为未完成）。
   - **结构化字段非空**：`输入字段` / `输出字段` 两张表每行 6 列均非空，且不是模板示例行内容；至少各有 1 行真实字段（除非该 REQ 确实无输入/输出，需在卡片显式标注）。
   - **`示例值` 列已填真实取值**：每行示例值列为真实约束下的合法取值，非占位。
   - **`{{...}}` 残留**：不得残留任何 `{{` 占位（说明渲染未替换）。
3. 任一卡片不通过：打印不通过的卡片路径 + 具体缺口行，用 `AskUserQuestion` 引导用户当场补齐（可针对具体字段含义/校验规则发问），修订后重跑 E.1，直到全部通过。

#### E.2 配置字段名锁进 config-vars.yaml（敏感键名引用 .env.local）

1. 据 `docs/04` § 零 + REQ 卡片盘点配置.
2. `Read` 模板 `${CLAUDE_SKILL_DIR}/templates/config-vars-template.yaml` → `Write` `config-vars.yaml`: 非敏感字段填默认值, 无技术栈整节删, 不可推断留 `【人工填写】`; 敏感字段只把键名+含义登 `secrets_ref`, 不写真实值.
3. `AskUserQuestion` 让用户确认齐全.

#### 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 顶层并停止

三项检查（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 字段表已填真实数据
   ✓ config-vars.yaml 配置字段 + secrets_ref 键名已锁（敏感真实值留待 A2 .env.local）

 运行以下命令继续进入 A2：
   /erp-workflow:plan-start

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## 参考

- `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`
- `${CLAUDE_PLUGIN_ROOT}/lib/render.mjs`