npm - @aipper/aiws-spec - Versions diffs - 0.0.7 → 0.0.9 - Mend

@aipper/aiws-spec 0.0.7 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/package.json CHANGED Viewed

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

package/templates/workspace/.agents/skills/ws-finish/SKILL.md CHANGED Viewed

@@ -1,13 +1,14 @@
 ---
 name: ws-finish
-description: 收尾（门禁 + 安全合并 change/<change-id> 回目标分支）
+description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push）
 ---
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 目标：
 - 在结束一次变更交付时，用 fast-forward 安全合并 `change/<change-id>` 回目标分支，减少手输分支名导致的错误
-- 不自动 push；不自动删分支；必要时先让用户确认
+- 合并成功后，按 `submodule -> superproject` 顺序 push，避免遗漏导致其它仓库拉取异常
+- 不自动删分支；push 前必须让用户确认
 前置（必须）：
 - 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
@@ -38,7 +39,56 @@ else
 fi
 ```
 3) 若 fast-forward 失败（提示需要 rebase）：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
-4) （可选）归档变更工件（完成交付后推荐）：
+4) 合并成功后，先把每个 submodule 的 gitlink commit 合并回其目标分支（解决 detached HEAD），并按顺序 push：
+```bash
+# superproject 当前分支（finish 后通常是 base 分支）
+base_branch="$(git branch --show-current)"
+# 子模块清单（没有则跳过）
+git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true
+# 对每个 submodule.<name>.path <sub_path>：
+# 1) 计算 superproject 当前 HEAD 记录的 gitlink commit
+sub_sha="$(git rev-parse "HEAD:<sub_path>")"
+# 2) 推断目标分支（优先：.gitmodules 的 submodule.<name>.branch；否则 origin/HEAD；否则 main/master）
+cfg_branch="$(git config --file .gitmodules --get "submodule.<name>.branch" 2>/dev/null || true)"
+if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
+origin_head="$(git -C "<sub_path>" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' || true)"
+target_branch="${cfg_branch:-${origin_head:-}}"
+if [[ -z "${target_branch:-}" ]]; then
+  if git -C "<sub_path>" show-ref --verify --quiet refs/heads/main || git -C "<sub_path>" show-ref --verify --quiet refs/remotes/origin/main; then
+    target_branch="main"
+  else
+    target_branch="master"
+  fi
+fi
+# 3) 切到目标分支（若本地无分支则从 origin 跟踪创建）
+git -C "<sub_path>" fetch origin
+git -C "<sub_path>" switch "$target_branch" || git -C "<sub_path>" switch -c "$target_branch" --track "origin/$target_branch"
+# 4) fast-forward 到 gitlink commit（非 ff 直接停止，避免错误合并）
+git -C "<sub_path>" status -sb
+if git -C "<sub_path>" merge-base --is-ancestor "$sub_sha" HEAD; then
+  echo "[skip] <sub_path> already contains $sub_sha"
+else
+  git -C "<sub_path>" merge --ff-only "$sub_sha"
+fi
+# 5) push（若无 upstream 则首次 -u）
+git -C "<sub_path>" push || git -C "<sub_path>" push -u origin "$target_branch"
+```
+规则：
+- 每个 submodule 必须先执行“切目标分支 + `merge --ff-only <gitlink-sha>`”，再 push；禁止在 detached HEAD 直接 push。
+- 若任一 submodule 不能 fast-forward（`merge --ff-only` 失败），立即停止，先人工处理冲突/分叉，再继续。
+5) 仅当 submodules 全部成功后，再 push superproject 当前分支：
+```bash
+git branch --show-current
+git status -sb
+git push
+```
+6) （可选）归档变更工件（完成交付后推荐）：
 ```bash
 change_id="<change-id>"
 if [[ -x "./node_modules/.bin/aiws" ]]; then

package/templates/workspace/.claude/commands/ws-finish.md CHANGED Viewed

@@ -16,10 +16,23 @@
    - 若当前就在 `change/<change-id>` 分支上，可直接执行：`aiws change finish`
    - 否则执行：`aiws change finish <change-id>`
 4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
