opsx-jira-fix-workflow

OPSX Jira 缺陷修复工作流

OpenSpec 风格的 Jira 修复方式：保留 jira-fix-workflow 的端到端修复能力，同时让 OpenSpec 成为行为事实的唯一来源。

输出模板：各阶段的格式请参阅 reference.md。

定位

将此技能用于值得留档的 Jira 缺陷修复：不仅修复代码，还要记录根因、行为变更、设计权衡、任务列表、验证证据和归档结果。

职责划分：

• Jira：问题来源、业务背景、状态流转和修复评论。
• openspec/changes/<change-name>/：Jira 背景、根因、行为约定、解决方案、任务、验证和最终归档。
• PR/MR：代码交付、验证证据、风险说明和评审入口。

不替代普通的 jira-fix-workflow：

• 不需要长期可追溯性的快速修复——使用 jira-fix-workflow。
• 行为约定、审计、团队协作、跨模块影响或长期可追溯性——使用此技能。

调用约定

• 触发条件：opsx-jira-fix、OpenSpec Jira 修复、规范化修复 Jira、opsx修复Jira、Jira OpenSpec 修复、opsx自动修复Jira、用OpenSpec修复Jira、opsx-jira-fix-workflow；ai-proxy 模式、AI 代理模式、切换 ai-proxy
• 覆盖模式：「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy" 请求按 workflow-mode-lifecycle 执行覆盖（如果同时存在自动触发条件，则覆盖+冻结优先）。按 ai-proxy-discipline 先轻量冻结，再接管。
• 自动模式：否则，包含“自动”的触发条件或 --auto 会进入自动模式。
• 强制模式：包含“强制”的触发条件或 --force 可以跳过基于难度的停止，但绝不会跳过验证或归档检查。
• 继续修复：包含“继续修复”“再次修复”“从上次继续”或 --retry 的触发条件会先定位现有的 OpenSpec 变更，然后从 design.md、tasks.md 复选框、当前 Git 分支和 PR/MR 状态中恢复上下文。

强依赖技能（frontmatter dependencies；启动时必须通过“前置技能检查”——缺少任何一项都必须中止）：

• staged-review-flow（第 4 阶段的评审编排；依赖 solution-review 和 code-design-review）
• hybrid-debug / runtime-evidence-debug / browser-debug-toolkit（通过 analysis-core 委派；第 2 阶段 + 第 7 阶段）
• analysis-core（第 2 阶段分析方法的唯一来源：临时变更门槛 / 基于插桩的调试，默认入口为 runtime-evidence-debug / 分析步骤骨架 / 分析门槛输出块 / 调试-验证循环）
• node-version-discipline（第 6 阶段执行验证前对齐 Node 版本）
• workflow-mode-lifecycle（自动/手动模式生命周期）、clarifying-question-discipline（严格的主动提问规范和调查优先原则）、known-issue-research（第 2 阶段的研究路由 / 已知问题快速搜索 / 行业范围评估）、competitive-research（分析期间用户可见的竞品行为；方法保留在该技能中）
• test-suite-ensure（第 6.2.5 阶段确保测试套件：基础设施存在时补全并运行测试；不存在时经用户确认后搭建）
• test-first-discipline（执行：行为变更须先编写失败测试；与 test-suite-ensure 不同）
• design-approval-gate（执行前：未经批准不得进行生产实现；可按明确命名的自动模式/热修复例外处理）
• delivery-discipline（第 8 阶段：归档后提交 + 打开/更新 PR/MR；字段映射使用占位符）
• feature-branch-closeout（第 8 阶段：收尾菜单；合并操作委派给 merge-discipline）
• decision-fog-discipline（探索解决方案前：先厘清模糊决策 / 创建决策工单）
• git-worktree-discipline（第 1 阶段前——首次写入产物前：工作树门槛 + 可选的隔离工作区）
• domain-language-discipline（澄清/分析：涉及领域术语时使用项目术语表 / CONTEXT.md）
• merge-discipline（第 8 阶段合并规范——收尾菜单选择合并后）
• opsx-workspace-gate（第 0 阶段 OpenSpec 工作区和原生技能门槛）
• jira-status-writeback（第 8 阶段合并后的回写：状态转换 + 修复评论 SOP，唯一来源）
• jira-wiki-markup（每条 Jira 评论正文均使用 Wiki 标记；回写时加载此技能以生成修复评论）
• learn-and-improve（第 8 阶段复盘和知识沉淀）
• figma-pixel-implement / figma-pixel-verify（严格遵循 Figma 导出内容实现 + 实测验证；必须已安装；当目标、卡片、问题或计划包含 figma.com 或 node-id=，或者用户要求按像素还原时调用）

