@aipper/aiws-spec 0.0.29 → 0.0.30

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
 ```

package/templates/workspace/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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/.githooks/pre-commit

@@ -30,3 +30,16 @@ if [[ -z "${aiws_bin:-}" ]]; then
 fi
 
 "$aiws_bin" validate .
+
+# Quality gates (non-blocking warnings)
+if [[ -f "package.json" ]] && grep -q '"lint"' package.json 2>/dev/null; then
+  npm run lint >/dev/null 2>&1 || echo "warn: lint found issues (non-blocking)" >&2
+fi
+
+if [[ -f "packages/aiws/package.json" ]] && grep -q '"build"' packages/aiws/package.json 2>/dev/null; then
+  npm run --workspace packages/aiws build >/dev/null 2>&1 || echo "warn: build/typecheck found issues (non-blocking)" >&2
+fi
+
+if [[ -f "package.json" ]] && grep -q '"test"' package.json 2>/dev/null; then
+  npm test >/dev/null 2>&1 || echo "warn: tests found issues (non-blocking)" >&2
+fi

package/templates/workspace/.githooks/pre-push

@@ -30,3 +30,10 @@ if [[ -z "${aiws_bin:-}" ]]; then
 fi
 
 "$aiws_bin" validate .
+
+# Quality gates — non-blocking (failures downgraded to warning to avoid false positives)
+if [[ -f "$root/package.json" ]]; then
+  npm --prefix "$root" run lint --if-present 2>/dev/null || echo "[aiws] lint: skipped or failed (non-blocking)" >&2
+  npm --prefix "$root" run typecheck --if-present 2>/dev/null || echo "[aiws] typecheck: skipped or failed (non-blocking)" >&2
+  npm --prefix "$root" test --if-present 2>/dev/null || echo "[aiws] test: skipped or failed (non-blocking)" >&2
+fi

package/templates/workspace/.opencode/commands/ws-finish.md

@@ -4,7 +4,72 @@ description: 收尾：fast-forward 合并并把 submodule 并回目标分支后
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-finish -->
 # ws finish
 
-Thin CLI wrapper. Delegates to `aiws finish`.
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，避免手输分支名导致的错误。
+补充：若团队希望减少 submodule detached 的人为差异，建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `/ws-pull`。
+
+前置（必须）：
+- 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
+- change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
+- 普通 finish 的 `validate/evidence/state` 应先在 `change/<change-id>` worktree 完成；真正执行 `aiws change finish` 时再切到目标分支所在 worktree
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`：说明 merge 已发生，只需继续 push / archive / cleanup closeout；直接在提示的 worktree 运行 `aiws change finish <change-id> --push`
+- 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
+
+步骤（建议）：
+0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
+```bash
+if [[ -f .gitmodules ]]; then
+  missing=0
+  while read -r key sub_path; do
+    name="${key#submodule.}"; name="${name%.path}"
+    b="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+    if [[ -z "${b:-}" ]]; then
+      echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+      missing=1
+    fi
+  done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+  if [[ "$missing" -ne 0 ]]; then
+    echo "hint: run /ws-submodule-setup (and commit .gitmodules), then retry"
+    exit 2
+  fi
+fi
+```
+1) 先运行 `/ws-preflight`（确保真值文件齐全）。
+2) 先运行 `aiws change status <change-id>`，优先看稳定字段 `governance_rule:`。
+   - 若为 `finish_resume_required`：直接跳到步骤 3 执行 `aiws change finish <change-id> --push`
+   - 若不是该值：按普通 finish 继续；不要依赖自然语言提示句做分支判断
+2.1) 普通 finish 时，`aiws validate . --stamp` / `aiws change evidence <change-id>` / `aiws change state <change-id> --write` 应在 `change/<change-id>` worktree 完成。
+   - 如果已经在目标分支 worktree，且 `governance_rule` 不是 `finish_resume_required`，不要在这里跑 `aiws validate . --stamp`；先回 `change/<change-id>` worktree，或先跑 `/ws-verify-before-complete`
+3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
+   - `aiws change finish <change-id> --push`
+   - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`
+   - 该命令会在 fast-forward 合并成功后 push 目标分支；默认优先使用 upstream 配置（`branch.<name>.remote` + `branch.<name>.merge`），只有在你明确知道要推向别的 remote 时才追加 `--remote <name>`
+   - 若 `change/<change-id>` 位于独立 worktree，且该 worktree 干净，则会在 push 成功后自动执行 `git worktree remove` + `git worktree prune`
+   - AI 入口执行前，应先向用户说明将要 push 的 remote/branch；显式传入 `--push` 即视为确认
+4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+5) 若需要先处理 submodules，则按顺序处理每个 submodule（减少 detached；再 push）：
+   - 先显式解析 base branch，不要用当前分支名替代：
+     - `python3 - <<'PY'`
+     - `import json, pathlib; meta = pathlib.Path("changes") / "<change-id>" / ".ws-change.json"; print((json.loads(meta.read_text(encoding="utf-8")).get("base_branch") or "").strip())`
+     - `PY`
+   - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+   - 对每个 `<sub_path>`：
+     - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
+     - 目标分支真值：`changes/<change-id>/submodules.targets`；若条目里分支写 `.`，则展开为刚才解析出的 `base_branch`
+     - 生成/检查 `submodules.targets` 时，detached HEAD 默认建议取 `.gitmodules` 的 `submodule.<name>.branch`；已附着在本地分支时默认建议取当前分支；这些都只是预填建议，不是 finish/push 的运行时真值
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached
+     - 用 pin 分支挂回（不改动现有 main/master 指针）：`git -C "<sub_path>" checkout -B "aiws/pin/<target-branch>" <gitlink-sha>`
+     - 仅当 `<gitlink-sha>` 属于 `origin/<target-branch>` 历史时才允许 push；否则停止并人工处理分叉
+     - push（只允许 fast-forward）：`git -C "<sub_path>" push origin "<gitlink-sha>:refs/heads/<target-branch>"`
+6) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
+7) submodules 全部成功后，再回到主仓库执行：
+   - `aiws change finish <change-id> --push`
+8) `aiws change finish --push` 成功后会自动归档并生成 handoff；只有历史/异常场景才需要手工运行 `aiws change archive <change-id>`。
+
+安全：
+- push 前先输出状态并说明远端/分支。
+- 不执行破坏性命令。
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then

package/templates/workspace/.opencode/helpers/approval-whitelist-check.sh

@@ -44,7 +44,7 @@ decision_kind = sys.argv[3]
 paths = sys.argv[4:]
 
 config_path = workspace_root / ".opencode" / "oh-my-opencode.json"
-out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".agentdocs" / "tmp" / "opencode-autonomy"))
+out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".aiws" / "tmp" / "opencode-autonomy"))
 out_dir.mkdir(parents=True, exist_ok=True)
 log_file = out_dir / "approval-whitelist.log"
 result_file = out_dir / "approval-whitelist-last.json"

package/templates/workspace/.opencode/helpers/approval-whitelist-run.sh

@@ -26,7 +26,7 @@ from pathlib import Path
 workspace_root = Path(sys.argv[1]).resolve()
 payload = json.loads(sys.argv[2])
 
-out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".agentdocs" / "tmp" / "opencode-autonomy"))
+out_dir = Path(os.environ.get("AIWS_OPENCODE_AUTONOMY_DIR", workspace_root / ".aiws" / "tmp" / "opencode-autonomy"))
 out_dir.mkdir(parents=True, exist_ok=True)
 log_file = out_dir / "approval-whitelist-exec.log"
 result_file = out_dir / "approval-whitelist-exec-last.json"

package/templates/workspace/.opencode/helpers/approval-whitelist-watchdog.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 workspace_root="${1:-.}"
 shift || true
 
-out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-${workspace_root}/.agentdocs/tmp/opencode-autonomy}"
+out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-${workspace_root}/.aiws/tmp/opencode-autonomy}"
 queue_file="${out_dir}/approval-watchdog-queue.jsonl"
 once=false
 poll_ms=2000

package/templates/workspace/.opencode/helpers/tmux-swarm-rescue.sh

@@ -6,7 +6,7 @@ if ! command -v tmux >/dev/null 2>&1; then
   exit 1
 fi
 
-out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-.agentdocs/tmp/opencode-autonomy}"
+out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-.aiws/tmp/opencode-autonomy}"
 scan_file="${1:-${out_dir}/tmux-scan.json}"
 log_file="${out_dir}/tmux-rescue.log"
 mkdir -p "${out_dir}"

package/templates/workspace/.opencode/helpers/tmux-swarm-scan.sh

@@ -6,7 +6,7 @@ if ! command -v tmux >/dev/null 2>&1; then
   exit 1
 fi
 
-out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-.agentdocs/tmp/opencode-autonomy}"
+out_dir="${AIWS_OPENCODE_AUTONOMY_DIR:-.aiws/tmp/opencode-autonomy}"
 out_file="${out_dir}/tmux-scan.json"
 mkdir -p "${out_dir}"