@aipper/aiws-spec 0.0.29 → 0.0.30

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

@@ -55,8 +55,8 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
     - finish / merge / push / cleanup：`$ws-finish`
     - handoff / archive summary：`$ws-handoff`
     - 新需求或中大型变更，且存在多条待确认问题 / 用户要求逐条多轮沟通：`$ws-intake`
-    - 需要先出设计方案（design 未过审前不进入实现）：`$ws-design`
-    - 需要更新规范/验收标准（必须先过 review）：`$ws-spec-update`
+    - 需要先出设计方案（design 作为 plan 阶段一部分）：`$ws-plan`
+    - 需要更新规范/验收标准（必须先过 req-review）：`$ws-req-change`
     - 中大型实现、需要方案、需要 change/worktree，且需求已经冻结：`$ws-plan`
    - 小步明确实现/修复/配置调整：`$ws-dev`（若是 simple/local 单点修复，且用户明确希望走轻量入口，可显式进入 `$ws-dev-lite`）
 4) 若任务意图或归因不明确：
@@ -81,10 +81,14 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
    - 否则：
      - `Next:` 进入对应主 skill
    - 然后在同一轮中继续遵循对应 skill 的契约
-7) 路由约束：
-   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
-   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
-   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+ 7) 路由约束：
+    - router 自己不是实现阶段；不要在给出 route 之前直接改代码
+    - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
+    - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+    - **上下文先于判决**：路由 `direct_implementation` 前必须先收集项目上下文——具体检查：`git status --porcelain`（已改动文件数）、`git diff --stat`（改动行范围）。仅当改动文件数 ≤ 3 且改动总行数 ≤ 100 且验证入口明确时，才可判 direct。
+    - **Subagent 不可用时**：降级为当前 agent 直接执行，但必须在 evidence 中记录降级原因
+   - **上下文先于判决**：路由 `direct_implementation` 前必须先收集项目上下文——`git status --porcelain`（已改动文件数）、`git diff --stat`（改动行范围）。仅当改动文件数 ≤ 3 且改动总行数 ≤ 100 且验证入口明确时，才可判 direct。
+   - Subagent 不可用时的降级路径：`ready-for-dev` → 当前 agent 直接执行 ws-dev；`in-progress` → 当前 agent 自审（evaluate-optimize 1 轮）；`review` → 当前 agent 本地 review（不阻断）。降级时必须在 evidence 中记录降级原因
 8) 若执行过程中发现复杂度升高：
    - 从 `$ws-dev` 回退到 `$ws-plan`
    - 从 `$ws-plan` 回退到 `$ws-intake`（当发现需求并未冻结）

package/templates/workspace/.agents/skills/ws-commit/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-commit
-description: `aiws ws-commit` 的薄包装入口
+description: `aiws commit` 的薄包装入口
 ---
 
 # ws-commit
 
-`aiws ws-commit` 的薄包装入口。
+`aiws commit` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-commit
+  ./node_modules/.bin/aiws commit
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-commit
+  aiws commit
 else
-  npx @aipper/aiws ws-commit
+  npx @aipper/aiws commit
 fi
 ```

package/templates/workspace/.agents/skills/ws-deliver/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-deliver
-description: `aiws ws-deliver` 的薄包装入口
+description: `aiws deliver` 的薄包装入口
 ---
 
 # ws-deliver
 
-`aiws ws-deliver` 的薄包装入口。
+`aiws deliver` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-deliver
+  ./node_modules/.bin/aiws deliver
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-deliver
+  aiws deliver
 else
-  npx @aipper/aiws ws-deliver
+  npx @aipper/aiws deliver
 fi
 ```

package/templates/workspace/.agents/skills/ws-dev/SKILL.md

@@ -43,6 +43,17 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 - 已有计划：先 `$ws-plan-verify`，通过后进入实现。
 - `$ws-plan` 已创建 worktree：直接在该 worktree 中继续。
 
+### 1.5 Design Gate（入口检查）
+
+在进入实现前，先验证绑定工件是否完整：
+
+- 若计划或实际改动超过 2 个文件：**必须**检查 `changes/<change-id>/` 下是否存在 `proposal.md` 和 `tasks.md`
+- 若缺失：**阻断**并输出信息 `Design Gate: proposal.md and tasks.md required for multi-file implementations. Run $ws-plan first.`
+- 若为单文件/小改动（≤2 文件）：此检查为 advisory 级别，缺失仅在输出中提示但不阻断
+- Design Gate 检查结果需记录在输出中，作为实现入口证据
+
+Design Gate 通过后，继续进入变更归因与实现。
+
 ### 2. 建立变更归因
 
 - 若 `git status --porcelain` 仅有计划/工件文件，属于预期行为，继续即可。
