spec-merge-back

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

spec-merge-back

Overview

Merge-back 是 Spec Pack 生命周期的“晋升阶段”：把本次需求中会长期复用/会约束未来需求的内容晋升到

.aisdlc/project/

（Project SSOT），其余内容仍留在

{FEATURE_DIR}

作为交付证据。

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

Merge-back is the "promotion phase" of the Spec Pack lifecycle: content in this requirement that will be reused for a long time / will constrain future requirements is promoted to

.aisdlc/project/

(Project SSOT), and the remaining content stays in

{FEATURE_DIR}

as delivery evidence.

Core Principle: Project SSOT only stores entry + guardrails (invariants) + evidence chain; it is forbidden to move "one-time delivery details" to the project.

When to Use

适用于：

本次需求完成，准备将资产晋升到
```
.aisdlc/project/
```
（ADR / API Contract / Data Contract / Ops / NFR / Registry）。

{FEATURE_DIR}/implementation/plan.md

中已出现

## Merge-back 待办清单

，需要在结束前清空或留痕。

团队反复在多个需求里重复同一类“契约口径/门禁口径/运维入口”，需要沉淀为长期资产。

不适用于：

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

Applicable scenarios:

This requirement is completed, and you are ready to promote assets to
```
.aisdlc/project/
```
(ADR / API Contract / Data Contract / Ops / NFR / Registry).
```
## Merge-back To-do List
```
has appeared in
```
{FEATURE_DIR}/implementation/plan.md
```
, which needs to be cleared or documented before closing.
The team repeatedly repeats the same type of "contract caliber/access control caliber/operation and maintenance entry" in multiple requirements, which needs to be precipitated as long-term assets.

Inapplicable scenarios:

You just want to merge code branches to main (that is git merge/rebase, not merge-back).
The repository does not yet have the
```
.aisdlc/project/
```
skeleton (this is CONTEXT GAP, you should first use
```
project-discover*
```
or the project initialization process to build the project SSOT).

Core Pattern (Gates first)

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

Gate 0: FEATURE_DIR must be located (verbal path is forbidden)

powershell

. ".\skills\spec-context\scripts\spec-common.ps1"
$context = Get-SpecContext
$FEATURE_DIR = $context.FEATURE_DIR
Write-Host "FEATURE_DIR=$FEATURE_DIR"

失败即停止：

Get-SpecContext

报错就停止，不允许“先写一版/先猜路径”。

powershell

. ".\skills\spec-context\scripts\spec-common.ps1"
$context = Get-SpecContext
$FEATURE_DIR = $context.FEATURE_DIR
Write-Host "FEATURE_DIR=$FEATURE_DIR"

Stop on failure: Stop immediately if

Get-SpecContext

reports an error, do not allow "write a version first / guess the path first".

Gate 1: project SSOT 必须存在

Gate 1: Project SSOT must exist

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

Must exist:
```
.aisdlc/project/
```
If not exist: Output
```
CONTEXT GAP: .aisdlc/project missing
```
and stop (forbid "just create a random directory to make it run").

Implementation (SOP)

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

Step 1: Collect promotion list (the only main entry)

以

{FEATURE_DIR}/implementation/plan.md

中的 ## Merge-back 待办清单
为主入口，汇总本次需要晋升的条目，并按类别分组：

ADR（关键决策）
API Contract（按模块）
Data Contract（按模块）
Ops（runbook/monitoring/rollback）
NFR（如适用）
Registry（
```
.aisdlc/project/index.md
```
）
可选晋升（通用测试策略/质量门禁口径等）

禁止：跳过
plan.md
待办改用“凭记忆总结”。若时间紧，可用
git diff
补证据，但清单来源仍以
plan.md
为主。

Take ## Merge-back To-do List
in

{FEATURE_DIR}/implementation/plan.md

as the main entry, summarize the items to be promoted this time, and group them by category:

ADR (key decisions)
API Contract (by module)
Data Contract (by module)
Ops (runbook/monitoring/rollback)
NFR (if applicable)
Registry (
```
.aisdlc/project/index.md
```
)
Optional promotion (general test strategy/quality access control caliber, etc.)

