Skip to content

Stable IDs for requirements, scenarios and decisions #2167

Open

Description

@clay-good

The problem

Links to a requirement, scenario or decision point at its heading text, so rewording a heading breaks them, and archive refuses a renamed scenario (#1697).

Who this affects

Anyone who links tests, tasks or code to specs. In epam/ai-dial-chat, about 1 in 4 broken spec links was just a reworded heading.

What we have in mind

### Requirement: [AUTH-3] Users sign in
#### Scenario: [AUTH-3.1] Correct password

### D1
Use Redis for sessions, because restarts must not sign users out.
  • The agent writes a visible ID in square brackets at the start of the heading. There's no hidden metadata and no new command, and the CLI only reads IDs.
  • Brackets are required, so ordinary headings like SHA-256 checksum or HTTP-2 support are never mistaken for IDs.
  • Validate and archive match on the ID before the name, so renames work. Dropping an ID is still refused, and a bare prefix like NAV-5 can gain brackets.
  • Duplicate IDs are refused, which catches two parallel changes picking the same number.
  • Decisions are a ### D1 heading plus one or two sentences. There are no Rationale or Alternatives fields (the concern on docs: add stable design decision anchors #2113).
  • Specs without IDs are unchanged.

Evidence: agents kept IDs in 264 of 265 runs (details), and all 2,022 past archives in five repos rebuild byte-identical with the change.

Plan: #1979 is the CLI side; #2134 teaches the openspec-beta skills.

Not in scope: coverage reports, checking task links to removed decisions (#2056 step 2), deliberate removals (#1843), parallel-change overlap (#1669, #1387), and databases or two-way traceability.

Consolidates #2056, #2113, #743 (discussion) and #2157, plus #1967's first two directions and #2033's Direction 3.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions