@flyin-ai/alloy 0.2.0-beta.0 → 0.2.0-beta.2

package/commands/alloy/references/plan-rollback.md

@@ -0,0 +1,84 @@
+# plan-rollback.md
+
+plan 阶段的制品回溯清理——轻量修正和需求变更两条路径。
+
+## 轻量修正（措辞/格式，不改变功能边界）
+
+**判断规则：** 只有用户明确说"措辞/格式调整"才走此路径。用户主动提出"加入/删除/修改功能"= 需求变更，**禁止使用 `alloy _artifact reset`**，必须走下面的回溯路径。不确定时默认需求变更。
+
+使用 `alloy _artifact reset` 一步完成 hash 清除 + 文件删除：
+
+```bash
+alloy _artifact reset openspec/changes/<name> <artifact>
+```
+
+该命令自动：
+1. 清除 `.alloy.yaml` 中该制品的 hash 记录
+2. 删除制品文件（specs 目录递归删除）
+
+然后调用 `/opsx:continue` 重新生成 → 审查 → 重新锁定。下游已锁定制品保持不变。
+
+```bash
+git add openspec/changes/<name>/
+git commit -m "chore(<name>): 轻量修正——清除 <artifact>，准备重新生成"
+```
+
+## 需求变更回溯清理（功能增删、行为变更）
+
+删除所有 plan 制品（保留 draft.md），重置 records 和 phase_timings：
+
+```bash
+# 1. 打 snapshot tag（task #15）——回溯前留恢复入口
+# 不可逆删除前必须留 git tag，事后用户可 git checkout <tag> 完整恢复 plan 制品
+TS=$(date +%Y%m%d-%H%M%S)
+SNAPSHOT_TAG="rollback-<name>-${TS}"
+git tag "$SNAPSHOT_TAG"
+echo "已打 snapshot tag: $SNAPSHOT_TAG（事后恢复：git checkout $SNAPSHOT_TAG -- openspec/changes/<name>/）"
+
+# 2. 删除 plan 制品文件（保留 draft.md）
+rm -f openspec/changes/<name>/proposal.md
+rm -f openspec/changes/<name>/design.md
+rm -f openspec/changes/<name>/tasks.md
+rm -f openspec/changes/<name>/plans.md
+rm -rf openspec/changes/<name>/specs/
+
+# 3. 清理 records（只保留 draft）
+DRAFT_RECORD=$(alloy _state read openspec/changes/<name> records | python3 -c "
+import sys,json
+content = sys.stdin.read().strip()
+records = json.loads(content) if content and content != 'null' else []
+draft = [r for r in records if r.get('artifact') == 'draft']
+print(json.dumps(draft))
+")
+alloy _state write openspec/changes/<name> records "$DRAFT_RECORD"
+
+# 4. 清理 phase_timings
+# ⚠️ 此处是 phase_timings 唯一允许 _state write 的场景：回溯需要删除 key + 覆盖值，merge 语义不支持
+TIMINGS=$(alloy _state read openspec/changes/<name> phase_timings 2>/dev/null || echo "{}")
+echo "$TIMINGS" | python3 -c "
+import sys,json
+content = sys.stdin.read().strip()
+d = json.loads(content) if content and content != 'null' else {}
+for k in ['plan','apply','archive','finish']:
+    d.pop(k, None)
+if 'start' in d:
+    d['start']['completed_at'] = None
+print(json.dumps(d))
+" | while read -r val; do alloy _state write openspec/changes/<name> phase_timings "$val"; done
+
+git add openspec/changes/<name>/
+git commit -m "chore(<name>): 回溯——清理 plan 制品，回到 brainstorming"
+```
+
+```
+→ 制品已清理（仅保留 draft），records/phase_timings 已重置
+→ 请运行 /alloy:start <name> 重新走需求确认流程
+```
+
+## apply 阶段的需求变更
+
+apply 阶段的需求变更闸门见 apply.md——以 tasks.md checkbox 状态判断：
+- 未编码（全部 unchecked）→ 清理 plan 制品 → 回到 brainstorming（使用上面的回溯清理步骤）
+- 已编码（有 [x]）→ 拒绝回溯，开新 change
+
+apply 的 verify/retrospective 验证"代码是否匹配规格"，发现问题修正代码，不改变需求/设计。

package/commands/alloy/references/spec-sync.md

