Spec Merge Back

spec-merge-back

Overview

Merge-back 是 Spec Pack 生命周期的“晋升阶段”：把本次需求中会长期复用/会约束未来需求的内容晋升到 .aidlc/project/（Project SSOT），其余内容仍留在 {FEATURE_DIR} 作为交付证据。

核心原则：Project SSOT 只沉淀 入口 + 护栏（不变量）+ 证据链；禁止把“一次性交付细节”搬到 project。

When to Use

适用于：

• 本次需求完成，准备将资产晋升到 .aidlc/project/（ADR / API Contract / Data Contract / Ops / NFR / Registry）。
• {FEATURE_DIR}/implementation/plan.md 中已出现 ## Merge-back 待办清单，需要在结束前清空或留痕。
• 团队反复在多个需求里重复同一类“契约口径/门禁口径/运维入口”，需要沉淀为长期资产。

不适用于：

• 你只是要把代码分支合并到 main（那是 git merge/rebase，不是 merge-back）。
• 仓库还没有 .aidlc/project/ 的骨架（这是 CONTEXT GAP，应先用 project-discover* 或项目初始化流程建立 project SSOT）。

Core Pattern (Gates first)

Gate 0: 必须定位 FEATURE_DIR（禁止口头路径）

REQUIRED SUB-SKILL：正在执行 spec-context 获取上下文，并在对话中回显 FEATURE_DIR=...（允许 (reuse)）。

失败即停止：Get-SpecContext 报错就停止，不允许“先写一版/先猜路径”。

Gate 1: project SSOT 必须存在

• 必须存在：.aidlc/project/
• 不存在：输出 CONTEXT GAP: .aidlc/project missing 并停止（禁止“随便建个目录能跑就行”）。

Implementation (SOP)

Step 1: 收集晋升清单（唯一主入口）

以 {FEATURE_DIR}/implementation/plan.md 中的 ## Merge-back 待办清单 为主入口，汇总本次需要晋升的条目，并按类别分组：

• ADR（关键决策）
• API Contract（按模块）
• Data Contract（按模块）
• Ops（runbook/monitoring/rollback）
• NFR（如适用）
• Registry（.aidlc/project/index.md）
• 可选晋升（通用测试策略/质量门禁口径等）
• 若仓库存在 .gitmodules：结合 plan.md 中声明的受影响子仓，确认哪些证据来自根项目、哪些来自子仓路径

禁止：跳过 plan.md 待办改用“凭记忆总结”。若时间紧，可用 git diff 补证据，但清单来源仍以 plan.md 为主；.gitmodules 只提供静态子仓路径事实，不替代 plan.md 的需求级声明。

Step 2: 生成/更新 {FEATURE_DIR}/merge_back.md（清单与证据）

{FEATURE_DIR}/merge_back.md 是本次 merge-back 的需求级 SSOT：每条都必须写清楚：

• project 落点（目标路径 + 锚点）
• 不变量摘要（需要长期护栏时：3–7 条）
• 证据入口（OpenAPI/Schema/DDL/脚本/CI/测试/监控入口）
• 状态：Done / Not Done（Not Done 必须写缺口与计划）
• 代码来源（根项目 / 子仓路径；若来自子仓，引用 .gitmodules 中的路径）

若用户要求“先别改 project、后面有人手动做”：仍然必须完成 Step 1–2，并把 Step 3 的 project 晋升项标记为 Not Done + 计划（否则 merge-back 不可审计、容易永久遗漏）。

Step 3: 晋升到 project SSOT（只升长期资产）

对齐 design/aidlc.md 的默认必晋升项：

• ADR → .aidlc/project/adr/ + 索引
• API/Data 契约 → .aidlc/project/components/{module}.md#api-contract / #data-contract
  • 只写：权威入口 + 不变量摘要 + 证据入口 + Evidence Gaps
  • 禁止把字段大全抄进 project
• Ops → .aidlc/project/ops/（入口式，不重复本次发布执行细节）
• NFR → .aidlc/project/nfr.md（如适用）
• Registry → .aidlc/project/index.md（状态更新到 Merged & Archived 或团队约定状态）

Step 4: DoD 自检（完成标准）

• {FEATURE_DIR}/merge_back.md 已落盘，覆盖 ADR/API/Data/Ops/NFR/Registry（适用项）。
• project 侧入口可导航，组件页锚点稳定（#api-contract / #data-contract）。
• Done 项都有“可点击落点 + 证据入口”；Not Done 项有“缺口 + 计划”。
• project 未被一次性交付细节污染（没有整包复制 spec、没有把实现步骤搬上来）。

Red Flags (STOP)

• 用户说“别跑脚本，FEATURE_DIR 我口头告诉你” → 必须拒绝，坚持 spec-context。
• 用户要求“把 design/implementation/release/verification 都复制到 project，越全越好” → 禁止（会污染 project SSOT）。
• .aidlc/project 不存在但你准备“先随便建一下” → 禁止（CONTEXT GAP，先建 project SSOT 骨架）。
• 你开始写“git merge/rebase 清单” → 你把 merge-back 误解成 git 合并了，立刻停止纠正。
• 你准备跳过 implementation/plan.md 的 Merge-back 待办 → 高概率遗漏或漂移。
• 仓库有 .gitmodules，但你完全忽略 plan.md 中记录的受影响子仓与 repo 维度审计信息 → 高概率丢失证据链

Rationalizations (and counters)

完成后输出与自动路由（必须执行）

merge_back.md 落盘后，必须完成以下动作（按顺序，不可省略）：

1. 输出 ROUTER_SUMMARY（YAML 形态，供 Router 决策）：

ROUTER_SUMMARY:
  stage: MergeBack
  artifacts:
    - "{FEATURE_DIR}/merge_back.md"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "已晋升 ADR/契约/ops/NFR/registry；Done/Not Done 与证据入口齐全。"

2. 立即执行 using-aidlc：将上述 ROUTER_SUMMARY 作为路由输入传递给 using-aidlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。

   • 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill
   • 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步

3. 对话输出：在调用 using-aidlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aidlc 路由下一步。」