@kafka0102/onespec 0.1.2

package/assets/skills/onespec/scripts/onespec-state.sh

@@ -0,0 +1,341 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+die() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+valid_change() {
+  local change="$1"
+  [[ -n "$change" ]] || die "change name is required"
+  [[ "$change" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]] || die "invalid change name: $change"
+  [[ "$change" != *".."* ]] || die "change name must not contain '..'"
+}
+
+change_dir() {
+  local change="$1"
+  if [ -d "openspec/changes/$change" ]; then
+    printf 'openspec/changes/%s\n' "$change"
+  elif [ -d "openspec/changes/archive/$change" ]; then
+    printf 'openspec/changes/archive/%s\n' "$change"
+  else
+    printf 'openspec/changes/%s\n' "$change"
+  fi
+}
+
+state_file() {
+  local change="$1"
+  printf '%s/.onespec.yaml\n' "$(change_dir "$change")"
+}
+
+today() {
+  date +%Y-%m-%d
+}
+
+now_utc() {
+  date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+field_value() {
+  local file="$1"
+  local key="$2"
+  awk -F ': *' -v key="$key" '$1 == key { sub(/^[^:]+: */, ""); print; found=1; exit } END { if (!found) exit 0 }' "$file" 2>/dev/null
+}
+
+enum_contains() {
+  local needle="$1"
+  shift
+  local candidate
+  for candidate in "$@"; do
+    if [ "$candidate" = "$needle" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+validate_enum_value() {
+  local key="$1"
+  local value="$2"
+
+  case "$key" in
+    phase)
+      enum_contains "$value" intake proposal-ready approved plan-ready implementing review done archived \
+        || die "invalid value for $key: $value"
+      ;;
+    ambiguity)
+      enum_contains "$value" unknown low high || die "invalid value for $key: $value"
+      ;;
+    complexity)
+      enum_contains "$value" unknown low medium high || die "invalid value for $key: $value"
+      ;;
+    implementation_path)
+      enum_contains "$value" undecided openspec-apply superpowers || die "invalid value for $key: $value"
+      ;;
+    execution_method)
+      enum_contains "$value" undecided subagent local native || die "invalid value for $key: $value"
+      ;;
+    workspace|origin_workspace_mode)
+      enum_contains "$value" unknown undecided worktree current-branch main-override \
+        || die "invalid value for $key: $value"
+      ;;
+    review_result)
+      enum_contains "$value" pending changes-requested approved || die "invalid value for $key: $value"
+      ;;
+    archive)
+      enum_contains "$value" pending skipped archived || die "invalid value for $key: $value"
+      ;;
+  esac
+}
+
+phase_transition_allowed() {
+  local old="$1"
+  local new="$2"
+
+  [ "$old" = "$new" ] && return 0
+
+  case "$old" in
+    intake)
+      enum_contains "$new" proposal-ready
+      ;;
+    proposal-ready)
+      enum_contains "$new" intake approved
+      ;;
+    approved)
+      enum_contains "$new" proposal-ready plan-ready implementing
+      ;;
+    plan-ready)
+      enum_contains "$new" proposal-ready approved implementing
+      ;;
+    implementing)
+      enum_contains "$new" proposal-ready approved plan-ready review
+      ;;
+    review)
+      enum_contains "$new" implementing done archived
+      ;;
+    done)
+      enum_contains "$new" review archived
+      ;;
+    archived)
+      return 1
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+set_field() {
+  local file="$1"
+  local key="$2"
+  local value="$3"
+  local tmp
+  tmp="$(mktemp)"
+  if grep -q "^${key}:" "$file"; then
+    awk -v key="$key" -v value="$value" '
+      $0 ~ "^" key ":" { print key ": " value; next }
+      { print }
+    ' "$file" > "$tmp"
+  else
+    cat "$file" > "$tmp"
+    printf '%s: %s\n' "$key" "$value" >> "$tmp"
+  fi
+  mv "$tmp" "$file"
+}
+
+cmd_init() {
+  local change="$1"
+  valid_change "$change"
+
+  local dir file
+  dir="$(change_dir "$change")"
+  file="$(state_file "$change")"
+  mkdir -p "$dir"
+
+  if [ -f "$file" ]; then
+    echo "$file"
+    return 0
+  fi
+
+  cat > "$file" <<EOF
+version: 1
+change: $change
+phase: intake
+ambiguity: unknown
+complexity: unknown
+implementation_path: undecided
+execution_method: undecided
+workspace: undecided
+origin_branch: unknown
+origin_workspace_path: unknown
+origin_workspace_mode: unknown
+plan: null
+handoff_context: null
+handoff_purpose: null
+handoff_summary: null
+handoff_hash: null
+touched_files_b64: null
+review_result: pending
+archive: pending
+created_at: $(today)
+updated_at: $(now_utc)
+EOF
+  echo "$file"
+}
+
+cmd_get() {
+  local change="$1"
+  local key="$2"
+  valid_change "$change"
+  local file
+  file="$(state_file "$change")"
+  [ -f "$file" ] || die "state not found: $file"
+  field_value "$file" "$key"
+}
+
+cmd_set() {
+  local change="$1"
+  local key="$2"
+  local value="$3"
+  valid_change "$change"
+  local file
+  file="$(state_file "$change")"
+  [ -f "$file" ] || die "state not found: $file"
+
+  case "$key" in
+    phase|ambiguity|complexity|implementation_path|execution_method|workspace|origin_branch|origin_workspace_path|origin_workspace_mode|plan|handoff_context|handoff_purpose|handoff_summary|handoff_hash|touched_files_b64|review_result|archive|updated_at)
+      ;;
+    *)
+      die "unsupported field: $key"
+      ;;
+  esac
+
+  validate_enum_value "$key" "$value"
+  if [ "$key" = "phase" ]; then
+    local current_phase
+    current_phase="$(field_value "$file" phase)"
+    phase_transition_allowed "$current_phase" "$value" \
+      || die "illegal phase transition: $current_phase -> $value"
+  fi
+
+  set_field "$file" "$key" "$value"
+  set_field "$file" "updated_at" "$(now_utc)"
+}
+
+cmd_recover() {
+  local change="$1"
+  valid_change "$change"
+  local file
+  file="$(state_file "$change")"
+  [ -f "$file" ] || die "state not found: $file"
+
+  echo "OneSpec 恢复状态"
+  echo "change: $change"
+  for key in phase ambiguity complexity implementation_path execution_method workspace origin_branch origin_workspace_path origin_workspace_mode plan handoff_context handoff_purpose handoff_summary handoff_hash review_result archive updated_at; do
+    printf '%s: %s\n' "$key" "$(field_value "$file" "$key")"
+  done
+  local phase next_skill next_gate allowed_actions next_step
+  phase="$(field_value "$file" phase)"
+
+  case "$phase" in
+    intake)
+      next_skill="onespec-design"
+      next_gate="ambiguity-scan"
+      allowed_actions="scan-ambiguity,draft-proposal"
+      next_step="执行歧义扫描，然后创建或恢复 OpenSpec 提案"
+      ;;
+    proposal-ready)
+      next_skill="onespec-design"
+      next_gate="proposal-approval"
+      allowed_actions="show-approval-menu,revise-artifacts,pause-design"
+      next_step="汇总提案并展示编号批准选项，等待用户回复数字"
+      ;;
+    approved)
+      next_skill="onespec-execute"
+      next_gate="implementation-route"
+      allowed_actions="confirm-route,create-plan,choose-workspace"
+      next_step="进入 \`onespec-execute\`，创建或校验实现计划"
+      ;;
+    plan-ready)
+      next_skill="onespec-execute"
+      next_gate="start-implementation"
+      allowed_actions="record-phase-implementing,start-work,track-files"
+      next_step="进入 \`onespec-execute\`，确认执行方式后开始实现，并先写入 \`phase implementing\`"
+      ;;
+    implementing)
+      next_skill="onespec-execute"
+      next_gate="implementation-in-progress"
+      allowed_actions="continue-implementation,update-tasks,run-tests"
+      next_step="继续未完成任务，然后更新 tasks.md"
+      ;;
+    review)
+      next_skill="onespec-archive"
+      next_gate="user-review-closeout"
+      allowed_actions="request-changes,choose-archive-menu,direct-instruction"
+      next_step="等待用户评审；若用户回复非编号内容则继续修改，若选择归档菜单则进入 \`onespec-archive\` 处理删除 worktree / 归档组合选项"
+      ;;
+    done|archived)
+      next_skill="onespec-archive"
+      next_gate="no-implementation-work"
+      allowed_actions="stop,archive-if-needed"
+      next_step="没有剩余实现工作"
+      ;;
+    *)
+      next_skill="onespec"
+      next_gate="repair-state"
+      allowed_actions="inspect-artifacts,repair-state"
+      next_step="检查 OpenSpec 产物并修复状态"
+      ;;
+  esac
+
+  printf 'next_skill: %s\n' "$next_skill"
+  printf 'next_gate: %s\n' "$next_gate"
+  printf 'allowed_actions: %s\n' "$allowed_actions"
+  printf '下一步: %s\n' "$next_step"
+}
+
+cmd_list() {
+  if [ ! -d openspec/changes ]; then
+    return 0
+  fi
+  find openspec/changes -name .onespec.yaml -type f | sort
+}
+
+usage() {
+  cat <<'EOF'
+用法:
+  onespec-state.sh init <change>
+  onespec-state.sh get <change> <field>
+  onespec-state.sh set <change> <field> <value>
+  onespec-state.sh recover <change>
+  onespec-state.sh list
+EOF
+}
+
+cmd="${1:-}"
+case "$cmd" in
+  init)
+    [ "$#" -eq 2 ] || { usage; exit 2; }
+    cmd_init "$2"
+    ;;
+  get)
+    [ "$#" -eq 3 ] || { usage; exit 2; }
+    cmd_get "$2" "$3"
+    ;;
+  set)
+    [ "$#" -eq 4 ] || { usage; exit 2; }
+    cmd_set "$2" "$3" "$4"
+    ;;
+  recover)
+    [ "$#" -eq 2 ] || { usage; exit 2; }
+    cmd_recover "$2"
+    ;;
+  list)
+    cmd_list
+    ;;
+  *)
+    usage
+    exit 2
+    ;;
+esac

