---
name: sdd-sync
description: |-
  Use when merging delta specs from a change into the main baseline specs. Triggers: "sync specs", "merge delta specs", "update main specs", "apply the spec changes", "sync the change".
---

# SDD Sync

Merge delta specs from a change directory into the main baseline specs.
Applies each delta marker intelligently, preserving existing content not mentioned in the delta.

> `SPECS_ROOT` is resolved by the `sdd` router before this skill runs.
> Replace `.specs/` with your project's actual specs root in all paths below.

## Invocation Notice

- Inform the user when this skill is being invoked by name: `sdd-sync`.

## When to Use

- After `sdd-verify` passes with no blocking findings — implementation is confirmed correct
- After `sdd-verify` reports only blockers that are explicitly overridden per `references/sdd-change-formats.md`
- Ready to finalize the change and update the source-of-truth specs

## When Not to Use

- Delta specs don't exist for this change — nothing to sync
- Implementation isn't verified — run `sdd-verify` first
- Blocking findings remain from `sdd-verify`

## Soft Gate

If no delta specs exist in `.specs/changes/<name>/specs/`, warn:

> "No delta specs to sync."

Stop unless the user confirms to proceed.

Before syncing, confirm verification status and any recorded override trail:

1. `sdd-sync` consumes the latest `sdd-verify` outcome; it does not reconstruct verification from `design.md`.
2. If the latest verify result is not in context, stop and tell the user to run `sdd-verify` first.
3. If sync is proceeding under override, read `.specs/changes/<name>/design.md` for `## Verification Overrides` and confirm each applicable entry has all required fields (finding, stage, reason, constraints, follow-up task, approved by, recorded).
   Stop if any required field is missing.
4. Any blocker from the current verify result that is not covered by a recorded override remains blocking.
   Stop and tell the user which blockers remain uncovered.

## Process

### Phase 1: Identify What to Sync

1. Confirm the active change (ask if multiple active changes exist)
2. List all delta spec files in `.specs/changes/<name>/specs/`
3. For each delta spec, identify the corresponding main spec in `.specs/specs/`
4. If sync is proceeding under override, load the matching override entries and the referenced unchecked tasks from `tasks.md`

### Phase 2: Apply Each Delta

For each delta spec, read both files:

- Delta: `.specs/changes/<name>/specs/<capability>/spec.md`
- Main: `.specs/specs/<capability>/spec.md` (may not exist for new capabilities)

Apply delta markers:

| Delta marker              | Action                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| **ADDED** requirements    | Insert as new `### Requirement:` entries in the main spec                                              |
| **MODIFIED** requirements | Find the matching requirement by name and replace it — apply the **MODIFIED preservation guard** first |
| **REMOVED** requirements  | Find the matching requirement by name and delete it                                                    |
| **RENAMED** capabilities  | Rename the capability directory and update the spec header                                             |

**Preservation rule:** Content in the main spec not mentioned in the delta is never touched.

**MODIFIED preservation guard:** The preservation rule operates at requirement granularity — a MODIFIED requirement is replaced as a whole, so scenarios its delta block omits are _not_ preserved.
Before replacing, compare the baseline requirement's scenarios and sub-clauses against the MODIFIED delta block.
If the delta omits any baseline scenario that the change did not deliberately remove (no rationale in `design.md`), stop and surface it:

> "MODIFIED `<name>`: baseline scenario(s) `<…>` are absent from the delta block and will be deleted on sync. Restore the full post-change requirement, or confirm the removal is intentional."

Replace only after the omission is confirmed intentional, and strip the delta-only `> Previously: …` provenance line — it does not belong in the baseline.

A mechanical backstop ships with the skill for the **dropped-scenario** half of this guard: run `scripts/check_modified_completeness.py <specs-root> --change <name>` (a `uv` script; deps are declared inline).
It compares scenario names only and exits non-zero when a MODIFIED delta drops a baseline scenario — sub-clause and body-text preservation is _not_ mechanically checked, so keep verifying that by reading.
Mark intentional scenario drops with a `<!-- modified-removes: ScenarioName -->` comment inside the delta block.

**Idempotency rule:** Applying the same delta twice produces the same result as applying it once.
For ADDED: check whether the requirement already exists by name before inserting — skip if already present.
For RENAMED: check whether the new directory name already exists before renaming — skip if already renamed.