前置技能检查

启动时（第 0 阶段的前置检查之前）检查 frontmatter dependencies：缺少任何一项 → 输出结构化提示并立即中止（格式见 solve-workflow/reference.md）。

不降级原则：缺少强依赖意味着中止——绝不退回到简化版评审或调试流程。

模式生命周期

自动模式的进入、持续和退出规则，可防止用户未察觉 AI 仍在自动决策时模式持续生效。核心规则（恢复手动模式／显式重新进入／隐式延续永不重新激活／批量场景）位于强依赖技能 workflow-mode-lifecycle 中（前置检查已确保该技能可用）——此处不再重述。本工作流的“完整流程完成”指按正常流程经过阶段 0-8（在阶段 8 归档结束）；失败终止、用户主动停止或评审上限暂停都属于流程中断，都会恢复为手动模式。

OpenSpec 特定说明

• 阶段 8 归档完成后，模式会自动恢复为手动模式。
• --retry（继续修复）：重置为手动模式。
• --resume（检查点恢复）：沿用检查点中的模式。
• OpenSpec 归档失败属于流程中断——恢复为手动模式。

无人值守代理退出

当本次运行契约或任务卡记录了 Stage-exit policy: ai-proxy（自动承载；队列子任务足够，但并非必需）时，每个手动停止点都会根据 ai-proxy-discipline 成为代理检查点。精简冻结（口头触发 ≠ 占用）规则见该技能。合并、不可逆操作、受保护分支和 Jira 写回仍仅限人工处理（搁置并创建工单）。其他任何策略值或未指定策略 → 采用当前的非代理行为。

停止点预测：如果本次运行开始时已有冻结契约（包含问题和已冻结决策的队列子任务，或已写入的独立精简冻结），则在分析前先给出预测表——逐一列出每个手动退出点，并标明其是否已由冻结决策覆盖，还是会形成新工单。如果在运行中途请求叠加策略，则在精简冻结后输出剩余退出点的预测，然后继续当前阶段（不要从分析阶段重新开始）。

队列子任务模式（goal-driven-queue 调度）

由 goal-driven-queue 调度时（调用中带有显式的 queue-child 上下文标记——绝不根据环境信号猜测），此流程会相应调整：任务卡的目标条件包含 Jira 问题链接；其冻结决策区块提供阶段 0-1 的信息；同时传递 Stage-exit policy（当策略为 ai-proxy 时，按 ai-proxy-discipline 处理占用——队列子任务足够，但并非必需）；开始时先给出停止点预测（逐一列出每个手动退出点，并标明其是否已由冻结决策覆盖，还是会形成新工单）。终止点为归档 + 打开 PR：归档 OpenSpec 变更（此模型的原生步骤，绝不延期），然后停在打开 PR 这一步——合并和 Jira 写回延期由人工处理（合并权限和外部跟踪器写回绝不代理）；队列的验收包会将其列为待处理的后续事项。独立使用（无标记）时：叠加策略／占用仍遵循 Stage-exit policy；不适用队列的归档 + 打开 PR终止流程；收尾仍按此技能的原生归档后进入阶段流程进行（叠加策略不代表可以不经人工介入就自动完成合并／写回）。如果任务卡提供了队列关系梳理记录，请将其写入此变更的 design.md，标题为 ## Related Issues。如果本次运行是队列子任务，完成报告需包含问题、原因、已完成的修复，以及证据列表。每项证据都必须是引用 png、jpg、jpeg 或 webp 路径的已打开 UI 检查，或引用命令及简短输出摘要的非 UI 检查。缺失或为空的图像视为待处理，并注明仍需截图。不得编造图像。在已打开的 UI 图像用于佐证检查之前，须按 completion-evidence-discipline 检查图像。本次运行不编写 HTML 页面，也不编写证据 HTML。

