Fix OpenSpec Archive Structure in Archive Skill

[Ajithkumar08]

Reason for Change:
Previous archiving actions using AI resulted in inconsistent spec formatting, outdated delta headers and missing purpose summaries. This update standardizes the output format to match expected OpenSpec conventions, ensuring clean, predictable, and parseable specifications across all archived changes.

Overview
Addresses maintainer review feedback on #1742 by moving workflow customization out of generated artifacts and into source templates, preserving existing ## Purpose semantics, and aligning post-sync main spec validation with canonical OpenSpec contracts.

Key Changes

• Source-of-Truth Fix: Updated the workflow source template in src/core/templates/workflows/archive-change.ts instead of directly editing SKILL.md. Regenerated skills/openspec-archive-change/SKILL.md using pnpm generate:skills to restore cross-platform template parity.
• Preserve Authored Purpose: Updated the Purpose handling contract during archive sync:
  For existing main specs, ## Purpose is authoritative and remains completely untouched.
  For new main specs, the delta ## Purpose is copied verbatim (issuing a warning only if below expected length), preventing accidental AI rewrites of authored prose.
• Canonical Sync Alignment: Reused the standard requirement formatting and delta-header removal rules defined in sync-specs.ts rather than introducing a second mutation rule set in the archive skill.
• Test Snapshot Updates: Updated EXPECTED_GENERATED_SKILL_CONTENT_HASHES in test/core/templates/skill-templates-parity.test.ts to reflect the updated skill generation snapshot.

Verification

• Ran pnpm generate:skills to verify deterministic skill markdown generation.
• Verified pnpm test test/core/templates/skillssh-parity.test.ts and pnpm test test/core/templates/ pass cleanly.

Summary by CodeRabbit

• Bug Fixes

  • Archive workflows now verify that synchronized specifications follow the required title, purpose, requirements, and scenario structure.
  • Existing purpose sections are preserved, while new specifications copy provided purpose content or use the standard fallback when needed.
  • Synchronization now rejects delta-specific section headers and ensures requirements and scenarios use a unified format.

• Tests

  • Updated validation checks to cover the enhanced archive workflow guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 5302d620-44eb-401f-b2cd-e9b1187ff540

📥 Commits

Reviewing files that changed from the base of the PR and between e9269c5 and 0ec18a1.

📒 Files selected for processing (1)

• test/core/templates/skill-templates-parity.test.ts

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

---

📝 Walkthrough

Walkthrough

The archive workflow now verifies main-spec structure after synchronization. The skill and command templates contain the same verification rules. Template parity tests update expected hashes and assert the new contract.

Changes

Archive sync verification

Layer / File(s)	Summary
Post-sync structure contract skills/openspec-archive-change/SKILL.md, src/core/templates/workflows/archive-change.ts, test/core/templates/skill-templates-parity.test.ts	The archive workflow checks specification titles, purpose-section handling, removal of all four delta headers, and unified requirement/scenario headings. Both templates receive the same instructions. Parity hashes and semantic assertions reflect the updated outputs.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 0ec18

Archive synchronization now verifies and preserves the intended main-spec structure, including Purpose and Requirements formatting. The generated skill and template parity coverage were updated consistently, with no current merge-blocking risk identified.

Suggested reviewers: clay-good, alfred-openspec

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: fixing the OpenSpec archive structure in the archive skill. It is concise and directly related to the changeset.
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.

• Fix all pre-merge checks with AI

✨ 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.}

[alfred-openspec]

Requesting changes at 6974b14.

The source/generated parity and Purpose ownership issues from #1742 are fixed. Two remaining blockers:

1. The new delta-header check omits ## RENAMED Requirements. That header is part of the canonical sync delta format, so a leaked rename section could pass this verification even though the PR claims all delta-only headers are excluded. Cover ADDED, MODIFIED, REMOVED, and RENAMED, ideally with the exact canonical headings rather than partial prefixes.

2. The only test change updates golden hashes. Those prove that text changed and generated artifacts match, not that this behavior contract stays intact. Add semantic assertions for both archive surfaces in the existing gates-the-archive-on-a-completed-spec-sync test: existing Purpose stays untouched; a new Purpose is copied verbatim or gets the TBD fallback; the main-spec title, Requirements, Requirement, and Scenario structure is required; and every delta header, including RENAMED, is rejected.

I approved the hosted workflows, and CI is running. Re-request review once these two points land.

[Ajithkumar08]

Thanks @alfred-openspec for review. I had addressed the review comments and changes were pushed.

[alfred-openspec]

Approved at e9269c5. Both requested blockers are resolved: the archive contract now rejects all four canonical delta headers, including RENAMED, and the parity test asserts the structure and Purpose rules for both archive surfaces. The focused test and build pass locally. The branch currently conflicts with main, so please update it and make sure the newly approved CI and Security runs finish green.

[alfred-openspec]

Approved at 0ec18a1. The merge from main preserved the archive changes and refreshed the unrelated parity hashes. Both prior blockers remain resolved: all four canonical delta headers are rejected, and both archive surfaces are pinned to the Purpose and main-spec structure contract. A frozen install, build, all 26 focused parity tests, and the full hosted CI/Security matrix pass. The canonical docs-lab skill contract remains accurate because this tightens internal post-sync validation without changing the documented arguments, outputs, or response.