spec-merger

Name: spec-merger
Author: MageByte-Zero

24installs58forks

How to install spec-merger?

magebyte-zero/spec-superflow/spec-merger

$npx -y skills add MageByte-Zero/spec-superflow --skill spec-merger

Installs into the current project.

Summary

Sync delta specs to main specs before closure. Invoke while an executing change has delta specs to merge into the main spec base, or when detecting spec drift across multiple changes.

Files · 1

View on GitHub

SKILL.md

1	# Spec Merger
2
3	Before the final `executing → closing` transition, delta specs (ADDED/MODIFIED/REMOVED/RENAMED) must be merged into the main spec base. Specs that aren't synced become lies. A change already in `closing` must not be routed to `spec-merger`.
4
5	## Execution-State Guard
6
7	Before `ssf sync` or any other write, run
8	`npx --yes --package spec-superflow@0.11.0 ssf state get <change-dir> state`.
9	Continue only when the persisted state is exactly `executing`. If it is
10	`closing` → STOP: "Closing is terminal. Do not route this change to spec-merger;
11	synchronization belongs before the final executing → closing transition." For
12	any other state, or if the state cannot be read → STOP and route through
13	`workflow-start`; do not perform side effects.
14
15	## Pre-Flight Checks
16
17	### Conflict Detection
18	Run `npx --yes --package spec-superflow@0.11.0 ssf sync <change-dir>`. If conflicts are detected (same requirement modified by multiple changes), present the conflict list to the user for resolution order.
19
20	## Sync Process
21
22	### Step 1: Identify Deltas
23	Each `specs/<capability>/spec.md` under the change folder contains delta operations under `## ADDED/MODIFIED/REMOVED/RENAMED Requirements`.
24
25	### Step 2: Apply by Operation
26
27	ADDED: Append to `specs/<capability>/spec.md`. Create the main spec if it doesn't exist. Insert before any REMOVED section.
28
29	MODIFIED: Match on `### Requirement: <name>`. Replace description and scenarios. Preserve original in a `### Previous version` subsection. Flag if requirement doesn't exist in main spec.
30
31	REMOVED: Move to `## Removed` section with deprecation note: reason, migration, and change name. Flag if requirement doesn't exist.
32
33	RENAMED: Match old name, change header to new name, add `_Renamed from <old> in <change>_`. Flag if new name collides with existing.
34
35	### Step 3: Conflict Detection
36	Before executing, detect:
37	- Same requirement modified by multiple unsynced changes → manual resolution
38	- RENAMED target collides with existing requirement → manual resolution
39	- MODIFIED/REMOVED targeting nonexistent requirements → flag
40
41	### Step 4: Execute Merge
42	Apply changes. Do NOT delete delta specs — they remain for traceability. After merge, validate: no duplicate requirement names, no orphaned references, REMOVED section clearly separated.
43
44	### Step 5: Report
45	Output sync report table: Capability, ADDED/MODIFIED/REMOVED/RENAMED counts, Status (✓/⚠). Summary with totals and unresolved conflicts.
46
47	## Guardrails
48
49	- Do not delete delta spec files (historical record)
50	- Do not auto-resolve conflicts across changes
51	- Do not merge specs for unverified changes
52	- Validate main spec consistency after each capability merge
53
54	## Post-Sync
55
56	1. Report results. If no conflicts → ready to archive. If conflicts → user resolves before archive.
57	2. Change folder (including deltas) remains for traceability.
58	3. Record that merging is complete so the `executing → closing` guard allows closure:
59	```bash
60	npx --yes --package spec-superflow@0.11.0 ssf state set <change-dir> spec_merged true
61	```
62	(If the change had no delta sections, still set `spec_merged true` — there was nothing to merge.)
63
64	## Exception Handling
65
66	- Parse failures: Report file and section. Do not attempt partial merges.
67	- No deltas: If change has no delta sections, report nothing to merge and exit cleanly.
68	- User interruption: On resume, check for merge conflict markers before proceeding.

People who liked this also viewed