阶段 0：前置条件检查

任何关键检查失败都会暂停流程——不要进入修复阶段：

1. 解析 Jira URL / Jira ID；检测模式（manual / auto / force / retry / overlay）。Overlay 会先触发请求进行轻量冻结，然后按 ai-proxy-discipline 进行占用。
2. 检查 Jira 数据是否可读取：优先使用 jira-read {JIRA-ID} --live 或 mcp-atlassian；失败时回退到本地缓存；两者都失败则中止。
3. 检查 Git 状态：auto 模式可以 stash；manual 模式提示用户处理。
4. OpenSpec 工作区和原生技能门禁：加载 opsx-workspace-gate，并运行其项目根目录位置检查、openspec/ 检查和精确的原生 OPSX 技能门禁；通过后继续此工作流。
5. 检查 OpenSpec 命令（从项目根目录运行）：优先使用 openspec list、openspec status、openspec validate。
6. 继续修复时，先定位 OpenSpec change：优先根据当前分支名称推断；然后在 openspec/changes/*/{proposal.md,design.md,tasks.md} 中搜索 Jira ID；再检查 PR/MR 描述中的 OpenSpec change 路径；如果仍无法唯一确定，则只向用户提 1 个问题以确认 change 名称。定位后，通过 openspec status --change <name>、openspec show <change-name>、design.md、tasks.md 复选框和当前 Git 分支恢复进度。

OpenSpec 记录模型

此技能不会创建额外的运行时目录。单个 Jira 缺陷修复周期应保持简短清晰；所有工程记录都归入 OpenSpec 工件：

目录	用途	长期事实来源
Jira issue	问题来源、评论、状态转换	否——外部流程来源
openspec/changes/<change-name>/	proposal、增量规格、design、tasks、归档前的 change 事实	是——归档后合并到 openspec/specs/
PR/MR	交付说明、验证证据、风险与回滚	否——交付沟通载体

切勿为 OPSX Jira 修复创建额外的本地运行时目录。继续修复时，从 OpenSpec change、tasks.md 复选框、Git 分支和 PR/MR 状态恢复状态。

阶段工具约束表

阶段	✅ 允许	❌ 禁止
0 前置条件检查	Read、Grep、Glob、Bash（只读检查）、Jira API（只读）	Edit、Write、Git 写操作
1 读取 Jira	Jira API、jira-read、Read、OPSX 技能（创建 change）、Bash（worktree 门禁）	Edit/Write 业务代码；会更改实现的 Bash 命令
2 分析问题	Read、Grep、WebSearch；按 analysis-core §1 使用 analysis-assist Edit/Write（必须登记以便回滚）	为实现修复而进行的业务代码更改
3 创建 change	原生 OPSX 技能、Write（工件）	Edit 业务代码
4 探索解决方案	Read、Grep	Edit/Write 业务代码
5 制定计划	Read、Write（仅限 tasks.md）	Edit 业务代码
6 执行并验证	全部（Edit、Write、Bash、Git、测试）；运行 build/lint/tsc/test 前，按 node-version-discipline（该技能 SOP 中的探测链）与项目声明的 Node 版本保持一致	跳过验证；跳过复选框更新
7 检查验证	Read、Bash（仅测试命令）、OPSX 技能（openspec-verify-change）	Edit/Write 业务代码
8 提交并收尾	Git、Jira API、OPSX 技能、Bash（如果 Part C 决定运行覆盖率，还可使用 test-coverage-analyzer 脚本）	跳过归档；跳过 Jira 回写

模式差异速查表

阶段	手动模式	自动模式
0 前置条件检查	Git 状态不干净 → 提示用户	Git 状态不干净 → 自动暂存
1 读取 Jira	输出候选变更名称，等待确认	自动创建草稿变更
2 分析问题	与自动模式相同	与手动模式相同
3 创建变更	用户确认名称后创建	自动生成并创建
4 探索解决方案	输出解决方案表并暂停，等待用户选择	自动选择最佳方案
5 制定计划	输出计划并暂停，等待确认	常规：自动进入阶段 6；困难 / 非常困难：暂停
6 执行与验证	与自动模式相同	与手动模式相同
7 检查验证结果	输出结果并暂停，等待确认	自动判断通过 / 失败；失败时自动重试（最多 2 轮，然后暂停）
8 提交并收尾	与自动模式相同	与手动模式相同

阶段 1：读取 Jira

在首次写入产物（design.md 中的 Jira 上下文）之前，加载 git-worktree-discipline（worktree 门控 + 可选隔离）。

尽早读取最新 Jira 数据并写入 OpenSpec 产物——切勿只将其留在聊天上下文中。

• Jira ID、标题、优先级、状态
• 描述、复现步骤、预期结果、实际结果
• 附件、评论、历史上下文
• 数据来源（实时 / 缓存 / 用户提供）

阶段 1 完成后，必须确定或创建 OpenSpec 变更：

• 自动模式：按照阶段 3 的命名规则创建草稿变更，并将 Jira 上下文写入 design.md。
• 手动模式：输出候选变更名称并等待确认；确认前不要进入深入分析。
• 继续修复：复用阶段 0 中找到的现有变更，并将最新 Jira 上下文合并到 design.md。

工具限制：允许使用 Jira API / jira-read；禁止编辑 / 写入业务代码；禁止使用会改变实现的 Bash 命令。

完成后自动进入阶段 2。

⚠️ 主动提问：遵循 clarifying-question-discipline（每轮只问一个问题，多轮提问直至明确；先澄清，不要急于回答）。涉及领域词汇时，还要遵循 domain-language-discipline。

🚩 红线：在一条消息中向用户抛出多个含糊的问题（违反硬性规范，参见 clarifying-question-discipline）——每次只问最关键的一个问题，得到回答后再问下一个。

范围拆分（可选，涉及多个子系统时）

如果 Jira 问题涉及 2 个或更多子系统或模块（例如前端 + 后端 + 数据库），请在进入阶段 2 前进行拆分：

1. 列出涉及的子系统 / 模块。
2. 对每个子系统 / 模块，注明：是否有独立的根本原因；是否需要独立的变更；是否依赖主变更。
3. 强依赖的子系统 → 合并到一个变更中；相互独立的子系统 → 考虑拆分为多个变更，每个变更各自执行修复流程。

将拆分结论写入 design.md 的 Scope 部分。

阶段 2：分析问题

分析方法的唯一来源：analysis-core。修复实现属于执行阶段。

委托给 analysis-core

加载强依赖项 analysis-core 并执行其 §§1-3。本工作流的映射（编号 + 名称）：

• {next-stage} = 阶段 3「创建 OpenSpec 变更」
• {root-cause step} = 步骤 5；{impact-assessment step} = 步骤 7；{upstream-eval step} = 步骤 6

阶段输出必须以分析门控输出块结尾（analysis-core §5——红色循环 / 调试入口 / 场景补充 / 临时变更）；缺少该块时，不得进入阶段 3。当预期结果是用户可见或可操作的结果时，同一次加载还会按照 analysis-core 执行 competitive-research。不要重复说明其方法。

此工作流的编排（保留）

在 analysis-core 框架的基础上，此阶段还会完成：

• 难度分级（简单 / 中等 / 困难 / 非常困难）和 路径选择（精简 / 渐进 / 完整）；如果范围扩大，则升级路径
• 产物写入位置：写入 design.md 的 Problem Analysis / Root Cause / Impact（必须已存在变更，否则返回阶段 1）
• 不存在 ❌ / 描述不匹配：暂停；写入 Jira 评论前先征得用户确认（加载 jira-wiki-markup）

分级和路径表：

Level	触发条件	行为
简单	≤3 个文件，根因明确	可以采用精简路径
中等	4-10 个文件，根因基本明确	采用渐进路径
困难	风险较高或影响范围较广	阶段 5 后暂停审核
非常困难	根因未知、架构变更、数据迁移、API 契约变更、跨仓库	自动模式中止；手动模式需要再次确认

难度	路径	要求
简单	精简	proposal/delta specs 可以精简，但绝不能跳过验证
中等	渐进	完整的 proposal/specs/design/tasks
困难/非常困难	完整	完整执行阶段 1-8

🚩 危险信号：跳过存在性检查；根因分析过浅；未将结论写入 design.md；存在歧义但未触发检测（analysis-core §3）；未升级路径；违反 analysis-core / known-issue-research 的门槛要求

---

阶段 3：创建 OpenSpec 变更

🔌 OPSX 技能调用规范：在本阶段或后续阶段委派任何原生 OPSX 技能前，先阅读该技能的 SKILL.md；绝不能凭记忆调用。

确认或创建 Jira 问题对应的 OpenSpec 变更。如果阶段 1 已创建或复用了变更，则本阶段只需验证并补全产物；手动模式必须先确认变更名称；自动模式可以生成并继续。

• 命名：fix-<jira-id-lower>-<short-topic>（例如：fix-proj-12167-ai-summary-button）
• 创建：委派给 openspec-new-change（先阅读其 SKILL.md；/opsx:new 是入口别名）
• Jira 完整性：design.md 必须至少包含 Jira Context / Root Cause / Options / Risk / Verification Notes；proposal / delta-spec 字段详情见 reference.md「阶段 3 产物字段检查清单」

阶段 4：探索并评审解决方案

如果思路仍不清晰，请在方案表／提案之前遵循 decision-fog-discipline。根据阶段 2 的根因和阶段 3 的产物，输出 2-3 个解决方案：

• 核心思路
• 涉及的文件／模块
• 对 OpenSpec 要求的覆盖情况
• 优点、缺点、复杂度、风险
• 推荐的解决方案

YAGNI：解决方案必须严格聚焦于修复 Jira 根因并覆盖差异规格，剔除非必要功能和过度设计。任何超出根因范围的新增内容都必须明确标注为“额外优化”，并说明承担风险的理由。

架构边界预检（决策顺序）：当候选方案跨越进程或层边界时，应先回答预检问题，再权衡短期成本（改动规模／复用／单仓库）——（1）运行时初始化位置：哪个进程／层初始化被调用的能力；（2）边界合法性：跨层导入是否会将被调用方的依赖树引入调用方的打包图（打包器的静态预扫描会使动态 require/import 无法作为规避方案）；（3）归属分类：系统能力、数据／产品能力，还是调用层的定位。边界判断结果应与比较表一同呈现，并作为自动模式选择方案的门槛。方法论：code-design-review 的 Layer A 依赖方向维度。单层方案无需触发此预检。

手动模式下，输出解决方案表并等待用户选择；自动模式下，自动选择最佳方案。

加载 staged-review-flow 并执行其完整评审约定。此工作流的映射：{next-stage} = 阶段 5“制定计划”；{artifact-sink} = openspec/changes/<change-name>/design.md；{extra-dimensions} = 规格覆盖情况（要求／场景）和 Jira 状态边界（仅转换为“fixed”）；{batch-overcap-behavior} = N/A。

🚩 红旗（阶段 4）：

• 评审只覆盖根因，未检查规格覆盖情况或副作用
• 仅有 1 个解决方案时便跳过比较和评审

阶段 5：制定计划

将 openspec/changes/<change-name>/tasks.md 作为唯一任务清单。

任务要求：

• 使用复选框：- [ ] 1.1 ...
• 每项任务都应足够小，以便独立验证。
• 覆盖每项差异规格要求和场景。
• 包含必要的测试、验证、回滚、OpenSpec 归档以及合并后的 Jira 回写步骤。
• 不得使用 TBD、TODO、“适当处理”、“同上”或其他不可执行的描述。

手动模式下，输出计划并等待用户确认；自动模式下，通常会自动进入阶段 6——困难或极困难的情况必须暂停并等待确认。

🚩 红旗（阶段 5）：

• 任务项包含 TBD、TODO、“适当处理”、“同上”或其他不可执行的文本
• 任务未覆盖每项差异规格要求和场景
• 缺少测试、验证、回滚、归档或合并后的 Jira 回写步骤
• 任务粒度过大，无法独立验证

阶段 6：执行修复并验证

进行生产代码修改之前，遵循 design-approval-gate（手动模式：用户通过；自动／强制／精简模式：注明例外并留痕）。

上下文预算：根据 context-budget-discipline，评估阶段边界重置以及压缩阈值（账本路径来自阶段 5 的计划／卡片供给）；任何重置都必须先有完整的账本条目。

6.1 创建修复分支

分支命名：

fix/jira-fix-<JIRA-ID>

多仓库场景需要为每个仓库创建一个分支，并在 PR/MR 描述中列出每个仓库、分支及对应的 OpenSpec 变更。

6.2 执行任务

Figma 像素级保真度： 如果目标、卡片、问题或计划文本中包含 figma.com 或 node-id=，或者用户要求像素级还原，则加载 figma-pixel-implement 并遵循其指引。这些子字符串是确定范围的依据。将这些行保持为硬性要求；不要因为任务也会检查行为，就把它们归入软性要求或人工检查。探测可见文本、可见性标记或列表长度，都无法通过像素级要求。如果同一文本还包含 参考、match the existing 或 same as，则将这一依据传入 verify，使指定控件的交互状态成为检查项。若目标仓库中没有持久化的清单+规格文件路径，Implement 就不算完成。在同一轮运行中，该技能会继续执行 figma-pixel-verify，直至总体结果为 PASS，或测量命令无法运行。此处不再重复其方法。

按顺序处理 tasks.md：

1. 一次只处理当前任务。
2. 在修改业务代码之前，确认提案、规格、设计和任务文件均已存在。
3. 完成任务后立即更新复选框：使用 StrReplace 将 tasks.md 中对应的 [ ] 改为 [x]——不要等一组任务完成后再批量更新。跳过此操作会导致 stage-7 验证器报告 CRITICAL 级别的错误未完成。
4. 如果发现规格或设计有误，先更新相应文件，再继续实现。
5. 说明任何偏离计划的原因；如果影响行为契约，则返回 stage 3 或 4。

可选的跟踪注释：

// fix <JIRA-ID>

如果项目惯例不接受修复注释，不要强行添加——但要在执行报告中列出修复点。

6.2.5 先测试，再确保测试套件（必须在进入 stage 7 之前完成）

对于会改变行为的工作，在实现过程中遵循 test-first-discipline。tasks.md 中的所有复选框都勾选后、进入 stage 7 验证之前，必须完成此步骤：

加载并调用 test-suite-ensure，声明 mode=mandatory，并将范围限定为此次修复涉及的逻辑文件；如果调用失败，或拒绝必要的脚手架请求，则不得进入 stage 7。test-suite-ensure 不能替代 test-first。

阶段 7：检查验证

上下文预算：发生重置时，根据 context-budget-discipline 对照台账和制品进行验证；切勿重放之前会话的历史记录。

必须涵盖：

1. OpenSpec 验证：
   • 如果检测到 openspec-verify-change 技能 → 阅读其 SKILL.md，并委托该技能执行验证。
   • 如果不存在 → 直接运行 openspec validate <change-name> 或 openspec validate --changes（这是 CLI 工具调用，不是降级处理）。

Node 版本对齐（前置条件）：运行以下验证命令前，调用 node-version-discipline，使 Node 版本与项目声明的版本对齐。

2. 工程验证：测试、lint、类型检查、构建（使用对齐后的版本）
3. 行为交叉检查：逐项确认 delta 规范中的每项要求和场景
4. Jira 交叉检查：复现步骤以及预期／实际结果是否已全部解决
5. 副作用检查：相关模块和平台是否受到影响；验证报告必须注明 Node (declared vX) ✅/⚠️ not aligned
6. 调试验证循环：如果阶段 2 使用了调试技能来定位根本原因，则必须使用同一技能验证修复，遵循 analysis-core §4（不能只运行测试）
7. Figma 像素验证：当目标、卡片、问题或计划包含 figma.com 或 node-id=，或者本次运行是根据 Figma 实现时，加载 figma-pixel-verify 并遵循其说明；如果缺少测量报告（常驻制品的 Verify 部分，或 Spec 源文件的同级文件），则此验证阶段不能通过。Spec 缺口 FAIL 不算通过验证——重新进入 figma-pixel-implement，补全表格。此外，如果需要检查对齐情况但本次运行未执行实现，也要加载该技能。只有当该报告的总体状态为 PASS（包括已接受的残余问题），且其渠道是已布局的测量渠道（storybook、isolated-harness、preview、full-app 或 layout-probe）时，此阶段才算通过。任何其他结果都表示此阶段失败，并返回实现阶段，继续修复／重新测量循环。此阶段还会针对该报告运行 figma-pixel-verify 技能中的 scripts/check-figma-verify-report.mjs；非零退出码表示此阶段失败。

验证执行遵循 runtime-verification-discipline（强依赖项）：AI 必须在环境中自行执行验证；只有在判定为真正的硬性边界时，才将某步骤列为手动验证项，并说明原因。

根据 staged-review-flow 的验证报告诚信规则和 completion-evidence-discipline 标注每项结果（没有本轮最新证据时不得声称通过）。

输出格式：参见 reference.md「阶段 7 验证结果」。

验证失败时不得提交 PR。执行记录包括 tasks.md 复选框、PR/MR 描述和 design.md 的 Verification Notes。

阶段 8：归档、提交 PR、合并并收尾

8.1 OpenSpec 归档

归档前同步步骤：

1. 如果存在增量规范：调用 openspec-sync-specs 技能（如果已安装），将增量规范合并到主规范 specs/<capability>/spec.md；或者让 openspec-archive-change 在归档过程中提示并处理同步。
2. 执行归档：调用 openspec-archive-change 技能（先阅读其 SKILL.md，然后按说明操作）。

如果 openspec-archive-change 失败，不要手动操作 openspec/ 目录——停止操作，并告知用户检查 OpenSpec 安装。

在合并或准备合并之前，确认归档已完成（符合 merge-discipline Part A 的要求）：

• 存在关联的活动 OpenSpec 变更时：必须先归档（同步主规范 + 移入 openspec/changes/archive/），确认差异，然后再合并；“合并后归档”绝不是常规流程。
• 没有关联变更的 PR：Part A 直接通过，无需归档。

默认流程：验证通过后，先归档，确认差异中包含 openspec/specs/ 更新和移入 openspec/changes/archive/ 的变更，然后交付并收尾。

8.2 提交与 PR（delivery-discipline）

交付前，确认：

• 所有相关的 tasks.md 复选框均已完成。
• OpenSpec 产物、代码变更和必要的验证说明均已包含在差异中或 PR/MR 描述中。
• 验证已通过，或已明确列出需手动验证的事项。

加载 delivery-discipline 并按其要求操作。提供：

• {commit-context}：优先使用 fix(<scope>): <JIRA-ID> <subject>
• {pr-body-extra}：Jira 链接、根因、修复方案、OpenSpec 变更路径、变更文件列表、验证证据、风险与回滚

8.3 分支收尾

归档、交付和差异检查完成后，加载 feature-branch-closeout 以选择后续操作（PR / 合并 / 保留 / 继续）。验证未通过或归档未完成时，绝不要宣布完成。

顺序约束：归档（8.1）→ delivery-discipline（8.2）→ feature-branch-closeout（8.3）→ 合并时执行 merge-discipline（8.3.1）→ 执行合并 → Jira 回写（8.4）。选择保留/继续会跳过合并规范和 Jira 回写。

8.3.1 合并规范（merge-discipline 技能）

合并时（通过收尾流程或用户直接发出合并命令），加载 merge-discipline 并依次执行 Part A → B → C → R → D；合并前检查清单位于 merge-discipline/reference.md。绝不要隐式跳过。

8.4 Jira 回写（合并完成后）

PR/MR 合并且代码进入主分支后，将 Jira 状态回写为修复已上线。加载强依赖 jira-status-writeback，并按其 SOP 处理状态转换和修复评论（jira-wiki-markup 负责组织 Wiki body）。此工作流提供以下字段映射：

jira-status-writeback 字段	值
修复分支 / 提交 / PR/MR URL	修复分支名称 / 合并后的最新提交 SHA / PR/MR 链接
根因	第 2 阶段根因摘要
修复摘要	修复方案
变更文件	变更文件列表
验证	第 7 阶段验证场景
其他	OpenSpec 变更路径、风险或 QA 后续事项

PR/MR、Jira 评论和 OpenSpec 归档结果共同构成权威的收尾记录。

8.5 回顾（委派给 learn-and-improve）

归档和分支收尾完成后（如果执行了合并，还要完成 Jira 回写），加载 learn-and-improve 并遵循其框架。通过常规流程归档的 OpenSpec 工件不受其沉淀价值门槛限制。AI 工程知识（AGENTS.md、规则、技能等）使用该技能的载体决策树；只有在用户明确提出请求后，才能写入。

🚩 红旗（阶段 8）：

• 验证通过前提交 PR
• 通过 jira_transition_issue 的 comment 参数传递 Jira 评论，或越权将状态转换为“closed” / “verified”（SOP：jira-status-writeback）
• 归档失败后手动操作 openspec/ 目录
• PR 描述缺少 OpenSpec 变更路径或验证证据
• 在 ask 偏好下默认运行分析器，而没有询问用户（参见 merge-discipline C 部分）
• 在归档（8.1）完成前触发合并规范（顺序：8.1 归档 → 8.2 delivery-discipline → 8.3 分支收尾 → 8.3.1 合并规范 → 合并 → 8.4 Jira 回写）

批量 OPSX Jira 修复

使用 opsx-jira-fix-queue 技能（轻量封装：解析 Jira 列表，并使用 Engine: opsx-jira-fix-workflow 将任务加入 goal-driven-queue；不会循环执行此工作流，也不会合并）。队列已记录的关联关系判断会写入此处每项变更的 design.md，作为 ## Related Issues。

常见错误

此处仅列出本技能中不明显的陷阱。合并/覆盖率/归档 → merge-discipline；项目根目录/openspec//原生技能门槛 → opsx-workspace-gate；Jira 回写 SOP → jira-status-writeback；评论 Wiki 标记 → jira-wiki-markup。阶段正文中已说明的规则不再重复。

错误	后果	修正方法
创建额外的本地运行时目录	在 OpenSpec 之外建立第二套记录系统	将所有内容记录在 OpenSpec 工件、PR/MR 和 Jira 评论中
只写入 OpenSpec，从不回写 Jira	Jira 流程中断，QA 无法跟进	阶段 8.4 合并后加载 jira-status-writeback，完成回写
在阶段 8.4 中重述 jira-status-writeback 的两步 API 细节或状态权限逻辑	与 jira-status-writeback 不一致，导致评论丢失或错误关闭问题	阶段 8.4 只传递字段映射；SOP 细节由 jira-status-writeback 负责
为快速修复采用 OPSX 流程	流程变得过于繁重	不需要追溯沉淀时，使用 jira-fix-workflow
机械地按列表批量执行	重复修复、遗漏依赖关系或行为冲突	执行前后识别问题关联关系；将其记录在 Related Issues / Risk / Dependencies 中
阶段 2 分析后立即创建提案	Why/What 脱节，工件需要重写	阶段 4 选定方案后，一次性写好提案
design.md 缺少 Jira Context / Root Cause / Options / Risk / Verification Notes	无法逐项回顾	这五个部分是 Jira×OPSX 的最低完整性要求
MODIFIED 只写入部分内容，或技能简称错误	归档时丢失需求 / 无法找到 SKILL.md	复制完整区块后再编辑；使用准确的 openspec-*-change 名称

最低成功标准

一次完整运行：通过原生技能为 OpenSpec 变更创建 proposal / delta specs / design / tasks；创建或更新 PR/MR；Jira 中有评论，且状态已转换为“fixed”（如果获准）；OpenSpec 已归档（或 PR 中注明归档策略和负责人）；已记录验证证据。