From 09687ccd300b591102ca6754d99babb5bde2fab4 Mon Sep 17 00:00:00 2001
From: Mikael Hugo <mikkihugo@users.noreply.github.com>
Date: Sun, 17 May 2026 08:52:37 +0200
Subject: [PATCH] spec(R059): typed entity vocabulary (R/A/D/M/S/T/F/G/K/P/E)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .sf/REQUIREMENTS.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

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").