@@ -60,9 +71,28 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 - 根据 review 结果决定 fix 或收敛 evidence
 - **Inline escape hatch**：如果用户明确说"你直接改"或"do it inline"，主 session 可直接写代码，但必须落盘 evidence 记录理由
 
+### 3.1 自我修正循环（evaluate-optimize）
+
+收到 sub-agent 或自行产出实现后，执行自我修正循环：
+
+1. **Evaluate** — 检查实现质量：
+   - lint / typecheck 是否通过
+   - 是否遵循现有代码模式（文件结构、命名约定、错误处理风格）
+   - 是否有明显 bug 或边界缺失
+2. **Optimize** — 修复发现的问题（最多 2 轮）
+   - 每轮修复后重新 evaluate
+   - 若 2 轮后仍有问题 → escalate 到 `$ws-review`
+3. **TDD 优先** — 对于中大型改动，优先按 RED→GREEN→REFACTOR 顺序：
+   - RED：先写一个会失败的测试
+   - GREEN：实现最小代码让测试通过
+   - REFACTOR：在测试保护下重构
+
+注意：TDD 在简单修复时不强制，但对新增功能/中等以上复杂度变更建议遵循。
+
 ### 4. 其他规则
 
 - 需求调整：先 `$ws-req-review` → 确认后 `$ws-req-change`
+- **TDD 约束**：新增功能必须补测试（RED→GREEN→REFACTOR）；bug fix 至少补一条回归测试
 - 最小改动：每处改动必须归因到 `REQUIREMENTS.md` 或 `issues/problem-issues.csv`
 - 验证：运行 `AI_WORKSPACE.md` 声明的命令；未运行不声称已运行
 - 多步任务：使用 `update_plan` 工具跟踪状态

package/templates/workspace/.agents/skills/ws-finish/SKILL.md

@@ -1,18 +1,22 @@
 ---
 name: ws-finish
-description: `aiws ws-finish` 的薄包装入口
+description: `aiws finish` 的收尾入口（finish_resume_required）
 ---
 
 # ws-finish
 
-`aiws ws-finish` 的薄包装入口。
+`aiws finish` 的收尾入口。
+
+关键契约：
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`，继续执行 `aiws change finish <change-id> --push`
+- 普通 finish 的 `validate/evidence/state` 仍应在 `change/<change-id>` worktree 完成，不要在目标 worktree 里跑 `aiws validate . --stamp`
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-finish
+  ./node_modules/.bin/aiws finish
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-finish
+  aiws finish
 else
-  npx @aipper/aiws ws-finish
+  npx @aipper/aiws finish
 fi
 ```

package/templates/workspace/.agents/skills/ws-handoff/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-handoff
-description: `aiws ws-handoff` 的薄包装入口
+description: `aiws handoff` 的薄包装入口
 ---
 
 # ws-handoff
 
-`aiws ws-handoff` 的薄包装入口。
+`aiws handoff` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-handoff
+  ./node_modules/.bin/aiws handoff
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-handoff
+  aiws handoff
 else
-  npx @aipper/aiws ws-handoff
+  npx @aipper/aiws handoff
 fi
 ```

package/templates/workspace/.agents/skills/ws-migrate/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: ws-migrate
+description: `aiws migrate` 的薄包装入口
+---
+
+# ws-migrate
+
+`aiws migrate` 的薄包装入口。
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws migrate
+elif command -v aiws >/dev/null 2>&1; then
+  aiws migrate
+else
+  npx @aipper/aiws migrate
+fi
+```

package/templates/workspace/.agents/skills/ws-plan-verify/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-plan-verify
-description: `aiws ws-plan-verify` 的薄包装入口
+description: `aiws plan-verify` 的薄包装入口
 ---
 
 # ws-plan-verify
 
-`aiws ws-plan-verify` 的薄包装入口。
+`aiws plan-verify` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-plan-verify
+  ./node_modules/.bin/aiws plan-verify
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-plan-verify
+  aiws plan-verify
 else
-  npx @aipper/aiws ws-plan-verify
+  npx @aipper/aiws plan-verify
 fi
 ```

package/templates/workspace/.agents/skills/ws-pull/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: ws-pull
+description: `aiws pull` 的薄包装入口
+---
+
+# ws-pull
+
+`aiws pull` 的薄包装入口。
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws pull
+elif command -v aiws >/dev/null 2>&1; then
+  aiws pull
+else
+  npx @aipper/aiws pull
+fi
+```

