diff --git a/.sf/REQUIREMENTS.md b/.sf/REQUIREMENTS.md index 183f35625..9929fe2c3 100644 --- a/.sf/REQUIREMENTS.md +++ b/.sf/REQUIREMENTS.md @@ -737,3 +737,32 @@ ADR-0000 declares SF a **purpose-to-software compiler**. R036–R040 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").