@aipper/aiws-spec 0.0.28 → 0.0.30

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/commands/ws-review.md

@@ -14,7 +14,11 @@
 3) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
-4) 回复中输出：
+4) 若当前任务已进入“准备提交/交付/finish”的语境，继续补齐 dual review gate：
+   - 运行/收敛 `/ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`
+   - 运行/收敛 `/ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+5) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

package/templates/workspace/.claude/settings.json.example

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "mkdir -p .agentdocs/tmp/opencode-autonomy && printf '[user-prompt-submit] %s\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" >> .agentdocs/tmp/opencode-autonomy/claude-hooks.log"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "mkdir -p .agentdocs/tmp/opencode-autonomy && printf '[stop] %s\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" >> .agentdocs/tmp/opencode-autonomy/claude-hooks.log"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,130 +1,18 @@
 ---
 name: ws-commit
-description: 提交（当前分支可直提；submodule 感知；先审计/门禁再 commit）
+description: `aiws commit` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-commit
 
-目标：
-- 支持在**当前分支直接提交**（不要求必须先切 `change/<change-id>`）
-- 提交前审计与证据落盘（`$ws-review`）
-- 提交前门禁校验与证据落盘（`aiws validate . --stamp`）
-- 最后执行 `git commit`（commit 前必须让用户确认 message；不使用 `--no-verify` 绕过 hooks）
-- 若仓库含 submodule：提交前识别并提示正确顺序（先 submodule，再 superproject）
- - 若你经常遇到 submodule detached：建议日常拉取使用 `$ws-pull`（尽量把 submodule “挂回分支”且不改变 gitlink commit）
+`aiws commit` 的薄包装入口。
 
-安全约束（强制）：
-- 不自动 `git add -A`（避免误提交）；只在用户明确指示时才执行 staging 命令
-- 不自动 push
-- 不写入任何 secrets
-- 检测到 submodule 有未提交改动时，不允许直接提交 superproject（先处理 submodule）
-- commit message 优先使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
-- 若启用了 `.githooks/commit-msg`：默认按仓库角色区分
-  - superproject / root 仓库（存在 `.gitmodules`）默认允许自由 commit message
-  - submodule / 普通仓库默认提示优先中文
-  - 只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
-
-阶段定位：
-- commit gate；负责在提交前收敛 review、validate 和 message 确认，不允许跳过 hooks。
-
-必需输入：
-- 当前分支与 staged diff
-- `$ws-review` 生成的审计证据
-- `aiws validate . --stamp` 生成的校验证据
-- 用户确认后的 commit message
-
-必需输出：
-- `证据（Evidence）:` review 文件路径 + validate stamp 路径
-- `上下文（Context）:` 当前分支、submodule 检测结果、阻断原因（若有）
-- `提交信息（Commit）:` 最终提交信息
-
-阻断条件：
-- 没有 staged changes
-- submodule 工作区不干净或 detached 处理不完整
-- 用户未确认 commit message
-- validate 失败
-
-完成判定：
-- 提交已完成，证据路径明确，且没有通过 `--no-verify` 绕过门禁。
-
-执行步骤（建议）：
-1) 运行 `$ws-preflight`（确保真值文件就绪）。
-2) 运行 `$ws-review`（优先生成审计证据：`changes/<change-id>/review/codex-review.md`；无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`）。
-3) 运行门禁校验并写 stamp：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate . --stamp
+  ./node_modules/.bin/aiws commit
 elif command -v aiws >/dev/null 2>&1; then
-  aiws validate . --stamp
+  aiws commit
 else
-  npx @aipper/aiws validate . --stamp
-fi
-```
-4) 输出当前提交上下文（必须输出给用户确认）：
-```bash
-git branch --show-current
-git status --porcelain
-```
-5) 检测是否存在 submodule（有则进入 submodule 感知模式）：
-```bash
-if [[ -f .gitmodules ]]; then
-  git config --file .gitmodules --get-regexp '^submodule\..*\.path$' || true
-else
-  echo "[info] no .gitmodules"
-fi
-```
-6) 若存在 submodule，逐个检查子仓库工作区是否干净：
-```bash
-while read -r _ sub_path; do
-  [[ -z "${sub_path:-}" ]] && continue
-  echo "== submodule: ${sub_path} =="
-  git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
-  git -C "${sub_path}" status --porcelain || true
-done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true)
-```
-判定规则（强制）：
-- 任一 submodule `git status --porcelain` 非空：停止 superproject commit，先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
-- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target_branch>`；不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
-处理指引（detached submodule）：
-```bash
-cur_branch="$(git branch --show-current)"
-change_id="$(echo "${cur_branch}" | sed -n 's|^change/||p')"
-targets="changes/${change_id}/submodules.targets"
-
-source tools/ws_resolve_sub_target.sh
-ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${cur_branch}" || exit 2
-target_branch="${_resolved_branch}"
-remote="${_resolved_remote}"
-
-git -C "${sub_path}" fetch "${remote}" --prune
-if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
-  echo "error: missing ${remote}/${target_branch} for submodule path=${sub_path}"
-  exit 2
+  npx @aipper/aiws commit
 fi
-git -C "${sub_path}" checkout -B "aiws/pin/${target_branch}" HEAD
-git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
 ```
-7) 检查当前 staging 内容（必须输出给用户确认）：
-```bash
-git status --porcelain
-git diff --staged --submodule=short
-```
-8) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-9) 生成中文 commit message 草案（格式：`<类型>: <简述>`），输出给用户确认后再执行。
-   - 类型参考：`功能` / `修复` / `重构` / `文档` / `测试` / `构建` / `杂项`
-   - 简述用一句话概括本次改动的"为什么"而非"改了什么"
-   - 命令/路径/代码标识符保持原样不翻译
-   - 若用户给出全英文 message：优先改写成中文；若用户明确要求保留英文，也可以提交（但 strict 模式下会被 hook 拒绝）
-10) 执行提交（不带 `--no-verify`）：
-```bash
-git commit -m "<message>"
-```
-11) 输出提交结果（可选）：
-```bash
-git show --stat --oneline -1
-```
-
-输出要求：
-- `证据（Evidence）:` `changes/<change-id>/review/codex-review.md`（无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`） + `.agentdocs/tmp/aiws-validate/*.json`
-- `上下文（Context）:` 当前分支 + 是否检测到 submodule + 若阻断则给出阻断原因
-- `提交信息（Commit）:` 最终使用的 commit message（仅当用户确认后）