ADR-0102 — Lean the artifact surface: intake is an optional pointer; reference material single-sources to docs
- Sections
- 5
- Format
- Markdown
- Order
- 138 / 156
Context
Two leanness wins from the session deliberation (RFC-lean-artifact-set) that stand on their own, independent of the larger spec-as-living-form change (which stays an open proposal — see that RFC):
- Intake is presented as a station with a file, but a spec's source is often a Jira issue or any
provider with no middleman file, and no notation belongs around it. The spec template already allows
sources: selfor a ticket id — the loop docs just over-imply anintake/step. - The kit duplicates reference material (
advanced/checks-reference.md,advanced/sol-reference.md) that restates the canonicaldocs/reference/checks.md+structured-requirements.md— and it has been caught drifting (stale at C014 in a prior pass). Duplicated reference content is a standing drift liability (the anti-duplication concern of ADR-0096 §3.5).
Decision
-
Intake is an optional source pointer, not a required station. A spec names its origin in
sources:— a Jira URL/id, anintake/file, orself. The loop is Spec → Review; capturing a raw request inintake/is available but never implied as a step, and no notation surrounds it. Level: convention. -
Reference material single-sources to docs. The kit's
advanced/checks-reference.mdandadvanced/sol-reference.mdno longer duplicate the canon — their bodies become a one-line pointer todocs/reference/checks.md(+checks/checks.yaml) anddocs/reference/structured-requirements.mdrespectively. The templates inadvanced/(adr/prd/rfc/audit/bug/research/threat-model) stay — they are blanks nothing else ships. This resolves RFC-lean-artifact-set's offline-self-containment open question in favour of single-sourcing: a drifting copy is worse than a pointer, and the canon is one fetch away. Level: convention. Full removal of the card files (with inbound-pointer surgery) is a tracked follow-up, not required by this ADR.
Consequences
- No
checks.yamlrule, no contract bump — conventions, consistent with the honesty framework (ADR-0063). - The kit stops carrying a drift liability;
spec-check(which used the checks card as its reference) points at the canonicaldocs/reference/checks.md. - Scope note: the larger spec-as-living-form / task-on-demand change (RFC-lean-artifact-set D1) is not decided here — it amends the frozen spec format (ADR-0058) and touches the parser, C006, and ~50 specs, so it awaits ratification rather than autonomous execution (keeping the tree coherent and pristine).
Propagation
docs/02-basic-workflow.md, docs/03-where-files-live.md, docs/ADOPTING.md (intake optional), and
the kit cards advanced/checks-reference.md + advanced/sol-reference.md (→ pointers) + the
spec-check guide (→ canonical checks doc). suspec-works vendored copies re-sync from the kit.
Affected obligations / constraints
- Reaffirms: ADR-0096 (anti-duplication), the spec template's
sourcesfield (already allowedself). - Does NOT change: the spec format, the verdict model, the checks contract, or the
advanced/templates.
Starter kit: Set up a workspace