@@ -0,0 +1,62 @@
+# Spec-Sync：Spec/Skill 对账工作流
+
+所有 alloy 阶段命令共享的 spec-skill 对账工作流。修改 `commands/alloy/*.md` 或 `src/` 后触发。
+
+## 1. 自动检测
+
+```bash
+alloy _spec-audit
+```
+
+输出差异报告：
+- `✓ <name>: spec 与 skill 一致` — 无需操作
+- `✗ <name>: spec 与 skill 不一致` — 需要同步
+- `⚠ <name>: 未声明 spec 锚点，跳过对账` — 缺少 `spec` frontmatter
+- `✗ <name>: 对应 spec 文件 <path> 不存在` — spec 路径有误
+
+## 2. 定位变更源
+
+确认哪个 skill 文件修改了 behaviors：
+- 新增/删除了 🔴 STOP → `stops` 或 `hard_stops` 变化
+- 变更了外部调用 → `external_calls` 变化
+- 产物列表更新 → `artifacts` 变化
+- 阶段目标变更 → `transitions_to` 变化
+
+## 3. 更新 spec 正文
+
+确保 spec 正文描述与 skill 一致。例如：
+- skill 新增了 🔴 STOP → spec 正文应有对应的确认点描述
+- skill 新增了 external_call → spec 正文应有该技能的调用说明
+- skill 修改了 transitions_to → spec 正文的目标阶段描述应更新
+
+## 4. 更新 spec frontmatter
+
+方式一：手动修改 spec 文件的 `behaviors` frontmatter
+
+方式二：自动更新（仅修改 frontmatter，不修改正文）
+```bash
+alloy _spec-audit --fix
+```
+
+## 5. 验证
+
+```bash
+alloy _spec-audit
+```
+
+确认所有字段输出 `✓`。
+
+## 6. 提交
+
+skill 变更和 spec 变更在同一 commit 中：
+```bash
+git add commands/alloy/<skill>.md docs/specification/01-product-spec/<spec>.md
+git commit -m "docs(<name>): 同步 spec 与 skill behaviors"
+```
+
+## 注意事项
+
+- **对账方向是 skill → spec**（skill 是真相源）
+- 只改 spec 匹配 skill，不反向修改 skill
+- 正文同步是人工判断，frontmatter 同步可自动化
+- `--fix` 只修改 frontmatter，不修改 spec 正文——正文必须手动同步

package/commands/alloy/references/start-rationalizations.md

@@ -0,0 +1,18 @@
+# start Red Flags 完整表（第三层防御——任一借口出现即 STOP）
+
+主文件保留 5 条核心，完整 12 条在此。
+
+| 借口 | 现实 |
+|------|------|
+| "不用建分支了，就在 main 上干吧" | ⛔ HARD_STOP：主分支污染不可逆。建分支只需 2 秒。违反字面 = 违反精神：哪怕"只是先建个目录后面再切"也算（Iron Law 第一层）。 |
+| "分支创建是可选步骤" / "用户没提分支" | 分支创建是硬性闸门——没有验证，后续步骤全部禁止。闸门默认生效，不需要用户主动请求。 |
+| "项目简单/一个人开发，不需要分支" | 分支保护的是 discard 安全性，不是团队协作。简单项目一样需要——否则 discard 丢失主分支无关变更。 |
+| "不用 brainstorming，直接写代码" | brainstorming 不可跳过。跳过需求设计 = 规格和代码分叉的起点。 |
+| "brainstorming 完成了，写 spec 文件吧" | Alloy start 的产出是 draft.md，不是 docs/superpowers/specs/。brainstorming 完成后直接输出方案，由 Alloy 流程生成 draft.md。 |
+| "start 完成了，直接进 plan" / "用户没回复，我先继续" | ⛔ HARD_STOP：start 完成后绝不自动进入 plan。沉默 ≠ 授权（Iron Law 第二层）。替用户做阶段转换 = 剥夺审查机会。 |
+| "draft.md 讨论过了，直接 commit" | brainstorming 讨论的是概念，draft.md 是最终文本。必须展示完整内容，等用户 USER_GATE 确认。 |
+| "openspec/changes/<name>/ 已经有了，直接复用" | ⛔ PRECONDITION_FAIL：目录已存在 = #12 冲突。USER_GATE 让用户决策（改名 / 接续 / 中止），禁 agent 自动复用——可能覆盖用户既有工作。 |
+| "/opsx:new 失败了，git mkdir 凑合一下" | ⛔ PRECONDITION_FAIL：opsx:new 是 schema 闸门，手工 mkdir 绕过制品 DAG 验证——退出 skill 引导用户排查。 |
+| "change name 还没确认，先把分支建了" | ⛔ HARD_STOP：change name 未确认前禁继续步骤 2-9。违反字面 = 违反精神：哪怕"反正 name 大概就这个"。 |
+| "git init 后 reset --hard 一下，把环境清干净" | ⛔ HARD_STOP：git 初始化失败禁 reset --hard / clean -fd / checkout .（§3.5.1 git 自救禁令）。退出 skill 让用户处理。 |
+| "用户没明确选 (a) 但意思就是进 plan，加载吧" | 沉默 ≠ 授权。USER_GATE 必须明确选择 (a)，不接受推断（Iron Law 第二层）。 |