@aipper/aiws-spec 0.0.29 → 0.0.31

package/templates/workspace/.agents/skills/ws-spec-review/SKILL.md

@@ -7,7 +7,7 @@ description: 规范审查（requirements / plan / evidence / gate 完整性）
 
 目标：
 - 审查当前改动是否满足真值文件、change 绑定、证据路径和 gate 完整性要求
-- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `changes/<change-id>/review/spec-review.md`
+- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `.aiws/changes/<change-id>/review/spec-review.md`
 
 阶段定位：
 - review 子 gate；负责 requirements / plan / evidence / workflow gate 完整性审查。
@@ -17,10 +17,10 @@ description: 规范审查（requirements / plan / evidence / gate 完整性）
 - `REQUIREMENTS.md`
 - `AI_WORKSPACE.md`
 - 当前 `git diff`
-- 若存在：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`、`review/`、`evidence/`
+- 若存在：`plan/...`、`.aiws/changes/<change-id>/proposal.md`、`tasks.md`、`review/`、`evidence/`
 
 必需输出：
-- `证据（Evidence）:` `changes/<change-id>/review/spec-review.md` 或回退 `.agentdocs/tmp/review/spec-review.md`
+- `证据（Evidence）:` `.aiws/changes/<change-id>/review/spec-review.md` 或回退 `.aiws/tmp/review/spec-review.md`
 - `阻断项（Blockers）:` requirements 归因 / gate / evidence 缺口
 - `下一步（Next）:` 修复项与最小验证命令
 
@@ -40,8 +40,8 @@ description: 规范审查（requirements / plan / evidence / gate 完整性）
    - 是否存在越界目录改动、危险操作、未声明的非目标扩张
    - 是否已经准备好可复现验证入口
 3) 把结论落盘到：
-   - 默认：`changes/<change-id>/review/spec-review.md`
-   - 回退：`.agentdocs/tmp/review/spec-review.md`
+   - 默认：`.aiws/changes/<change-id>/review/spec-review.md`
+   - 回退：`.aiws/tmp/review/spec-review.md`
 4) 输出：
    - `证据（Evidence）:`
    - `阻断项（Blockers）:`

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,

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

@@ -213,7 +213,7 @@ def parse_archived_change_dir_name(entry_name: str) -> Optional[Tuple[str, str,
 
 
 def find_archived_change(root: Path, change_id: str) -> Optional[Path]:
-    archive_root = root / "changes" / "archive"
+    archive_root = root / ".aiws" / "changes" / "archive"
     if not archive_root.exists():
         return None
     matches: List[Path] = []
@@ -283,7 +283,7 @@ def summarize_finish_state(change_dir: Path) -> str:
 
 
 def terminated_change_message(root: Path, change_id: str) -> Optional[str]:
-    change_dir = root / "changes" / change_id
+    change_dir = root / ".aiws" / "changes" / change_id
     if change_dir.exists() and summarize_finish_state(change_dir) == "done":
         return (
             f"change/{change_id} already reached finish, but archive/push closeout is still pending; "
@@ -335,7 +335,7 @@ def split_declared_values(value: str) -> List[str]:
 
 def normalize_contract_ref(raw: str) -> Tuple[str, str]:
     token = raw.strip().strip("`").strip()
-    token = re.sub(r"^(requirements/requirements-issues\.csv|issues/problem-issues\.csv)\s*[:#]\s*", "", token)
+    token = re.sub(r"^(\.aiws/requirements/requirements-issues\.csv|\.aiws/issues/problem-issues\.csv)\s*[:#]\s*", "", token)
     m = re.match(r"(?i)^(req[_-]?id|problem[_-]?id)\s*=\s*(.+)$", token)
     if m:
         key = m.group(1).lower()
@@ -560,7 +560,7 @@ def validate_change(
     check_evidence: bool,
     check_scope: bool,
 ) -> int:
-    change_dir = root / "changes" / change_id
+    change_dir = root / ".aiws" / "changes" / change_id
     required_files = ["proposal.md", "tasks.md"]
 
     errors: List[str] = []
