Proposal: depends_on change metadata — detect and declare ordering between parallel changes #1915

Summary

Add an optional depends_on field to per-change metadata (.openspec.yaml) that names other changes this one builds on, and surface it wherever changes are listed. Detecting the dependency shouldn't be manual: when a new change is created, OpenSpec should compare it against the existing active changes and propose a depends_on entry when it looks like one builds on another, the same way /opsx:explore already inspects openspec list --json before thinking through a new idea.

Use case

With several changes in flight, nothing records that one change's scope only makes sense after another lands. Today the only way to discover that add-oauth-scopes needs add-oauth-provider to exist first is to read both proposals by hand. Once a project has more than a couple of parallel changes, an agent (or a person) picking up work has no way to tell which change is safe to start now versus which one will conflict with, or build on top of, something still in flight.

This is the ordering half of a problem the "priority"/"author" work in #1899 addressed for triage, and it's adjacent to the parallel-change overlap detection in #1387 / #1698 — but overlap detection reports that two changes touch the same requirement; it doesn't say which one should go first, or that one only makes sense once the other is archived.

Current behavior

• Per-change metadata lives in .openspec.yaml, validated by ChangeMetadataSchema (src/core/change-metadata/schema.ts). It has no notion of one change relating to another.
• openspec list (src/core/list.ts) has no concept of ordering or relationships between changes — each row is independent.
• openspec new change (src/commands/workflow/new-change.ts) scaffolds a change without looking at what else is active.
• /opsx:explore (src/core/templates/workflows/explore.ts) already runs openspec list --json up front to see active changes, but only uses that to orient the conversation — it never compares the new idea's scope against them.

Proposed behavior

• Add depends_on: string[] (optional, change names) to ChangeMetadataSchema, validated against currently active changes — once a dependency archives, it's baked into the specs and there's nothing left to depend on.
• openspec list surfaces the relationship — e.g. a column/marker for "blocked by " — and --json includes the raw depends_on array, so tooling can do its own topological sort instead of everyone re-deriving order from directory timestamps or manual numbering (the workaround people reach for today, per Is it possible to track development order? #1145 / Support numbered change names (NNNNN-slug) for sequencing #1169).
• When /opsx:explore or openspec new change runs, check the new change's stated scope/affected areas against existing active changes' proposals (already available via openspec list --json + openspec status) and, when there's a plausible overlap or ordering constraint, propose depends_on: [<existing-change>] back to the user rather than silently scaffolding an independent change. This is a proposal to confirm, not an automatic write — consistent with explore's existing "don't auto-capture" guardrail.
• openspec validate (or a new check) could flag a depends_on cycle, or a dependency that names a change that no longer exists.

Related

• Feature request: surface priority and author in openspec list #1899 — priority/author metadata for triage (in progress); this is the ordering counterpart, kept as a separate proposal.
• Pre-archive drift and overlap checking for parallel changes: working tool, offer to contribute #1387 / feat(validate): report requirements two active changes both claim #1698 — parallel-change overlap detection (same requirement edited twice); complementary but answers a different question (conflict, not order).
• Is it possible to track development order? #1145 / Support numbered change names (NNNNN-slug) for sequencing #1169 — closed as answered by allowing numeric-prefixed change names for manual ordering; this proposes an explicit, machine-readable relationship instead of encoding order into the name.
• Promote lifecycle time to a first-class concept in change metadata (created/updated/archived timestamps) #1245 / Proposal: lifecycle: status — record change state as data, not directory position (experimental) #1683 — other proposed additions to .openspec.yaml (lifecycle timestamps, status); same file, different field.