package/templates/workspace/.agents/skills/ws-push/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: ws-push
+description: `aiws push` 的薄包装入口
+---
+
+# ws-push
+
+`aiws push` 的薄包装入口。
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws push
+else
+  npx @aipper/aiws push
+fi
+```

package/templates/workspace/.agents/skills/ws-submodule-setup/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: ws-submodule-setup
+description: `aiws submodule-setup` 的薄包装入口
+---
+
+# ws-submodule-setup
+
+`aiws submodule-setup` 的薄包装入口。
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws submodule-setup
+elif command -v aiws >/dev/null 2>&1; then
+  aiws submodule-setup
+else
+  npx @aipper/aiws submodule-setup
+fi
+```

package/templates/workspace/.agents/skills/ws-verify-before-complete/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-verify-before-complete
-description: `aiws ws-verify-before-complete` 的薄包装入口
+description: `aiws verify-bc` 的薄包装入口
 ---
 
 # ws-verify-before-complete
 
-`aiws ws-verify-before-complete` 的薄包装入口。
+`aiws verify-bc` 的薄包装入口。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-verify-before-complete
+  ./node_modules/.bin/aiws verify-bc
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-verify-before-complete
+  aiws verify-bc
 else
-  npx @aipper/aiws ws-verify-before-complete
+  npx @aipper/aiws verify-bc
 fi
 ```

package/templates/workspace/{changes → .aiws/changes}/README.md

@@ -9,7 +9,7 @@
 
 建议结构：
 ```
-changes/
+.aiws/changes/
   README.md
   <change-id>/
     proposal.md
@@ -36,8 +36,8 @@ changes/
 - `aiws change start <change-id> --no-switch`（superproject + submodule 场景：不切分支，仅准备 `change/<change-id>` 分支与工件目录）
 - `aiws change start <change-id> --switch`（显式允许切换 superproject 分支；仅切 superproject，不递归切换 submodule）
 - `aiws change finish <change-id>`（安全合并：fast-forward 合并回目标分支；在 `change/<change-id>` 分支上执行时会尝试使用 `.ws-change.json` 的 `base_branch` 作为目标分支）
-- `aiws change finish <change-id> --push [--remote <name>]`（最小收尾闭环：若存在 `.gitmodules` 则先按 `changes/<id>/submodules.targets` 顺序 push submodule，再 push 目标分支；默认优先遵循 upstream 配置；push 成功后把 `changes/<id>/` 自动归档到 `changes/archive/...`，同时生成 `handoff.md` 与 archive commit）
-- 已 archive 的 `change/<change-id>` 才算真正终态；若只是“已 finish 但仍有 active `changes/<id>/` 未归档”，默认应重跑 `aiws change finish <change-id> --push` 续完收尾，而不是继续开发或复用旧 branch 做新需求。
+- `aiws change finish <change-id> --push [--remote <name>]`（最小收尾闭环：若存在 `.gitmodules` 则先按 `.aiws/changes/<id>/submodules.targets` 顺序 push submodule，再 push 目标分支；默认优先遵循 upstream 配置；push 成功后把 `.aiws/changes/<id>/` 自动归档到 `.aiws/changes/archive/...`，同时生成 `handoff.md` 与 archive commit）
+- 已 archive 的 `change/<change-id>` 才算真正终态；若只是"已 finish 但仍有 active `.aiws/changes/<id>/` 未归档"，默认应重跑 `aiws change finish <change-id> --push` 续完收尾，而不是继续开发或复用旧 branch 做新需求。
 - `aiws change new <change-id>`
 - `aiws change list`
 - `aiws change status <change-id>`
@@ -45,24 +45,24 @@ changes/
 - `aiws change validate <change-id>`
 - `aiws change sync <change-id>`
 - `aiws change archive <change-id>`（手工恢复 / 历史兼容入口；标准链路一般不需要单独执行）
