Fix greenfield archive sync guidance (#1222)

[zhangsan582]

Commit

Commit: c22fa5e

Message: Fix greenfield archive sync guidance (#1222)

The commit only contains:

• src/core/templates/workflows/archive-change.ts

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

Summary

Fixed an issue in #1222 where the agent might skip spec sync during the first archive of a greenfield project.

Previously, the archive guidance did not explicitly mark missing main specs as needing sync, and the agent might directly move changes into the archive.

This adds/changes/fixes archive workflow guidance so missing openspec/specs//spec.md is treated as sync-needed and should be created from delta specs before archive.

Changes

• Code: Enhanced the sync assessment documentation for archive skill and opsx archive command.

• Testing: Added a regression assertion for missing main specs; updated template hashes.

• OpenSpec: Local analysis files exist but have not been committed.

Verification

• pnpm exec vitest run test/core/templates/skill-templates-parity.test.ts

• pnpm exec vitest run test/core/archive.test.ts

• pnpm run lint

• pnpm test

• pnpm run build

Summary by CodeRabbit

Bug Fixes

• Greenfield archive guidance now treats missing main specs as sync-needed, preventing first-change specs from being lost during agent-driven archive.

Documentation

• Updated generated workflow guidance text. OpenSpec process files were not committed.

Tests

• Added template coverage for greenfield archive sync guidance.

Summary by CodeRabbit

• Bug Fixes

  • Fixed archive workflow for greenfield projects to properly handle missing main specs: the system now treats missing specs as requiring sync and creates the main spec before archiving, ensuring a source-of-truth spec always exists.

• Documentation

  • Added proposal and specification documentation clarifying the archive workflow behavior for projects with delta specs.

[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

Run ID: 91e31855-2791-417b-99a1-64d0608671fc

📥 Commits

Reviewing files that changed from the base of the PR and between 1b06fdd and 896ff2b.

📒 Files selected for processing (5)

• openspec/changes/fix-greenfield-archive-sync/proposal.md
• openspec/changes/fix-greenfield-archive-sync/specs/opsx-archive-skill/spec.md
• openspec/changes/fix-greenfield-archive-sync/tasks.md
• src/core/templates/workflows/archive-change.ts
• test/core/templates/skill-templates-parity.test.ts

---

📝 Walkthrough

Walkthrough

Adds a proposal, spec update, template guidance, and tests so archive workflows treat missing openspec/specs/<capability>/spec.md files as a sync-needed state when delta specs exist, requiring spec creation before archiving.

Changes

Archive sync guidance

Layer / File(s)	Summary
Define greenfield archive sync behavior openspec/changes/fix-greenfield-archive-sync/proposal.md, openspec/changes/fix-greenfield-archive-sync/specs/opsx-archive-skill/spec.md, openspec/changes/fix-greenfield-archive-sync/tasks.md	Adds the proposal, OPSX archive skill requirement, and task checklist for the case where delta specs exist but the main spec file is missing.
Apply guidance in templates and tests src/core/templates/workflows/archive-change.ts, test/core/templates/skill-templates-parity.test.ts	Updates both archive template variants to treat missing main specs as changes needed, and updates parity hashes plus assertions covering the new wording.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Fission-AI/OpenSpec#452: Updates the same archive template logic around missing main specs and sync-needed guidance.
• Fission-AI/OpenSpec#404: Handles the same missing-main-spec archive scenario in archive processing logic.
• Fission-AI/OpenSpec#451: Touches the same OPSX archive skill and command template area updated here.

Suggested reviewers

• TabishB

Poem

🐇 I found a spec that wasn't there,
yet delta tracks still filled the air.
So before the archive door swings tight,
we sync the missing page just right.
Hop, hash, and test—now all is fair.

🚥 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%.	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 and concisely summarizes the main change: fixing greenfield archive sync guidance, with a direct reference to the related issue #1222.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

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

Warning

⚠️ This pull request shows signs of AI-generated slop (description_diff_mismatch). It has been flagged by CodeRabbit slop detection and should be reviewed carefully.