Reqtrace v2.1.5 Architecture Decision Records

ADR-001 — Do not ship hierarchy presets in core

Status: Accepted for v2.1.5

Decision: Reqtrace v2.1.5 will not ship built-in hierarchy presets.

Tools considered:

Tool What it already owns
Doorstop Document-tree requirements management with document prefixes and parent document relationships
Sphinx-Needs / Open-Needs Configurable need types, links, filters, tables, and flows
OpenFastTrace Artifact-type coverage chains with explicit coverage/dependency semantics

Reasoning: Hierarchy presets would make Reqtrace appear to choose one requirements model too early. Real teams use different structures: document trees, typed docs-as-code objects, artifact-coverage chains, tracker-native issue hierarchies, and flat ADR logs. Reqtrace should not compete with tools that already own those hierarchy models.

Reqtrace core responsibility: Reqtrace owns portable evidence handles, annotations, registry records, generated ledgers, JSON reports, and strict checks.

Delegated responsibility: Teams that want opinionated hierarchy presets should use Doorstop, Sphinx-Needs/Open-Needs, OpenFastTrace, or their tracker-native hierarchy. Reqtrace can coexist by using those IDs as handles.

Implementation consequence: Do not add preset commands, preset templates, auto-numbering, or preset validation in v2.1.5.

Status: Accepted for v2.1.5

Decision: Reqtrace v2.1.5 will document and preserve parent and links fields in docs/handle-registry.jsonl, but will not validate their semantics in check --strict.

Clarification: In v2.1.5, register writes handle, type, and source. It does not write parent or links. Those fields may be added manually or by downstream tools and must be preserved by Reqtrace when present.

Tools considered:

Tool Relationship model
Doorstop Parent document prefixes and item links define document-tree traceability
Sphinx-Needs / Open-Needs Need objects support configurable links, including default links and parent_needs behavior
OpenFastTrace Separates coverage, need, and dependency semantics

Reasoning: Vertical hierarchy and horizontal links are real, but their meanings vary. A parent may mean “belongs under this document,” “satisfies this requirement,” “implements this design,” or “is a child work item.” A link may mean “depends on,” “supersedes,” “verifies,” “cross-cuts,” or “references.” Validating those relationships before real usage data would hard-code the wrong semantics.

Reqtrace core responsibility: Reqtrace preserves relationship metadata when present.

Delegated responsibility: Downstream tools may write and traverse parent and links immediately. Dedicated hierarchy tools may enforce stricter relationship rules.

Implementation consequence: parent and links are reserved fields. They must not be stripped or rejected. They must not be validated by check --strict in v2.1.5. register --parent and register --link are deferred.

ADR-003 — Do not implement a native grep proxy in v2.1.5

Status: Accepted for v2.1.5

Decision: Reqtrace v2.1.5 will not implement reqtrace grep.

Tools considered:

Tool What it already owns
GNU grep Universal plain-text search baseline
ripgrep Fast recursive repository search with developer-friendly defaults
RTK AI-agent-oriented CLI proxying and compact command output

Reasoning: Reqtrace’s value is not search performance or command-output compression. Its value is the convention: @reqtrace <handle> markers remain plain text and searchable with ordinary tools. A native grep proxy may be useful later, but adding it now risks weakening the “grep-first” promise by making discovery feel Reqtrace-dependent.

Reqtrace core responsibility: Reqtrace keeps annotations grep-native and emits stable JSON for tools that need structured output.

Delegated responsibility: Use grep, ripgrep, or RTK for search and compressed command output.

Implementation consequence: Do not add reqtrace grep in v2.1.5. Documentation may show examples using grep, rg, and rtk grep.

ADR-004 — Do not implement native HTML reports in v2.1.5

Status: Accepted for v2.1.5

Decision: Reqtrace v2.1.5 will not implement native HTML report generation.

Tools considered:

Tool What it already owns
Sphinx-Needs / Open-Needs Documentation-native tables, flows, filtering, and rendered trace views
OpenFastTrace Trace reports, including HTML-oriented reporting workflows
GitHub Actions Job Summaries CI-native Markdown report surfaces

Reasoning: HTML reporting is presentation. Reqtrace core should emit stable machine-readable contracts first: JSON scan output, JSON report envelopes, generated JSONL ledgers, and deterministic status lines. Once those contracts are stable, any downstream renderer can generate HTML, Markdown, dashboards, or CI summaries.

Reqtrace core responsibility: Provide stable JSON and JSONL output.

Delegated responsibility: Downstream tools render HTML or CI summaries from Reqtrace outputs.

Implementation consequence: Do not add native HTML reports in v2.1.5. Add schema documentation so renderers know what to consume.

ADR-005 — Do not implement native blame in v2.1.5

Status: Accepted for v2.1.5

Decision: Reqtrace v2.1.5 will not implement --blame.

Tools considered:

Tool What it already owns
Git blame Line-level commit provenance
Reqtrace ledger consumers Occurrence-level evidence provenance from scan and trace-ledger.jsonl
RTK / downstream agent tools Compact provenance presentation for agent workflows

Reasoning: “Blame” has multiple meanings: Git commit attribution, evidence occurrence identity, reviewer attribution, actor attribution, and downstream audit provenance. Implementing native blame too early risks choosing the wrong semantic model. v2.1.5 should instead make occurrence objects complete enough that downstream tools can join scan output to the ledger and produce their own blame view.

Reqtrace core responsibility: Expose complete occurrence records with handle, path, line, kind, and id.

Delegated responsibility: Downstream tools join Reqtrace output with Git, local ledgers, review systems, or agent logs.

Implementation consequence: Do not add --blame in v2.1.5. Complete scan --format json instead.

ADR-006 — Stabilize machine contracts before adding new UX surfaces

Status: Accepted for v2.1.5

Decision: Reqtrace v2.1.5 will prioritize machine-readable stabilization over new product surfaces.

Tools considered:

Tool What it already owns
GitHub Actions CI execution and job summaries
pre-commit Local hook execution before commit
downstream agents / CLIs Consuming JSON contracts and presenting tailored output

Reasoning: Reqtrace must be safe for unconditional agentic usage before it expands. Silent success, incomplete JSON fields, unversioned report envelopes, and missing schema documentation create ambiguity for agents. v2.1.5 should remove that ambiguity first.

Reqtrace core responsibility: Provide stable command outputs, stable schemas, deterministic exit codes, and a low-friction register command.

Delegated responsibility: CI, hooks, agents, and dashboards decide how to present those stable outputs.

Implementation consequence: Implement only the stabilization tasks: complete scan --format json, envelope report --format json, status check --strict, add register, document schemas, and document hierarchy patterns.