Skip to content

Fix archive guidance for greenfield spec sync#1233

Closed
hutiefang76 wants to merge 1 commit into
Fission-AI:mainfrom
hutiefang76:codex/fix-archive-greenfield-spec-sync
Closed

Fix archive guidance for greenfield spec sync#1233
hutiefang76 wants to merge 1 commit into
Fission-AI:mainfrom
hutiefang76:codex/fix-archive-greenfield-spec-sync

Conversation

@hutiefang76

@hutiefang76 hutiefang76 commented Jun 21, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown

Summary

  • Clarify archive workflow instructions so missing main specs are treated as unsynced greenfield capabilities
  • Tell archive skill and /opsx:archive command to create a new main spec from ADDED requirements during sync
  • Add template coverage to prevent regressions

Fixes #1222.

Tests

  • pnpm vitest run test/core/templates/skill-templates-parity.test.ts test/core/archive.test.ts
  • pnpm run build
  • pnpm run lint
  • pnpm test

Summary by CodeRabbit

  • Bug Fixes

    • Improved archive workflow guidance when delta specs exist but the corresponding main spec is missing—now treated as a greenfield capability and instructed to create a new main spec during sync, avoiding “already synced”/skip behavior.

  • Tests

    • Updated parity-hash expectations and added a test to verify both the generated archive skill and the opsx archive command template include the missing-main-spec handling messaging.

@hutiefang76
hutiefang76 requested a review from TabishB as a code owner June 21, 2026 19:11
@coderabbitai

coderabbitai Bot commented Jun 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review Change Stack

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: fb44083e-df06-416b-8828-4794c6fd5eda

📥 Commits

Reviewing files that changed from the base of the PR and between 4cc6fe6 and fa770ea.

📒 Files selected for processing (1)
  • src/core/templates/workflows/archive-change.ts
💤 Files with no reviewable changes (1)
  • src/core/templates/workflows/archive-change.ts
📝 Walkthrough

Walkthrough

Instruction text in the archive workflow templates now treats a missing openspec/specs/<capability>/spec.md as an unsynced greenfield case that should create a new main spec from ADDED requirements. Matching parity hashes and test assertions were updated.

Changes

Greenfield main spec handling in archive workflow

Layer / File(s) Summary
Archive template greenfield instructions
src/core/templates/workflows/archive-change.ts		 Updates the delta-spec sync assessment text in both archive workflow templates so a missing main spec is handled as an unsynced greenfield capability and a new main spec is created from ADDED requirements.
Parity hash updates and greenfield assertion test
test/core/templates/skill-templates-parity.test.ts		 Refreshes expected hashes for the affected templates and adds a test that checks for the missing-main-spec handling text in both generated skill content and the opsx archive command template.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

  • #1222: Main spec is never created for the first change in a greenfield project — This PR updates archive handling so a missing main spec is treated as a greenfield case and created during sync.

Possibly related PRs

Suggested reviewers: TabishB

🚥 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 describes the archive guidance update for greenfield spec sync.
Linked Issues check ✅ Passed The changes address #1222 by treating missing main specs as unsynced greenfield capabilities and creating specs from ADDED requirements.
Out of Scope Changes check ✅ Passed The PR stays within the archive bootstrap objective and adds only related template and test updates.
✨ 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.

@clay-good clay-good mentioned this pull request Jun 29, 2026
Closed
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
23f3c10 
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>
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
48ea8ae 
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>
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
af48253 
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>
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
3e1e8fb 
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>
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
04a386d 
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>
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
6d3298d 
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>
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
9ae0781 
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>
clay-good added a commit to clay-good/OpenSpec that referenced this pull request Jun 29, 2026
@clay-good @claude
docs(proposal): add prevent-silent-spec-drop change
dd24830 
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>
@hutiefang76
hutiefang76 force-pushed the codex/fix-archive-greenfield-spec-sync branch from 4cc6fe6 to fa770ea Compare July 5, 2026 19:17
@hutiefang76

hutiefang76 commented Jul 10, 2026

Copy link
Copy Markdown
Author

Closing this to avoid duplicate review work. #1241 now covers the same #1222 greenfield archive-sync behavior and the same template/test area, so keeping two conflicting implementations open would not help maintainers. I will follow the replacement PR instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@TabishB TabishB Awaiting requested review from TabishB TabishB is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Main spec is never created for the first change in a greenfield project

1 participant

@hutiefang76