**RENAMED processing order:** When a delta spec contains RENAMED alongside other markers, process the rename first (directory rename + spec header update), then apply any ADDED/MODIFIED/REMOVED markers against the already-renamed main spec.
The delta spec is always identified by the _old_ capability name — look it up before renaming.

### Phase 3: Handle New Capabilities

If a delta spec covers a capability with no corresponding main spec:

1. Create `.specs/specs/<capability>/` directory
2. Create `spec.md` in baseline format (no delta markers)
3. Strip the `## ADDED`, `## MODIFIED`, `## REMOVED` section headings and keep the `### Requirement:` entries beneath them as plain requirements

See `references/sdd-spec-formats.md` for the baseline spec format.

If the delta spec contains only RENAMED and the old capability does not exist in main specs, create the capability under the new name using the ADDED requirements as baseline content.

### Phase 4: Update Schema Snapshots (if schemas configured)

If `.specs/.sdd/schema-config.yaml` exists and `schemas/after/` is present in the change directory:

1. Copy each schema file from `.specs/changes/<name>/schemas/after/<schema-type>` to `.specs/schemas/<schema-type>` (overwrite).

2. Update `.specs/schemas/.schema-sources.yaml` with the generation date and change name.

3. If the repo contains a committed authored schema (e.g., `docs/openapi.yaml`), surface a reminder — do **not** auto-update it:

   > "Authored schema at `<path>` may need updating to match the implementation.
   > Reference: `.specs/changes/<name>/schemas/after/`"

If no schema config exists but `.specs/schemas/` contains files and no `schemas/after/` directory exists in the change, emit a visible warning:

> **WARNING:** Schema baseline exists at `.specs/schemas/` but this change has no after-snapshot. The schema baseline may be stale. Run `sdd-derive` or create `.specs/.sdd/schema-config.yaml` to enable schema tracking.

If no schema config exists and `.specs/schemas/` is empty or absent, skip silently.

### Phase 5: Validate Output

- [ ] All ADDED requirements appear in the main spec
- [ ] All MODIFIED requirements reflect the updated behavior (old version removed) with no baseline scenario dropped unintentionally
- [ ] All REMOVED requirements are gone from the main spec
- [ ] No delta markers (ADDED/MODIFIED/REMOVED/RENAMED) or `> Previously:` provenance lines remain in main specs
- [ ] Content not mentioned in deltas is unchanged

### Phase 6: Report

List each capability synced:

```text
Synced:
- auth/          → 2 requirements added, 1 modified
- payments/      → 1 requirement removed
- notifications/ → new capability created (3 requirements)
Schema snapshots updated:
- openapi.yaml   → 2 endpoints added, 1 model modified
- Reminder: authored docs/openapi.yaml may be stale (schema sync did not update it)

Synced under overrides:
- `pip audit` failure for `litellm` → stage: `verify`; reason: upstream fix unavailable in current environment; constraints: no ignore added; follow-up remains open in `tasks.md`
```

## Common Mistakes

- Replacing the entire main spec instead of merging selectively
- Leaving delta markers (ADDED/MODIFIED/REMOVED) in the main spec after sync
- Touching content not mentioned in the delta
- Replacing a MODIFIED requirement without first checking that its delta block preserves the baseline's still-applicable scenarios — the wholesale replace silently deletes any scenario the delta did not restate
- Carrying the delta-only `> Previously: …` provenance line into the baseline spec
- Reconstructing the verify outcome from `design.md` instead of consuming the latest `sdd-verify` result plus any recorded overrides
- Syncing before `sdd-verify` clears all blockers, whether by a clean pass or a recorded override
- Treating a blocker as non-blocking without a recorded `design.md` override and an unchecked remediation task in `tasks.md`

## References

- `references/sdd-spec-formats.md` — baseline spec format for new capabilities created during sync
- `references/sdd-change-formats.md` — change directory artifact formats (proposal, design, tasks)
- `references/sdd-schema.md` — schema lifecycle policy (§ 4) and `.schema-sources.yaml` format (§ 3)
- `scripts/check_modified_completeness.py` — mechanical dropped-scenario check (scenario names only, not body sub-clauses); exits non-zero on dropped baseline scenarios, wireable as a pre-commit/CI gate