-5) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+5) 合并成功后，按顺序处理每个 submodule（先“并回目标分支”，再 push）：
+   - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+   - 对每个 `<sub_path>`：
+     - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
+     - 推断目标分支：优先 `.gitmodules` 的 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支），否则 `origin/HEAD`，再 fallback `main/master`
+     - 切到目标分支（必要时创建跟踪分支）：`git -C "<sub_path>" switch <target-branch> || git -C "<sub_path>" switch -c <target-branch> --track origin/<target-branch>`
+     - 合并 gitlink commit：`git -C "<sub_path>" merge --ff-only <gitlink-sha>`
+     - push：`git -C "<sub_path>" push`（无 upstream 则 `git -C "<sub_path>" push -u origin <target-branch>`）
+6) 任一 submodule `merge --ff-only` 失败时立即停止（不要继续 push 主仓库）。
+7) submodules 全部成功后，再 push 主仓库当前分支：
+   - `git branch --show-current`
+   - `git status -sb`
+   - `git push`
+8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 安全：
-- 不自动 push。
+- push 前先输出状态并请用户确认远端/分支。
 - 不执行破坏性命令。
 <!-- AIWS_MANAGED_END:claude:ws-finish -->

package/templates/workspace/.iflow/commands/ws-finish.toml CHANGED Viewed

@@ -1,14 +1,14 @@
 # Command: ws:finish
-# Description: AI Workspace 安全收尾（门禁 + fast-forward 合并 change/<change-id> 回目标分支）
+# Description: AI Workspace 安全收尾（门禁 + fast-forward 合并 + submodule 并回分支后顺序 push）
 # Category: workspace
 # Version: 1
-description = "AI Workspace 安全收尾（门禁 + fast-forward 合并 change/<change-id> 回目标分支）"
+description = "AI Workspace 安全收尾（门禁 + fast-forward 合并 + submodule 并回分支后顺序 push）"
 prompt = """
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
-目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，减少手输分支名导致的错误。
+目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，并按 `submodule -> superproject` 顺序 push，减少遗漏。
 强制步骤：
 1) 读取真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`（缺失则先运行 `/aiws-init` 或 `aiws init .`）。
@@ -22,9 +22,22 @@ prompt = """
    - 在 `change/<change-id>` 分支上：`aiws change finish`（会尝试读 `changes/<change-id>/.ws-change.json` 的 `base_branch` 并切回目标分支）
    - 否则：`aiws change finish <change-id>`
 7) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里执行 `git rebase <target-branch>`，再重试 `aiws change finish`。
