Context: spec-driven schema, project-local fork (openspec/schemas/spec-driven/), openspec CLI v1.6.0.
The specs artifact's instruction text (and by extension the proposal artifact's "Modified Capabilities" guidance) tells the author: "Leave empty if no requirement changes." This is correct advice for a change that is a pure technical refactor with no user-observable behavior change (e.g., migrating a client from hand-written fetch calls to a typed RPC client, with zero HTTP-contract changes).
However, openspec validate (and presumably archive) enforces ChangeSchema.deltas.min(1, CHANGE_NO_DELTAS) in dist/core/schemas/change.schema.js unconditionally, regardless of which workflow schema was used to generate the change's artifacts. This means:
- An author following the propose-phase guidance literally (leaving Modified/New Capabilities empty because there truly are no requirement changes) will pass the propose phase, but fail validate later with "Change must have at least one delta. No deltas found."
- Forking a new project-local workflow schema does NOT help, since CHANGE_NO_DELTAS is enforced at the core data-model layer (ChangeSchema), not the workflow-schema layer. There is no schema-level or CLI-flag way to opt out of the >=1 delta requirement.
- This creates a late-discovery footgun: the contradiction only surfaces at validate time, well after the proposal/specs/design/tasks artifacts have already been written, causing rework.
Suggested fixes (any one would help):
- Make the
specs artifact's instruction (and/or the proposal's Capabilities section instruction) explicitly state: "Every change must have at least one delta (ADDED/MODIFIED/REMOVED/RENAMED requirement) — even a pure technical refactor should identify at least one explicit, testable property or guarantee it changes (e.g., a non-functional requirement), since validate/archive will reject a change with zero deltas."
- Or, relax CHANGE_NO_DELTAS to be conditional on whether the workflow schema declares a
specs artifact at all, so schemas that intentionally omit a specs stage aren't affected (not our preferred fix, since it would fragment behavior across schemas, but noting it as an option).
- Or, surface a warning/error earlier — e.g. at
openspec status/instructions time when the proposal's Capabilities sections are both empty — rather than only at validate time.
Separately: openspec feedback itself failed for me with "could not add label: 'feedback' not found" when submitting this via gh issue create --repo Fission-AI/OpenSpec --label feedback — the feedback label doesn't appear to exist on this repo, and the command doesn't fall back to the manual-URL path on a generic gh issue create error (only on missing/unauthenticated gh). Filing this issue directly without the label as a workaround.
This was discovered while proposing a pure internal refactor (migrating a monorepo's client-server communication to Hono's RPC feature) that initially had zero capability changes in its proposal.md, following the documented guidance to leave Modified Capabilities empty.
Submitted via OpenSpec CLI (manual gh issue create, feedback command's built-in gh path failed on label)
- Version: 1.6.0
- Platform: darwin
Context: spec-driven schema, project-local fork (openspec/schemas/spec-driven/), openspec CLI v1.6.0.
The
specsartifact's instruction text (and by extension theproposalartifact's "Modified Capabilities" guidance) tells the author: "Leave empty if no requirement changes." This is correct advice for a change that is a pure technical refactor with no user-observable behavior change (e.g., migrating a client from hand-written fetch calls to a typed RPC client, with zero HTTP-contract changes).However,
openspec validate(and presumablyarchive) enforcesChangeSchema.deltas.min(1, CHANGE_NO_DELTAS)in dist/core/schemas/change.schema.js unconditionally, regardless of which workflow schema was used to generate the change's artifacts. This means:Suggested fixes (any one would help):
specsartifact's instruction (and/or the proposal's Capabilities section instruction) explicitly state: "Every change must have at least one delta (ADDED/MODIFIED/REMOVED/RENAMED requirement) — even a pure technical refactor should identify at least one explicit, testable property or guarantee it changes (e.g., a non-functional requirement), sincevalidate/archivewill reject a change with zero deltas."specsartifact at all, so schemas that intentionally omit a specs stage aren't affected (not our preferred fix, since it would fragment behavior across schemas, but noting it as an option).openspec status/instructionstime when the proposal's Capabilities sections are both empty — rather than only at validate time.Separately:
openspec feedbackitself failed for me with "could not add label: 'feedback' not found" when submitting this viagh issue create --repo Fission-AI/OpenSpec --label feedback— thefeedbacklabel doesn't appear to exist on this repo, and the command doesn't fall back to the manual-URL path on a genericgh issue createerror (only on missing/unauthenticatedgh). Filing this issue directly without the label as a workaround.This was discovered while proposing a pure internal refactor (migrating a monorepo's client-server communication to Hono's RPC feature) that initially had zero capability changes in its proposal.md, following the documented guidance to leave Modified Capabilities empty.
Submitted via OpenSpec CLI (manual gh issue create, feedback command's built-in gh path failed on label)