@aipper/aiws-spec 0.0.28 → 0.0.30

package/docs/workflow-stage-contracts.schema.json

@@ -43,7 +43,8 @@
           "requiredInputs": { "type": "string", "minLength": 1 },
           "requiredOutputs": { "type": "string", "minLength": 1 },
           "blockers": { "type": "string", "minLength": 1 },
-          "next": { "type": "string", "minLength": 1 }
+          "next": { "type": "string", "minLength": 1 },
+          "gateBefore": { "type": "string", "minLength": 1 }
         },
         "additionalProperties": false
       }
@@ -53,6 +54,16 @@
       "minItems": 1,
       "items": { "type": "string", "minLength": 1 }
     },
+    "boundaryDescriptions": {
+      "type": "object",
+      "required": ["mainSession", "subagent", "handoff"],
+      "properties": {
+        "mainSession": { "type": "string", "minLength": 1 },
+        "subagent": { "type": "string", "minLength": 1 },
+        "handoff": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
     "evidence": {
       "type": "object",
       "required": ["intro", "minimum", "notes"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

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

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

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

@@ -1,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（仅当用户确认后）

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

@@ -1,230 +1,18 @@
 ---
 name: ws-deliver
-description: 交付（submodules + superproject 分步提交，并安全合并回目标分支）
+description: `aiws deliver` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-deliver
 
-目标：
-- 适配 superproject + submodule（数量不固定）的交付收尾：
-  1) 先逐个提交 submodule（每个 repo 单独确认 commit message）
-  2) 再提交 superproject（包含 submodule gitlink 指针更新 + 变更工件/代码）
-  3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`，减少手动 merge 出错）
+`aiws deliver` 的薄包装入口。
 
-非目标（强制）：
-- 不自动 `git add -A`（避免误提交）
-- 不自动 push
-- 不自动删除分支
-
-前置（强制）：
-1) 先运行 `$ws-preflight`。
-2) 确认当前处于 change 分支（推荐）：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）。
-   - 若不在 change 分支：要求用户先切换到 `change/<change-id>`（或在命令里显式提供 `<change-id>`）。
-3) 任何自动提交都必须在提交前输出：
-   - 该 repo 的 `git status --porcelain`
-   - 该 repo 的 `git diff --staged`
-   并让用户确认 commit message（每个 repo 单独确认）。
-
-阶段定位：
-- delivery 阶段；负责在多 repo / submodule 场景下完成顺序提交、证据收敛和最终合并前准备。
-
-必需输入：
-- 当前 `change/<change-id>` 上下文
-- 若存在 submodule：`.gitmodules` + `changes/<change-id>/submodules.targets`
-- 各 repo 当前状态与 staged diff
-
-必需输出：
-- `Submodules:` 每个 submodule 的提交摘要
-- `Superproject:` 主仓库提交摘要
-- `Evidence:` validate stamp 与持久证据路径
-- `Next:` 进入 `$ws-finish` 或 `aiws change finish`
-
-阻断条件：
-- 不在正确的 change 上下文
-- submodule branch / targets 真值不完整
-- 任一 repo 未确认 commit message 或存在未处理冲突
-
-完成判定：
-- submodule 与 superproject 提交都已完成，证据已收敛，且可以安全进入 finish 阶段。
-
-建议流程（按顺序）：
-
-## 0) submodule branch 真值检查（减少 detached 与人为差异）
-如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `$ws-submodule-setup` 并提交 `.gitmodules`，否则后续 `aiws validate .` 会失败，且 `ws-pull/ws-finish` 无法确定性工作。
-> 说明：若同一 superproject 分支内存在多渠道 submodule 目标分支的交付需求，可在 `changes/<change-id>/submodules.targets` 额外声明本次 change 的目标分支；交付时会优先使用该文件（不改变 `.gitmodules` 的团队默认真值）。
-> 生成该文件时，可以按当前状态做默认预填，但必须显式说明来源并让用户确认：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在某个本地分支时默认建议取当前分支；finish/push 最终只认 `submodules.targets`。
 ```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
-
-  # 强约束：当 .gitmodules 声明 submodules 时，要求本次 change 存在 submodules.targets 且覆盖所有 submodule path
-  if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
-    change_id="$(git branch --show-current | sed -n 's|^change/||p')"
-    targets="changes/${change_id}/submodules.targets"
-    if [[ ! -f "${targets}" ]]; then
-      echo "error: missing ${targets} (required when .gitmodules declares submodules)"
-      exit 2
-    fi
-    t_missing=0
-    while read -r _ sub_path; do
-      [[ -z "${sub_path:-}" ]] && continue
-      if ! awk -v p="${sub_path}" '$1==p && $0 !~ /^[[:space:]]*#/ && $2!="" { found=1 } END { exit(found?0:1) }' "${targets}" 2>/dev/null; then
-        echo "error: ${targets} missing entry for submodule path=${sub_path}"
-        t_missing=1
-      fi
-    done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
-    if [[ "${t_missing}" -ne 0 ]]; then
-      echo "hint: fill ${targets} as: <path> <target_branch> [remote]"
-      exit 2
-    fi
-  fi
-fi
-```
-
-## A) 发现 submodules 清单（数量不固定）
-在 superproject 根目录执行：
-```bash
-git submodule status --recursive
-```
-如果没有 submodule：跳到 C)。
-
-## B) 逐个提交 submodules（先 submodule，后 superproject）
-对每个 submodule path（可递归）重复以下步骤（建议按 `git submodule status --recursive` 顺序）：
-1) 定位并检查状态：
-```bash
-sub_path="<path>"
-git -C "$sub_path" branch --show-current
-git -C "$sub_path" status --porcelain
-```
-2) 先确定该 submodule 的目标分支来源，并显式说明给用户：
-   - `branch --show-current` 非空：默认建议用当前分支
-   - `branch --show-current` 为空（detached HEAD）：默认建议用 `.gitmodules` 的 `submodule.<name>.branch`
-   - 若建议值与 `changes/<change-id>/submodules.targets` 已落盘值不一致：以 `submodules.targets` 为准，并先提示差异
-3) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
-   - 说明：这通常是因为 superproject 的 gitlink checkout（例如 `git submodule update`）导致 detached。
-   - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached。
-   - 若你要在该 submodule 里提交：先按目标分支挂到 pin 分支 `aiws/pin/<target-branch>`，再在其上提交：
-     - 目标分支真值优先级：`changes/<change-id>/submodules.targets`（若存在）> `.gitmodules submodule.<name>.branch`
-```bash
-change_id="<change-id>"
-targets="changes/${change_id}/submodules.targets"
-sub_name="$(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null | awk -v p="${sub_path}" '$2==p { name=$1; sub(/^submodule\\./,"",name); sub(/\\.path$/,"",name); print name; exit }')"
-base_branch="$(python3 - <<'PY'
-import json, pathlib
-change_id = "<change-id>"
-meta = pathlib.Path("changes") / change_id / ".ws-change.json"
-data = json.loads(meta.read_text(encoding="utf-8"))
-print((data.get("base_branch") or "").strip())
-PY
-)"
-test -n "${sub_name}"
-test -n "${base_branch}"
-
-source tools/ws_resolve_sub_target.sh
-ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${base_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
-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
-```
-   - 若 `origin/<target-branch>` 不存在，或用户明确不想使用 pin 分支：停止，解释风险（提交可能不可追溯/难以推送）。
-4) 选择性 staging（默认用 `-p` 更安全）：
-```bash
-git -C "$sub_path" add -p
-git -C "$sub_path" diff --staged --stat
-git -C "$sub_path" diff --staged
-```
-5) AI 生成该 submodule 的 commit message（标题+可选 body），并让用户确认（每个 repo 单独确认）。
-6) 执行提交（不带 `--no-verify`）：
-```bash
-git -C "$sub_path" commit -m "<message>"
-```
-7) 若该 submodule 没有 staged changes：跳过（不要硬提交空 commit）。
-
-## C) 提交 superproject（更新 gitlinks + 自身改动 + changes 工件）
-1) 先检查 submodule 指针差异（gitlinks）：
-```bash
-git diff --submodule
-```
-2) 选择性 staging：
-   - 先 stage 发生指针变化的 submodule 路径（明确列出）：
-```bash
-git add <submodule-path-1> <submodule-path-2>
-```
-   - 再 stage superproject 自身改动（默认 `-p`）：
-```bash
-git add -p
-git diff --staged --stat
-git diff --staged
-```
-3) AI 生成 superproject 的 commit message（应包含 `bump submodule <name> -> <sha>` 等关键信息），并让用户确认。
-4) 提交：
-```bash
-git commit -m "<message>"
-```
-
-## D) 门禁与证据（推荐）
-```bash
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate . --stamp
-elif command -v aiws >/dev/null 2>&1; then
-  aiws validate . --stamp
-else
-  npx @aipper/aiws validate . --stamp
-fi
-```
-
-## D2) 生成持久证据并回填 Evidence_Path（强烈建议）
-> 说明：`.agentdocs/tmp/...` 默认 gitignored；交付前建议把关键结果落到 `changes/<change-id>/evidence/...` 并回填 `proposal.md`/`plan` 的 `Evidence_Path`，避免后续评审/二次会话读不到证据。
-```bash
-change_id="<change-id>"
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change evidence "${change_id}"
+  ./node_modules/.bin/aiws deliver
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change evidence "${change_id}"
+  aiws deliver
 else
-  npx @aipper/aiws change evidence "${change_id}"
+  npx @aipper/aiws deliver
 fi
 ```
-
-## D3) 生成状态快照（可选，建议）
-```bash
-aiws change state "${change_id}" --write
-```
-
-## E) 安全合并回目标分支（fast-forward）
-优先使用 `$ws-finish`（底层调用 `aiws change finish`，并在 push 成功后清理对应 change worktree）。
-
-若需要显式指定目标分支：
-```bash
-aiws change finish <change-id> --into <base-branch>
-```
-
-## F) 归档说明
-- 标准链路下不需要再单独执行 `aiws change archive <change-id>`。
-- 进入 `$ws-finish` 并使用 `aiws change finish --push` 时，会自动完成 archive + handoff。
-
-输出要求：
-- `Submodules:` 每个 submodule 的分支/提交摘要（repo → commit sha → message）
-- `Superproject:` 提交摘要
-- `Merge:` `aiws change finish` 的输出（into/from）
-- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
-- `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）