@aipper/aiws-spec 0.0.24 → 0.0.26

package/templates/workspace/.claude/commands/ws-spec-review.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-spec-review -->
+# ws spec review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
+   - 当前改动是否能归因到 `Req_ID` / `Problem_ID`
+   - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否保持一致
+   - 是否存在越界改动、危险操作或缺失 gate
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/spec-review.md`
+   - 回退：`.agentdocs/tmp/review/spec-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `阻断项（Blockers）:`
+   - `警告（Warnings）:`
+   - `下一步（Next）:`
+<!-- AIWS_MANAGED_END:claude:ws-spec-review -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-verify-before-complete.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-verify-before-complete -->
+# ws verify before complete
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 `/ws-finish` 或 `/ws-handoff` 前检查双审查、validate stamp 与 evidence 是否齐全。
+
+步骤（建议）：
+1) 检查以下最小 gate：
+   - `changes/<change-id>/review/spec-review.md`
+   - `changes/<change-id>/review/quality-review.md`
+   - `.agentdocs/tmp/aiws-validate/*.json`
+2) 若存在 `changes/<change-id>/evidence/`，检查 review / validate / collaboration summary 是否已收敛。
+3) 将结果落盘到：
+   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
+   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `结论（Result）: pass|fail`
+   - `缺失项（Missing）:`
+   - `下一步（Next）:`
+<!-- AIWS_MANAGED_END:claude:ws-verify-before-complete -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/skills/p-aiws-change-archive/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: p-aiws-change-archive
+description: 私有：归档变更工件（会先做严格校验并生成 handoff.md）
+---
+
+目标：
+- 将 `changes/<change-id>/` 归档到 `changes/archive/<YYYY-MM-DD>/...`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change archive "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change archive "$change_id"
+else
+  npx @aipper/aiws change archive "$change_id"
+fi
+```
+
+说明：
+- `archive` 默认会先跑严格校验并要求 tasks 全部勾选
+- `--force` 会绕过部分门禁（不推荐）
+- 归档后会生成交接文档：`changes/archive/<date>-<change-id>/handoff.md`

package/templates/workspace/.claude/skills/p-aiws-change-finish/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: p-aiws-change-finish
+description: 私有：安全合并 change/<change-id> 回目标分支（默认 fast-forward）
+---
+
+目标：
+- 将 `change/<change-id>` fast-forward 合并回目标分支，减少手输分支名导致的错误
+
+执行（在目标分支所在 worktree 的仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "$change_id"
+else
+  npx @aipper/aiws change finish "$change_id"
+fi
+```
+
+说明：
+- 默认等价于：`git merge --ff-only change/<change-id>`
+- 若你当前就在 `change/<change-id>` 分支上，`finish` 会尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch` 作为目标分支
+- 若无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`

