Bug Report: spec-driven schema dependency order

[gabinoguera]

Bug: In schemas/spec-driven/schema.yaml, the design artifact only requires proposal, allowing it to be generated in parallel
with specs. This contradicts the documented sequence proposal → specs → design → tasks.

Impact: /opsx:continue offers design before specs are written, so the design document is created without spec requirements as
input.

Fix (line 110-111 of schema.yaml):

Before

- id: design
  requires:
    - proposal

After

- id: design
  requires:
    - proposal
    - specs

Rationale: Design documents explain HOW to implement — they need the specs (WHAT to build) as input. The schema's own
description says proposal → specs → design → tasks, and the instruction field for design says "Reference the proposal for
motivation and specs for requirements."

[1code-async]

Task completed.

The comment has been posted on issue #695. Here's a summary of what I found and commented:

Confirmed bug: The design artifact in schemas/spec-driven/schema.yaml:110-111 only requires proposal, but the schema's own description (line 3), workflow docs, and the design artifact's instruction text (line 107: "Reference the proposal for motivation and specs for requirements") all indicate it should also require specs.

Key findings in the comment:

• Three internal contradictions within schema.yaml itself that confirm the bug
• The proposed fix in the issue is correct — add specs to the design artifact's requires list
• A documentation inconsistency in docs/concepts.md that would also need updating
• Two potentially related/duplicate issues: Generation order seems reversed between design and spec #692 (same symptoms) and Artifacts generation order #674 (closed, may be incomplete fix)
• A test fixture in test/core/artifact-graph/state.test.ts:153-156 that mirrors the buggy behavior and would need updating

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Confirmed Bug

The dependency definition for the design artifact at schemas/spec-driven/schema.yaml:110-111 is inconsistent with the documented workflow. The design artifact only requires proposal, but should also require specs.

Three sources within this file contradict the current requires definition:

Location	What it says
Line 3 (description)	proposal → specs → design → tasks — sequential ordering
Line 107 (design instruction)	"Reference the proposal for motivation and specs for requirements."
Lines 110-111 (requires)	requires: [proposal] — missing specs

Because design and specs both only depend on proposal, the artifact graph allows them to run in parallel. This means /opsx:continue can offer to generate design.md before any spec files exist, producing a design document that cannot reference the spec requirements its own instructions tell it to use.

Proposed Fix

The fix in the issue description is correct. At line 110-111 of schemas/spec-driven/schema.yaml:

# Current (line 110-111)
    requires:
      - proposal

# Should be
    requires:
      - proposal
      - specs

This makes the actual dependency graph match the documented sequence: proposal → specs → design → tasks.

Documentation Inconsistency

Note that docs/concepts.md (around lines 379-386) explicitly documents the current (incorrect) behavior as intentional, showing design and specs running in parallel from proposal. If the schema is fixed, that documentation section and its ASCII dependency diagram should also be updated to reflect the sequential ordering.

Meanwhile, docs/workflows.md (line 21) shows the correct sequential flow: proposal ──► specs ──► design ──► tasks.

Possibly Related Issues

• Generation order seems reversed between design and spec #692 — "Generation order seems reversed between design and spec" — appears to describe the same root cause from a user-facing perspective.
• Artifacts generation order #674 (closed) — "Artifacts generation order" — previously addressed artifact ordering; this may be a regression or incomplete fix.

Affected Tests

test/core/artifact-graph/state.test.ts:153-156 uses a test schema where design requires only [proposal], mirroring the current (buggy) behavior. This test fixture would need updating if the fix is applied, to ensure the test graph reflects the corrected dependency chain.