# ADR-0006: Introduce a Reference Discipline as a top-level standard sub-system

## Status
Accepted

## Date
2026-05-07

## Context

Through v1.0.3 the standard's citations lived as plain markdown links in three places. The standards spine in `standard.md`, inline citations in specimens, and run-time references the agent skill might emit. They were not verified, not machine-readable, not cross-linked between artefacts, and decayed silently as URLs rotted or content shifted.

Three failure modes followed:

1. **Silent rot.** Without a `verified_on` cadence, half a year later the standards spine looks authoritative but half the URLs no longer resolve.
2. **One-source bias.** A single article repeated in 10 specialist outlets is still one source. Without independent triangulation, "five citations" can collapse to one wire-service feed.
3. **Tool-locked claims.** When the skill cites NIST or ISO at run time, it should verify the URL, not assert from training-data memory.

The standards spine had grown to ~22 entries; the stablecoin specimen had a 71-source corpus. The combined surface was now too large for ad-hoc treatment.

## Decision

Introduce **Reference Discipline** as a top-level sub-system of the standard:

- A new section in `standard.md` between Rule 5 and the Finding Packet template names the 5-tier source classification (ADR-0005), the triangulation rule, the Exa-as-recommended primitive (ADR-0004), and the 90-day `verified_on` floor.
- A methodology document at `/methodology` (`specimens/methodology.md`) documents the Exa-driven workflow with a worked example.
- A `references.json` at the project root unifies every citation across the standards spine and every specimen corpus into one machine-readable index.
- An `audits/` directory accumulates dated, immutable verification logs.
- The agent skill (`deepsec/SKILL.md`) gains step 5b. Triangulate cited references via web-search MCP before emitting any finding that cites an external URL.

This is a **MINOR version** event (v1.0.3 → v1.1.0): adds a top-level capability without changing the five rules or four templates.

## Alternatives Considered

### Keep references as plain markdown
- Pros: Zero infrastructure.
- Cons: Silent rot; no triangulation; no audit trail.
- Rejected: production-grade citations require verification cadence.

### Build a custom citation database (Postgres / Notion / spreadsheet)
- Pros: Richer querying.
- Cons: Adds infrastructure dependency; not portable; not deep-linkable.
- Rejected: violates the "everything is plain markdown / JSON over CORS" project posture.

### Adopt an existing academic citation manager (BibTeX / Zotero / CSL-JSON)
- Pros: Mature ecosystem.
- Cons: Sized for academic citation, not for time-sensitive regulatory + technical + journalism mix; no native concept of `verified_on` cadence.
- Rejected: existing tooling does not fit the use case; the JSON schema is small enough to define ourselves.

### Defer to v2.0
- Pros: Smaller v1.x surface.
- Cons: The standards spine and stablecoin specimen had already crossed the threshold where ad-hoc treatment fails. Deferring would have shipped v1.1 with known evidence-integrity gaps.
- Rejected: the cost of waiting was higher than the cost of introducing the sub-system now.

## Consequences

- The standard now ships with a verifiable evidence layer rather than an aspirational citation list.
- Adopters can cite by `id` (`ref:nist-sp-800-218-ssdf`) instead of pasting URLs, reducing duplication and rot.
- Future specimens inherit the discipline by default. No per-specimen citation invention.
- The 90-day `verified_on` floor creates an explicit re-verify cadence that prevents silent rot.
- The MCP roadmap (v2.0) gains a natural surface. `verify_reference()` as a programmatic gate.
- ADRs 0004 and 0005 (Exa-as-recommended, 5-tier classification) are sub-decisions of this one; this ADR is the umbrella.

## Reference

- Standard section: [`standard.md` `#reference-discipline`](https://www.deepsec-skill.dev/standard.md#reference-discipline)
- Methodology: [`/methodology`](https://www.deepsec-skill.dev/methodology)
- Index: [`/references.json`](https://www.deepsec-skill.dev/references.json)
- Worked example: [`specimens/stablecoin.md`](https://www.deepsec-skill.dev/specimens/stablecoin.md) v1.2
- Inaugural audit: [`audits/2026-05-07-stablecoin-cross-reference.md`](https://github.com/johndfowler/deepsec-skill/blob/main/audits/2026-05-07-stablecoin-cross-reference.md)
- Sub-decisions: ADR-0004, ADR-0005