6 picks

Type

spec-merger

24installs58forks

View on GitHub

How to install spec-merger?

magebyte-zero/spec-superflow/spec-merger

$npx -y skills add MageByte-Zero/spec-superflow --skill spec-merger

Installs into the current project.

Summary

Sync delta specs to main specs before closure. Invoke while an executing change has delta specs to merge into the main spec base, or when detecting spec drift across multiple changes.

Files · 1

View on GitHub

SKILL.md

1	# Spec Merger
2
3	Before the final `executing → closing` transition, delta specs (ADDED/MODIFIED/REMOVED/RENAMED) must be merged into the main spec base. Specs that aren't synced become lies. A change already in `closing` must not be routed to `spec-merger`.
4
5	## Execution-State Guard
6
7	Before `ssf sync` or any other write, run
8	`npx --yes --package spec-superflow@0.11.0 ssf state get <change-dir> state`.
9	Continue only when the persisted state is exactly `executing`. If it is
10	`closing` → STOP: "Closing is terminal. Do not route this change to spec-merger;
11	synchronization belongs before the final executing → closing transition." For
12	any other state, or if the state cannot be read → STOP and route through
13	`workflow-start`; do not perform side effects.
14
15	## Pre-Flight Checks
16
17	### Conflict Detection
18	Run `npx --yes --package spec-superflow@0.11.0 ssf sync <change-dir>`. If conflicts are detected (same requirement modified by multiple changes), present the conflict list to the user for resolution order.
19
20	## Sync Process
21
22	### Step 1: Identify Deltas
23	Each `specs/<capability>/spec.md` under the change folder contains delta operations under `## ADDED/MODIFIED/REMOVED/RENAMED Requirements`.
24
25	### Step 2: Apply by Operation
26
27	ADDED: Append to `specs/<capability>/spec.md`. Create the main spec if it doesn't exist. Insert before any REMOVED section.
28
29	MODIFIED: Match on `### Requirement: <name>`. Replace description and scenarios. Preserve original in a `### Previous version` subsection. Flag if requirement doesn't exist in main spec.
30
31	REMOVED: Move to `## Removed` section with deprecation note: reason, migration, and change name. Flag if requirement doesn't exist.
32
33	RENAMED: Match old name, change header to new name, add `_Renamed from <old> in <change>_`. Flag if new name collides with existing.
34
35	### Step 3: Conflict Detection
36	Before executing, detect:
37	- Same requirement modified by multiple unsynced changes → manual resolution
38	- RENAMED target collides with existing requirement → manual resolution
39	- MODIFIED/REMOVED targeting nonexistent requirements → flag
40
41	### Step 4: Execute Merge
42	Apply changes. Do NOT delete delta specs — they remain for traceability. After merge, validate: no duplicate requirement names, no orphaned references, REMOVED section clearly separated.
43
44	### Step 5: Report
45	Output sync report table: Capability, ADDED/MODIFIED/REMOVED/RENAMED counts, Status (✓/⚠). Summary with totals and unresolved conflicts.
46
47	## Guardrails
48
49	- Do not delete delta spec files (historical record)
50	- Do not auto-resolve conflicts across changes
51	- Do not merge specs for unverified changes
52	- Validate main spec consistency after each capability merge
53
54	## Post-Sync
55
56	1. Report results. If no conflicts → ready to archive. If conflicts → user resolves before archive.
57	2. Change folder (including deltas) remains for traceability.
58	3. Record that merging is complete so the `executing → closing` guard allows closure:
59	```bash
60	npx --yes --package spec-superflow@0.11.0 ssf state set <change-dir> spec_merged true
61	```
62	(If the change had no delta sections, still set `spec_merged true` — there was nothing to merge.)
63
64	## Exception Handling
65
66	- Parse failures: Report file and section. Do not attempt partial merges.
67	- No deltas: If change has no delta sections, report nothing to merge and exit cleanly.
68	- User interruption: On resume, check for merge conflict markers before proceeding.

People who liked this also viewed

6 picks

Type