docs+ci: traceability IDs (PRIN/SCEN) and docs link-check

.github/workflows/ci.yml

@@ -97,4 +97,17 @@ jobs:
       - name: Build WASM
         run: wasm-pack build crates/core-rs --target web --out-dir bindings/wasm/pkg
       - name: Typecheck project
-        run: pnpm typecheck
+        run: pnpm typecheck
+
+  linkcheck:
+    name: Docs Link Check
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install lychee
+        uses: lycheeverse/lychee-action@v1
+        with:
+          args: --verbose --no-progress --accept 200,206,429 --exclude-path './coverage' './**/*.md' './**/*.mdc'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/PRD.md

@@ -80,5 +80,19 @@ on‑device, system‑wide, with zero input sent to cloud. Target uplift:
 
 ### Traceability
 
-- See REQ → tests/modules mapping in the PRD “Traceability” appendix
-  after test scaffolding lands.
+IDs:
+
+- Requirements: REQ-\*
+- Principles: PRIN-\*
+- ADRs: ADR-\*
+- Scenarios: SCEN-\*
+
+Appendix — Traceability Map (starter)
+
+| REQ-ID                   | Principles                   | ADRs     | QA Scenarios                        | Modules/Guides                                    |
+| ------------------------ | ---------------------------- | -------- | ----------------------------------- | ------------------------------------------------- |
+| REQ-IME-CARETSAFE        | PRIN-SAFETY-04               | ADR-0002 | SCEN-CARETS-001                     | utils/diff.ts; band-policy.md                     |
+| REQ-STREAMED-DIFFUSION   | PRIN-HUMAN-01, PRIN-LOGIC-10 | —        | SCEN-DIFFUSION-001                  | core/diffusionController.ts; lm-behavior.md       |
+| REQ-VALIDATION-BAND      | PRIN-HUMAN-01, PRIN-LOGIC-10 | —        | SCEN-DIFFUSION-001, SCEN-HILITE-001 | band-policy.md; ui/highlighter.ts                 |
+| REQ-A11Y-MOTION          | PRIN-HUMAN-03                | —        | SCEN-HILITE-001                     | a11y/wcag-checklist.md; ui/motion.ts              |
+| REQ-LOCAL-LM-INTEGRATION | PRIN-SAFETY-05, PRIN-PERF-11 | ADR-0003 | SCEN-LMLOCAL-001                    | lm-behavior.md; core/lm/\*; transformersRunner.ts |

docs/adr/0002-caret-safe-diff.md

@@ -20,9 +20,9 @@ Context
 Users must never see unexpected forward edits; IME/secure fields require
 strict boundaries.
 
-Decision
+Decision (Traceability)
 All diffs MUST satisfy `end <= caret`. Engines MUST reject proposals that
-cross the caret. (PRD: REQ-IME-CARETSAFE)
+cross the caret. (PRD: REQ-IME-CARETSAFE, Principles: PRIN-SAFETY-04)
 
 Consequences
 
@@ -33,7 +33,10 @@ Alternatives
 
 - Allow ahead edits with preview/confirm — rejected for flow/latency.
 
-Links
+Links (Traceability)
 
+- PRD: `docs/PRD.md#functional-requirements`
+- Principles: `docs/system_principles.md#4-caret-safe-never-risky`
+- Architecture: `docs/architecture/C3-components.md`
 - Code: `utils/diff.ts`, `engines/tidySweep.ts`
 - Tests: `tests/diff.spec.ts`, `tests/tidySweep.spec.ts`

docs/qa/README.md

@@ -66,6 +66,12 @@ Keep this file short and link to detailed specs in `docs/implementation.md` and
 
 ### Cross‑links
 
-- Principles → QA: Each acceptance test cites the governing principle in `docs/system_principles.md`.
+- Principles → QA: Each acceptance test cites the governing principle in `docs/system_principles.md` (PRIN‑IDs).
 - ADRs → QA: ADRs define non‑negotiables that acceptance scenarios must validate (e.g., caret safety).
 - Guides → QA: Reference docs (band policy, injector, LM behavior) define the behaviors under test.
+
+### Traceability Fields (per scenario)
+
+- REQ‑IDs (from PRD), PRIN‑IDs (from Principles), ADR‑IDs (from ADRs)
+- Modules involved (e.g., `core/diffusionController.ts`)
+- Link to unit/integration tests when applicable

docs/qa/acceptance/backfill_name_consistency.feature

@@ -4,6 +4,7 @@
 # WHAT ▸ Ensure consistent proper-name spelling
 # WHY  ▸ Cohesion during later passes
 # HOW  ▸ BackfillConsistency proposes stable-zone edits
+# IDs  ▸ SCEN-BACKFILL-001 | PRIN: PRIN-LOGIC-08 | FUTURE REQ: Backfill consistency
 
 Feature: Backfill name consistency (REF: engines/backfillConsistency)
   Scenario: Consistent person name within paragraph

docs/qa/acceptance/caret_safety.feature

@@ -4,6 +4,7 @@
 # WHAT ▸ Prevent edits at/after the CARET
 # WHY  ▸ Trust and predictability (REQ-IME-CARETSAFE)
 # HOW  ▸ Engine rejects diffs crossing caret
+# IDs  ▸ SCEN-CARETS-001 | PRIN: PRIN-SAFETY-04 | ADR: ADR-0002 | REQ: REQ-IME-CARETSAFE
 
 Feature: Caret-safe diffs (REQ-IME-CARETSAFE)
   Scenario: No edits when caret mid-word

docs/qa/acceptance/local_lm_integration.feature

@@ -4,6 +4,7 @@
 # WHAT ▸ On-device language model corrections with graceful fallback
 # WHY  ▸ Semantic/grammatical quality beyond rules while staying local
 # HOW  ▸ Stream LM tokens into validation band; fallback to rules; <150MB memory
+# IDs  ▸ SCEN-LMLOCAL-001 | PRIN: PRIN-SAFETY-05, PRIN-PERF-11 | REQ: REQ-LOCAL-LM-INTEGRATION, REQ-CONTEXTUAL-CORRECTIONS
 
 Feature: Local LM Integration (REQ-LOCAL-LM-INTEGRATION, REQ-CONTEXTUAL-CORRECTIONS)
   Scenario: LM enhances contextual corrections

docs/qa/acceptance/streamed_diffusion.feature

@@ -4,6 +4,7 @@
 # WHAT ▸ Word-by-word streamed corrections behind caret
 # WHY  ▸ Make the trailing process visible and predictable
 # HOW  ▸ Validation band (3–8 words), caret-safe edits, pause catch-up
+# IDs  ▸ SCEN-DIFFUSION-001 | PRIN: PRIN-LOGIC-10, PRIN-HUMAN-01 | REQ: REQ-STREAMED-DIFFUSION, REQ-VALIDATION-BAND
 
 Feature: Streamed diffusion (REQ-STREAMED-DIFFUSION, REQ-VALIDATION-BAND)
   Scenario: Frontier advances during typing

docs/qa/acceptance/two_word_highlight.feature

@@ -4,6 +4,7 @@
 # WHAT ▸ Briefly highlight two words behind caret
 # WHY  ▸ Awareness without distraction (REQ-A11Y-MOTION)
 # HOW  ▸ UI respects prefers-reduced-motion
+# IDs  ▸ SCEN-HILITE-001 | PRIN: PRIN-HUMAN-02, PRIN-HUMAN-03 | REQ: REQ-A11Y-MOTION
 
 Feature: Two-word highlight (REQ-A11Y-MOTION)
   Scenario: Highlight after short pause