Overview The traceability-graph.json file is a structured representation of all SDD artifacts, their relationships, code/test/commit references, and statistical metrics. It powers the interactive HTML dashboard and the MCP server.
Location dashboard/traceability-graph.jsonSchema version Current: v4 (introduced in SDD Plugin v2.0.0)Backward compatibility: All v1/v2/v3 fields are preserved. Each version is a pure extension.Root fields Schema version identifier. Always "traceability-graph-v4".
ISO-8601 timestamp when the graph was generated. Example: "2026-03-01T15:30:00.000Z"
Name of the project. Derived from package.json, directory name, or pipeline-state.json.
Pipeline execution status snapshot. Active stage name from pipeline-state.json, or "unknown" if file not found.
Ordered array of 7 pipeline stages with their status. Stage identifier (e.g., "requirements-engineer").
One of: "done", "stale", "running", "error", "pending".
ISO-8601 timestamp of last completion. null if never run.
Count of artifacts produced by this stage.
Array of all SDD artifacts found in the project. Unique artifact identifier. Format depends on type:
REQ-{PREFIX}-{NNN} (e.g., REQ-EXT-001)UC-{NNN}, WF-{NNN}, BDD-{NNN}INV-{PREFIX}-{NNN}, API-{name}, ADR-{NNN}TASK-F{N}-{NNN}, FASE-{N} Artifact type: REQ, UC, WF, API, BDD, INV, ADR, NFR, RN, FASE, TASK.
Sub-category (e.g., EXT, CVA, SYS, SEC, F, NF). null if not applicable.
Artifact title or first line of definition.
Relative file path where the artifact is defined (forward slashes).
Line number of definition (1-indexed).
Priority level if available (e.g., "Must Have", "Should Have").
Pipeline stage that owns this artifact.
Business/technical/functional classification. Only present for REQ artifacts. Show Classification object
Business domain inferred from REQ prefix (e.g., "Extraction & Processing").
One of: "Infrastructure", "Backend", "Frontend", "Integration/Deployment", "Unknown".
One of: "Functional", "Non-Functional", "Security", "Data", "Integration".
Source code references implementing this artifact. Empty array [] if none. Relative path to source file.
Line number where the Refs: comment was found.
Nearest symbol name (function, class, const) or "filename:line" fallback.
One of: "function", "class", "const", "interface", "type", "method", "variable", "unknown".
Artifact IDs referenced in the comment (e.g., ["UC-001", "INV-EXT-005"]).
v4 only. true if this reference was inferred transitively via call graph. Absent in v1-v3.
v4 only. Confidence score 0.0-1.0 for inferred references. Absent in v1-v3.
Test references verifying this artifact. Empty array [] if none. Relative path to test file.
Line number of the test definition or Refs: comment.
Test description (e.g., "validates size per INV-EXT-005").
Test framework: "vitest", "jest", "pytest", "jasmine", "unknown".
Artifact IDs referenced in the test.
Git commits referencing this artifact via Refs:/Task: trailers. Empty array [] if none. Short SHA (7 chars) of the commit.
Full 40-char SHA of the commit.
Commit subject line (first line of commit message).
ISO-8601 timestamp of commit author date.
Task ID from Task: trailer (e.g., "TASK-F0-003"). null if no Task trailer.
Artifact IDs from Refs: trailer.
Array of all relationships between artifacts. ID of the referencing artifact.
ID of the referenced artifact.
Relationship type:
implements - UC implements REQorchestrates - WF orchestrates APIverifies - BDD verifies REQ/UCguarantees - INV guarantees domain ruledecides - ADR decides architecturedecomposes - TASK decomposes FASEimplemented-by - Task Refs fieldimplemented-by-code - Code references artifacttested-by - Test references artifactimplemented-by-commit - Commit references artifactinferred-implements - v4 only. Inferred code→artifact linkreads-from - FASE reads spectraces-to - Generic cross-reference File where the reference was found.
Line number of the reference.
Aggregate statistics about the graph. Total count of all artifacts.
Count per artifact type (e.g., {"REQ": 330, "UC": 41}).
Total count of all relationships.
Coverage metrics as {count, total, percentage} objects:
reqsWithUCs - REQs with at least one UCreqsWithBDD - REQs with at least one BDDreqsWithTasks - REQs with at least one TASKreqsWithCode - REQs with at least one codeRefreqsWithTests - REQs with at least one testRefreqsWithCommits - REQs with at least one commitRef Artifact IDs with no incoming references.
Array of {ref, referencedIn, line} objects for references to undefined artifacts.
Code scanning statistics: {totalFiles, totalSymbols, symbolsWithRefs}.
Test scanning statistics: {totalTestFiles, totalTests, testsWithRefs}.
Commit scanning statistics: {totalCommits, commitsWithRefs, commitsWithTasks, uniqueTasksCovered}.
Classification breakdown: {byDomain, byLayer, byCategory} with counts.
v3 only. Adoption score, grade, findings counts, alignment percentage. null if no onboarding data.
v3 only. Onboarding skill data. Defaults to {"present": false} when no onboarding data exists.Whether any adoption/onboarding data exists.
Data from onboarding/ONBOARDING-REPORT.md.
Data from findings/FINDINGS-REPORT.md and reverse-engineering/INVENTORY.md.
Data from reconciliation/RECONCILIATION-REPORT.md.
Data from import/IMPORT-REPORT.md.
v4 only. Code intelligence block from /sdd:code-index. Absent by default.Show Code intelligence object
Whether code has been indexed.
ISO-8601 timestamp of last index generation.
Analysis engine: "gitnexus" or "regex-lite".
Symbol table with artifact refs, call graph participation, and community clustering.
Call relationships between symbols.
Detected execution flows.
Aggregate statistics: {totalSymbols, symbolsWithRefs, symbolsWithInferredRefs, uncoveredSymbols, totalProcesses, processesWithRefs}.
Example See the full schema reference for a complete example.
{ "$schema" : "traceability-graph-v4" , "generatedAt" : "2026-03-01T15:30:00.000Z" , "projectName" : "my-project" , "pipeline" : { "currentStage" : "task-generator" , "stages" : [ { "name" : "requirements-engineer" , "status" : "done" , "lastRun" : "2026-02-25T10:00:00.000Z" , "artifactCount" : 330 } ] }, "artifacts" : [ { "id" : "REQ-EXT-001" , "type" : "REQ" , "category" : "EXT" , "title" : "Extract text from PDF files" , "file" : "requirements/REQUIREMENTS.md" , "line" : 42 , "priority" : "Must Have" , "stage" : "requirements-engineer" , "classification" : { "businessDomain" : "Extraction & Processing" , "technicalLayer" : "Backend" , "functionalCategory" : "Functional" }, "codeRefs" : [], "testRefs" : [], "commitRefs" : [] } ], "relationships" : [], "statistics" : { "totalArtifacts" : 800 , "byType" : { "REQ" : 330 }, "totalRelationships" : 1200 , "traceabilityCoverage" : { "reqsWithUCs" : { "count" : 280 , "total" : 330 , "percentage" : 84.8 } }, "orphans" : [], "brokenReferences" : [], "codeStats" : { "totalFiles" : 85 , "totalSymbols" : 340 , "symbolsWithRefs" : 120 }, "testStats" : { "totalTestFiles" : 42 , "totalTests" : 285 , "testsWithRefs" : 95 }, "commitStats" : { "totalCommits" : 48 , "commitsWithRefs" : 42 , "commitsWithTasks" : 45 , "uniqueTasksCovered" : 40 }, "classificationStats" : { "byDomain" : { "Extraction & Processing" : 45 }, "byLayer" : { "Backend" : 80 }, "byCategory" : { "Functional" : 200 } }, "adoptionStats" : null } }
Usage Generation Generate the graph with the dashboard skill:
This scans all pipeline directories and produces both traceability-graph.json and index.html.
Consumption MCP Server : The graph is loaded by the MCP server at server/src/graph-loader.ts with file watching and graceful degradation.Dashboard : The HTML dashboard reads the graph to render the interactive UI.Context Hook : The sdd-augment-hook.js uses the graph to inject traceability context into file operations.
Skills : /sdd:dashboard, /sdd:code-indexHooks : H5 (sdd-augment-hook)MCP server : All 5 tools and 7 resourcesReference : graph-schema.md