docs: define graph data model (#322)

flyingrobots · flyingrobots · commit c5cf9562e416 · 2026-05-31T21:40:31.000-07:00
diff --git a/GRAPH_SCHEMA.md b/GRAPH_SCHEMA.md
@@ -6,6 +6,7 @@
 >
 > This document is the graph contract, not the canonical product narrative.
 > Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain supported, but they are not the current center of the product story.
+> The product-level node and edge vocabulary lives in [docs/design/graph-data-model.md](docs/design/graph-data-model.md).
 
 ---
 
diff --git a/README.md b/README.md
@@ -175,6 +175,7 @@ Canonical docs:
 - [docs/adr/ADR-0006.md](docs/adr/ADR-0006.md)
 - [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md)
 - [docs/design/git-mind.md](docs/design/git-mind.md)
+- [docs/design/graph-data-model.md](docs/design/graph-data-model.md)
 - [docs/design/feature-profiles/README.md](docs/design/feature-profiles/README.md)
 - [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md)
 - [docs/adr/](docs/adr/)
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -147,6 +147,7 @@ Primary references:
 
 - [docs/design/git-mind.md](docs/design/git-mind.md)
 - [docs/design/h1-semantic-bootstrap.md](docs/design/h1-semantic-bootstrap.md)
+- [docs/design/graph-data-model.md](docs/design/graph-data-model.md)
 - [docs/design/feature-profiles/README.md](docs/design/feature-profiles/README.md)
 - [docs/design/git-warp-upgrade-audit.md](docs/design/git-warp-upgrade-audit.md)
 - [docs/design/repo-fixture-strategy.md](docs/design/repo-fixture-strategy.md)
diff --git a/docs/README.md b/docs/README.md
@@ -12,6 +12,7 @@ These describe what Git Mind is now and how work should be judged:
 - [ROADMAP.md](../ROADMAP.md) — active Hills, supporting lanes, and playback cadence
 - [Git Mind Product Frame](./design/git-mind.md) — IBM Design Thinking style product frame
 - [Hill 1 Semantic Bootstrap Spec](./design/h1-semantic-bootstrap.md) — first executable Hill 1 slice
+- [Graph Data Model](./design/graph-data-model.md) — canonical product node and edge vocabulary
 - [Feature Profiles](./design/feature-profiles/README.md) — per-feature IBM Design Thinking profiles with executable test plans
 - [git-warp Upgrade Audit](./design/git-warp-upgrade-audit.md) — next enabling cycle before major Hill 1 implementation
 - [Git Mind North Star](./VISION_NORTH_STAR.md) — longer-form strategic articulation
diff --git a/docs/design/feature-profiles/README.md b/docs/design/feature-profiles/README.md
@@ -10,6 +10,7 @@ profile uses the same IBM Design Thinking frame:
 - relevant Hill or supporting lane
 - user stories
 - requirements
+- graph data model usage
 - playback evidence
 - test plan
 
@@ -85,6 +86,18 @@ Each profile should name tests in these buckets.
 - Playback evidence: the human or agent demonstration that proves the Hill
   moved, not just that code ran.
 
+## Shared Graph Model
+
+All feature profiles use the canonical vocabulary in
+[Graph Data Model](../graph-data-model.md). Feature-specific graph sections
+should show:
+
+- which node prefixes the feature reads or writes
+- which edge types the feature creates, updates, filters, or cites
+- where confidence, provenance, review, or observer metadata enters the model
+- a Mermaid example that a reviewer can compare against the feature's test
+  fixtures and golden artifacts
+
 ## Fixture Strategy
 
 Repository-shaped behavior should use the canonical fixture strategy:
diff --git a/docs/design/feature-profiles/agent-contracts.md b/docs/design/feature-profiles/agent-contracts.md
@@ -52,6 +52,20 @@ Playback evidence:
 - Breaking changes require versioning.
 - Human formatting changes must not break JSON contracts.
 
+## Graph Data Model Usage
+
+Agent contracts expose [Graph Data Model](../graph-data-model.md) through
+machine-readable payloads. Agents should receive canonical node IDs, edge
+types, confidence, evidence, and graph refs rather than prose-only context.
+
+```mermaid
+flowchart LR
+    Agent["tool:codex"] -->|references| Contract["spec:agent-answer-contract"]
+    Contract -->|documents| Query["feature:query-receipts"]
+    Answer["doc:answer-json"] -->|references| Node["module:bootstrap"]
+    Answer -->|references| Evidence["doc:h1-semantic-bootstrap"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/artifact-inventory.md b/docs/design/feature-profiles/artifact-inventory.md
@@ -70,6 +70,22 @@ Initial artifact kinds:
 - `binary`
 - `unsupported`
 
+## Graph Data Model Usage
+
+Artifact inventory owns the first stable mapping from repository paths to
+canonical artifact and subject nodes in
+[Graph Data Model](../graph-data-model.md). It should classify what can become
+`file:`, `doc:`, `adr:`, `spec:`, `module:`, and `pkg:` nodes before inference
+tries to connect them.
+
+```mermaid
+flowchart LR
+    Package["pkg:@git-stunts/git-warp"] -->|consumed-by| Graph["module:graph"]
+    Graph -->|groups| Source["file:src/graph.js"]
+    Docs["doc:GRAPH_SCHEMA"] -->|documents| Schema["spec:graph-schema-v1"]
+    Adr["adr:0006"] -->|documents| Fixture["module:fixtures"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/bootstrap-command.md b/docs/design/feature-profiles/bootstrap-command.md
@@ -102,6 +102,22 @@ Initial JSON shape:
 - Cross-repo bootstrap.
 - Interactive terminal review UI.
 
+## Graph Data Model Usage
+
+This feature is the first producer of the canonical model in
+[Graph Data Model](../graph-data-model.md). Bootstrap creates artifact,
+subject, work, and concept nodes, then writes typed edges with confidence and
+evidence-oriented rationale.
+
+```mermaid
+flowchart LR
+    Readme["doc:README"] -->|documents| Cli["module:cli"]
+    Cli -->|groups| Bin["file:bin/git-mind.js"]
+    Adr["adr:0006"] -->|documents| Bootstrap["feature:semantic-bootstrap"]
+    Commit["commit:34636d3"] -->|touches| Readme
+    Readme -->|references| Issue["issue:322"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/content-on-node.md b/docs/design/feature-profiles/content-on-node.md
@@ -50,6 +50,20 @@ Playback evidence:
 - Large content limits and warnings need explicit policy.
 - Binary content support needs explicit encoding policy before expansion.
 
+## Graph Data Model Usage
+
+Content-on-node attaches Git-backed content to canonical nodes from
+[Graph Data Model](../graph-data-model.md). The node identity remains the graph
+fact; content properties provide the payload and integrity metadata.
+
+```mermaid
+flowchart LR
+    Note["doc:design-note"] -->|documents| Module["module:bootstrap"]
+    Note -->|references| Blob["metric:content-oid"]
+    Module -->|groups| File["file:src/bootstrap.js"]
+    Doctor["tool:doctor"] -->|references| Blob
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/doctor-integrity.md b/docs/design/feature-profiles/doctor-integrity.md
@@ -51,6 +51,21 @@ Playback evidence:
 - Doctor must never hide unfixable issues.
 - Repair operations must be atomic.
 
+## Graph Data Model Usage
+
+Doctor and integrity checks validate that
+[Graph Data Model](../graph-data-model.md) remains coherent. The feature reads
+canonical nodes, edges, and assertion properties, then reports structural issues
+as actionable diagnostics.
+
+```mermaid
+flowchart LR
+    Doctor["tool:git-mind-doctor"] -->|references| Graph["module:graph"]
+    Graph -->|groups| File["file:src/graph.js"]
+    Edge["file:missing.js implements spec:bootstrap-json"] -->|references| Problem["event:dangling-edge"]
+    Problem -->|blocks| Healthy["metric:graph-health"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/entity-extraction.md b/docs/design/feature-profiles/entity-extraction.md
@@ -67,6 +67,21 @@ Candidate properties:
 - `gitmind.lastSeen`
 - `gitmind.kind`
 
+## Graph Data Model Usage
+
+Entity extraction creates the node side of
+[Graph Data Model](../graph-data-model.md). It should emit stable IDs and node
+properties before relationship inference adds semantic edges.
+
+```mermaid
+flowchart LR
+    PathA["README.md"] --> Readme["doc:README"]
+    PathB["docs/adr/ADR-0006.md"] --> Adr["adr:0006"]
+    PathC["src/graph.js"] --> File["file:src/graph.js"]
+    PackageJson["package.json"] --> Package["pkg:@git-stunts/git-warp"]
+    Heading["Semantic Bootstrap"] --> Concept["concept:semantic-bootstrap"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/extensions-runtime.md b/docs/design/feature-profiles/extensions-runtime.md
@@ -52,6 +52,22 @@ Playback evidence:
 - Manifest errors must be typed and actionable.
 - Extension loading must not create hidden network or host coupling.
 
+## Graph Data Model Usage
+
+Extensions can read or propose writes to
+[Graph Data Model](../graph-data-model.md), but their output must use canonical
+prefixes, edge types, confidence, and origin metadata. Extension-specific
+semantics should be modeled as `tool:`, `spec:`, or documented feature nodes
+before adding new vocabulary.
+
+```mermaid
+flowchart LR
+    Extension["tool:markdown-extension"] -->|augments| Bootstrap["feature:semantic-bootstrap"]
+    Extension -->|references| Manifest["spec:extension-manifest"]
+    Doc["doc:README"] -->|documents| Module["module:cli"]
+    Extension -->|references| Doc
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/graph-substrate.md b/docs/design/feature-profiles/graph-substrate.md
@@ -54,6 +54,21 @@ Playback evidence:
 - Compatibility wrappers must be small and covered by tests.
 - Upgrade fixtures must run isolated from the checkout.
 
+## Graph Data Model Usage
+
+The substrate stores [Graph Data Model](../graph-data-model.md) facts in Git via
+WARP. It does not define product semantics itself; it must preserve canonical
+nodes, edges, properties, history, and observer behavior exactly enough for
+higher-level features to trust them.
+
+```mermaid
+flowchart LR
+    Warp["pkg:@git-stunts/git-warp"] -->|consumed-by| Graph["module:graph"]
+    Graph -->|groups| Adapter["file:src/graph.js"]
+    Patch["commit:graph-patch"] -->|touches| Adapter
+    Schema["doc:GRAPH_SCHEMA"] -->|documents| Graph
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/import-export-interchange.md b/docs/design/feature-profiles/import-export-interchange.md
@@ -53,6 +53,21 @@ Playback evidence:
 - Invalid imports must fail before partial writes.
 - Schema drift must be intentional and documented.
 
+## Graph Data Model Usage
+
+Import/export is the interchange boundary for
+[Graph Data Model](../graph-data-model.md). It must preserve node IDs, edge
+types, assertion properties, and schema versions without inventing a different
+portable model.
+
+```mermaid
+flowchart LR
+    Export["doc:graph-export"] -->|references| Node["module:bootstrap"]
+    Export -->|references| Edge["file:src/bootstrap.js implements spec:bootstrap-json"]
+    File["file:src/bootstrap.js"] -->|implements| Spec["spec:bootstrap-json"]
+    Import["tool:import"] -->|references| Export
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/living-map-updates.md b/docs/design/feature-profiles/living-map-updates.md
@@ -50,6 +50,20 @@ Playback evidence:
 - Incremental updates must be deterministic.
 - Stale inferred facts must not silently masquerade as current truth.
 
+## Graph Data Model Usage
+
+Living map updates keep [Graph Data Model](../graph-data-model.md) current as
+commits change artifacts. The update path should add, revise, or retire nodes
+and edges with visible provenance instead of rebuilding the graph blindly.
+
+```mermaid
+flowchart LR
+    Commit["commit:def4567"] -->|touches| File["file:src/bootstrap.js"]
+    Module["module:bootstrap"] -->|groups| File
+    Doc["doc:h1-semantic-bootstrap"] -->|documents| Module
+    Review["decision:adjust-bootstrap-edge"] -->|references| Module
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/packaging-adoption.md b/docs/design/feature-profiles/packaging-adoption.md
@@ -53,6 +53,21 @@ Playback evidence:
 - Packaging must not depend on local monorepo paths.
 - Install docs must match shipped reality.
 
+## Graph Data Model Usage
+
+Packaging and adoption do not create new graph semantics, but they must make
+[Graph Data Model](../graph-data-model.md) visible and usable. The install path
+should expose commands that create and inspect canonical nodes and edges without
+requiring users to learn the storage substrate first.
+
+```mermaid
+flowchart LR
+    Package["pkg:git-mind"] -->|consumed-by| Cli["module:cli"]
+    Cli -->|groups| Bin["file:bin/git-mind.js"]
+    Guide["doc:GUIDE"] -->|documents| Cli
+    Quickstart["doc:README"] -->|references| Guide
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/provenance-confidence.md b/docs/design/feature-profiles/provenance-confidence.md
@@ -64,6 +64,21 @@ Playback evidence:
 - Medium: strong lexical evidence or unambiguous reference.
 - Low: fuzzy association, weak convention, or ambiguous but plausible signal.
 
+## Graph Data Model Usage
+
+This feature defines the assertion metadata that makes
+[Graph Data Model](../graph-data-model.md) trustworthy. The edge is the claim;
+confidence, rationale, origin, detector, and evidence explain why the claim
+exists.
+
+```mermaid
+flowchart LR
+    File["file:src/bootstrap.js"] -->|implements| Spec["spec:bootstrap-json"]
+    Evidence["doc:h1-semantic-bootstrap"] -->|documents| Spec
+    Detector["tool:bootstrap-detector"] -->|references| Evidence
+    Reviewer["person:reviewer"] -->|references| Decision["decision:accept-bootstrap-edge"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/query-receipts.md b/docs/design/feature-profiles/query-receipts.md
@@ -66,6 +66,22 @@ Playback evidence:
 - What issue or PR references shaped this path?
 - What weak or missing connections should I review?
 
+## Graph Data Model Usage
+
+Query receipts read the canonical nodes and edges from
+[Graph Data Model](../graph-data-model.md) and return answer payloads that cite
+the exact assertions used. A receipt should identify the answer node, the edge
+path, confidence, and the evidence behind each inferred step.
+
+```mermaid
+flowchart LR
+    Question["spec:question-implements"] -->|references| Target["spec:bootstrap-json"]
+    Impl["file:src/bootstrap.js"] -->|implements| Target
+    Doc["doc:h1-semantic-bootstrap"] -->|documents| Target
+    Answer["doc:answer-json"] -->|references| Impl
+    Answer -->|references| Doc
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/relationship-inference.md b/docs/design/feature-profiles/relationship-inference.md
@@ -59,6 +59,22 @@ Initial inference should prefer precision over breadth. It is acceptable for the
 first bootstrap map to be incomplete if the relationships it does emit are
 understandable and reviewable.
 
+## Graph Data Model Usage
+
+Relationship inference is the primary edge producer for
+[Graph Data Model](../graph-data-model.md). It must choose the most specific
+edge type that the evidence supports and record confidence for every inferred
+assertion.
+
+```mermaid
+flowchart LR
+    Doc["doc:h1-semantic-bootstrap"] -->|documents| Feature["feature:semantic-bootstrap"]
+    Source["file:src/bootstrap.js"] -->|implements| Spec["spec:bootstrap-json"]
+    Commit["commit:def4567"] -->|touches| Source
+    Doc -->|references| Issue["issue:305"]
+    Feature -->|depends-on| Fixture["feature:repo-fixtures"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/repo-fixture-builder.md b/docs/design/feature-profiles/repo-fixture-builder.md
@@ -60,6 +60,20 @@ Playback evidence:
 - Archived binary snapshots must be exceptional and justified.
 - Helpers must not hide meaningful semantic setup behind magic defaults.
 
+## Graph Data Model Usage
+
+The fixture builder creates repositories and expected graph shapes for
+[Graph Data Model](../graph-data-model.md). It should make canonical nodes,
+edges, confidence bands, and broken cases easy to express in tests.
+
+```mermaid
+flowchart LR
+    Fixture["tool:repo-fixture-builder"] -->|references| Base["event:minimal-doc-code"]
+    Base -->|references| Readme["doc:README"]
+    Readme -->|documents| Module["module:cli"]
+    Module -->|groups| File["file:bin/git-mind.js"]
+```
+
 ## Test Plan
 
 Fixtures:
diff --git a/docs/design/feature-profiles/review-refinement.md b/docs/design/feature-profiles/review-refinement.md
diff --git a/docs/design/feature-profiles/time-travel-diff.md b/docs/design/feature-profiles/time-travel-diff.md
diff --git a/docs/design/feature-profiles/trust-observers.md b/docs/design/feature-profiles/trust-observers.md
diff --git a/docs/design/feature-profiles/views-lenses.md b/docs/design/feature-profiles/views-lenses.md
diff --git a/docs/design/graph-data-model.md b/docs/design/graph-data-model.md
diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@`
`6`	`6`	`>`
`7`	`7`	`> This document is the graph contract, not the canonical product narrative.`
`8`	`8`	`> Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain supported, but they are not the current center of the product story.`
	`9`	`+> The product-level node and edge vocabulary lives in [docs/design/graph-data-model.md](docs/design/graph-data-model.md).`
`9`	`10`
`10`	`11`	`---`
`11`	`12`