openspec-archive

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     # 仅跳过 tasks.md [x] 校验 (v1.42.0+ 收口: 不绕过 Status 归一化 gate)
  keep_changes_copy: false     # 在 changes/ 中保留副本
  dry_run: false               # 仅验证不执行 (三路输出, 见示例 3)
  archive_design_only: false   # 逃生舱 (--archive-design-only): 归档未实施稿, 须配 reason
                                # #95: 同一逃生舱也覆盖 "complete=true ∧ verdict=block" 死代码组合
                                # (见 Step 1 verdict 路由表) — 显式豁免时须在输出中同时回显
                                # 被豁免的 blocking_reasons, 不静默吞掉死代码判定
  reason: ''                   # archive_design_only 必填; ≥10 非空白字符, 拒纯空白
  ack_unverified: ''            # #95 可选, 交互模式人工确认 unverified_claims (仅记录, 不影响 D 是否建 issue — 见 §D ack 解耦)

步骤

Step 1 - 完成 gate + C 分级证据闸 (#134 v1.42.0+ 完成度 ∧ #95 tri-state verdict):
  # ── 前置 (最前): already-archived 检查 ──
  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 路径零残留)

  # ── 完成 + C 分级判定: Bash 调单一可执行 SOT (--gate tri-state 模式), 不再由 AI 解释 prose ──
  # #95 TG-2: 原 legacy 二元调用 (`python3 spec_complete.py <spec_dir>`) 改为统一走 --gate 模式 ——
  # 一次调用同时拿到 #134 的 complete/complete_reason (字段不变, 只是改从同一份 JSON 里读)
  # 和 #95 新增的 tri-state verdict, 不必两次调脚本。
  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
# #95 新增字段 (verdict=warn 或 d_payload 非 null 时出现; 干净归档时省略, 向后兼容):
gate_verdict: "pass"|"warn"|"block"
unverified_claims_written: false        # true 时对应 Step 2 warn_overlay 已写 frontmatter
runtime_probe_written: false            # runtime-probe-archive-gate-integration (#95 follow-up A)
                                         # additive 字段, 与 unverified_claims_written 同一可见性
                                         # 条件 (verdict=warn 或 d_payload 非 null 时出现; 干净归档
                                         # 或无 runtime_probe 声明时省略) 但独立取值: 仅当探针自身
                                         # outcome ∈ {warn, invalid} 且 runtime_probe 键已落盘才为
                                         # true —— unverified_claims_written=true 不蕴含本字段为
                                         # true (混合场景: probe=pass 但其它声称致
                                         # unverified_claims_written=true 而本字段=false, 见 Step 2
                                         # warn_overlay 内容归属条件)
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: "  存档  "        # 去除空白后 < 10 字符

输出:
  📋 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"   # Layer L golden 负例

执行:
  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 #201

输出:
  ⚠️ 归档完成 (逃生舱豁免了 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   # 本次未交互提供 --ack-unverified (headless 默认场景)
  Step 3-6: ✅ 正常归档流程
  Step 7: ✅ d_payload 非 null (unverified_claims 非空, 无论 ack 与否都进 payload)
    → 幂等检查未命中既有 issue → 创建 tracker issue #202

输出:
  ⚠️ 归档完成, 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