Forbidden: Skip the
plan.md
to-do list and use "summarize from memory" instead. If time is tight, you can use
git diff
to supplement evidence, but the source of the list is still mainly
plan.md
.

Step 2: 生成/更新

{FEATURE_DIR}/merge_back.md

（清单与证据）

Step 2: Generate/update

{FEATURE_DIR}/merge_back.md

(list and evidence)

{FEATURE_DIR}/merge_back.md

是本次 merge-back 的需求级 SSOT：每条都必须写清楚：

project 落点（目标路径 + 锚点）
不变量摘要（需要长期护栏时：3–7 条）
证据入口（OpenAPI/Schema/DDL/脚本/CI/测试/监控入口）
状态：Done / Not Done（Not Done 必须写缺口与计划）

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

{FEATURE_DIR}/merge_back.md

is the requirement-level SSOT for this merge-back: each entry must clearly state:

Project landing location (target path + anchor)
Invariant summary (when long-term guardrails are needed: 3–7 items)
Evidence entry (OpenAPI/Schema/DDL/script/CI/test/monitoring entry)
Status: Done / Not Done (Not Done items must specify gaps and plans)

If the user requires "don't modify the project first, someone will do it manually later": You still must complete Step 1–2, and mark the project promotion items in Step 3 as Not Done + plan (otherwise merge-back is not auditable and easy to be permanently missed).

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

Step 3: Promote to project SSOT (only promote long-term assets)

对齐

design/aisdlc.md

的默认必晋升项：

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

Align with the default mandatory promotion items in

design/aisdlc.md

ADR →
```
.aisdlc/project/adr/
```
+ index
API/Data Contract →
```
.aisdlc/project/components/{module}.md#api-contract
```
/
```
#data-contract
```
- Only write: authoritative entry + invariant summary + evidence entry + Evidence Gaps
- Forbid copying the full field list into the project
Ops →
```
.aisdlc/project/ops/
```
(entry type, do not repeat the execution details of this release)
NFR →
```
.aisdlc/project/nfr.md
```
(if applicable)
Registry →
```
.aisdlc/project/index.md
```
(update status to Merged & Archived or the status agreed by the team)

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

Step 4: DoD self-check (completion criteria)

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

```
{FEATURE_DIR}/merge_back.md
```
has been saved, covering ADR/API/Data/Ops/NFR/Registry (applicable items).
The entry on the project side is navigable, and the component page anchor is stable (
```
#api-contract
```
/
```
#data-contract
```
).
Done items have "clickable landing location + evidence entry"; Not Done items have "gap + plan".
The project is not contaminated by one-time delivery details (no full package replication of spec, no moving implementation steps to the project).

Red Flags (STOP)

用户说“别跑脚本，FEATURE_DIR 我口头告诉你” → 必须拒绝，坚持
```
spec-context
```
。
用户要求“把 design/implementation/release/verification 都复制到 project，越全越好” → 禁止（会污染 project SSOT）。
```
.aisdlc/project
```
不存在但你准备“先随便建一下” → 禁止（CONTEXT GAP，先建 project SSOT 骨架）。
你开始写“git merge/rebase 清单” → 你把 merge-back 误解成 git 合并了，立刻停止纠正。
你准备跳过
```
implementation/plan.md
```
的 Merge-back 待办 → 高概率遗漏或漂移。

The user says "don't run the script, I'll tell you the FEATURE_DIR verbally" → Must refuse, insist on using
```
spec-context
```
.
The user requires "copy all design/implementation/release/verification to the project, the more comprehensive the better" → Forbidden (will contaminate the project SSOT).
```
.aisdlc/project
```
does not exist but you are going to "build a random one first" → Forbidden (CONTEXT GAP, build the project SSOT skeleton first).
You start writing a "git merge/rebase list" → You have mistaken merge-back for git merge, stop and correct immediately.
You are going to skip the Merge-back to-do list in
```
implementation/plan.md
```
→ High probability of omission or drift.

Rationalizations (and counters)

