Add planning traceability families

docs/canonical/GRAPH_SCHEMA.md

@@ -30,6 +30,10 @@ Example: `task:BDK-001`, `campaign:BEDROCK`, `submission:abc123`
 | `req` | Requirement | Concrete requirement implemented by work. | `req:TRC-001` |
 | `criterion` | Criterion | Verifiable acceptance criterion for a requirement. | `criterion:TRC-001` |
 | `evidence` | Evidence | Evidence that verifies a criterion or links to a requirement. | `evidence:scan-TRC-001` |
+| `constraint` | Constraint | Planning boundary that constrains delivery or a campaign. | `constraint:TRC-001` |
+| `assumption` | Assumption | Believed-true planning premise that may require validation. | `assumption:TRC-001` |
+| `risk` | Risk | Known unknown with likelihood, impact, and mitigation. | `risk:TRC-001` |
+| `spike` | Spike | Time-boxed investigation or exploratory planning item. | `spike:TRC-001` |
 | `policy` | Policy | Campaign-scoped Definition of Done policy. | `policy:done-default` |
 | `config` | Config | Graph-resident operational configuration singleton. | `config:xyph` |
 | `suggestion` | Suggestion | Advisory intake family; `type` distinguishes trace-link vs AI suggestion semantics. | `suggestion:019xyz` |
@@ -77,6 +81,11 @@ Example: `task:BDK-001`, `campaign:BEDROCK`, `submission:abc123`
 | `implements` | task/evidence → req | Quest-to-requirement lineage is canonical; analyzer-generated evidence may also attach directly to a requirement. |
 | `has-criterion` | req → criterion | Requirement owns one or more acceptance criteria. |
 | `verifies` | evidence → criterion | Evidence verifies a criterion. |
+| `constrains` | constraint → req/campaign | Planning boundary constrains a requirement or campaign. |
+| `assumes` | assumption → task/req | Planning premise depends on a work item or requirement. |
+| `threatens` | risk → task/req | Known danger applies to a quest or requirement. |
+| `informs` | spike → req | Investigation produces spec or requirement truth. |
+| `investigates` | spike → risk/assumption | Investigation refines a planning premise or risk. |
 | `governs` | policy → campaign/milestone | Definition of Done policy governs a campaign or milestone. |
 | `documents` | spec/adr/note/brief → target | Durable narrative or brief context records linked material for a node. |
 | `comments-on` | comment → target | Append-only discussion attached to a node. |
@@ -245,6 +254,55 @@ Legacy: Pre-VOC-001 `INBOX` values are normalized to `BACKLOG` at read time.
 - `verifies` → `criterion:` (canonical evidence-to-criterion link)
 - optional `implements` → `req:` (auxiliary requirement-level auto-link produced by analysis/suggestions)
 
+### Constraint (`constraint:*`)
+
+| Property | Type | Set By | Notes |
+|----------|------|--------|-------|
+| `type` | `'constraint'` | constraint command | Required. |
+| `description` | string | constraint command | ≥5 chars. |
+| `threshold` | string | constraint command | Human-readable boundary, for example `250ms` or `no external oracles`. |
+| `unit` | string | constraint command | Unit or boundary label, for example `ms`, `requests/sec`, or `scope`. |
+
+**Edges:**
+- `constrains` → `req:` or `campaign:`/`milestone:`
+
+### Assumption (`assumption:*`)
+
+| Property | Type | Set By | Notes |
+|----------|------|--------|-------|
+| `type` | `'assumption'` | assumption command | Required. |
+| `description` | string | assumption command | ≥5 chars. |
+| `validated` | boolean | assumption command | Whether the assumption has been validated. |
+| `validated_at` | number | assumption command | Optional validation timestamp. |
+
+**Edges:**
+- `assumes` → `task:` or `req:`
+
+### Risk (`risk:*`)
+
+| Property | Type | Set By | Notes |
+|----------|------|--------|-------|
+| `type` | `'risk'` | risk command | Required. |
+| `description` | string | risk command | ≥5 chars. |
+| `likelihood` | number | risk command | Normalized likelihood from `0` to `1`. |
+| `impact` | number | risk command | Normalized impact from `0` to `1`. |
+| `mitigation` | string | risk command | Optional mitigation note. |
+
+**Edges:**
+- `threatens` → `task:` or `req:`
+
+### Spike (`spike:*`)
+
+| Property | Type | Set By | Notes |
+|----------|------|--------|-------|
+| `type` | `'spike'` | spike command | Required. |
+| `timebox_hours` | number | spike command | Investigation timebox. |
+| `outcome` | string | spike command | Summary of the resulting knowledge or decision. |
+
+**Edges:**
+- `informs` → `req:`
+- `investigates` → `risk:` or `assumption:`
+
 ---
 
 ### Policy (`policy:*`)

