Clarify archive sync for new specs by Jalendar10 · Pull Request #1271 · Fission-AI/OpenSpec

Jalendar10 · 2026-06-28T03:14:44Z

Summary

Closes #1264 by making archive workflow instructions explicitly handle delta specs whose target main spec does not exist yet.

Changes

Adds missing-main-spec guidance to both archive workflow skill and /opsx:archive command templates.
Clarifies that ADDED requirements still need sync and create a new main spec.
Clarifies MODIFIED/RENAMED as blocking for a new spec, and REMOVED as ignored with a warning.
Adds regression assertions and updates intentional template parity hashes.

Validation

./node_modules/.bin/vitest run test/core/templates/skill-templates-parity.test.ts
node build.js
./node_modules/.bin/eslint src/core/templates/workflows/archive-change.ts

Summary by CodeRabbit

Bug Fixes
- Improved archive workflow guidance when the corresponding main spec is missing.
- ADDED requirements now proceed as sync work to create a new main spec; MODIFIED/RENAMED requirements are treated as blocking errors.
- REMOVED requirements are ignored with a warning; sync is no longer skipped due to a missing target, and the workflow will stop when blocking errors are present (without offering “archive without syncing”).
Tests
- Updated template parity expectations and added assertions for the revised guidance.

coderabbitai · 2026-06-28T03:14:56Z

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: 374f5e49-5565-4869-a0fc-b72a2515374c

📥 Commits

Reviewing files that changed from the base of the PR and between 33227e5 and ea56dc5.

📒 Files selected for processing (2)

src/core/templates/workflows/archive-change.ts
test/core/templates/skill-templates-parity.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

src/core/templates/workflows/archive-change.ts
test/core/templates/skill-templates-parity.test.ts

📝 Walkthrough

Walkthrough

Two archive workflow template functions gain explicit guidance for delta specs when the corresponding main spec is missing. Parity test hashes are updated, and a new test asserts the added instruction strings are present.

Changes

Archive workflow missing main spec guidance

Layer / File(s)	Summary
Delta-spec guidance added to archive templates `src/core/templates/workflows/archive-change.ts`	Both archive template functions add a missing-main-spec branch that maps `ADDED` to sync work for a new main spec, `MODIFIED`/`RENAMED` to blocking errors, `REMOVED` to a warning-only ignore path, and keeps sync from being skipped solely because the target spec is absent.
Parity test hash updates and new content assertion `test/core/templates/skill-templates-parity.test.ts`	Expected hashes are refreshed for the affected template factories and generated skill content, and a new test checks that both template outputs include the missing-main-spec guidance strings.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

#1264: Directly matches the new archive prompt behavior for empty main spec directories and delta-spec handling.
#913: Shares the archive workflow sync-gating prompt path, including when /opsx-archive should offer or stop sync-related options.
#678: Covers the same archive template pair and prompt logic around delta-spec reconciliation.

Possibly related PRs

Fission-AI/OpenSpec#514: Updates the same archive template instruction flow and prompt options around delta-spec sync assessment.
Fission-AI/OpenSpec#452: Related archive workflow prompt changes for delta-spec and missing-main-spec handling.
Fission-AI/OpenSpec#632: Also updates archive-change skill/template instruction text for the delta-spec syncing flow.

Suggested reviewers

TabishB

🐇 The main spec was missing, the path felt new,
So the rabbit said, “Sync the ADDED through!”
MODIFIED pauses, RENAMED says stop,
REMOVED just waves from the edge of the crop.
Hops and hashes now line up just right.

🚥 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 is clear and matches the main change: clarifying archive sync behavior for new specs.
Linked Issues check	✅ Passed	The prompt updates and regression tests implement the missing-main-spec behavior requested in `#1264`.
Out of Scope Changes check	✅ Passed	The changes are scoped to archive workflow guidance and matching test baselines, with no unrelated additions.

✨ 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

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

Copilot

Pull request overview

