@aipper/aiws-spec 0.0.29 → 0.0.31

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}"