常见借口	现实/反制
“很急，先复制整包到 project，后面再整理”	整包复制会长期污染 project；正确做法是只晋升“入口+不变量+证据链”。
“用户给了 FEATURE_DIR，不用跑 spec-context”	口头路径不可信；必须以 `spec-context` 输出为唯一锚点。
“project 目录没有，我先建个最小的让它跑起来”	merge-back 不负责初始化 project SSOT；缺失即 `CONTEXT GAP` 并停止。
“不看 plan.md 待办也能总结”	待办是唯一执行期汇总入口；跳过会遗漏且不可审计。

Common Excuses	Facts/Countermeasures
"It's urgent, copy the whole package to the project first, and sort it out later"	Full package replication will contaminate the project for a long time; the correct approach is to only promote "entry + invariants + evidence chain".
"The user gave the FEATURE_DIR, no need to run spec-context"	Verbal paths are not reliable; the output of `spec-context` must be used as the only anchor.
"The project directory does not exist, I will build a minimal one first to make it run"	merge-back is not responsible for initializing the project SSOT; if missing, report `CONTEXT GAP` and stop.
"I can summarize without looking at the plan.md to-do list"	The to-do list is the only summary entry during the execution period; skipping it will lead to omission and is not auditable.

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

Post-completion Output and Automatic Routing (Mandatory)

merge_back.md

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

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

yaml

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 与证据入口齐全。"

立即执行
using-aisdlc
：将上述
```
ROUTER_SUMMARY
```
作为路由输入传递给 using-aisdlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。
- 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill
- 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步
对话输出：在调用 using-aisdlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aisdlc 路由下一步。」

After

merge_back.md

is saved, must complete the following actions (in order, cannot be omitted):

Output ROUTER_SUMMARY (YAML format, for Router decision making):

yaml

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 与证据入口齐全。"

Execute
using-aisdlc
immediately: Pass the above
```
ROUTER_SUMMARY
```
as routing input to using-aisdlc, and the Router will determine the next step and automatically advance (no need to wait for the user to say "continue").
- If the Router determines that automatic continuation is possible: Continue to execute the next worker skill in the same round of conversation
- If the Router triggers a hard interrupt: Stop and output the blocking reason, required input, and candidate next steps
Conversation output: Before calling using-aisdlc, you can briefly explain "The products of this phase have been saved, and using-aisdlc is being called to route the next step."

spec-merge-back

Original

Translation

spec-merge-back

spec-merge-back

Overview

Overview

When to Use

When to Use

Core Pattern (Gates first)

Core Pattern (Gates first)

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

Gate 0: FEATURE_DIR must be located (verbal path is forbidden)

Gate 1: project SSOT 必须存在

Gate 1: Project SSOT must exist

Implementation (SOP)

Implementation (SOP)

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

Step 1: Collect promotion list (the only main entry)

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

Step 2: Generate/update
`{FEATURE_DIR}/merge_back.md`
(list and evidence)

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

Step 3: Promote to project SSOT (only promote long-term assets)

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

Step 4: DoD self-check (completion criteria)

Red Flags (STOP)

Red Flags (STOP)

Rationalizations (and counters)

Rationalizations (and counters)

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

Post-completion Output and Automatic Routing (Mandatory)

spec-merge-back

Original

Translation

spec-merge-back

spec-merge-back

Overview

Overview

When to Use

When to Use

Core Pattern (Gates first)

Core Pattern (Gates first)

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

Gate 0: FEATURE_DIR must be located (verbal path is forbidden)

Gate 1: project SSOT 必须存在

Gate 1: Project SSOT must exist

Implementation (SOP)

Implementation (SOP)

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

Step 1: Collect promotion list (the only main entry)

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

Step 2: Generate/update {FEATURE_DIR}/merge_back.md (list and evidence)

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

Step 3: Promote to project SSOT (only promote long-term assets)

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

Step 4: DoD self-check (completion criteria)

Red Flags (STOP)

Red Flags (STOP)

Rationalizations (and counters)

Rationalizations (and counters)

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

Post-completion Output and Automatic Routing (Mandatory)

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

Step 2: Generate/update
`{FEATURE_DIR}/merge_back.md`
(list and evidence)