| name | openspec-archive |
| description | 归档已完成的 OpenSpec 变更到正确的 archive/ 目录，自动修正 CLI bug。
使用场景："归档 Spec"、"Phase D.2"、"完成变更归档"
|
| argument-hint | [change-name] |
| disable-model-invocation | false |
| user-invocable | true |
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep |
OpenSpec Archive (归档器)
版本: 1.1.0 | 十步循环: D.2
更新: 2026-07-05 - #95 归档 gate 硬化: Step1 扩展 C 分级证据闸 (block 死代码 / warn 模糊) + 新增 Step7 D auto-issue (归档不吞未完成)
历史: 2026-02-08 - 初始版本，修复 CLI 归档位置 bug
快速开始
我应该使用这个 Skill 吗？
使用场景:
- Spec 所有任务已完成，需要归档
- Phase D.2 收尾阶段
- 清理已完成的变更
不使用场景:
- Spec 仍有活跃任务 → 完成任务后再归档
- 需要继续修改 Spec → 保持变更活跃状态
核心功能
| 功能 | 说明 |
|---|
| 状态验证 | 检查 Spec 完成状态和任务完成度 (#134 完成度二元判定) |
| 完成声称真实性证据闸 (#95) | C 分级 (🔴 block 高置信死代码 / 🟠 warn 模糊声称) — 验 tasks.md [x] 代码集成类声称有无真实生产语义引用 |
| 执行归档 | 调用 openspec archive CLI |
| 自动修正 | 修正 CLI 的归档目录位置 bug |
| 清理验证 | 清理空目录，验证最终结果 |
| D auto-issue (#95) | 归档不吞未完成 — deferred/unverified 项自动建 Forgejo tracker issue (幂等 + headless 默认) |
⚠️ 已知 Bug: OpenSpec CLI 归档位置错误
问题: openspec archive CLI 命令有 bug，输出到错误位置：
❌ CLI 输出: openspec/changes/archive/YYYY-MM-DD-{feature}/
✅ 正确位置: openspec/archive/YYYY-MM-DD-{feature}/
本 Skill 会自动修正此问题。
正确的目录结构
openspec/
├── archive/ # ✅ 正确的归档位置
│ └── YYYY-MM-DD-{feature}/
│ ├── proposal.md
│ ├── tasks.md
│ └── detailed-tasks.yaml
└── changes/ # 活跃变更
└── {active-feature}/
执行流程
输入
change_name:
required: true
description: 要归档的变更目录名
example: "cloudflare-access-auto-handling"
options:
skip_verification: false
keep_changes_copy: false
dry_run: false
archive_design_only: false
reason: ''
ack_unverified: ''
步骤
Step 1 - 完成 gate + C 分级证据闸 (#134 v1.42.0+ 完成度 ∧
already_archived_precheck:
检查: ls openspec/archive/ | grep -E '^[0-9]{4}-[0-9]{2}-[0-9]{2}-{change_name}$'
若已存在: 立即 abort (BLOCKED-already-archived)
约束: 不进入完成度判定、不写任何标记 (标记写入属 Step 2, abort 路径零残留)
gate_result:
命令: |
python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/state-scanner/scripts/lib/spec_complete.py" \
--gate "openspec/changes/{change_name}"
读取: stdout JSON {complete, complete_reason, verdict, blocking_reasons[], [],
[{,,}], , []}
[]
[]
{}
{, }
{, }
{, }
{}
[ ] { }
[ ]
输出格式
success: true
change_name: "cloudflare-access-auto-handling"
archive_path: "openspec/archive/2026-02-08-cloudflare-access-auto-handling"
cli_bug_fixed: true
warnings: []
verification:
archive_exists: true
contains_proposal: true
contains_tasks: true
contains_detailed_tasks: true
wrong_dir_cleaned: true
gate_verdict: "pass"|"warn"|"block"
unverified_claims_written: false
runtime_probe_written: false
d_issue_created: false
使用示例
示例 1: 标准归档
输入:
change_name: "cloudflare-access-auto-handling"
执行:
Step 1: ✅ gate_result verdict=pass (complete=true, 无死代码声称)
Step 2: ✅ 更新 proposal.md 状态
Step 3: ✅ 执行 openspec archive
Step 4: ✅ 修正归档位置 (检测到 CLI bug)
Step 5: ✅ 清理活跃变更目录
Step 6: ✅ 验证归档结果
Step 7: ⏭️ 跳过 (d_payload=null, 无 deferred/unverified, 干净归档)
输出:
✅ 归档成功
📍 位置: openspec/archive/2026-02-08-cloudflare-access-auto-handling
🐛 CLI bug 已自动修正
示例 2: 未完成任务
输入:
change_name: "incomplete-feature"
执行:
Step 1: ❌ 完成 gate BLOCK (gate_result complete=false, verdict=pass — 纯 completeness 缺口,
无死代码/模糊声称问题)
complete_reason 回显: "tasks.md has 2/4 unchecked task(s); normalized Status = 'approved' (≠ done)"
未完成:
- [ ] Task 3: 实现错误处理
- [ ] Task 4: 添加单元测试
输出:
❌ 归档中止 (默认 BLOCK)
原因: spec_complete.py 判定 complete=false (缺口见 complete_reason 回显)
建议: 完成所有任务后再执行归档; 确需归档未实施稿 → --archive-design-only + reason
示例 3: Dry Run (三路输出)
dry_run=true 执行 Step 1 gate 全部判断 (already-archived 前置 + tasks.md + Status + 标记读取),
报告三路结果并保持"不实际写入"不变量。
注: dry_run 三路完全基于 (a) CLI flag (b) 本地 tasks.md (c) proposal.md Status —
均由本 Skill 直接读取, 不依赖 state-scanner snapshot 预计算字段。
术语消歧 (#95): 下方 3a/3b/3c 示例中的 verdict: 前缀是历史遗留的展示文字标签
(表示"本次 completeness 判定结果"), 不是 #95 新增的 JSON verdict 枚举字段
(pass/warn/block)。dry_run 复用同一个 --gate 调用 (Step 1 gate_result 不区分
dry_run 与否, 都读同一份 JSON), 因此 3a/3b/3c 场景下 gate_verdict 字段实际都是 pass
(无死代码/模糊声称声称), 只是 completeness 二元判定 (complete) 独立为 true/false ——
3e 补充 dry_run 下 gate_verdict=block 的场景, 二者不冲突。
3a: BLOCKED (未完成且未配逃生舱)
输入:
change_name: "test-feature"
dry_run: true
输出:
📋 Dry Run 结果: ❌ BLOCKED
verdict: complete=false
reason 回显: "tasks.md has 1/4 unchecked task(s); normalized Status = 'approved' (≠ done)"
声明: 未发生任何写入 (dry_run)
建议: 完成缺口后重试, 或 --archive-design-only + reason
3b: ALLOWED (完成, 正常归档可执行)
输入:
change_name: "test-feature"
dry_run: true
输出:
📋 Dry Run 结果: ✅ ALLOWED
verdict: complete=true ("tasks.md 全 [x] (4 task(s), 无 carry-forward/defer 注释)")
预期归档路径: openspec/archive/2026-02-08-test-feature
声明: 未发生任何写入 (dry_run)
建议: 可以安全执行归档
3c: ALLOWED-design-only (逃生舱 + reason 回显)
输入:
change_name: "design-doc-feature"
dry_run: true
archive_design_only: true
reason: "方案被 DEC-20260609-001 替代, 仅存档设计稿供追溯"
输出:
📋 Dry Run 结果: ✅ ALLOWED-design-only
verdict: complete=false (逃生舱放行)
reason 回显: "方案被 DEC-20260609-001 替代, 仅存档设计稿供追溯"
若执行将写入 frontmatter: "archive_type: implementation-deferred" + archived_reason
声明: 未发生任何写入 (dry_run)
3d: reason 校验拒绝 (BLOCKED-invalid-reason)
输入:
change_name: "design-doc-feature"
dry_run: true
archive_design_only: true
reason: " 存档 "
输出:
📋 Dry Run 结果: ❌ BLOCKED-invalid-reason
原因: reason 不足 10 非空白字符 (拒纯空白)
声明: 未发生任何写入 (dry_run)
建议: 提供 ≥10 非空白字符的实质性 reason
3e: C-block dry-run (#95, complete=true 但 gate_verdict=block)
输入:
change_name: "multi-terminal-coordination"
dry_run: true
输出:
📋 Dry Run 结果: ❌ BLOCKED (C-block, 非 completeness BLOCK)
completeness: complete=true ("tasks.md 全 [x] (12 task(s), 无 carry-forward/defer 注释)")
gate_verdict: block
blocking_reasons: ["symbol 'phase1_gate' (claim: '集成 state-scanner') has zero production semantic reference (dead-code-on-arrival)"]
声明: 未发生任何写入 (dry_run)
建议: 补齐集成后重试, 或 --archive-design-only + reason (同时豁免 completeness 与 C-block, 若两者皆缺口)
示例 4: C-block 高置信死代码 (#95, complete=true 但仍 BLOCK)
输入:
change_name: "multi-terminal-coordination"
执行:
Step 1: ❌ gate_result complete=true 但 verdict=block
blocking_reasons: ["symbol 'phase1_gate' (claim: '集成 state-scanner') has zero
production semantic reference (dead-code-on-arrival)"]
输出:
❌ 归档中止 (BLOCK — 高置信死代码, 即便 tasks.md 全 [x])
原因: phase1_gate 在 3 个生产 collector 中只有注释/docstring 提及, 剥离后零真实
代码引用/dynamic-dispatch/集成面/通用路径调用
建议: 补齐 phase1_gate 的实际集成后重试; 确认此声称属实但暂缓集成 →
--archive-design-only + reason (逃生舱同时豁免死代码判定, 见下方豁免变体)
豁免变体 (owner 显式承认残留, 仍需归档):
输入:
change_name: "multi-terminal-coordination"
archive_design_only: true
reason: "phase1_gate 集成推迟到 #94 follow-up, 本次先归档设计稿"
执行:
Step 1: ⚠️ verdict=block 但逃生舱有效 → 放行 (路径 b), 输出显式回显 blocking_reasons 未被吞掉
Step 2: ✅ 写 frontmatter archive_type=implementation-deferred + archived_reason
Step 3-6: ✅ 正常归档流程
Step 7: ✅ d_payload 非 null (含未完成 deferred 项) → 创建 tracker issue
输出:
⚠️ 归档完成 (逃生舱豁免了 C-block 死代码判定, 非静默通过)
🎫 已建 tracker issue: https://forgejo.10cg.pub/10CG/Aria/issues/201
示例 5: C-warn 模糊声称 + D auto-issue (#95)
输入:
change_name: "some-dogfood-heavy-spec"
执行:
Step 1: ⚠️ complete=true, verdict=warn
unverified_claims: [{claim: "dogfood 验证通过", reason: "无可链接产物路径", symbols: []}]
Step 2: ✅ 正常归档 (路径 a) + warn_overlay 写入 frontmatter:
unverified_claims: [...]
unverified_ack: false
Step 3-6: ✅ 正常归档流程
Step 7: ✅ d_payload 非 null (unverified_claims 非空, 无论 ack 与否都进 payload)
→ 幂等检查未命中既有 issue → 创建 tracker issue
输出:
⚠️ 归档完成, 1 条声称无法静态核验 (已写入 frontmatter)
错误处理
| 错误 | 原因 | 解决方案 |
|---|
| 变更目录不存在 | change_name 拼写错误 | 检查 openspec/changes/ 目录 |
| 完成 gate BLOCK | spec_complete.py 判定 complete=false | 完成缺口后重试; 确需归档未实施稿 → --archive-design-only + reason |
| C-block (#95) | verdict=block — 点名符号零生产语义引用 (高置信死代码, 可与 complete=true 共存) | 补齐集成后重试; 确认残留待补 → --archive-design-only + reason (逃生舱同时豁免, 见示例 4) |
| BLOCKED-invalid-reason | reason 不足 10 非空白字符 (含纯空白) | 提供 ≥10 非空白字符的实质性 reason |
| BLOCKED-already-archived | openspec/archive/ 已存在对应条目 (Step 1 前置 abort) | 检查是否已归档; 不重复写标记 |
--force (DEPRECATED) | 旧绕过通道, v1.42.0+ 收口 | 改用 --archive-design-only + reason (可追溯逃生舱) |
| skip_verification=true 未配逃生舱 | backward-compat shim 触发 | WARN + abort (不静默降级); 改用 --archive-design-only + reason |
| CLI 命令失败 | openspec CLI 未安装 | 安装 openspec CLI |
| 权限不足 | 无法移动/删除文件 | 检查文件权限 |
| Step 7 非-Forgejo backend (#95) | forgejo CLI 不可用 / remote 非 Forgejo | 降级打印 d_payload.body 待创建草稿, 提示手动在项目 issue tracker 创建; 归档本身不受影响 |
| Step 7 API 失败 (#95) | forgejo POST 非 2xx / 网络错误 | 打印 d_payload.body 完整草稿 + WARN, 不静默; 归档 (Step 1-6) 已完成, 不因此 abort |
| Step 7 重复归档同 spec (#95) | marker 幂等检查命中既有 open issue | 跳过创建, 输出既有 issue 编号, 不重复开 |
与其他 Phase 的关系
phase-d-closer
│
│ D.1 - 进度更新 (progress-updater)
│ └── 更新 UPM 进度状态
│
│ D.2 - Spec 归档 (openspec-archive) ◄── 本 Skill
│ ├── Step 1 验证完成状态 + C 分级证据闸 (#95)
│ ├── Step 2 写 proposal.md (含 warn frontmatter, #95)
│ ├── Step 3-6 执行归档 / 修正 CLI bug / 验证结果
│ └── Step 7 D auto-issue (归档不吞未完成, #95, 单一 owner)
│
▼
完成闭环
相关文档
- Phase D 规范:
standards/core/ten-step-cycle/phase-d-closure.md
- OpenSpec 项目规范:
standards/openspec/project.md
- 归档目录说明:
openspec/archive/README.md
- 已知 Bug 列表:
standards/openspec/AGENTS.md
- #95 Spec:
openspec/changes/aria-archive-gate-runtime-reality/proposal.md (主仓, C 分级证据闸 + D auto-issue 设计 SOT)
- spec_complete.py --gate 契约:
state-scanner/scripts/lib/spec_complete.py module docstring (tri-state gate_result 完整 schema)
变更历史
| 版本 | 日期 | 变更 |
|---|
| 1.1.0 | 2026-07-05 | #95 归档 gate 硬化: Step 1 扩展 C 分级证据闸 (tri-state verdict, --gate 契约) + Step 2 warn frontmatter 覆盖层 + 新增 Step 7 D auto-issue (单一 owner + 幂等 + headless 默认) |
| 1.0.0 (含 #134 v1.42.0+ 完成度 gate, 本表历史未及时补记) | 2026-02-08 | 初始版本，实现 CLI bug 自动修正 |
最后更新: 2026-07-05
Skill版本: 1.1.0
