docs: address graph model review findings (#322)

Author: flyingrobots

GRAPH_SCHEMA.md

@@ -5,8 +5,11 @@
 > Ref: #180 (BDK-001)
 >
 > 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).
+> 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).
 
 ---
 

ROADMAP.md

@@ -124,7 +124,6 @@ Goal:
 
 Deliverables:
 
-- git-warp audit / upgrade cycle before major Hill 1 implementation (issue [#312](https://github.com/flyingrobots/git-mind/issues/312))
 - bootstrap command contract with default write behavior and `--dry-run`
 - canonical repo fixture substrate for repository-shaped bootstrap scenarios (issue [#311](https://github.com/flyingrobots/git-mind/issues/311))
 - repo-local artifact inventory and scan boundaries
@@ -135,6 +134,12 @@ Deliverables:
 - acceptance criteria translated into failing executable tests (issue [#310](https://github.com/flyingrobots/git-mind/issues/310))
 - implementation issues `#304` through `#307`, plus enabling test issues [#310](https://github.com/flyingrobots/git-mind/issues/310) and [#311](https://github.com/flyingrobots/git-mind/issues/311), moved into merged runnable behavior
 
+Completed enabling work:
+
+- git-warp audit and upgrade cycle completed in issue [#312](https://github.com/flyingrobots/git-mind/issues/312)
+- isolated git-warp v17 upgrade fixture harness completed in issue
+  [#320](https://github.com/flyingrobots/git-mind/issues/320)
+
 Exit criteria:
 
 - `git mind bootstrap` runs end-to-end on a representative unfamiliar repository

docs/README.md

@@ -13,8 +13,10 @@ These describe what Git Mind is now and how work should be judged:
 - [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
+- [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) — completed
+  enabling cycle before major Hill 1 implementation
 - [Git Mind North Star](./VISION_NORTH_STAR.md) — longer-form strategic articulation
 - [ADR-0005](./adr/ADR-0005.md) — official planning and governance model
 - [ADR-0006](./adr/ADR-0006.md) — official delivery cycle and tests-as-spec model

docs/design/feature-profiles/doctor-integrity.md

@@ -62,7 +62,10 @@ as actionable diagnostics.
 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"]
+    Missing["file:missing.js"] -->|implements| Spec["spec:bootstrap-json"]
+    Problem["event:dangling-edge"] -->|references| Missing
+    Problem -->|references| Spec
+    Doctor -->|references| Problem
     Problem -->|blocks| Healthy["metric:graph-health"]
 ```
 

docs/design/feature-profiles/entity-extraction.md

@@ -26,7 +26,8 @@ Hill:
 Playback evidence:
 
 - Bootstrap creates useful `file:`, `doc:`, `adr:`, conservative `module:`,
-  `commit:`, `issue:`, and `pr:` nodes from repo-local evidence.
+  `issue:`, and `pr:` nodes from repo-local evidence. History-aware bootstrap
+  may also create system-owned `commit:` nodes through Git Mind's system writer.
 
 ## User Stories
 
@@ -75,11 +76,11 @@ 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"]
+    Readme["doc:README"]
+    Adr["adr:0006"]
+    File["file:src/graph.js"]
+    Package["pkg:@git-stunts/git-warp"]
+    Concept["concept:semantic-bootstrap"]
 ```
 
 ## Test Plan
@@ -97,7 +98,8 @@ Golden path:
 - Markdown docs become `doc:` nodes.
 - ADR files become `adr:` nodes.
 - Package boundaries become conservative `module:` nodes.
-- Commit metadata produces `commit:` nodes when bootstrap includes history.
+- Commit metadata produces system-owned `commit:` nodes when bootstrap includes
+  history.
 - `#123` and `PR #45` references create placeholder `issue:` and `pr:` nodes.
 
 Edge cases:
@@ -113,6 +115,8 @@ Known failures:
 - Invalid node IDs must fail or be normalized with explicit reason.
 - Collisions must be reported and deterministic.
 - Missing package metadata must prevent module inference rather than guessing.
+- YAML/frontmatter imports that try to author `commit:` or `epoch:` nodes must
+  remain rejected by the graph schema.
 
 Fuzz:
 

docs/design/feature-profiles/import-export-interchange.md

@@ -63,8 +63,9 @@ 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"]
+    Export -->|references| File
+    Export -->|references| Spec
     Import["tool:import"] -->|references| Export
 ```
 

docs/design/feature-profiles/query-receipts.md

@@ -70,8 +70,9 @@ Playback evidence:
 
 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.
+the exact assertions used. A receipt should identify the answer node, the
+`(source, target, type)` assertion key, confidence, and the evidence behind each
+inferred step.
 
 ```mermaid
 flowchart LR
@@ -93,7 +94,7 @@ Fixtures:
 
 Golden path:
 
-- Query returns direct answer with receipt edge IDs and provenance.
+- Query returns direct answer with assertion keys and provenance.
 - Query returns inferred answer with confidence and evidence.
 - Query returns no-answer result with suggested follow-up.
 - JSON validates against a query-answer schema.

docs/design/feature-profiles/views-lenses.md

@@ -61,7 +61,7 @@ and edge types without creating alternate semantics.
 
 ```mermaid
 flowchart LR
-    Architecture["feature:architecture-view"] --> Module["module:graph"]
+    Architecture["feature:architecture-view"] -->|references| Module["module:graph"]
     Module -->|groups| Source["file:src/graph.js"]
     Doc["doc:GRAPH_SCHEMA"] -->|documents| Spec["spec:graph-schema-v1"]
     Module -->|depends-on| Package["pkg:@git-stunts/git-warp"]

docs/design/graph-data-model.md

@@ -60,9 +60,9 @@ flowchart LR
     Artifact["Artifact nodes"] -->|documents| Subject["Subject nodes"]
     Work["Work nodes"] -->|touches| Artifact
     Subject -->|depends-on| Dependency["Dependency nodes"]
-    Assertion["Edge assertion"] -->|references| Evidence["Evidence artifact"]
+    Evidence["doc:evidence"] -->|references| Artifact
     Reviewer["person:reviewer"] -->|references| Decision["decision:review"]
-    Decision -->|documents| Assertion
+    Decision -->|references| Subject
 ```
 
 The local Git repository is the graph scope. In v1, the local repository itself
@@ -86,68 +86,154 @@ stable, human-readable, and derived from repo artifacts whenever possible.
 
 ### Artifact Nodes
 
-| Prefix | Use | Example | Typical properties |
-|--------|-----|---------|--------------------|
-| `file:` | Repo file path | `file:src/graph.js` | `path`, `language`, `artifactKind`, `hash` |
-| `doc:` | General documentation artifact | `doc:README` | `path`, `title`, `heading`, `artifactKind` |
-| `adr:` | Architecture decision record | `adr:0006` | `path`, `title`, `status`, `date` |
-| `spec:` | Product, API, schema, or behavior spec | `spec:bootstrap-json` | `path`, `title`, `schemaVersion` |
-| `commit:` | Git commit discovered by history scan | `commit:34636d3` | `sha`, `author`, `date`, `summary` |
-| `epoch:` | System temporal marker for historical views | `epoch:34636d3` | `ref`, `tick`, `createdAt` |
+- `file:` identifies a repo file path.
+  Example: `file:src/graph.js`.
+  Typical properties: `path`, `language`, `artifactKind`, `hash`.
+- `doc:` identifies a general documentation artifact.
+  Example: `doc:README`.
+  Typical properties: `path`, `title`, `heading`, `artifactKind`.
+- `adr:` identifies an architecture decision record.
+  Example: `adr:0006`.
+  Typical properties: `path`, `title`, `status`, `date`.
+- `spec:` identifies a product, API, schema, or behavior spec.
+  Example: `spec:bootstrap-json`.
+  Typical properties: `path`, `title`, `schemaVersion`.
 
 ### Subject Nodes
 
-| Prefix | Use | Example | Typical properties |
-|--------|-----|---------|--------------------|
-| `module:` | Internal module or subsystem | `module:bootstrap` | `name`, `path`, `package`, `owner` |
-| `crate:` | Internal package when the repo uses crate language | `crate:git-mind-core` | `name`, `path`, `language` |
-| `pkg:` | External package or dependency | `pkg:@git-stunts/git-warp` | `name`, `version`, `ecosystem` |
-| `concept:` | Named idea that appears across artifacts | `concept:semantic-bootstrap` | `name`, `aliases` |
-| `decision:` | Review or architecture decision event | `decision:bootstrap-contract` | `action`, `reviewer`, `timestamp` |
+- `module:` identifies an internal module or subsystem.
+  Example: `module:bootstrap`.
+  Typical properties: `name`, `path`, `package`, `owner`.
+- `crate:` identifies an internal package when the repo uses crate language.
+  Example: `crate:git-mind-core`.
+  Typical properties: `name`, `path`, `language`.
+- `pkg:` identifies an external package or dependency.
+  Example: `pkg:@git-stunts/git-warp`.
+  Typical properties: `name`, `version`, `ecosystem`.
+- `concept:` identifies a named idea that appears across artifacts.
+  Example: `concept:semantic-bootstrap`.
+  Typical properties: `name`, `aliases`.
+- `decision:` identifies a review or architecture decision event.
+  Example: `decision:bootstrap-contract`.
+  Typical properties: `action`, `reviewer`, `timestamp`.
 
 ### Work Nodes
 
-| Prefix | Use | Example | Typical properties |
-|--------|-----|---------|--------------------|
-| `issue:` | GitHub or tracker issue | `issue:322` | `number`, `title`, `state`, `url` |
-| `pr:` | Pull request | `pr:323` | `number`, `title`, `state`, `url` |
-| `task:` | Local work item or actionable unit | `task:h1-bootstrap-tests` | `title`, `status`, `owner` |
-| `feature:` | Product feature grouping | `feature:query-receipts` | `title`, `hill`, `status` |
-| `milestone:` | Historical or release grouping | `milestone:h1` | `title`, `status` |
-| `phase:` | Phase alias used by legacy views | `phase:stabilize` | `title`, `status` |
+- `issue:` identifies a GitHub or tracker issue.
+  Example: `issue:322`.
+  Typical properties: `number`, `title`, `state`, `url`.
+- `pr:` identifies a pull request.
+  Example: `pr:323`.
+  Typical properties: `number`, `title`, `state`, `url`.
+- `task:` identifies a local work item or actionable unit.
+  Example: `task:h1-bootstrap-tests`.
+  Typical properties: `title`, `status`, `owner`.
+- `feature:` identifies a product feature grouping.
+  Example: `feature:query-receipts`.
+  Typical properties: `title`, `hill`, `status`.
+- `milestone:` identifies a historical or release grouping.
+  Example: `milestone:h1`.
+  Typical properties: `title`, `status`.
+- `phase:` identifies a phase alias used by legacy views.
+  Example: `phase:stabilize`.
+  Typical properties: `title`, `status`.
 
 ### Actor And Tool Nodes
 
-| Prefix | Use | Example | Typical properties |
-|--------|-----|---------|--------------------|
-| `person:` | Human actor or reviewer | `person:james` | `handle`, `displayName` |
-| `tool:` | Tool, agent, service, or local integration | `tool:codex` | `name`, `version`, `capabilities` |
-| `event:` | Named event in repo history | `event:bootstrap-playback` | `date`, `summary` |
-| `metric:` | Measured value or health indicator | `metric:graph-density` | `name`, `unit`, `value` |
+- `person:` identifies a human actor or reviewer.
+  Example: `person:james`.
+  Typical properties: `handle`, `displayName`.
+- `tool:` identifies a tool, agent, service, or local integration.
+  Example: `tool:codex`.
+  Typical properties: `name`, `version`, `capabilities`.
+- `event:` identifies a named event in repo history.
+  Example: `event:bootstrap-playback`.
+  Typical properties: `date`, `summary`.
+- `metric:` identifies a measured value or health indicator.
+  Example: `metric:graph-density`.
+  Typical properties: `name`, `unit`, `value`.
+
+### System-Owned Nodes
+
+The schema reserves some prefixes for Git Mind system writers:
+
+- `commit:` identifies a Git commit discovered through repository history.
+  Example: `commit:34636d3`.
+  Typical properties: `sha`, `author`, `date`, `summary`.
+- `epoch:` identifies a system temporal marker for historical views.
+  Example: `epoch:34636d3`.
+  Typical properties: `ref`, `tick`, `createdAt`.
+
+Users and import files must not author `commit:` or `epoch:` nodes directly.
+Bootstrap and history-aware features may create them only through Git Mind's
+system-owned writers, with tests that also prove YAML/frontmatter import still
+rejects those prefixes where the schema requires rejection.
 
 ## Canonical Edges
 
 Edges are directed. Direction matters because query receipts, views, and
 review flows rely on it.
 
-| Edge | Direction | Use | Example |
-|------|-----------|-----|---------|
-| `documents` | explainer -> subject | Artifact explains a subject | `doc:README -> module:cli` |
-| `references` | source -> referenced | Explicit citation or mention | `doc:README -> issue:322` |
-| `implements` | implementation -> spec or feature | Code or work realizes behavior | `file:src/bootstrap.js -> spec:bootstrap-json` |
-| `touches` | change -> artifact | Commit, PR, or issue modifies or affects artifact | `commit:34636d3 -> file:README.md` |
-| `groups` | parent -> child | Structural containment | `module:cli -> file:bin/git-mind.js` |
-| `belongs-to` | member -> group | Planning membership | `task:h1-bootstrap-tests -> feature:bootstrap` |
-| `depends-on` | dependent -> dependency | Requires dependency first | `module:query -> module:graph` |
-| `blocks` | blocker -> blocked | Work cannot proceed until blocker changes | `issue:310 -> issue:304` |
-| `consumed-by` | resource -> consumer | Dependency is consumed by a module | `pkg:@git-stunts/git-warp -> module:graph` |
-| `augments` | extension -> base | Adds capability to subject | `tool:extension -> module:git-mind` |
-| `relates-to` | source -> related | Low-specificity association | `concept:receipts -> concept:provenance` |
+- `documents`: explainer -> subject.
+  Use when an artifact explains a subject.
+  Example: `doc:README -> module:cli`.
+- `references`: source -> referenced.
+  Use for explicit citation, mention, or receipt evidence.
+  Example: `doc:README -> issue:322`.
+- `implements`: implementation -> spec or feature.
+  Use when code or work realizes behavior.
+  Example: `file:src/bootstrap.js -> spec:bootstrap-json`.
+- `touches`: change -> artifact.
+  Use when a commit, PR, or issue modifies or affects an artifact.
+  Example: `commit:34636d3 -> file:README.md`.
+- `groups`: parent -> child.
+  Use for structural containment.
+  Example: `module:cli -> file:bin/git-mind.js`.
+- `belongs-to`: member -> group.
+  Use for planning membership.
+  Example: `task:h1-bootstrap-tests -> feature:bootstrap`.
+- `depends-on`: dependent -> dependency.
+  Use when one subject requires another first.
+  Example: `module:query -> module:graph`.
+- `blocks`: blocker -> blocked.
+  Use when work cannot proceed until blocker changes.
+  Example: `issue:310 -> issue:304`.
+- `consumed-by`: resource -> consumer.
+  Use when a dependency is consumed by a module.
+  Example: `pkg:@git-stunts/git-warp -> module:graph`.
+- `augments`: extension -> base.
+  Use when one subject adds capability to another.
+  Example: `tool:extension -> module:git-mind`.
+- `relates-to`: source -> related.
+  Use only for low-specificity associations.
+  Example: `concept:receipts -> concept:provenance`.
 
 Use `relates-to` only when a stronger edge would be dishonest. If the evidence
 can justify `documents`, `references`, `implements`, `groups`, or `touches`,
 prefer the stronger type.
 
+## Assertion Identity
+
+Git Mind does not currently model edges as first-class `edge:` nodes. The
+canonical identity for an assertion is the edge tuple:
+
+```text
+(source, target, type)
+```
+
+Examples:
+
+```text
+(file:src/bootstrap.js, spec:bootstrap-json, implements)
+(doc:README, issue:322, references)
+```
+
+Query receipts, import/export contracts, diagnostics, and review decisions
+should cite this tuple key unless a future schema version deliberately adds
+first-class assertion IDs. Do not invent synthetic graph nodes such as
+`edge:abc123` or `assertion:xyz` without updating this model, the validators,
+and the affected feature profiles.
+
 ## Assertion Properties
 
 The current runtime already uses these edge properties:
@@ -165,7 +251,7 @@ Feature work should converge on these additional conventions:
 |----------|---------|
 | `origin` | `manual`, `import`, `bootstrap`, `inference`, `review`, or `extension` |
 | `detector` | Rule, parser, importer, or tool that produced the assertion |
-| `evidence` | Stable evidence references such as paths, headings, line spans, commits, or URLs |
+| `evidence` | Stable paths, headings, line spans, commits, or URLs |
 | `observer` | Trust or observer context used when the edge was read or written |
 | `schemaVersion` | Machine contract version for structured edge metadata |
 
@@ -202,8 +288,9 @@ flowchart LR
 ```mermaid
 flowchart LR
     Question["spec:query-question"] -->|references| Target["module:bootstrap"]
-    Answer["doc:answer-json"] -->|references| EdgeA["doc:README documents module:bootstrap"]
-    EdgeA -->|references| Evidence["file:README.md"]
+    Doc["doc:README"] -->|documents| Target
+    Answer["doc:answer-json"] -->|references| Doc
+    Answer -->|references| Target
     Reviewer["person:maintainer"] -->|references| Answer
 ```
 
@@ -212,7 +299,7 @@ flowchart LR
 ```mermaid
 flowchart LR
     Suggestion["file:src/bootstrap.js"] -->|implements| Contract["spec:bootstrap-json"]
-    Decision["decision:accept-bootstrap-edge"] -->|documents| Contract
+    Decision["decision:accept-bootstrap-edge"] -->|references| Contract
     Decision -->|references| Suggestion
     Reviewer["person:reviewer"] -->|references| Decision
 ```