docs/canonical/ONTOLOGY_CATALOG.md

@@ -72,7 +72,7 @@ This is the product-wide ontology catalog.
 |--------|-------|----------|
 | Execution work | shared plan state | `task`, `campaign`, `milestone`, `intent` |
 | Narrative and specification | durable context and discussion | `spec`, `adr`, `note`, `comment` |
-| Traceability and completion | requirement/evidence truth | `story`, `req`, `criterion`, `evidence`, `policy` |
+| Traceability and completion | requirement/evidence truth | `story`, `req`, `criterion`, `evidence`, `constraint`, `assumption`, `risk`, `spike`, `policy` |
 | Review and settlement | change review and governed completion | `submission`, `patchset`, `review`, `decision`, `approval`, `artifact` |
 | Advisory intake | recommendations and suggestion queues | `suggestion`, `proposal`, `config` |
 | Shape-governance | governed cases and briefs | `case`, `brief`, scoped `decision` |
@@ -107,6 +107,10 @@ This is the product-wide ontology catalog.
 | Requirement | `req:*` | `type: 'requirement'` | Implemented | Concrete requirement implemented by quests. |
 | Criterion | `criterion:*` | `type: 'criterion'` | Implemented | Acceptance criterion attached to a requirement. |
 | Evidence | `evidence:*` | `type: 'evidence'` | Implemented | Proof or linkage that bears on a criterion or requirement. |
+| Constraint | `constraint:*` | `type: 'constraint'` | Implemented | Planning boundary that constrains a quest, requirement, or campaign. |
+| Assumption | `assumption:*` | `type: 'assumption'` | Implemented | Believed-true premise that can be validated or invalidated. |
+| Risk | `risk:*` | `type: 'risk'` | Implemented | Known unknown with likelihood, impact, and mitigation. |
+| Spike | `spike:*` | `type: 'spike'` | Implemented | Time-boxed investigation that informs planning truth. |
 | Policy | `policy:*` | `type: 'policy'` | Implemented | Definition-of-Done policy applied at campaign scope. |
 
 ### Review And Settlement

docs/canonical/TRACEABILITY.md

@@ -9,7 +9,9 @@ ROADMAP_PROTOCOL.md states: DONE means "acceptance criteria met, evidence attach
 DATA_CONTRACTS.md specifies `userStory` on every task.
 VISION_NORTH_STAR.md declares: "trust, tests, and deployment safety are cryptographically provable."
 
-None of this is implemented. This document specifies the graph model that makes it real.
+The core chain is already implemented in the product. This document now
+specifies the canonical graph model, including the planning qualifiers that
+frame readiness and risk analysis.
 
 ## 2. The Traceability Chain
 
@@ -44,7 +46,7 @@ criteria are modeled.
 | `evidence:` | Evidence | Proof or linkage for a criterion | `kind` (test / benchmark / manual / screenshot), `result` (pass / fail / linked), `produced_at`, `produced_by`, `artifact_hash` |
 | `constraint:` | Constraint | Non-functional boundary (perf, security, compat) | `description`, `threshold`, `unit` |
 | `assumption:` | Assumption | Believed-true condition that could invalidate work | `description`, `validated` (bool), `validated_at` |
-| `risk:` | Risk | Known unknown with impact assessment | `description`, `likelihood`, `impact`, `mitigation` |
+| `risk:` | Risk | Known unknown with impact assessment | `description`, `likelihood` (0..1), `impact` (0..1), `mitigation` |
 | `spike:` | Spike | Time-boxed investigation producing knowledge | `timebox_hours`, `outcome` |
 | `policy:` | Policy | Definition of Done / campaign-level rules | `conditions[]` |
 