@@ -572,7 +572,7 @@ def validate_change(
     if subs:
         targets_path = change_dir / "submodules.targets"
         if not targets_path.exists() or targets_path.stat().st_size == 0:
-            msg = "missing/empty: changes/<change-id>/submodules.targets (required when .gitmodules declares submodules)"
+            msg = "missing/empty: .aiws/changes/<change-id>/submodules.targets (required when .gitmodules declares submodules)"
             hint = f"hint: create it under {change_dir} (format: <sub_path> <target_branch> [remote])"
             if strict:
                 errors.append(msg)
@@ -685,7 +685,7 @@ def validate_change(
                         f"{sub_path}: gitlink commit {gitlink_sha} is not contained in declared target branch {remote}/{target_branch}"
                     )
                     errors.append(
-                        f"hint: fix `.gitmodules` / `changes/{change_id}/submodules.targets`, or move the submodule gitlink onto a commit reachable from {remote}/{target_branch}"
+                        f"hint: fix `.gitmodules` / `.aiws/changes/{change_id}/submodules.targets`, or move the submodule gitlink onto a commit reachable from {remote}/{target_branch}"
                     )
 
     def placeholder_scan(rel: str, text: str) -> None:
@@ -696,7 +696,7 @@ def validate_change(
 
     def evidence_is_persistent(p: str) -> bool:
         p2 = p.replace("\\", "/")
-        return p2.startswith(f"changes/{change_id}/evidence/") or p2.startswith(f"changes/{change_id}/review/")
+        return p2.startswith(f".aiws/changes/{change_id}/evidence/") or p2.startswith(f".aiws/changes/{change_id}/review/")
 
     def parse_scope_patterns_from_plan(plan_text: str) -> List[str]:
         # Extract allow-list bullet items from a plan's scope section.
@@ -777,7 +777,7 @@ def validate_change(
         has_persistent = any(evidence_is_persistent(p) for p in paths)
         if not has_persistent:
             (errors if strict else warnings).append(
-                f"{rel} Evidence_Path should include at least one persistent path under changes/<id>/evidence or changes/<id>/review"
+                f"{rel} Evidence_Path should include at least one persistent path under .aiws/changes/<id>/evidence or .aiws/changes/<id>/review"
             )
         for raw in paths:
             p = raw.strip()
@@ -819,7 +819,7 @@ def validate_change(
                 base_branch = ""
         if not base_branch:
             (errors if strict else warnings).append(
-                "scope check requires base_branch recorded in changes/<id>/.ws-change.json (run `aiws change start <id>` to record it)"
+                "scope check requires base_branch recorded in .aiws/changes/<id>/.ws-change.json (run `aiws change start <id>` to record it)"
             )
             return
 
@@ -879,11 +879,11 @@ def validate_change(
 
         # Always allow core workflow artifacts.
         always_allow = [
-            f"changes/{change_id}/**",
-            "plan/**",
+            f".aiws/changes/{change_id}/**",
+            ".aiws/plan/**",
             "REQUIREMENTS.md",
-            "requirements/requirements-issues.csv",
-            "issues/problem-issues.csv",
+            ".aiws/requirements/requirements-issues.csv",
+            ".aiws/issues/problem-issues.csv",
         ]
         all_patterns = patterns + always_allow
 
@@ -898,8 +898,8 @@ def validate_change(
     contract_row_decl = ""
     plan_file_decl = ""
     evidence_path_decl = ""
-    req_csv = root / "requirements" / "requirements-issues.csv"
-    prob_csv = root / "issues" / "problem-issues.csv"
+    req_csv = root / ".aiws" / "requirements" / "requirements-issues.csv"
+    prob_csv = root / ".aiws" / "issues" / "problem-issues.csv"
 
     if proposal_path:
         t = read_text(proposal_path)
@@ -936,18 +936,18 @@ def validate_change(
             try:
                 ok = csv_has_id(req_csv, "Req_ID", req_id)
             except Exception as e:
-                warnings.append(f"failed to read requirements/requirements-issues.csv: {e}")
+                warnings.append(f"failed to read .aiws/requirements/requirements-issues.csv: {e}")
             if not ok:
-                (errors if strict else warnings).append(f"Req_ID not found in requirements/requirements-issues.csv: {req_id}")
+                (errors if strict else warnings).append(f"Req_ID not found in .aiws/requirements/requirements-issues.csv: {req_id}")
 
         if prob_id and prob_csv.exists():
             ok = False
             try:
                 ok = csv_has_id(prob_csv, "Problem_ID", prob_id)
             except Exception as e:
-                warnings.append(f"failed to read issues/problem-issues.csv: {e}")
+                warnings.append(f"failed to read .aiws/issues/problem-issues.csv: {e}")
             if not ok:
-                (errors if strict else warnings).append(f"Problem_ID not found in issues/problem-issues.csv: {prob_id}")
+                (errors if strict else warnings).append(f"Problem_ID not found in .aiws/issues/problem-issues.csv: {prob_id}")
 
         normalized_contract_refs: List[Tuple[str, str]] = []
         for raw_ref in split_declared_values(contract_row_decl):
@@ -969,7 +969,7 @@ def validate_change(
             except Exception as e:
                 warnings.append(f"failed to resolve Contract_Row reference {raw_ref}: {e}")
             if not found:
-                (errors if strict else warnings).append(f"Contract_Row not found in requirements/problem CSVs: {raw_ref}")
+                (errors if strict else warnings).append(f"Contract_Row not found in .aiws/requirements/problem CSVs: {raw_ref}")
                 continue
             normalized_contract_refs.append((resolved_kind, value))
 
@@ -995,8 +995,8 @@ def validate_change(
                 plan_rel = plan_rel[2:]
             if os.path.isabs(plan_rel):
                 (errors if strict else warnings).append(f"Plan_File must be workspace-relative, got absolute path: {plan_rel}")
-            if not plan_rel.startswith("plan/"):
-                (errors if strict else warnings).append(f"Plan_File should be under plan/: {plan_rel}")
+            if not plan_rel.startswith(".aiws/plan/"):
+                (errors if strict else warnings).append(f"Plan_File should be under .aiws/plan/: {plan_rel}")
 
             plan_abs = (root / plan_rel).resolve()
             try:
@@ -1178,7 +1178,7 @@ def main(argv: Optional[List[str]] = None) -> int:
                         eprint(f"error: change-id does not match branch (branch={branch_arg}, change_id={change_id})")
                         return 2
 
-    change_dir = root / "changes" / change_id
+    change_dir = root / ".aiws" / "changes" / change_id
     terminated = terminated_change_message(root, change_id) if (inferred_from_branch or bool(branch_arg)) else None
     if terminated:
         eprint(f"error: {terminated}")

package/templates/workspace/{tools → .aiws/tools}/ws_resolve_sub_target.sh

@@ -2,7 +2,7 @@
 # ws_resolve_sub_target.sh — Resolve the target branch & remote for a submodule path.
 #
 # Usage:
-#   source tools/ws_resolve_sub_target.sh
+#   source .aiws/tools/ws_resolve_sub_target.sh
 #   ws_resolve_sub_target <sub_path> <sub_name> <targets_file> <base_branch>
 #
 # Outputs two variables: _resolved_branch and _resolved_remote.
@@ -13,7 +13,7 @@ ws_resolve_sub_target() {
   _resolved_branch=""
   _resolved_remote=""
 
-  # Priority 1: changes/<id>/submodules.targets (per-change override)
+  # Priority 1: .aiws/changes/<id>/submodules.targets (per-change override)
   local override=""
   if [[ -f "${targets}" ]]; then
     override="$(awk -v p="${sub_path}" '

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Generate an update_plan JSON payload from changes/<id>/tasks.md checkbox tasks.
+Generate an update_plan JSON payload from .aiws/changes/<id>/tasks.md checkbox tasks.
 
 This script is intended to be used by the `p-tasks-plan` Codex skill.
 It reads tasks.md only and does not modify it.
@@ -116,11 +116,11 @@ def build_parser() -> argparse.ArgumentParser:
     sub = p.add_subparsers(dest="cmd", required=True)
 
     p_status = sub.add_parser("status", help="Print progress summary from tasks.md")
-    p_status.add_argument("--file", required=True, help="Path to changes/<id>/tasks.md")
+    p_status.add_argument("--file", required=True, help="Path to .aiws/changes/<id>/tasks.md")
     p_status.set_defaults(fn=cmd_status)
 
     p_plan = sub.add_parser("plan", help="Generate update_plan JSON payload from tasks.md")
-    p_plan.add_argument("--file", required=True, help="Path to changes/<id>/tasks.md")
+    p_plan.add_argument("--file", required=True, help="Path to .aiws/changes/<id>/tasks.md")
     p_plan.add_argument("--explanation", default="", help="Explanation for update_plan payload")
     p_plan.set_defaults(fn=cmd_plan)
 

package/templates/workspace/.claude/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
 ```