-8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+8) 合并成功后，按顺序处理每个 submodule（先“并回目标分支”，再 push）：
+   - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+   - 对每个 `<sub_path>`：
+     - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
+     - 推断目标分支：优先 `.gitmodules` 的 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支），否则 `origin/HEAD`，再 fallback `main/master`
+     - 切到目标分支（必要时创建跟踪分支）：`git -C "<sub_path>" switch <target-branch> || git -C "<sub_path>" switch -c <target-branch> --track origin/<target-branch>`
+     - 合并 gitlink commit：`git -C "<sub_path>" merge --ff-only <gitlink-sha>`
+     - push：`git -C "<sub_path>" push`（无 upstream 则 `git -C "<sub_path>" push -u origin <target-branch>`）
+9) 任一 submodule `merge --ff-only` 失败时立即停止（不要继续 push 主仓库）。
+10) submodules push 完成后，再 push 主仓库当前分支：
+   - `git branch --show-current`
+   - `git status -sb`
+   - `git push`
+11) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 边界：
-- 不自动 push。
+- push 前先输出状态并请用户确认远端/分支。
 - 不执行破坏性命令。
 """

package/templates/workspace/.opencode/command/aiws-init.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 初始化：落盘 AIWS 真值与门禁文件
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-init -->
 # aiws init
@@ -16,4 +19,3 @@
 <!-- AIWS_MANAGED_END:opencode:aiws-init -->
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-rollback.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 回滚：从 .aiws/backups 恢复快照
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-rollback -->
 # aiws rollback
@@ -9,4 +12,3 @@
 <!-- AIWS_MANAGED_END:opencode:aiws-rollback -->
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-update.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 更新：刷新模板与 tool-native 文件（先备份）
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-update -->
 # aiws update
@@ -15,4 +18,3 @@
 <!-- AIWS_MANAGED_END:opencode:aiws-update -->
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-validate.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 门禁：校验 required/托管块/漂移（可落盘 stamp）
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-validate -->
 # aiws validate
@@ -10,4 +13,3 @@
 <!-- AIWS_MANAGED_END:opencode:aiws-validate -->
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-analyze.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 分析：实现前技术分析并落盘证据
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-analyze -->
 # ws analyze

package/templates/workspace/.opencode/command/ws-deliver.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 交付：submodules+superproject 分步提交并安全合并回 base
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-deliver -->
 # ws deliver
@@ -42,4 +45,3 @@
 <!-- AIWS_MANAGED_END:opencode:ws-deliver -->
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-dev.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 开发：在 AIWS 约束下完成小步交付
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-dev -->
 # ws dev

package/templates/workspace/.opencode/command/ws-finish.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 收尾：fast-forward 合并并把 submodule 并回目标分支后顺序 push
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-finish -->
 # ws finish
@@ -16,10 +19,23 @@
    - 若当前就在 `change/<change-id>` 分支上，可直接执行：`aiws change finish`
    - 否则执行：`aiws change finish <change-id>`
 4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
-5) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+5) 合并成功后，按顺序处理每个 submodule（先“并回目标分支”，再 push）：
+   - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+   - 对每个 `<sub_path>`：
+     - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
+     - 推断目标分支：优先 `.gitmodules` 的 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支），否则 `origin/HEAD`，再 fallback `main/master`
+     - 切到目标分支（必要时创建跟踪分支）：`git -C "<sub_path>" switch <target-branch> || git -C "<sub_path>" switch -c <target-branch> --track origin/<target-branch>`
+     - 合并 gitlink commit：`git -C "<sub_path>" merge --ff-only <gitlink-sha>`
+     - push：`git -C "<sub_path>" push`（无 upstream 则 `git -C "<sub_path>" push -u origin <target-branch>`）
+6) 任一 submodule `merge --ff-only` 失败时立即停止（不要继续 push 主仓库）。
+7) submodules 全部成功后，再 push 主仓库当前分支：
+   - `git branch --show-current`
+   - `git status -sb`
+   - `git push`
+8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 安全：
-- 不自动 push。
+- push 前先输出状态并请用户确认远端/分支。
 - 不执行破坏性命令。
 <!-- AIWS_MANAGED_END:opencode:ws-finish -->

package/templates/workspace/.opencode/command/ws-migrate.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 迁移：把仓库对齐到 aiws workspace 模板
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-migrate -->
 # ws migrate

package/templates/workspace/.opencode/command/ws-preflight.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 预检：读取真值文件并输出约束摘要
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-preflight -->
 # ws preflight

package/templates/workspace/.opencode/command/ws-req-change.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 需求变更：更新 REQUIREMENTS 并同步执行合同
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-req-change -->
 # ws req change

package/templates/workspace/.opencode/command/ws-req-contract-sync.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 合同同步：把 REQUIREMENTS FlowSpec 同步到 requirements-issues.csv
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-sync -->
 # ws req contract sync

package/templates/workspace/.opencode/command/ws-req-contract-validate.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 合同校验：校验 requirements-issues.csv 字段完整性
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-validate -->
 # ws req contract validate

package/templates/workspace/.opencode/command/ws-req-flow-sync.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: Flow 同步：从 REQUIREMENTS 生成 api-flow 与场景执行合同
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-req-flow-sync -->
 # ws req flow sync

package/templates/workspace/.opencode/command/ws-req-review.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 需求评审：对 REQUIREMENTS 做整体 QA（不改文件）
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-req-review -->
 # ws req review

package/templates/workspace/.opencode/command/ws-review.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: Review：提交前审计改动并落盘证据
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-review -->
 # ws review

package/templates/workspace/.opencode/command/ws-rule.md CHANGED Viewed

@@ -1,3 +1,6 @@
+---
+description: 规则：把口述规则整理并写入 AI_PROJECT.md 托管段
+---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-rule -->
 # ws rule