package/templates/workspace/.claude/skills/p-aiws-change-list/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-change-list
+description: 私有：列出 changes 工件（只读）
+---
+
+目标：
+- 列出当前仓库的变更工件与状态
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change list
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change list
+else
+  npx @aipper/aiws change list
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-new/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: p-aiws-change-new
+description: 私有：创建 changes/<change-id> 工件
+---
+
+目标：
+- 创建 `changes/<change-id>/` 工件目录与基础文件（proposal/tasks/可选 design）
+
+要求：
+- `change-id` 必须是 kebab-case：`^[a-z0-9]+(-[a-z0-9]+)*$`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change new "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change new "$change_id"
+else
+  npx @aipper/aiws change new "$change_id"
+fi
+```
+
+可选参数：
+- `--title <title>`：写入标题
+- `--no-design`：不生成 design.md

package/templates/workspace/.claude/skills/p-aiws-change-next/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: p-aiws-change-next
+description: 私有：给出下一步建议（只读）
+---
+
+目标：
+- 基于当前仓库与 changes 工件状态，输出最小下一步建议
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change next "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change next "$change_id"
+else
+  npx @aipper/aiws change next "$change_id"
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-start/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: p-aiws-change-start
+description: 私有：切分支并初始化变更工件（可选安装 hooks）
+---
+
+目标：
+- 切到分支 `change/<change-id>` 并初始化 `changes/<change-id>/` 工件
+  - 若检测到 `.gitmodules`（git submodules），默认优先使用 `--worktree`（失败则回退为 `--no-switch`），避免切走 superproject 分支导致 submodule 状态混乱
+
+要求：
+- 需要 git 仓库；若不是 git 仓库先 `git init`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change start "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change start "$change_id"
+else
+  npx @aipper/aiws change start "$change_id"
+fi
+```
+
+可选参数：
+- `--hooks`：同时执行 `aiws hooks install .`
+- `--title <title>`：写入标题
+- `--no-design`：不生成 design.md
+- `--switch`：显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义）
+- `--no-switch`：不切换当前分支（仅确保 `change/<change-id>` 分支存在并初始化工件）；适用于 superproject + submodule 场景
+- `--worktree`：用 `git worktree` 创建独立工作区并在其中 checkout `change/<change-id>`（推荐用于 superproject + submodule）
+  - `--worktree-dir <path>`：覆盖 worktree 目录
+  - `--submodules`：在 worktree 内执行 `git submodule update --init --recursive`

package/templates/workspace/.claude/skills/p-aiws-change-status/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: p-aiws-change-status
+description: 私有：查看单个变更工件状态（只读）
+---
+
+目标：
+- 查看指定 `change-id` 的工件状态与下一步建议
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change status "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change status "$change_id"
+else
+  npx @aipper/aiws change status "$change_id"
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-sync/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: p-aiws-change-sync
+description: 私有：同步真值基线到 changes/<change-id>（写入 .ws-change.json）
+---
+
+目标：
+- 将当前真值文件（`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`）的 hash 快照同步到 `changes/<change-id>/.ws-change.json`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change sync "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change sync "$change_id"
+else
+  npx @aipper/aiws change sync "$change_id"
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-templates-init/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-change-templates-init
+description: 私有：在仓库内初始化 change templates（写入 changes/templates）
+---
+
+目标：
+- 初始化 `changes/templates/`（用于在仓库内自定义 proposal/tasks/design 模板）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates init
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates init
+else
+  npx @aipper/aiws change templates init
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-templates-which/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-change-templates-which
+description: 私有：查看当前 change templates 来源（只读）
+---
+
+目标：
+- 输出当前仓库 change templates 的解析来源与路径（用于排查模板来自哪里）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates which
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates which
+else
+  npx @aipper/aiws change templates which
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-change-validate/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: p-aiws-change-validate
+description: 私有：校验 changes 工件（可 strict）
+---
+
+目标：
+- 校验 `changes/<change-id>/` 工件完整性、归因与 WS:TODO（用于 hooks/CI）
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate "$change_id" --strict
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate "$change_id" --strict
+else
+  npx @aipper/aiws change validate "$change_id" --strict
+fi
+```
+
+说明：
+- `--strict` 会把 `WS:TODO`/缺少归因视为错误，并启用计划质量门（章节完整、步骤粒度、验证命令与预期）
+- 紧急情况下可用 `--allow-truth-drift`（不推荐）

package/templates/workspace/.claude/skills/p-aiws-hooks-install/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: p-aiws-hooks-install
+description: 私有：启用 git hooks 门禁（core.hooksPath=.githooks）
+---
+
+目标：
+- 为当前 git 仓库启用 aiws 门禁 hooks（`git commit`/`git push` 自动跑 `aiws validate .`）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks install .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks install .
+else
+  npx @aipper/aiws hooks install .
+fi
+```
+
+验证（可选）：
+```bash
+git config core.hooksPath
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-hooks-status/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-hooks-status
+description: 私有：查看当前仓库 hooks 状态（只读）
+---
+
+目标：
+- 输出当前仓库 hooks 状态（不修改文件）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-init/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: p-aiws-init
+description: 私有：初始化工作区（生成真值文件与门禁）
+---
+
+目标：
+- 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
+- 写入/更新 `.gitignore` 的 aiws 托管块
+- 生成/更新 `.aiws/manifest.json`（用于漂移检测）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws init .
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws init .
+  aiws validate .
+else
+  npx @aipper/aiws init .
+  npx @aipper/aiws validate .
+fi
+```
+
+约束：
+- 不写入任何 secrets
+- 只允许更新托管块（`AIWS_MANAGED_BEGIN/END`）或 spec 指定的 `replace_file` 文件