@@ -60,6 +62,7 @@ criteria are modeled.
 | `assumes` | Assumption → Task or Requirement | Validity dependency |
 | `threatens` | Risk → Task or Requirement | Known danger |
 | `informs` | Spike → Requirement | Investigation produces spec |
+| `investigates` | Spike → Risk or Assumption | Investigation informs planning risk or hypothesis |
 | `governs` | Policy → Campaign | Definition of Done scope |
 
 ## 5. Computed Queries

src/cli/commands/dashboard.ts

@@ -218,6 +218,7 @@ export function registerDashboardCommands(program: Command, ctx: CliContext): vo
             computeFailingCriteria,
             computeUntestedCriteria,
             computeCoverageRatio,
+            computePlanningGapSummary,
           } = await import('../../domain/services/TraceabilityAnalysis.js');
 
           const reqSummaries = snapshot.requirements.map((r) => ({
@@ -241,6 +242,21 @@ export function registerDashboardCommands(program: Command, ctx: CliContext): vo
           const untestedCriteria = computeUntestedCriteria(critSummaries);
           const failingCriteria = computeFailingCriteria(critSummaries);
           const coverage = computeCoverageRatio(critSummaries);
+          const planningGaps = computePlanningGapSummary(
+            snapshot.assumptions.map((assumption) => ({
+              id: assumption.id,
+              validated: assumption.validated,
+              validatedAt: assumption.validatedAt,
+              targetIds: assumption.targetIds,
+            })),
+            snapshot.risks.map((risk) => ({
+              id: risk.id,
+              likelihood: risk.likelihood,
+              impact: risk.impact,
+              mitigation: risk.mitigation,
+              targetIds: risk.targetIds,
+            })),
+          );
           const questCompletion = snapshot.quests
             .filter((quest) => quest.computedCompletion?.tracked || quest.computedCompletion?.discrepancy)
             .map((quest) => ({
@@ -287,17 +303,27 @@ export function registerDashboardCommands(program: Command, ctx: CliContext): vo
                 criteria: snapshot.criteria,
                 evidence: snapshot.evidence,
                 policies: snapshot.policies,
+                constraints: snapshot.constraints,
+                assumptions: snapshot.assumptions,
+                risks: snapshot.risks,
+                spikes: snapshot.spikes,
                 summary: {
                   stories: snapshot.stories.length,
                   requirements: snapshot.requirements.length,
                   criteria: snapshot.criteria.length,
                   policies: snapshot.policies.length,
+                  constraints: snapshot.constraints.length,
+                  assumptions: snapshot.assumptions.length,
+                  risks: snapshot.risks.length,
+                  spikes: snapshot.spikes.length,
                   evidenced: coverage.evidenced,
                   satisfied: coverage.satisfied,
                   failing: coverage.failing,
                   linkedOnly: coverage.linkedOnly,
                   unevidenced: coverage.unevidenced,
                   coverageRatio: coverage.ratio,
+                  unvalidatedAssumptions: planningGaps.unvalidatedAssumptionIds.length,
+                  unmitigatedRisks: planningGaps.unmitigatedRiskIds.length,
                   computedCompleteQuests: questCompletion.filter((entry) => entry.computedCompletion?.complete).length,
                   computedTrackedQuests: questCompletion.filter((entry) => entry.computedCompletion?.tracked).length,
                   computedCompleteCampaigns: campaignCompletion.filter((entry) => entry.computedCompletion?.complete).length,
@@ -308,6 +334,7 @@ export function registerDashboardCommands(program: Command, ctx: CliContext): vo
                 unmetRequirements: unmetReqs,
                 untestedCriteria,
                 failingCriteria,
+                planningGaps,
                 questCompletion,
                 campaignCompletion,
                 questDiscrepancies,
@@ -324,10 +351,15 @@ export function registerDashboardCommands(program: Command, ctx: CliContext): vo
             criteria: snapshot.criteria,
             evidence: snapshot.evidence,
             policies: snapshot.policies,
+            constraints: snapshot.constraints,
+            assumptions: snapshot.assumptions,
+            risks: snapshot.risks,
+            spikes: snapshot.spikes,
             unmetRequirements: unmetReqs,
             untestedCriteria,
             failingCriteria,
             coverage,
+            planningGaps,
             questCompletion,
             campaignCompletion,
             questDiscrepancies,