spec(R059): typed entity vocabulary (R/A/D/M/S/T/F/G/K/P/E)

Operator: "should we have a for adrs and d for decisions? any other
type we should habe?" + "and so we use" — yes, file it and adopt.

Adds A (ADR), D (Decision), F (Finding), G (Gate), K (Knowledge),
P (Pattern), E (Evidence) prefixes to the existing R/M/S/T set.
Each gets a source-of-truth location and a mechanical migration path.

R048 (unbroken purpose chain) + R047 (per-R fulfillment validation)
both require typed cross-references to verify integrity. Without
typed IDs, "this M is covered by R, S, T, A, D" is unverifiable
free-text.

Owning milestone M041 (also added) splits the migration into 6
slices: rename ADRs, add D-IDs to DECISIONS, backfill F/G/K-IDs in
DB tables, doctor cross-link integrity check, lint for SF-authored
typed references.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mikael Hugo 2026-05-17 08:52:37 +02:00
parent 72c2ecb2b2
commit 09687ccd30

View file

@ -737,3 +737,32 @@ ADR-0000 declares SF a **purpose-to-software compiler**. R036R040 codify that
- Backpressure: queue depth >N triggers self-feedback (writer overwhelmed → operator visibility)
- Test contract: 1000 concurrent write requests from N lanes produce N total rows, no errors, no SQLITE_BUSY
- Migration is gradual: move writers one table at a time (slices first, then milestones, then memory_*, etc.)
### R059 — Typed Entity Vocabulary (R/A/D/M/S/T/F/G/K/P/E)
- Class: core-capability
- Status: active
- Description: Pin a consistent typed-prefix vocabulary so every cross-referenced entity in SF has a stable ID with a clear type. Today only R/M/S/T are typed; ADRs, Decisions, Findings (self-feedback), Gates, Knowledge facts, Patterns, and Evidence artifacts are referenced inconsistently. The chain integrity contract (R048) and per-R validation (R047) both require typed cross-references to function honestly.
| Prefix | Type | Source of truth | Migration |
|---|---|---|---|
| **R** | Requirement | .sf/REQUIREMENTS.md | already typed (R001-R058+) |
| **A** | ADR | docs/adr/NNNN-name.md | rename to A0000-name.md, IDs `A0000` etc. |
| **D** | Decision | .sf/DECISIONS.md | add D-IDs to each entry |
| **M** | Milestone | DB milestones table | already typed (M001-M040+) |
| **S** | Slice | DB slices table (per-M) | already typed |
| **T** | Task | DB tasks table (per-S) | already typed |
| **F** | Finding | DB self_feedback table (kind=*) | add F-IDs alongside legacy sf-{ts}-{rand} for human reference |
| **G** | Gate | DB quality_gates table | add G-IDs |
| **K** | Knowledge | KNOWLEDGE.md + memory_* tables | add K-IDs for cross-reference-worthy facts |
| **P** | Pattern | docs/dev/sf-ace-patterns.md and equivalents | add P-IDs to pattern entries |
| **E** | Evidence | per-slice SUMMARY.md / ASSESSMENT.md / UAT.md | already addressable by path; E-IDs optional |
- Why it matters: Without consistent typed IDs, cross-references are by free-text path. R048's unbroken purpose chain (R→M→S→T→Code) only works if every link is addressable. R024 (test-backed completion) needs to reference G-IDs. R039 (purpose-to-evidence audit) needs E-IDs. A doctor check that asserts "every active R has a covering G or E" needs all types to have stable IDs.
- Source: spec (responds to operator question 2026-05-17 — "should we have a for adrs and d for decisions? any other type we should have?")
- Primary owning slice: unmapped (future "M041 Typed Vocabulary Migration")
- Supporting slices: none
- Validation: unmapped
- Notes:
- Migration is mechanical: rename ADR files, add ID frontmatter to DECISIONS.md entries, backfill DB tables with id columns.
- Doctor check: every typed reference resolves (cross-link integrity).
- Lint: SF-authored docs/code must use typed IDs for cross-references (e.g. "per A0000" not "per ADR-0000" or "per the purpose ADR").