package/templates/workspace/.claude/skills/p-aiws-rollback/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-rollback
+description: 私有：回滚工作区（从备份恢复）
+---
+
+目标：
+- 从 `.aiws/backups/` 恢复到某次备份快照
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws rollback . latest
+elif command -v aiws >/dev/null 2>&1; then
+  aiws rollback . latest
+else
+  npx @aipper/aiws rollback . latest
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-update/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: p-aiws-update
+description: 私有：更新工作区（刷新模板与托管块）
+---
+
+目标：
+- 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
+- 更新前备份到 `.aiws/backups/<timestamp>/`
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws update .
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws update .
+  aiws validate .
+else
+  npx @aipper/aiws update .
+  npx @aipper/aiws validate .
+fi
+```
+
+约束：
+- 不写入任何 secrets
+- 只更新托管块或 spec 指定的 `replace_file` 文件

package/templates/workspace/.claude/skills/p-aiws-validate/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: p-aiws-validate
+description: 私有：校验工作区（漂移检测 + 门禁）
+---
+
+目标：
+- 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
+- 强门禁：缺 `python3`/缺 required 脚本也应失败
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  AIWS_VALIDATE_STAMP=1 ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  AIWS_VALIDATE_STAMP=1 aiws validate .
+else
+  AIWS_VALIDATE_STAMP=1 npx @aipper/aiws validate .
+fi
+```
+
+证据（可选）：
+- stamp：`.agentdocs/tmp/aiws-validate/*.json`（由 `.gitignore` 忽略）

