fix(archive): preserve requirement order when renaming

[Marzx13]

Risk: low-medium. Archive output order changes only when a requirement is successfully renamed. Validation, collisions, transaction boundaries, and other operation ordering are unchanged.

What was wrong

Renaming deleted the requirement's old map key and inserted the new key. Recomposition then treated the renamed block like a new addition and moved it to the end.

For example, renaming Beta in Alpha, Beta, Gamma produced Alpha, Gamma, Beta Prime, creating unrelated archive diff churn.

What changes

A successful rename now updates a parallel positional key for the parsed requirement's source slot. The original parsed block remains available for loss attribution, the same slot follows multiple and chained renames, and genuinely added requirements still append as before.

Why it's safe

• Existing normalized-name lookup, collision, and already-applied checks are unchanged.
• The change is in-memory until the existing transactional archive write path succeeds.
• Rename-plus-modify still resolves through the renamed key.
• The original parsed block remains available to attribute absorbed-tail warnings correctly after rename-plus-modify.
• Rename-only still carries the complete raw block, including absorbed authored tails.
• No other parser, validation, formatting, or operation-precedence behavior changes.

Proof

• 12-case release/main/candidate matrix: first/middle/last, multiple, chained, rename-plus-modify, case/whitespace, foreign-tail, CRLF, already-applied, and collision controls.
• Focused archive and salvage suites: 205 passed, 24 skipped.
• Full suite: 4,012 passed, 67 skipped.
• Build, TypeScript, lint, and git diff --check pass on Windows.

Compatibility note: requirement order is not normative, but consumers that relied on renamed requirements moving to the tail will now see stable source order. This PR does not define semantic ordering or change general serialization policy.

A patch changeset records the user-visible archive ordering fix.

🤖 Generated with Codex (GPT-5).

Summary by CodeRabbit

• Bug Fixes

  • Requirement renames now preserve the original block order, including chained and multiple renames.
  • Rename-and-modify operations correctly handle removed trailing content and warning attribution.
  • Rename collisions are detected safely without altering or archiving affected specifications.
  • Archive operations preserve trailing content and source-order relationships.

• Tests

  • Added coverage for rename ordering, collisions, chained renames, modifications, re-additions, and warning behavior.

[openspec-cloud]

Fork pull request not scanned

Fork pull requests are not scanned. Open the branch in this repository, then create a new pull request.
View the OpenSpec Cloud check · A same-repository pull request is required.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 419512ae-6c86-48ca-a8e5-caacdbe3e095

📥 Commits

Reviewing files that changed from the base of the PR and between 672051b and 91cc70e.

📒 Files selected for processing (1)

• .changeset/calm-otters-order.md

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

Requirement recomposition now preserves original block positions across direct and chained renames. Foreign-tail warnings use the original block’s replacement. Tests cover ordering, collisions, trailing content, and rename-plus-modify behavior.

Changes

Requirement rename recomposition

Layer / File(s)	Summary
Preserve requirement order during recomposition src/core/specs-apply.ts	The apply logic tracks original positions through direct and chained renames. Recomposition uses positional keys and direct replacement selection for foreign-tail checks.
Validate archive and salvage rename behavior test/core/archive.test.ts, test/core/specs-apply.salvage.test.ts, .changeset/calm-otters-order.md	Tests cover rename ordering, chained and modified renames, trailing content, collision rollback, dropped content, counts, and warning attribution. The changeset records the ordering behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 91cc7

This localized change preserves requirement order during successful renames without altering validation or transaction behavior; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 3 files. (1 skipped: 1 unsupported.)
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving requirement order during archive renames.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[clay-good]

Status: LGTM.

What was wrong: successful RENAMED operations changed Map insertion order, so recomposition moved renamed requirements to the end and created unrelated archive diff churn.

How it was fixed: the merge now keeps lookup keys separate from positional keys, updates the source slot through direct and chained renames, and preserves the original block for foreign-tail loss attribution. Adds still append; collision and transaction behavior are unchanged.

Replication / proof: the focused archive and salvage suites pass (229/229), including first/middle/last, multiple and chained renames, rename-plus-modify, re-add, foreign-tail attribution, and collision rollback. Build and lint pass locally. The exact head commit is based on current main, is mergeable, and all required GitHub checks pass across Linux, macOS, and Windows.

Notes / nits: no blocking findings. No branch update or extra patch was needed; current main is already the PR base.