package/assets/skills/onespec-archive/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: onespec-archive
+description: 当用户需要对 OneSpec change 做最终评审、处理反馈、删除 worktree 或执行 OpenSpec archive 时使用。
+---
+
+# OneSpec Archive
+
+用于 OneSpec 的评审、收尾与归档阶段。目标是在用户确认后执行删除 worktree 与 OpenSpec archive，不默认执行有后果的操作。
+
+开始时说明：
+
+> 我正在使用 `onespec-archive` 处理 review / closeout 阶段。
+
+## 1. 评审入口
+
+先恢复状态：
+
+```bash
+ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
+. "$ONESPEC_ENV"
+"$ONESPEC_BASH" "$ONESPEC_STATE" list
+```
+
+如果发现相关 change，必须继续执行：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+`recover` 的输出是当前阶段合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_gate` 与 `allowed_actions`，再决定是否继续收尾阶段动作。
+
+读取最少必要上下文：
+
+- `openspec/changes/<change-id>/proposal.md`
+- `openspec/changes/<change-id>/tasks.md`
+- `openspec/changes/<change-id>/design.md`，如果存在
+- 相关 `openspec/specs/**`
+- 最新测试结果与 `openspec validate <change-id> --strict` 结果
+- 当前分支、worktree 和工作区状态
+- `origin_branch`、`origin_workspace_path`、`origin_workspace_mode`
+
+如果状态尚未到 `review`，先说明缺少什么：未实现、未验证、未回填 `tasks.md`，或 proposal 尚未批准。
+
+入口校验：如果 phase 已到 `review`，但 `.onespec.yaml` 里的 `handoff_purpose` 不是 `review`，或 `handoff_hash` 为空，说明 execute gate 可能未正常完成。此时必须告诉用户："执行阶段的 review handoff 状态未写回，建议先回到执行阶段补充汇报（回复 `补充汇报` 或重新触发 execute gate）。" 不允许静默跳过。
+
+## 2. 用户评审
+
+实现完成后让用户评审。若用户指出问题，继续修改并重新验证。
+
+开发完成后不需要再次让用户确认是否 review，也不需要展示常规“继续评审 / 保留分支”类选项。只需询问是否进行归档；如果用户回复任意非编号内容，默认视为“继续修改当前实现”，直接回到代码处理环节。
+
+不要让用户自己猜“下一步该输入什么”。进入 `onespec-archive` 时，必须给出可直接回复的编号选项；如果支持多动作组合，允许用户回复逗号分隔的数字，例如 `1,3`。
+
+进入收尾选择前，必须显式向用户汇报：
+
+- 当前分支名
+- 当前工作区路径
+- 最初开始这次 change 时记录的 `origin_branch` 与 `origin_workspace_path`
+- 当前是否仍在原始分支/原始工作区
+
+如果当前分支或工作区不同于 `origin_*`，必须明确说明“你当前看到的是临时实现分支或临时 worktree”。此时默认展示删除 worktree / 归档组合选项；如果用户改为输入任意非编号内容，则表示当前功能还有问题，需要继续修改。
+
+可选收尾路径只围绕两件事展开：
+
+- 删除 worktree
+- 执行归档
+
+不要默认自动删除 worktree。删除与归档都是有后果的操作，必须来自用户选择。
+
+## 2.1 Superpowers Worktree 优先规则
+
+如果 `origin_workspace_mode=worktree`，或当前路径是实现期新建的临时 worktree，收尾时必须把“回收到原始分支/工作区”的动作提到最前面说明。
+
+必须显式告诉用户：
+
+- 当前实现位于临时 worktree
+- 原始分支是 `origin_branch`
+- 原始工作区是 `origin_workspace_path`
+- 收尾后是否会删除本地临时 branch 与 worktree
+
+默认推荐顺序：
+
+1. 先在临时 worktree 完成 review。
+2. 如果无需继续修改，优先给出“删除 worktree 并归档”作为推荐收尾组合。
+3. 如果用户只想清理本地环境，则允许“仅删除 worktree”。
+4. 如果代码已经真正位于目标分支，则允许“仅归档”。
+
+## 2.2 多选收尾组合
+
+收尾选项不要再只做单选。动作本身就应围绕组合展开；组合输入使用编号列表，例如 `1,3`：
+
+- `删除 worktree`
+- `执行归档`
+
+推荐的组合校验逻辑：
+
+- `{删除 worktree 并归档}`：等价于 `{删除 worktree, 执行归档}`。
+- `{删除 worktree, 执行归档}`：合法。适用于临时 worktree 已完成使命，需要直接清理并归档。
+- `{仅删除 worktree}`：等价于 `{删除 worktree}`。
+- `{删除 worktree}`：合法。适用于只清理本地临时 worktree，稍后再归档。
+- `{仅归档}`：等价于 `{执行归档}`。
+- `{执行归档}`：仅当代码已经位于目标分支时合法；如果当前还在临时 branch / worktree，默认不合法。
+
+如果用户勾选了非法组合，必须明确指出冲突原因，不要替用户猜测执行顺序。
+
+默认推荐组合：
+
+- 当前在 Superpowers 临时 worktree：推荐 `{删除 worktree, 执行归档}`。
+- 当前在临时 worktree，但用户只想先清理本地环境：推荐 `{删除 worktree}`。
+- 当前不在临时 worktree，且代码已真正位于目标分支：推荐 `{执行归档}`。
+
+推荐向用户展示的收尾选项至少包含：
+
+1. 删除 worktree 并归档
+2. 仅删除 worktree
+3. 仅归档
+其他：如果意图不在以上选项里，允许用户直接补充说明；任意非编号内容视为继续修改当前实现
+
+菜单解释规则：
+
+- 用户回复 `1`：执行“删除 worktree 并归档”。
+- 用户回复 `2`：仅删除 worktree。
+- 用户回复 `3`：仅当代码已合并且归档前置条件满足时，执行 archive；否则先说明阻塞条件。
+- 用户回复多项编号，如 `1,3`：按组合规则校验。合法时按安全执行顺序运行；不合法时明确指出冲突原因。
+- 用户输入数字外的自由文本：默认视为继续修改当前实现，直接回到代码处理环节；只有意图不清晰时才补一个最短澄清问题。
+
+## 3. 归档规则
+
+进入 archive 或删除 worktree 的最终收尾前，必须检查当前是否仍有“与本次 change 相关的未提交代码”：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" related-dirty <change-id>
+```
+
+- 如果结果为空，继续后续收尾。
+- 如果结果为空，即使工作区里还有无关未跟踪目录，也不要阻塞收尾；例如未记录到 `.onespec.yaml` tracked file 列表里的 `.superpowers/` 可以明确说明“未纳入本次提交”，但不应视为本次 change 的阻塞项。
+- 如果结果非空，先向用户明确提示这些文件尚未提交，并暂停归档。
+- 若用户要求现在提交，只能 stage 本次 change 相关文件：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" stage-related <change-id>
+```
+
+- 提交信息优先遵循项目自身指定的 Git 提交策略。先探测项目内文档和配置：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" detect-policy <change-id>
+```
+
+- 如果项目里存在明确规范，按项目要求处理 commit message 的格式、scope 和语言。
+- 如果项目里没有明确规范，回退到通用 Conventional Commits：`<type>(<scope>): <简要描述>`。
+- 只能提交 `.onespec.yaml` 中记录的 tracked files 与当前脏文件的交集；如果 `.onespec.yaml` 本身是脏的，也应一并提交，不允许把无关改动一并提交。
+- 例外：位于 `openspec/changes/<change-id>/` 下、专属于本次 change 的临时压缩包、导出包或交接工件，也视为本次 change 相关文件；自动提交时要一并带上，这样 archive 后仍能保留在 change 历史里。
+- 如果代码已合并到目标分支且用户选择归档，直接执行 OpenSpec archive，并将状态设为 `archived`。
+- 如果用户当前只删除 worktree、不归档，将状态设为 `done`，并提示之后可再运行归档；此时不要删除 `.onespec.yaml`。
+- 只有真正执行 archive 后，才删除运行时状态文件：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" cleanup-runtime <change-id>
+```
+
+用户一旦通过收尾菜单明确选择了归档或组合归档动作，就把这次选择视为唯一确认；不要再追加第二次确认。
+
+实际执行收尾动作时，优先使用：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" run-actions <change-id> [delete-worktree] [archive]
+```
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase done
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> archive <skipped|archived>
+```
+
+归档前必须确认：
+
+- `tasks.md` 已按实际完成项勾选
+- 项目测试已通过，或未通过项已明确说明
+- `openspec validate <change-id> --strict` 已通过
+- 用户明确选择了删除 worktree、归档或它们的组合策略
+- 没有未处理的用户评审反馈
+
+## 4. 汇报
+
+收尾汇报必须覆盖：
+
+- 用户评审结果
+- 选择的收尾路径：删除 worktree、归档或组合执行
+- 分支/worktree 的最终状态
+- 当前分支与 `origin_branch` 的关系，以及是否仍保留临时 worktree
+- `tasks.md`、测试与 OpenSpec validate 状态
+- archive 字段：`skipped` 或 `archived`
+
+## 5. 停止条件
+
+以下情况必须暂停并向用户说明：
+
+- 用户还没有完成最终评审
+- 用户没有明确选择收尾路径
+- 用户没有明确确认删除 worktree 或 OpenSpec archive
+- 代码未合并到目标分支且也未选择允许的删除 worktree 组合时，却要求单独 archive
+- 测试或 `openspec validate <change-id> --strict` 未通过且用户未明确接受风险