Updates the archive-change workflow templates so agent-driven archive instructions explicitly handle delta specs whose target main spec does not yet exist (aligning guidance with the CLI behavior described in #1264).

Changes:

Extends the archive workflow template instructions with a missing-main-spec decision branch for ADDED/MODIFIED/RENAMED/REMOVED requirement ops.
Updates template parity hashes and adds a regression test asserting both the skill and /opsx:archive templates contain the new guidance.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
test/core/templates/skill-templates-parity.test.ts	Updates expected template hashes and adds regression assertions for missing-main-spec guidance (but currently has a backtick-matching bug in the new assertions).
src/core/templates/workflows/archive-change.ts	Adds explicit instructions for how to handle delta specs when the corresponding main spec is missing.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Jalendar10 · 2026-06-28T03:20:24Z

+      expect(content).toContain('If a corresponding main spec does not exist yet');
+      expect(content).toContain('ADDED` requirements as sync work that will create a new main spec');
+      expect(content).toContain('MODIFIED` or `RENAMED` requirements as blocking errors');
+      expect(content).toContain('Do not skip sync just because the target main spec is missing');


he new assertions for the archive templates have mismatched backtick quoting: they look for "ADDED"/"MODIFIED" (missing the leading backtick), but the templates include markdown code spans like "ADDED" and "MODIFIED". As written, this test will fail even when the templates are correct.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/templates/workflows/archive-change.ts`:
- Around line 67-72: The missing-main-spec handling in archive-change.ts still
allows the generic "Archive without syncing" flow to continue even when
`MODIFIED` or `RENAMED` requirements are marked as blocking errors. Update the
logic around the missing-main-spec analysis in the workflow template so that the
archive/skip path is explicitly disabled when those blocking deltas are present,
and only allow proceed-with-archive behavior for cases like `ADDED` or `REMOVED`
that are allowed by the rules. Use the existing missing-main-spec decision block
and any sync/archive gating branch in archive-change.ts to enforce this stop
condition.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5cd9e663-2d9b-42ff-9a6b-2a0938be16b0

📥 Commits

Reviewing files that changed from the base of the PR and between 737518b and 33227e5.

📒 Files selected for processing (2)

src/core/templates/workflows/archive-change.ts
test/core/templates/skill-templates-parity.test.ts

Propose a deterministic CLI backstop so a spec-driven change cannot archive while silently dropping the specs it declared. Root cause (confirmed): `openspec validate` runs validateChangeDeltaSpecs unconditionally and rejects a change with no deltas, but `openspec archive` gates the same check behind `if (hasDeltaSpecs)`, so a change with no specs/ skips validation and archives clean — the proposal's no-delta error is downgraded to a non-blocking warning. Fix: - Archive runs delta-spec validation unless --skip-specs (parity with validate); a no-delta change is blocked with CHANGE_NO_DELTAS. - instructions apply exits non-zero when blocked. - spec-driven apply.requires includes specs. - Archive skill prompt aligned with the new blocking behavior. Closes Fission-AI#1212, Fission-AI#1260, Fission-AI#1222, Fission-AI#1264, Fission-AI#799. Supersedes PRs Fission-AI#1250, Fission-AI#1271, Fission-AI#1241, Fission-AI#1233. References (out of scope) Fission-AI#1246, Fission-AI#1112, Fission-AI#1252. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Propose one deterministic completeness check, enforced in the validator and shared by `validate`, CI, and `archive`, so a spec-driven change cannot archive while silently dropping the specs it declared. Two silent failure modes, both closed: - Total drop: archive gated delta-spec validation behind `if (hasDeltaSpecs)`, so a change with no specs/ skipped the CHANGE_NO_DELTAS check that `validate` already enforces. Fix: validate unless --skip-specs (validate/archive parity). - Partial drop: nothing checked the proposal's declared capabilities against delivered delta specs. Fix: deterministic validateChangeCapabilityCoverage — every capability under `## Capabilities` must have specs/<id>/spec.md with a delta section. Parsing contract validated against all 93 in-repo proposals (found 7 real proposal/spec inconsistencies; zero false extractions). Plus earlier guardrails (incorporates Fission-AI#1250): apply exits non-zero when blocked; spec-driven apply.requires includes specs. Closes Fission-AI#1212, Fission-AI#1260, Fission-AI#1222, Fission-AI#1264, Fission-AI#799. Supersedes PRs Fission-AI#1250, Fission-AI#1271, Fission-AI#1241, Fission-AI#1233. References (out of scope) Fission-AI#1246, Fission-AI#1112, Fission-AI#1252. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Address the spec-driven silent-spec-drop family at its real root: one architectural fault — correctness-critical decisions live in agent prompts, not deterministic CLI logic — expressed at four layers. Fix, ordered by leverage: - Deterministic CLI gate: archive validates like `validate` unless --skip-specs, schema-aware (only when the schema graph has a `specs` artifact, per Fission-AI#997). Blocks total drop (CHANGE_NO_DELTAS), partial drop (new schema-aware capability-coverage rule), and format/mode-G (present non-delta spec → "No delta sections found"). - Loop fix: spec-driven apply.requires [specs, tasks] + propose/ff walk the full schema build order (incorporates Fission-AI#1250; Fission-AI#1250's reviewer explicitly deferred this archive guard). - Keystone: the archive skill calls `openspec archive` CLI instead of agent-judged sync + raw mv, so the CLI guarantees are reachable by agents (Fission-AI#656, Fission-AI#863). - Recovery audit for already-archived drift; delta-vs-full-spec clarity. Closes Fission-AI#1212 Fission-AI#1260 Fission-AI#1222 Fission-AI#1264 Fission-AI#799 Fission-AI#656 Fission-AI#863 Fission-AI#164. Supersedes PRs Fission-AI#1250 Fission-AI#1271 Fission-AI#1241 Fission-AI#1233. Addresses-in-part Fission-AI#997 Fission-AI#194 Fission-AI#426 Fission-AI#911. Out of scope Fission-AI#1246 Fission-AI#1112 Fission-AI#1252 Fission-AI#913 Fission-AI#1120. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Address the spec-driven silent-spec-drop family at its root: one fault — correctness-critical decisions live in agent prompts, not deterministic CLI logic — expressed at four layers, fixed at the most deterministic point for each. - CLI gate (guarantee): archive validates like `validate` unless --skip-specs, schema-aware (only when the schema graph produces delta specs, per Fission-AI#997). Blocks total (CHANGE_NO_DELTAS), partial (new capability-coverage rule), and format/mode-G ("No delta sections"). - Loop fix: spec-driven apply.requires [specs, tasks] + propose/ff create every artifact transitively required by applyRequires (incorporates Fission-AI#1250; its reviewer deferred this archive guard). - Keystone: archive skill calls `openspec archive` instead of agent-judged sync + raw mv (Fission-AI#656, Fission-AI#863); also removes the sync-specs skill dependency (Fission-AI#913). - Recovery audit; delta-vs-full-spec clarity. Verified against current main (rebuilt CLI): bug reproduces; archive --json + ArchiveBlockedError exist; Fission-AI#1250 not merged; Fission-AI#194/Fission-AI#1268 closed. Closes Fission-AI#1212 Fission-AI#1260 Fission-AI#1222 Fission-AI#1264 Fission-AI#799 Fission-AI#656 Fission-AI#863 Fission-AI#913. Supersedes PRs Fission-AI#1250 Fission-AI#1271 Fission-AI#1241 Fission-AI#1233. Addresses Fission-AI#997 Fission-AI#164 Fission-AI#426 Fission-AI#911. Out of scope Fission-AI#1246 Fission-AI#1112 Fission-AI#1252 Fission-AI#1120 Fission-AI#827 Fission-AI#1265. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Address the spec-driven silent-spec-drop family at its root: one fault — correctness-critical decisions live in agent prompts, not deterministic CLI logic — fixed at the most deterministic point for each of four layers. - CLI gate (guarantee): ONE shared schema-aware predicate (schemaProducesDeltaSpecs) gates the delta requirement in BOTH `validate` and `archive`, so they agree by construction and proposal-only schemas pass both while spec-driven-with-no-specs fails both (Fission-AI#997). Blocks total (CHANGE_NO_DELTAS), partial (capability coverage), and format/mode-G ("No delta sections"). `--yes` never bypasses the gate. - Loop fix: spec-driven apply.requires [specs, tasks] + propose/ff create every artifact transitively required by applyRequires (incorporates Fission-AI#1250). - Keystone: archive skill calls `openspec archive` instead of agent-judged sync + raw mv (Fission-AI#656, Fission-AI#863); removes the sync-specs skill dependency (Fission-AI#913). - Recovery audit; delta-vs-full-spec clarity. Addresses review feedback (alfred-openspec: validate needs the same schema-aware gate as archive; coderabbit: document --yes does not bypass, fenced-block tags, clarify partial detection, fail-open/--yes tests). Closes Fission-AI#1212 Fission-AI#1260 Fission-AI#1222 Fission-AI#1264 Fission-AI#799 Fission-AI#656 Fission-AI#863 Fission-AI#913. Supersedes PRs Fission-AI#1250 Fission-AI#1271 Fission-AI#1241 Fission-AI#1233. Addresses Fission-AI#997 Fission-AI#164 Fission-AI#426 Fission-AI#911. Out of scope Fission-AI#1246 Fission-AI#1112 Fission-AI#1252 Fission-AI#1120 Fission-AI#827 Fission-AI#1265. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Address the spec-driven silent-spec-drop family at its root: one fault — correctness-critical decisions live in agent prompts, not deterministic CLI logic — fixed at the most deterministic point for each of four layers. CLI gate (guarantee): one shared schema-aware predicate (schemaProducesDeltaSpecs, memoized per run) gates the delta requirement in BOTH validate and archive; blocks total/partial/format drops; proposal-only schemas pass both (Fission-AI#997). Loop: spec-driven apply.requires [specs, tasks] (apply gate is non-transitive — design stays optional). Keystone: ALL archive templates (skill + command + bulk) call `openspec archive` instead of agent-judged sync + raw mv (Fission-AI#656, Fission-AI#863); never --skip-specs/--no-validate. Recovery: specced archived-drift audit (forward-only). Clarity: delta-vs-full spec + stricter Capabilities-section contract. Incorporates three review rounds (alfred-openspec, CodeRabbit) and an internal adversarial pass: validate schema-aware parity, --yes doesn't bypass, all archive surfaces reworked, non-transitive apply gate, schema-resolution memoization, capability deletion/rename + bold-label/non-kebab handling, proposal-only fixture for Fission-AI#997 tests. Closes Fission-AI#1212 Fission-AI#1260 Fission-AI#1222 Fission-AI#1264 Fission-AI#799 Fission-AI#656 Fission-AI#863 Fission-AI#913. Supersedes PRs Fission-AI#1250 Fission-AI#1271 Fission-AI#1241 Fission-AI#1233. Addresses Fission-AI#997 Fission-AI#164 Fission-AI#426 Fission-AI#911. Out of scope Fission-AI#1246 Fission-AI#1112 Fission-AI#1252 (complementary; land first) Fission-AI#1120 Fission-AI#827 Fission-AI#1265. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Deterministic, CLI-enforced prevention of silent spec drop in the spec-driven workflow, addressing one root fault (correctness decisions in agent prompts) across four layers: schema-aware delta gate shared by validate+archive (Fission-AI#997), the non-transitive apply-gate loop fix (incorporates Fission-AI#1250), the keystone (all archive templates call `openspec archive` — Fission-AI#656/Fission-AI#863), and a specced archived-drift audit. Hardened across three review rounds (alfred-openspec, CodeRabbit), an internal adversarial pass, and an open-PR coordination scan: - reconciles Fission-AI#977 (allow-specless) via the schema-aware gate + --skip-specs, deliberately not allowing silent specless archives under spec-driven; - coordinates with Fission-AI#902 (propose/ff spec discovery), the unify-template-generation-pipeline manifest, add-change-stacking-awareness (provides/touches markers + overlap warnings), and add-artifact- regeneration-support (complementary staleness); - rebases onto approved Fission-AI#1186/Fission-AI#1151/Fission-AI#1153/Fission-AI#1252; Fission-AI#1252 is a prerequisite. Closes Fission-AI#1212 Fission-AI#1260 Fission-AI#1222 Fission-AI#1264 Fission-AI#799 Fission-AI#656 Fission-AI#863 Fission-AI#913. Supersedes PRs Fission-AI#1250 Fission-AI#1271 Fission-AI#1241 Fission-AI#1233. Addresses Fission-AI#997 Fission-AI#977 Fission-AI#902 Fission-AI#164 Fission-AI#426 Fission-AI#911. Out of scope Fission-AI#1246 Fission-AI#1112 Fission-AI#1252(prereq) Fission-AI#1120 Fission-AI#827 Fission-AI#1265. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat: clarify archive sync for new specs

33227e5

Jalendar10 requested a review from TabishB as a code owner June 28, 2026 03:14

Copilot AI review requested due to automatic review settings June 28, 2026 03:14

Copilot started reviewing on behalf of Jalendar10 June 28, 2026 03:15 View session

Copilot AI reviewed Jun 28, 2026

View reviewed changes

coderabbitai Bot reviewed Jun 28, 2026

View reviewed changes

Comment thread src/core/templates/workflows/archive-change.ts

fix: block archive on invalid missing-spec deltas

ea56dc5

clay-good mentioned this pull request Jun 29, 2026

Propose: prevent silent spec drop — deterministic, CLI-enforced, end-to-end #1277

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Clarify archive sync for new specs#1271

Clarify archive sync for new specs#1271
Jalendar10 wants to merge 2 commits into
Fission-AI:mainfrom
Jalendar10:codex/archive-empty-main-spec-guidance

Jalendar10 commented Jun 28, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 28, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Uh oh!

Jalendar10 Jun 28, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Jalendar10 commented Jun 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Validation

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Jalendar10 Jun 28, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Jalendar10 commented Jun 28, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 28, 2026 •

edited

Loading