Extract and Trace Commands for Code-to-Spec Traceability

[steveardis]

Proposal: Extract and Trace Commands for Code-to-Spec Traceability

Problem

OpenSpec’s workflow starts with specs and produces code. But there are many situations where the code already exists and the specs don’t:

• You inherit a codebase and need to understand what it actually does
• You need to prove that every line of production code ties back to a documented behavior — for compliance, audit, or your own confidence
• A team has been building for months and wants to retroactively bring their work under spec governance
• You want to catch drift — code that was committed outside the OpenSpec workflow and isn’t covered by any spec
• You’re modernizing a legacy system and need to prove the new implementation covers everything the old one did

Today, the only path into OpenSpec for existing code is to hand-write specs from scratch. There’s no tooling to derive specs from code, and no mechanism to verify that every line is accounted for.

Proposal

Add two new commands: extract and trace.

Extract (/opsx:extract, openspec extract)

Analyzes an entire repository and produces OpenSpec specifications.

• Scans the full repo in a single pass
• AI determines domains, boundaries, and decomposition autonomously
• Produces openspec/specs/<domain>/spec.md files in standard OpenSpec format
• Human reviews at the spec level, not file-by-file
• Re-runnable: subsequent runs read existing specs and only produce new specs for behavior not already described
• Does not read or write trace files — operates on code and specs only

Trace (/opsx:trace, openspec trace)

Maps code to existing specs and identifies gaps. Produces a traceability map linking every qualifying line of production code to one or more specs.

• Requires specs to already exist (from extract, hand-written, or any source)
• Maps all non-whitespace, non-comment, non-test lines to specs
• Produces openspec/specs/<domain>/traces/<target>.yaml with mappings and an unmapped section
• The unmapped section is the gap report — lines that need specs or are dead code
• Re-runnable: catches drift after code changes

What gets mapped

• All production source files (non-whitespace, non-comment lines)
• Infrastructure files (pom.xml, Dockerfile, CI configs) map to infrastructure specs
• Migrations and SQL map to domain specs they support
• Static resources map to the specs they serve
• Library-provided behavior (e.g., annotations, base class inheritance) traces to the lines in the repo that activate it
• Line ranges [start, end] inclusive — multiple ranges per file, multiple specs per range

What is excluded

• Whitespace-only lines
• Comment-only lines
• Test files (tests verify specs, they don’t implement specs)

The constraint

The trace map must balance to zero per target. Every qualifying line is either mapped to a spec or listed in the unmapped section. No gray area.

Trace file structure

Each implementation target gets its own file, enabling multi-target traceability:

openspec/specs/<domain>/
├── spec.md
└── traces/
    ├── legacy.yaml
    └── modernized.yaml

target:
  id: legacy
  repo: canopy-device-service
  language: java
mappings:
  - spec_id: "Session Validation"
    files:
      - path: src/main/java/com/canopy/auth/SessionFilter.java
        ranges:
          - [23, 67]
          - [102, 118]
unmapped:
  - path: src/main/java/com/canopy/ratelimit/RateLimiter.java
    ranges:
      - [1, 312]

This structure supports:

• Bidirectional lookup — spec → code and code → spec
• Multiple targets — same specs, different implementations
• Clean decommissioning — delete a target’s trace file, specs and other targets are unaffected
• Target auto-detection — repo resolved from git config, no flags needed for most operations

The extract/trace loop

/opsx:extract          → produces specs from code
  ↓
  human reviews and corrects specs
  ↓
/opsx:trace            → maps code to specs, populates unmapped section
  ↓
  human reviews gaps
  ↓
/opsx:extract          → reads existing specs, produces new specs for unspecified behavior
  ↓
/opsx:trace            → re-maps, unmapped section shrinks
  ↓
  repeat until unmapped is empty

Integration with existing workflow

Minimal changes to existing commands:

• No changes to /opsx:apply
• No changes to openspec validate
• /opsx:archive — after merging delta specs (existing behavior), if trace files exist, archive calls trace as a final step. If unmapped lines are found, archive warns and recommends running /opsx:extract followed by /opsx:trace to close gaps. Archive does not fail on unmapped lines.

The presence of trace files is the opt-in. No configuration flags. If trace files exist, the workflow maintains them. If they don’t, everything works exactly as it does today.

Use cases

Understand what you have

Run extract on any repo to produce specs that describe what the code actually does. Useful for onboarding, knowledge transfer, or simply getting a clear picture of a system you’re responsible for.

Prove coverage

Run trace against specs to verify every line of production code ties back to a documented behavior. Useful for compliance (SOC-2, ISO, regulatory), internal audits, or teams that want a hard guarantee their specs and code stay in sync.

Catch drift

When code is committed outside the OpenSpec workflow, trace surfaces it as unmapped lines. The archive step warns automatically when trace files are present. No silent divergence between specs and code.

Modernize with confidence

Use multiple targets against the same spec set. The legacy target traces the old codebase; the modernized target traces the new one. Diff them to see what’s been ported and what hasn’t. Decommission the old target by deleting its trace file.

Retroactive adoption

A team already has a working codebase and wants to bring it under OpenSpec. Extract produces the initial specs, trace verifies coverage, and the normal workflow takes over from there. No need to rewrite anything — just formalize what already exists.

Adoption on-ramp

Extract and trace can be adopted independently:

1. Extract only — produce specs from a codebase, iterate on them. No traceability commitment.
2. Extract + trace — full line-level traceability with the zero-balance constraint.
3. Trace on existing specs — if you already have hand-written specs, run trace directly to verify coverage.

Scope of changes

• New CLI command: openspec extract
• New CLI command: openspec trace
• New slash command skills: /opsx:extract, /opsx:trace
• New artifact type: trace files in openspec/specs/<domain>/traces/
• Modified: openspec archive calls trace when trace files are present
• New schema support: trace as an artifact type alongside proposal, specs, design, tasks