#1890·OpenSpec

Harden archive workflow against incomplete or invalid spec synchronization

Author: Ajithkumar08Created Sep 14, 2026Updated Sep 14, 2026

Problem

The archive workflow can incorrectly archive a change when the synchronization between the change and the main specification does not fully represent the requested change.

The archive operation should only succeed when the change has been completely and correctly synchronized into the main spec. In particular, the workflow needs to distinguish between:

  • a successful sync where the expected main-spec changes were applied;
  • a sync that was blocked or stopped and therefore left the main spec unchanged or partially changed;
  • a sync that produces structurally valid output but does not actually remove/rename the expected content;
  • an archive operation that would move the change even though the source-of-truth specification is not in the expected final state.

Required behavior

The archive workflow should:

  1. Run sync before archiving

    • Synchronize the change into the main specification before moving the change to the archive.
    • Do not archive based solely on the presence or structure of generated output.
  2. Fail on blocked sync

    • If sync reports that an operation is blocked, stopped, or cannot be completed, the archive operation must fail.
    • An unchanged main spec must not be interpreted as proof that synchronization succeeded.
    • The original changeRoot must remain in place.
  3. Validate removals

    • When a change removes requirements from the main spec, verify that the expected requirements are actually absent after sync.
    • Do not consider the archive successful if the removed requirement remains in the active spec.
  4. Validate renames

    • When a change renames a capability, verify that the old capability/section is no longer present and that the new capability is present as expected.
    • Prevent the archive operation from succeeding when only part of a rename has been applied.
  5. Validate semantic content, not only file equality

    • Archive validation should verify the actual specification state rather than relying only on whether generated files or expected text happen to match.
    • Validation should cover the relevant capability, purpose, requirements, scenarios, and other affected content.
  6. Handle final-requirement retirement safely

    • If removing the last requirement would require retiring a capability but the sync process blocks that retirement, archive must fail.
    • The change must not be moved to archive/ until the resulting main spec represents the intended state.
  7. Keep all archive workflow implementations consistent

    • Apply the same safeguards to every archive workflow template/variant affected by the change.
    • The generated skills/openspec-archive-change/SKILL.md must remain consistent with the source templates so that future generation does not reintroduce weaker behavior.
  8. Preserve the change on failure

    • Any failed validation or blocked synchronization must leave the change available for correction.
    • The archive move should be the final operation, performed only after every required validation succeeds.

Regression coverage

Add regression tests covering the complete archive lifecycle, including:

  • successful synchronization followed by successful archive;
  • removal of an existing requirement;
  • removal of the final requirement from a capability;
  • blocked capability retirement;
  • capability rename;
  • partially applied rename;
  • stale/unchanged main spec after a reported sync stop;
  • validation failure after sync;
  • ensuring changeRoot is not moved when any validation fails;
  • consistency between the archive workflow variants and the generated archive skill.

Acceptance criteria

  • Archive succeeds only after sync completes successfully.
  • A blocked/stopped sync can never result in an archived change.
  • Removed requirements are verified to be absent before archive.
  • Renamed capabilities are verified to have the expected old/new state.
  • Final-requirement retirement is handled safely when sync cannot complete it.
  • Archive validation checks semantic specification state rather than relying only on superficial file/output equality.
  • Failed validation leaves changeRoot untouched.
  • All affected archive workflow templates implement the same safeguards.
  • The generated skills/openspec-archive-change/SKILL.md contains the same behavior as the source templates.
  • Regression tests cover both successful and failure paths.