-- `aiws change evidence <change-id>`（收敛 review / validate / collaboration summary 到 `changes/<id>/evidence/`）
+- `aiws change evidence <change-id>`（收敛 review / validate / collaboration summary 到 `.aiws/changes/<id>/evidence/`）
 
 Active change（推荐，团队共享）：
 - 使用分支名声明当前变更：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
 - 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync`
 
 计划质量门（推荐，执行前）：
-- 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支，再在该上下文内写 `plan/...`）
+- 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支，再在该上下文内写 `.aiws/plan/...`）
 - 再执行计划质检：`$ws-plan-verify`
 - 最后进入实现：`$ws-dev`
 - 若 `$ws-plan` 创建了独立 `change/<change-id>` 分支，后续 `$ws-plan-verify` / `$ws-dev` / `$ws-finish` 都应优先在该分支内继续
 - 目标：确保计划具备主索引绑定、步骤不过长、验证命令可复现且有预期结果
 
 模板覆盖（可选）：
-- 在工作区创建 `changes/templates/` 可覆盖默认模板：
-  - `changes/templates/proposal.md`
-  - `changes/templates/tasks.md`
-  - `changes/templates/design.md`
+- 在工作区创建 `.aiws/changes/templates/` 可覆盖默认模板：
+  - `.aiws/changes/templates/proposal.md`
+  - `.aiws/changes/templates/tasks.md`
+  - `.aiws/changes/templates/design.md`
 - 快速初始化模板：`aiws change templates init`
 - 查看模板来源：`aiws change templates which`
 
@@ -77,7 +77,7 @@ Hooks/CI（推荐，硬约束）：
     - submodule / 普通仓库：默认 `warn`，提示优先使用中文 commit message
     - 若执行 `git config aiws.commitMessagePolicy strict`，则会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
   - `pre-commit` / `pre-push`：默认执行 `aiws validate .`
-- 还会安装门禁脚本（`tools/ws_change_check.py`、`tools/requirements_contract.py`）。
+- 还会安装门禁脚本（`.aiws/tools/ws_change_check.py`、`.aiws/tools/requirements_contract.py`）。
 - **启用 hooks 需要本地配置**（不会自动提交到 git）：
   - 直接启用：`git config core.hooksPath .githooks`
   - 或使用：`aiws hooks install .`（等价）
@@ -91,7 +91,7 @@ Hooks/CI（推荐，硬约束）：
   - 若失败：先在 change 分支 `git rebase main`（或更新 main 后再 rebase），再重试 `--ff-only`
 
 协同交付建议：
-- 委托分析先落到 `changes/<id>/analysis/`，由主 agent 在 `ws-review` 或 `review/*.md` 中收敛结论。
-- patch 草案先落到 `changes/<id>/patches/`，未经审查不要直接应用。
-- 交付前建议执行：`aiws change evidence <change-id>`，让 `delivery-summary` 与 `collaboration-summary` 一起落到 `changes/<id>/evidence/`。
+- 委托分析先落到 `.aiws/changes/<id>/analysis/`，由主 agent 在 `ws-review` 或 `review/*.md` 中收敛结论。
+- patch 草案先落到 `.aiws/changes/<id>/patches/`，未经审查不要直接应用。
+- 交付前建议执行：`aiws change evidence <change-id>`，让 `delivery-summary` 与 `collaboration-summary` 一起落到 `.aiws/changes/<id>/evidence/`。
 - finish 自动归档后生成的 `handoff.md` 会包含协同工件摘要，便于下一次会话继续接力。

package/templates/workspace/{changes → .aiws/changes}/templates/proposal.md

@@ -18,8 +18,8 @@
 - 需求交付：`Req_ID` = <!-- WS:TODO （需求交付可填；例如 TOOLING-001B） -->
 - 问题修复：`Problem_ID` = <!-- WS:TODO （问题修复可填；例如 PROB-001） -->
 - `Contract_Row` = <!-- WS:TODO 绑定执行合同中的行 ID，可多项（逗号分隔）；例如 Req_ID=TOOLING-001B -->
-- `Plan_File` = <!-- WS:TODO 例如 plan/2026-02-08_15-30-00-xxx.md -->
-- `Evidence_Path` = <!-- WS:TODO 证据路径，可多项（逗号分隔）；优先写持久证据 changes/<change-id>/evidence/...；也可附带 changes/<change-id>/review/... 或 .agentdocs/tmp/... -->
+- `Plan_File` = <!-- WS:TODO 例如 .aiws/plan/2026-02-08_15-30-00-xxx.md -->
+- `Evidence_Path` = <!-- WS:TODO 证据路径，可多项（逗号分隔）；优先写持久证据 .aiws/changes/<change-id>/evidence/...；也可附带 .aiws/changes/<change-id>/review/... 或 .aiws/tmp/... -->
 
 ## 依赖关系（可选）
 
@@ -33,7 +33,7 @@
 
 > 规则：
 > - `Req_ID` 与 `Problem_ID` 至少填写一项。
-> - `Contract_Row` 必须引用 `requirements/requirements-issues.csv` 或 `issues/problem-issues.csv` 中的真实行。
+> - `Contract_Row` 必须引用 `.aiws/requirements/requirements-issues.csv` 或 `.aiws/issues/problem-issues.csv` 中的真实行。
 > - `Plan_File` 对应的计划文件必须存在，且其绑定字段与本文件一致。
 > - `Evidence_Path` 可先声明计划路径，交付前需完成证据落盘。
 
@@ -48,9 +48,9 @@
 ## 协同与委托（可选）
 
 - `analysis/`：
-  - <!-- WS:TODO 如需委托分析，写明预计产物；例如 `changes/<change-id>/analysis/research-a.md` -->
+  - <!-- WS:TODO 如需委托分析，写明预计产物；例如 `.aiws/changes/<change-id>/analysis/research-a.md` -->
 - `patches/`：
-  - <!-- WS:TODO 如需外部 patch 草案，写明预计文件；例如 `changes/<change-id>/patches/fix-a.patch` -->
+  - <!-- WS:TODO 如需外部 patch 草案，写明预计文件；例如 `.aiws/changes/<change-id>/patches/fix-a.patch` -->
 - `review/`：
   - <!-- WS:TODO 如需多审查者，写明 reviewer 文件命名或汇总策略 -->
 
@@ -96,17 +96,17 @@
 > 从 `AI_WORKSPACE.md` 选择最贴近本变更的验证入口，写成可直接复制执行的命令。
 
 - 命令：
-  - <!-- WS:TODO 例如：`uv run tools/server_test_runner.py --workspace .` -->
+  - <!-- WS:TODO 例如：`uv run .aiws/tools/server_test_runner.py --workspace .` -->
 - 期望结果：
   - <!-- WS:TODO 例如：所有相关用例 DONE；无新增错误日志 -->
 
 ## 真值文件/合同更新清单
 
 - `REQUIREMENTS.md`：<!-- WS:TODO 需要/不需要；如需要，写明新增/修改的验收条款 -->
-- `requirements/CHANGELOG.md`：<!-- WS:TODO 需要/不需要 -->
-- `requirements/requirements-issues.csv`：<!-- WS:TODO 需要/不需要 -->
-- `issues/problem-issues.csv`：<!-- WS:TODO 需要/不需要 -->
+- `.aiws/requirements/CHANGELOG.md`：<!-- WS:TODO 需要/不需要 -->
+- `.aiws/requirements/requirements-issues.csv`：<!-- WS:TODO 需要/不需要 -->
+- `.aiws/issues/problem-issues.csv`：<!-- WS:TODO 需要/不需要 -->
 - 证据落盘（推荐双层）：
-  - 持久（建议入库）：`changes/<change-id>/evidence/...`（例如 validate 总结、review 总结、关键日志摘要）
-  - 临时（可忽略入库）：`.agentdocs/tmp/...`（例如 `aiws validate . --stamp` 的 JSON）
-  - 协同（按需）：`changes/<change-id>/analysis/...`、`patches/...`、`review/...`
+  - 持久（建议入库）：`.aiws/changes/<change-id>/evidence/...`（例如 validate 总结、review 总结、关键日志摘要）
+  - 临时（可忽略入库）：`.aiws/tmp/...`（例如 `aiws validate . --stamp` 的 JSON）
+  - 协同（按需）：`.aiws/changes/<change-id>/analysis/...`、`.aiws/changes/<change-id>/patches/...`、`.aiws/changes/<change-id>/review/...`

package/templates/workspace/{changes → .aiws/changes}/templates/tasks.md

@@ -9,16 +9,16 @@
 - [ ] 0.1 阅读并遵守 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`
 - [ ] 0.2 运行门禁校验：`aiws validate .`（或 `npx -y @aipper/aiws validate .`）
 - [ ] 0.3 若真值文件发生变化（例如你更新了 REQUIREMENTS.md），同步基线：`aiws change sync {{CHANGE_ID}}`
-- [ ] 0.4 在 `changes/{{CHANGE_ID}}/proposal.md` 填写主索引绑定：`Change_ID` / (`Req_ID` or `Problem_ID`) / `Contract_Row` / `Plan_File` / `Evidence_Path`
-- [ ] 0.5 生成 `plan/...` 后，确认计划文件中的绑定字段与 proposal 一致
+- [ ] 0.4 在 `.aiws/changes/{{CHANGE_ID}}/proposal.md` 填写主索引绑定：`Change_ID` / (`Req_ID` or `Problem_ID`) / `Contract_Row` / `Plan_File` / `Evidence_Path`
+- [ ] 0.5 生成 `.aiws/plan/...` 后，确认计划文件中的绑定字段与 proposal 一致
 - [ ] 0.6 执行计划质检：在 AI 工具运行 `$ws-plan-verify`（或按同等清单手工检查“章节/步骤粒度/验证命令与预期”）
 - [ ] 0.7 严格校验：`aiws change validate {{CHANGE_ID}} --strict`
 
 ## 1. 需求/问题合同（如适用）
 
 - [ ] 1.1 需求交付：补齐/更新 `REQUIREMENTS.md` 验收条款（或确认不需要）
-- [ ] 1.2 同步 `requirements/requirements-issues.csv`（或更新 `issues/problem-issues.csv`）
-- [ ] 1.3 记录到 `requirements/CHANGELOG.md`（如需求发生变化）
+- [ ] 1.2 同步 `.aiws/requirements/requirements-issues.csv`（或更新 `.aiws/issues/problem-issues.csv`）
+- [ ] 1.3 记录到 `.aiws/requirements/CHANGELOG.md`（如需求发生变化）
 
 ## 2. 实现
 
@@ -27,9 +27,9 @@
 
 ## 2A. 协同（可选）
 
-- [ ] 2A.1 若使用委托分析：把结果落盘到 `changes/{{CHANGE_ID}}/analysis/`
-- [ ] 2A.2 若使用 patch 草案：把结果落盘到 `changes/{{CHANGE_ID}}/patches/`，并记录是否采用
-- [ ] 2A.3 若存在多审查者：把审查结果落盘到 `changes/{{CHANGE_ID}}/review/`
+- [ ] 2A.1 若使用委托分析：把结果落盘到 `.aiws/changes/{{CHANGE_ID}}/analysis/`
+- [ ] 2A.2 若使用 patch 草案：把结果落盘到 `.aiws/changes/{{CHANGE_ID}}/patches/`，并记录是否采用
+- [ ] 2A.3 若存在多审查者：把审查结果落盘到 `.aiws/changes/{{CHANGE_ID}}/review/`
 
 ## 3. 验证（必须可复现）
 
@@ -38,7 +38,7 @@
 
 ## 4. 交付与归档
 
-- [ ] 4.1 证据落盘到 `.agentdocs/tmp/...`（报告/日志/请求响应等）
+- [ ] 4.1 证据落盘到 `.aiws/tmp/...`（报告/日志/请求响应等）
 - [ ] 4.2 生成持久证据：`aiws change evidence {{CHANGE_ID}}`
 - [ ] 4.3 交叉审计（可选但推荐）：在 AI 工具内运行 `/ws-review`（或按 `AI_PROJECT.md` 手工审计）
 - [ ] 4.4 收尾：`aiws change finish {{CHANGE_ID}} --push`（成功后自动归档并生成 handoff）

package/templates/workspace/{issues → .aiws/issues}/problem-issues.csv

@@ -1,2 +1,2 @@
 Problem_ID,Type,Severity,Title,Symptom,Repro,Root_Cause,Fix_Plan,Files,Tests,Evidence,Status,Owner,Created_At,Updated_At,Notes
-PROB-000,BUG,P2,示例：/api/system/menu/routes 返回 500,"访问 routes 接口报 500；日志提示参数解析错误","curl -sS -H 'Authorization: Bearer <token>' 'http://localhost:8080/api/system/menu/routes?x=1'","Controller 入参类型与前端实际 query 不一致","对齐入参定义并补充单测；复测 runner 端点状态更新为 DONE","server/src/...","uv run tools/server_test_runner.py --workspace . --service backend --max-endpoints 10",".agentdocs/tmp/server-test/report.json",TODO,ab,YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ,"若该问题阻塞某个需求交付，在 requirements/requirements-issues.csv 的 Notes 里关联 Problem_ID"
+PROB-000,BUG,P2,示例：/api/system/menu/routes 返回 500,"访问 routes 接口报 500；日志提示参数解析错误","curl -sS -H 'Authorization: Bearer <token>' 'http://localhost:8080/api/system/menu/routes?x=1'","Controller 入参类型与前端实际 query 不一致","对齐入参定义并补充单测；复测 runner 端点状态更新为 DONE","server/src/...","uv run .aiws/tools/server_test_runner.py --workspace . --service backend --max-endpoints 10",".aiws/tmp/server-test/report.json",TODO,ab,YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ,"若该问题阻塞某个需求交付，在 .aiws/requirements/requirements-issues.csv 的 Notes 里关联 Problem_ID"

package/templates/workspace/.aiws/journal/.gitkeep

@@ -0,0 +1 @@
+

package/templates/workspace/{requirements → .aiws/requirements}/requirements-issues.csv

@@ -1,2 +1,2 @@
 Req_ID,Title,Change_Type,Module,CRUD,Actor,Scenario,Preconditions,Inputs,Outputs,Data_Model,Business_Logic,API_Impact,NonFunctional,Spec_Status,Impl_Status,Tests,Evidence,Owner,Created_At,Updated_At,Notes
-REQ-000,示例：用户列表分页支持按部门筛选,ADD,system/user,R,admin,管理员在用户管理页按部门筛选列表,已登录且有 system:user:list 权限,"deptId=10&page=1&pageSize=20",返回包含 deptId=10 的用户列表,"user,dept 表（字段：dept_id）","查询条件增加 deptId；默认不传不筛选；分页参数边界：page>=1&pageSize<=100",GET /api/system/user/list 新增 query 参数 deptId（可选），响应字段不变,性能：分页查询需走索引；安全：权限不变,READY,TODO,"uv run tools/server_test_runner.py --workspace . --service demo-spring --max-endpoints 10",.agentdocs/tmp/server-test/report.json,ab,YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ,
+REQ-000,示例：用户列表分页支持按部门筛选,ADD,system/user,R,admin,管理员在用户管理页按部门筛选列表,已登录且有 system:user:list 权限,"deptId=10&page=1&pageSize=20",返回包含 deptId=10 的用户列表,"user,dept 表（字段：dept_id）","查询条件增加 deptId；默认不传不筛选；分页参数边界：page>=1&pageSize<=100",GET /api/system/user/list 新增 query 参数 deptId（可选），响应字段不变,性能：分页查询需走索引；安全：权限不变,READY,TODO,"uv run .aiws/tools/server_test_runner.py --workspace . --service demo-spring --max-endpoints 10",.aiws/tmp/server-test/report.json,ab,YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ,

package/templates/workspace/{tools → .aiws/tools}/requirements_contract.py

@@ -198,9 +198,9 @@ def validate_rows(rows: List[Dict[str, str]]) -> List[ValidateProblem]:
 
 
 def main(argv: List[str]) -> int:
-    p = argparse.ArgumentParser(description="Manage requirements execution contract CSV (requirements/requirements-issues.csv).")
+    p = argparse.ArgumentParser(description="Manage requirements execution contract CSV (.aiws/requirements/requirements-issues.csv).")
     p.add_argument("--workspace", default=".", help="workspace root")
-    p.add_argument("--csv", default="requirements/requirements-issues.csv", help="contract CSV path (relative to workspace)")
+    p.add_argument("--csv", default=".aiws/requirements/requirements-issues.csv", help="contract CSV path (relative to workspace)")
     sub = p.add_subparsers(dest="cmd", required=True)
 
     sub.add_parser("init", help="create CSV with header if missing")

package/templates/workspace/{tools → .aiws/tools}/requirements_contract_sync.py

@@ -243,7 +243,7 @@ def main(argv: List[str]) -> int:
     p = argparse.ArgumentParser(description="Backfill requirements contract CSV from REQUIREMENTS.md FlowSpec.")
     p.add_argument("--workspace", default=".", help="workspace root")
     p.add_argument("--requirements", default="REQUIREMENTS.md", help="requirements markdown path (relative to workspace)")
-    p.add_argument("--out-csv", default="requirements/requirements-issues.csv", help="output contract CSV path")
+    p.add_argument("--out-csv", default=".aiws/requirements/requirements-issues.csv", help="output contract CSV path")
     p.add_argument("--owner", default="", help="default Owner for new rows")
     p.add_argument(
         "--default-tests",
@@ -281,7 +281,7 @@ def main(argv: List[str]) -> int:
     print(f"- flows: {stats['total_flows']}")
     print(f"- created: {stats['created']}")
     print(f"- updated: {stats['updated']}")
-    print("next: fill missing fields, then run: python3 tools/requirements_contract.py validate")
+    print("next: fill missing fields, then run: python3 .aiws/tools/requirements_contract.py validate")
     return 0
 
 

package/templates/workspace/{tools → .aiws/tools}/requirements_flow_gen.py

@@ -222,7 +222,7 @@ def main(argv: List[str]) -> int:
     p.add_argument("--workspace", default=".", help="workspace root")
     p.add_argument("--requirements", default="REQUIREMENTS.md", help="requirements markdown path (relative to workspace)")
     p.add_argument("--out-mermaid", default="docs/api-flow.mmd", help="output mermaid file (relative to workspace)")
-    p.add_argument("--out-csv", default="issues/server-scenario-issues.csv", help="output scenario CSV (relative to workspace)")
+    p.add_argument("--out-csv", default=".aiws/issues/server-scenario-issues.csv", help="output scenario CSV (relative to workspace)")
     args = p.parse_args(argv)
 
     root = Path(args.workspace).resolve()

package/templates/workspace/{tools → .aiws/tools}/server_test_runner.py

@@ -114,7 +114,7 @@ class WorkspaceConfig:
     health_path: str = "/health"
     openapi_path: str = "docs/openapi.json"
     openapi_url: str = "/openapi.json"
-    log_path: str = ".agentdocs/tmp/server-test/app.log"
+    log_path: str = ".aiws/tmp/server-test/app.log"
     request_id_header: str = "X-Request-Id"
     server_dirs: Tuple[str, ...] = ()
     build_cmd: str = ""
@@ -359,7 +359,7 @@ def parse_ai_workspace_md(path: Path) -> WorkspaceConfig:
     health_path = find_scalar("health_path") or "/health"
     openapi_path = find_scalar("openapi_path") or "docs/openapi.json"
     openapi_url = find_scalar("openapi_url") or "/openapi.json"
-    log_path = find_scalar("log_path") or ".agentdocs/tmp/server-test/app.log"
+    log_path = find_scalar("log_path") or ".aiws/tmp/server-test/app.log"
     request_id_header = find_scalar("request_id_header") or "X-Request-Id"
 
     server_dirs = tuple(find_list("server_dirs"))
@@ -703,9 +703,9 @@ def render_cmd(template: str, *, service_dir: Path, service_name: str) -> str:
 
 def resolve_log_file(log_path: str, *, workspace_root: Path, service_name: str) -> Path:
     """
-    Resolve log file path with optional {service} placeholder; defaults to per-service log under .agentdocs/tmp/server-test.
+    Resolve log file path with optional {service} placeholder; defaults to per-service log under .aiws/tmp/server-test.
     """
-    path_str = (log_path or "").strip() or ".agentdocs/tmp/server-test/{service}.log"
+    path_str = (log_path or "").strip() or ".aiws/tmp/server-test/{service}.log"
     path_str = path_str.replace("{service}", service_name)
     return (workspace_root / path_str).resolve()
 
@@ -1278,7 +1278,7 @@ def write_fix_issues_csv(
         )
 
     write_fix_csv_rows(fix_csv_path, out_rows)
-    triage_csv_path = (workspace_root / "issues" / "server-triage-issues.csv").resolve()
+    triage_csv_path = (workspace_root / ".aiws" / "issues" / "server-triage-issues.csv").resolve()
     write_triage_issues_csv(triage_csv_path=triage_csv_path, fix_rows=out_rows, generated_at=generated_at)
 
 
@@ -1564,9 +1564,9 @@ def main(argv: List[str]) -> int:
     parser = argparse.ArgumentParser(description="Workspace server API test runner (OpenAPI -> CSV -> requests -> log correlation)")
     parser.add_argument("--workspace", default=".", help="workspace root (directory A)")
     parser.add_argument("--service", default="", help="optional: only run one service directory name")
-    parser.add_argument("--csv", default="issues/server-api-issues.csv", help="execution contract CSV path (relative to workspace)")
-    parser.add_argument("--out-dir", default=".agentdocs/tmp/server-test", help="output dir for responses (relative to workspace)")
-    parser.add_argument("--base-url", default="", help="override base_url (otherwise use secrets/test-accounts.json or AI_WORKSPACE.md)")
+    parser.add_argument("--csv", default=".aiws/issues/server-api-issues.csv", help="execution contract CSV path (relative to workspace)")
+    parser.add_argument("--out-dir", default=".aiws/tmp/server-test", help="output dir for responses (relative to workspace)")
+    parser.add_argument("--base-url", default="", help="override base_url (otherwise use .aiws/secrets/test-accounts.json or AI_WORKSPACE.md)")
     parser.add_argument("--health-timeout", type=int, default=60, help="seconds to wait for health endpoint")
     parser.add_argument("--no-wait-health", action="store_true", help="skip health check wait")
     parser.add_argument("--refresh-openapi", action="store_true", help="always export OpenAPI from openapi_url into docs/openapi.json")
@@ -1582,7 +1582,7 @@ def main(argv: List[str]) -> int:
     ai_workspace_md = workspace_root / "AI_WORKSPACE.md"
     cfg = parse_ai_workspace_md(ai_workspace_md)
 
-    secrets_path = workspace_root / "secrets" / "test-accounts.json"
+    secrets_path = workspace_root / ".aiws" / "secrets" / "test-accounts.json"
     secrets = load_secrets(secrets_path)
 
     csv_path = (workspace_root / args.csv).resolve()
@@ -1850,7 +1850,7 @@ def main(argv: List[str]) -> int:
         if openapi_used:
             report["openapi_used"] = openapi_used
         write_text_if_changed(report_path, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
-        fix_csv_path = (workspace_root / "issues" / "server-fix-issues.csv").resolve()
+        fix_csv_path = (workspace_root / ".aiws" / "issues" / "server-fix-issues.csv").resolve()
         write_fix_issues_csv(
             fix_csv_path=fix_csv_path,
             endpoint_rows=updated_rows,