Exploration: should OpenSpec stop merging specs deterministically in `openspec archive`?

[TabishB]

This is an open question, not a proposal ready to implement. Please don't open a PR from this issue yet. It needs more careful thought and discussion first, and we'd like to hear from the community.

The question

openspec archive merges delta specs into main specs by matching requirement headers. We're starting to think a deterministic merge isn't realistic to support well, and that the merge belongs with an agent instead. We don't yet know what should replace it, or what that would break.

What we're seeing

• The merge matches on names. When an agent edits a delta, its header can drift from the base spec and the match breaks. We ran into this before (feat(instructions): add runtime context and operation guidance #1062: "heading matching was too brittle").
• Some failures show up late. A bad MODIFIED header passes validate and only fails at archive, sometimes weeks later (validate: MODIFIED/REMOVED/RENAMED-from headers that don't exist in base spec aren't caught until archive (proposal: opt-in cross-change MODIFIED) #1112).
• Some failures are silent. Two changes that modified the same requirement lost scenarios (Archiving two changes that MODIFY the same requirement silently drops scenarios (distinct from #1112) #1246). A renamed scenario reads as a deleted one (Cannot rename a scenario — MODIFIED reads a rename as a dropped scenario and blocks archive #1697).
• The fixes keep coming. Since June, the merge code (archive.ts, specs-apply.ts, requirement-blocks.ts) has had 46 fix commits. For example, parser grammar (REMOVED and RENAMED entries written with * or + bullets are silently ignored #1799, Repeated delta section headers silently discard requirements #1801, A requirement written outside a delta section is dropped with no diagnostic #1803, Malformed RENAMED pairs silently skip a rename, or rename the wrong requirement #1805, show --json --deltas-only reports an invented MODIFIED for a bullet-form REMOVED, while archive deletes the requirement #1855, A REMOVED heading with a CommonMark closing # run is skipped, with a false "already removed" warning #1859, ADDED and RENAMED accept a name that differs only in case or spacing, leaving two copies of one requirement #1863, A delta at specs/<capability>.md is green-lit by status/apply, rejected by validate, then archived without being merged #1869) and lost formatting (archive: rebuilt specs end with an extra blank line at EOF #1527, openspec archive does not preserve blank lines around ## Requirements in the target spec #1625, archive rewrites the inside of fenced code blocks #1797, archive: define blank-line normalization policy for fenced code #1711, archive: applying a delta rewrites a CRLF spec to LF, turning a one-requirement change into a whole-file diff #1935, Feature: preserve specodelic frontmatter and four-layer tables when openspec archive deploys a delta #2017).
• The skills already work another way. /opsx:archive and /opsx:bulk-archive have the agent do the merge, then move the folder. So there are two merge paths, and users notice the difference (question: why achive skill or command relies on llm to manually merge specs why it does not use openspec archive cli command? #656, AI commands and skills for /opsx:archive do not invoke openspec archive CLI, unlike official docs and tutorials #863).

Directions we're thinking about

None of these are decided. Each one has trade-offs we haven't worked through.

1. Agent merges, CLI checks. Drop the deterministic merge. The agent updates the specs, and the CLI keeps checks that must hold. For example: specs parse, no leftover delta sections, tasks are done. Close to Proposal: prepare → agent work → validate → confirm → finalize flow for archive #1460.
2. Sync as you go, no archive step. Spec updates become part of the task list. Each task group updates the specs it implemented, and a final task checks that everything was updated. Specs land in the same PR as the code, so there's no separate archive PR. See Exploration: OpenSpec without archive #1968, and feat(cli): archive a completed change without a separate step #1831 for a related angle.
3. Keep the deterministic merge, fix what it matches on. For example, stable requirement IDs instead of names. This is the main option that keeps openspec archive as it is.

Open questions

1. What breaks for people who run openspec archive from CI or scripts?
2. If the CLI no longer merges, what can it still guarantee? Any "specs are in sync" check still has to match requirements somehow.
3. How does this work with several changes in progress at once, or specs in a separate repo?
4. What happens to bulk archive, and to hooks that run around archive (Feat : Add Extensible Hook Capability to OpenSpec Archive Operation #682, Feature Request: Support on_archive (post-archive hooks) in schema for custom artifact moves/copies #704, Add optional lifecycle hooks for sync and archive #1910)?
5. Should the command be removed, kept as a plain "move to archive" step, or kept as it is?

How you can help

• Tell us how you archive today, and whether the CLI merge has worked for you or against you.
• Share workflows where removing it would hurt.
• Suggest directions we've missed.

Related

• Direction: Exploration: OpenSpec without archive #1968, Proposal: prepare → agent work → validate → confirm → finalize flow for archive #1460, feat(instructions): add runtime context and operation guidance #1062, feat(cli): archive a completed change without a separate step #1831, Proposal: lifecycle: status — record change state as data, not directory position (experimental) #1683, feat(sync): fold delta specs without archiving the change #1813
• Failures: validate: MODIFIED/REMOVED/RENAMED-from headers that don't exist in base spec aren't caught until archive (proposal: opt-in cross-change MODIFIED) #1112, Archiving two changes that MODIFY the same requirement silently drops scenarios (distinct from #1112) #1246, Cannot rename a scenario — MODIFIED reads a rename as a dropped scenario and blocks archive #1697, feat(validator): detect stray delta headers that silently truncate main specs #954, Feature: preserve specodelic frontmatter and four-layer tables when openspec archive deploys a delta #2017, and the parser and formatting issues above
• Guardrails: archive --yes proceeds on self-reported task status — should archive be able to require evidence? #1652, archive: --yes skips the incomplete-task stop, and the refusal tells callers to rerun with --yes #2006, Harden archive workflow against incomplete or invalid spec synchronization #1890
• Hooks: Feat : Add Extensible Hook Capability to OpenSpec Archive Operation #682, Feature Request: Support on_archive (post-archive hooks) in schema for custom artifact moves/copies #704, Add optional lifecycle hooks for sync and archive #1910, Proposal: preserve additional artifacts other than specs during sync/archive #1706
• Parallel changes: Overlap between open changes is invisible until one archives (parallel-merge plan, Phase 1) #1669, Pre-archive drift and overlap checking for parallel changes: working tool, offer to contribute #1387, Feedback: Stores + git worktrees: per-checkout resolution, decoupled specs/changes roots, and archive locking #1714

[TimZander]

Thanks for opening this up. Here's one data point, from a small production site that moved to
OpenSpec 1.14 a few days ago. The whole app is regenerated from the specs, so the main specs
have to stay exactly right.

How we archive (Q1). One PR carries a change's deltas plus the code. After that PR
merges, a separate PR does nothing except run openspec archive <name> --yes (several
changes in name order). Archiving inside the change's own PR doesn't scale: parallel changes
conflict in specs/. Archiving later by hand gets forgotten.

To make that archive PR safe to merge without review, CI re-runs openspec archive on the
base and checks the PR is exactly that output, plus a few more conditions. This is where
the deterministic merge earns its keep for us. It makes the archive step verifiable,
which matters more to us than making it automatic. If an agent did the merge, we'd lose that
oracle and have to review every archive by hand.

What the CLI could still guarantee (Q2), and parallel changes (Q3). The silent overwrite
you describe is the case we worried about most. Change B, written against the old text of a
requirement, archives after change A and replaces A's edit. We guard against it with
base fingerprints, essentially Phase 0 of your
parallel delta plan:

• each change stores a SHA-256 of every requirement block it modifies, removes or renames,
  as the block read when the delta was written (null for ADDED). Blocks are canonicalised
  first: line endings, trailing whitespace, runs of blank lines;
• a PR check fails if a change's fingerprints are already stale, while the author can
  still fix the delta;
• the archive check compares fingerprints before archiving each change, so both cases are
  caught: two changes active at once, and B started before A was archived.

It needs no git history (squash merges and rebases don't matter), and it behaves the same
on GitHub and Azure DevOps. Whatever happens to the merge, the CLI could still own this
guarantee: "this delta was written against the requirement as it is now".

Other sharp edges we hit on 1.14.0, in case they're useful:

• archiving a change that creates a capability writes a placeholder Purpose, which then
  fails validate --strict, unless the delta has a ## Purpose;
• archive --yes archives with open tasks;
• archiving several changes in different orders gives a different requirement order;
• validate --specs doesn't check SHALL/MUST in main specs (only in deltas);
• a change folder named -y is parsed as an option.

On Q5 and the three directions, for what it's worth:

• we'd keep a deterministic merge, anchored on stable IDs (direction 3), and add
  fingerprints;
• we already prefix every requirement name with a permanent ID (NAV-5 …), which in
  practice avoids most header drift;
• an agent-performed merge (direction 1) would be fine as a helper for resolving a
  fingerprint conflict. We'd still want the CLI to be the one that can re-run and check the
  result.

We plan to run this on a second, larger project. If it holds up, we'd be glad to contribute
the fingerprint piece, coordinating with #1387 (concord), which detects the same drift from
git history.