package/templates/workspace/.claude/skills/p-tasks-plan/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: p-tasks-plan
+description: 原子：tasks 同步（从 changes/<id>/tasks.md 生成 update_plan payload）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 用 `changes/<change-id>/tasks.md` 的 checkbox 任务作为“步骤真值”
+- 生成可直接用于 `update_plan` 的 JSON payload（`pending/in_progress/completed`）
+- 输出当前进度摘要（done/total + 当前 in_progress）
+
+约束：
+- 不写入任何 secrets（token、账号、内网端点等不得进入 git）
+- 只读 `changes/<id>/tasks.md`（不自动改写 tasks 文件）
+- 未运行不声称已运行
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`。
+2) 推断 `change-id`：
+   - 优先从当前分支名读取：`git rev-parse --abbrev-ref HEAD`（期望形如 `change/<change-id>`）
+   - 若无法推断：让用户明确本次要同步的 `<change-id>`
+3) 检查 tasks 文件存在：`test -f changes/<change-id>/tasks.md`
+4) 输出进度摘要：
+```bash
+python3 tools/ws_tasks_plan.py status --file changes/<change-id>/tasks.md
+```
+5) 生成 `update_plan` payload（JSON 输出到 stdout）：
+```bash
+python3 tools/ws_tasks_plan.py plan --file changes/<change-id>/tasks.md --explanation "sync tasks.md -> update_plan"
+```
+6) 调用 `update_plan`，将上一步 JSON 原样作为入参（确保任意时刻最多 1 条 `in_progress`）。
+
+输出要求：
+- `Change_ID:` <change-id>
+- `Tasks:` `changes/<change-id>/tasks.md`
+- `Next:` 推荐下一步（通常为继续完善 tasks 或进入 `$ws-dev`）

package/templates/workspace/.claude/skills/using-aiws/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: using-aiws
+description: 默认 workflow bootstrap/router：先读真值，再路由到正确的 ws-* 入口
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 作为默认入口，先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 先判定当前任务属于哪个 workflow，再进入具体 `ws-*` skill
+- 若任务意图、归因或验证入口不明确：先澄清，不直接进入实现
+
+阶段定位：
+- bootstrap/router 阶段；负责 workflow 分流，而不是直接完成实现。
+
+必需输入：
+- 当前任务描述
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Task intent:` 当前任务意图分类
+- `Binding:` `Req_ID` / `Problem_ID` / change 上下文是否清晰
+- `Route:` 选中的下一步 skill
+- `Why:` 选择该 route 的原因
+- `Next:` 进入对应 skill，或先提澄清问题
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+- 无法明确当前任务意图
+- 无法明确归因或验证入口，且不能安全推断
+
+完成判定：
+- 已经明确给出单一路由结果，并进入对应 `ws-*` skill；或已提出关键澄清问题并停止。
+
+执行步骤（强制）：
+1) 先遵守 `$ws-preflight` 的真值读取要求：
+   - 定位项目根目录
+   - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+   - 输出 `Root:` / `Found:` / `Missing:`
+2) 若缺失任一真值文件：
+   - 不进入实现
+   - 输出下一步：先 `aiws init .`（或 `npx @aipper/aiws init .`），然后重新执行 `$using-aiws`
+   - 此时 route 视为 `$ws-preflight`
+3) 根据 `packages/spec/docs/workflow-router-rules.json` 判定任务属于哪一类：
+   - 需求/验收/合同变更：`$ws-req-review`
+   - 评审/审计/找风险：`$ws-review`
+   - finish / merge / push / cleanup：`$ws-finish`
+   - handoff / archive summary：`$ws-handoff`
+   - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
+   - 小步明确实现/修复/配置调整：`$ws-dev`（若是 simple/local 单点修复，且用户明确希望走轻量入口，可显式进入 `$ws-dev-lite`）
+4) 若任务意图或归因不明确：
+   - 只问 1-3 个关键澄清问题
+   - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
+   - 然后停止；不要直接写代码
+5) 若已确定 route：
+   - 先输出：
+     - `Task intent:`
+     - `Binding:`
+     - `Route:`
+     - `Why:`
+   - 若 `Route: $ws-dev` 且任务属于 simple/local 单点修复：
+     - `Next:` 可优先进入 `$ws-dev-lite`
+   - 否则：
+     - `Next:` 进入对应主 skill
+   - 然后在同一轮中继续遵循对应 skill 的契约
+6) 路由约束：
+   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
+   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
+   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+7) 若执行过程中发现复杂度升高：
+   - 从 `$ws-dev` 回退到 `$ws-plan`
+   - 从 `$ws-finish` 回退到前置门禁而不是硬推完成
+
+输出模板：
+- `Root:` <path>
+- `Found:` <files>
+- `Task intent:` <分类>
+- `Binding:` <清晰 / 缺失项>
+- `Route:` <$ws-... 或 clarify>
+- `Why:` <一句到三句>
+- `Next:` <继续执行对应 skill，或提出澄清问题>

package/templates/workspace/.claude/skills/ws-analyze/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ws-analyze
+description: 分析（定位问题与收集上下文）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+
+输入：
+- 主题/需求：用户在本次消息中提供的主题（若不明确，先问一句“本次分析主题是什么？”）
+
+步骤（建议）：
+1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+2) 基于真值文件与当前代码现状，输出：
+   - 目标 / 非目标
+   - 现状证据（文件路径/接口路径）
+   - 推荐方案（1 个）+ 备选（可选）
+   - 风险与回滚（3–8 条）
+   - 最小验证命令（可复现）
+3) 将分析落盘到：`.agentdocs/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
+4) 回复中必须包含：`Evidence:` 证据文件路径。
+
+安全：
+- 不打印 secrets（尤其 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。