spec-merge-back

Overview

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

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 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"

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 must exist

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: Collect promotion list (the only main entry)

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: Generate/update

{FEATURE_DIR}/merge_back.md

(list and evidence)

{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: Promote to project SSOT (only promote long-term assets)

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 self-check (completion criteria)

```
{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)

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)

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)

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

NPX Install

Tags

SKILL.md Content (Chinese)

spec-merge-back

Overview

When to Use

Core Pattern (Gates first)

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

Gate 1: Project SSOT must exist

Implementation (SOP)

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

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

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

Step 4: DoD self-check (completion criteria)

Red Flags (STOP)

Rationalizations (and counters)

Post-completion Output and Automatic Routing (Mandatory)