From 34636d331e5a7967097011b1929f2862f8f3359d Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 31 May 2026 20:51:25 -0700 Subject: [PATCH 1/5] docs: add feature profile test plans (#322) --- README.md | 1 + ROADMAP.md | 1 + docs/README.md | 2 + docs/design/feature-profiles/README.md | 118 ++++++++++++ .../feature-profiles/agent-contracts.md | 112 ++++++++++++ .../feature-profiles/artifact-inventory.md | 133 ++++++++++++++ .../feature-profiles/bootstrap-command.md | 171 ++++++++++++++++++ .../feature-profiles/content-on-node.md | 111 ++++++++++++ .../feature-profiles/doctor-integrity.md | 110 +++++++++++ .../feature-profiles/entity-extraction.md | 129 +++++++++++++ .../feature-profiles/extensions-runtime.md | 112 ++++++++++++ .../feature-profiles/graph-substrate.md | 115 ++++++++++++ .../import-export-interchange.md | 116 ++++++++++++ .../feature-profiles/living-map-updates.md | 110 +++++++++++ .../feature-profiles/packaging-adoption.md | 114 ++++++++++++ .../feature-profiles/provenance-confidence.md | 124 +++++++++++++ .../design/feature-profiles/query-receipts.md | 127 +++++++++++++ .../relationship-inference.md | 121 +++++++++++++ .../feature-profiles/repo-fixture-builder.md | 122 +++++++++++++ .../feature-profiles/review-refinement.md | 114 ++++++++++++ .../feature-profiles/time-travel-diff.md | 112 ++++++++++++ .../feature-profiles/trust-observers.md | 110 +++++++++++ docs/design/feature-profiles/views-lenses.md | 115 ++++++++++++ docs/design/h1-semantic-bootstrap.md | 1 + 24 files changed, 2401 insertions(+) create mode 100644 docs/design/feature-profiles/README.md create mode 100644 docs/design/feature-profiles/agent-contracts.md create mode 100644 docs/design/feature-profiles/artifact-inventory.md create mode 100644 docs/design/feature-profiles/bootstrap-command.md create mode 100644 docs/design/feature-profiles/content-on-node.md create mode 100644 docs/design/feature-profiles/doctor-integrity.md create mode 100644 docs/design/feature-profiles/entity-extraction.md create mode 100644 docs/design/feature-profiles/extensions-runtime.md create mode 100644 docs/design/feature-profiles/graph-substrate.md create mode 100644 docs/design/feature-profiles/import-export-interchange.md create mode 100644 docs/design/feature-profiles/living-map-updates.md create mode 100644 docs/design/feature-profiles/packaging-adoption.md create mode 100644 docs/design/feature-profiles/provenance-confidence.md create mode 100644 docs/design/feature-profiles/query-receipts.md create mode 100644 docs/design/feature-profiles/relationship-inference.md create mode 100644 docs/design/feature-profiles/repo-fixture-builder.md create mode 100644 docs/design/feature-profiles/review-refinement.md create mode 100644 docs/design/feature-profiles/time-travel-diff.md create mode 100644 docs/design/feature-profiles/trust-observers.md create mode 100644 docs/design/feature-profiles/views-lenses.md diff --git a/README.md b/README.md index 9005376..323594a 100644 --- 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/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 index 9d13434..0c3c83a 100644 --- 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/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) - issue [#303](https://github.com/flyingrobots/git-mind/issues/303) diff --git a/docs/README.md b/docs/README.md index 5dea030..eb33668 100644 --- 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 +- [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 - [ADR-0005](./adr/ADR-0005.md) — official planning and governance model @@ -80,6 +81,7 @@ When planning work, start with: 2. jobs to be done 3. Hills 4. playback evidence +5. the relevant feature profile and its test plan Do not start with architecture breadth, an old milestone, or a flat pile of backlog items. diff --git a/docs/design/feature-profiles/README.md b/docs/design/feature-profiles/README.md new file mode 100644 index 0000000..5f89254 --- /dev/null +++ b/docs/design/feature-profiles/README.md @@ -0,0 +1,118 @@ +# Git Mind Feature Profiles + +Status: draft planning set for issue #322 + +This directory breaks the Git Mind product surface into feature profiles. Each +profile uses the same IBM Design Thinking frame: + +- sponsor user +- job to be done +- relevant Hill or supporting lane +- user stories +- requirements +- playback evidence +- test plan + +The intent is to keep future implementation work from starting as an +architecture exercise. A feature is ready to implement only when the profile can +explain who it helps, what repository-understanding job it improves, and which +tests prove the claim. + +## Sponsor User + +The shared sponsor user for this profile set is a technical lead, staff +engineer, architect, or autonomous coding agent entering an unfamiliar +repository and needing a trustworthy semantic map quickly. + +## Product Hills + +- Hill 1: Zero-input semantic bootstrap +- Hill 2: Queryable answers with receipts +- Hill 3: Living map with low manual upkeep + +Supporting lanes exist to strengthen those Hills. They are not product centers +by themselves. + +## Profile Catalog + +### Hill 1: Semantic Bootstrap + +- [Bootstrap Command](./bootstrap-command.md) +- [Repo Fixture Builder](./repo-fixture-builder.md) +- [Artifact Inventory](./artifact-inventory.md) +- [Entity Extraction](./entity-extraction.md) +- [Relationship Inference](./relationship-inference.md) +- [Provenance And Confidence](./provenance-confidence.md) +- [Review Refinement](./review-refinement.md) + +### Hill 2: Queryable Answers With Receipts + +- [Query Receipts](./query-receipts.md) +- [Views And Lenses](./views-lenses.md) +- [Time Travel And Semantic Diff](./time-travel-diff.md) +- [Import Export Interchange](./import-export-interchange.md) +- [Agent Contracts](./agent-contracts.md) + +### Hill 3: Living Map With Low Manual Upkeep + +- [Living Map Updates](./living-map-updates.md) +- [Doctor And Integrity](./doctor-integrity.md) +- [Trust And Observer Contexts](./trust-observers.md) + +### Supporting Lanes + +- [Graph Substrate](./graph-substrate.md) +- [Content On Node](./content-on-node.md) +- [Extensions Runtime](./extensions-runtime.md) +- [Packaging And Adoption](./packaging-adoption.md) + +## Common Test Plan Taxonomy + +Each profile should name tests in these buckets. + +- Fixtures: repository or graph shapes needed to test the feature. +- Golden path: expected behavior on representative clean inputs. +- Edge cases: valid but tricky inputs. +- Known failures: invalid inputs, ambiguity, missing dependencies, or blocked + features that must fail predictably. +- Regression cases: bugs or review findings that must not return. +- Fuzz cases: generated or randomized inputs that probe parser, scanner, or + graph assumptions. +- Stress cases: large or deep scenarios that protect performance and memory + behavior. +- Golden artifacts: stable snapshots, schema samples, or CLI output contracts + that can be compared over time. +- Playback evidence: the human or agent demonstration that proves the Hill + moved, not just that code ran. + +## Fixture Strategy + +Repository-shaped behavior should use the canonical fixture strategy: + +1. fluent repo builder first +2. reusable base repos second +3. scenario overlays for history, ambiguity, and references +4. archived snapshots only when exact Git object state is the subject + +Feature profiles may request new base repos or overlays. They should not +invent one-off setup patterns unless the risk is truly local to the test. + +## Implementation Sequencing + +The recommended next implementation sequence remains: + +1. Bootstrap command contract and JSON output +2. Fixture builder support needed by bootstrap tests +3. Artifact inventory +4. Entity extraction +5. Relationship inference +6. Provenance and confidence surfacing +7. Review refinement and query receipts + +That sequence keeps Hill 1 executable before expanding into richer query and +living-map work. + +## Review Rule + +When a feature profile and implementation disagree, update the profile or stop +the implementation. Silent divergence is product debt. diff --git a/docs/design/feature-profiles/agent-contracts.md b/docs/design/feature-profiles/agent-contracts.md new file mode 100644 index 0000000..0088df4 --- /dev/null +++ b/docs/design/feature-profiles/agent-contracts.md @@ -0,0 +1,112 @@ +# Feature Profile: Agent Contracts + +Status: draft for Hill 2 implementation + +Related: + +- [CLI Contracts](../../contracts/CLI_CONTRACTS.md) +- [Git Mind Product Frame](../git-mind.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- An autonomous coding agent operating on repository knowledge. + +Job to be done: + +- When I use Git Mind as a machine-facing contract boundary, give me stable + commands, schemas, error behavior, and receipts I can trust. + +Hill: + +- Hill 2: Queryable answers with receipts. + +Playback evidence: + +- An agent can call Git Mind commands, parse JSON responses, handle typed + errors, and cite receipts without prompt-specific guesswork. + +## User Stories + +- As an agent, I can request JSON for every read-oriented command. +- As an agent, I can validate responses against schemas. +- As an agent, I can tell no-answer, low-confidence answer, and command failure + apart. +- As a maintainer, I can detect contract drift in CI. + +## Requirements + +### Functional + +- Every machine-facing JSON output must include `schemaVersion`. +- CLI commands must have predictable exit codes and typed error envelopes. +- Schemas must exist for stable command families. +- Contract tests must exercise representative command output. +- Agent-facing docs must state which commands are stable, transitional, or + experimental. + +### Non-Functional + +- Contracts must be deterministic. +- Breaking changes require versioning. +- Human formatting changes must not break JSON contracts. + +## Test Plan + +Fixtures: + +- `contract-canary-repo` +- `no-answer-repo` +- `invalid-command-repo` +- `large-output-repo` + +Golden path: + +- JSON outputs validate against schemas. +- Error outputs distinguish usage, validation, graph, and environment failures. +- Contract canaries cover status, nodes, views, export, import, review, diff, + content, and future query responses. + +Edge cases: + +- Empty graph. +- Large graph. +- No-answer query. +- Low-confidence answers. +- Observer/trust-filtered contexts. + +Known failures: + +- Missing `schemaVersion` fails CI. +- Unknown JSON field policy is explicit. +- Invalid command args return typed error. + +Fuzz: + +- Generate valid and invalid command arguments. +- Generate schema-valid and schema-invalid payloads. +- Generate random graph state and validate JSON stability. + +Stress: + +- Large JSON output with bounded memory. +- Repeated command invocation from clean environment. +- Parallel command reads. + +Regression: + +- Contract snapshots remain stable. +- Error taxonomy does not collapse into generic failures. +- JSON mode never prints decorative human text. + +Golden artifacts: + +- JSON schema files. +- Golden command outputs. +- Error envelope snapshots. + +Playback: + +- A coding agent can use Git Mind as a deterministic repo-knowledge API instead + of relying on fragile prompt context. diff --git a/docs/design/feature-profiles/artifact-inventory.md b/docs/design/feature-profiles/artifact-inventory.md new file mode 100644 index 0000000..2022161 --- /dev/null +++ b/docs/design/feature-profiles/artifact-inventory.md @@ -0,0 +1,133 @@ +# Feature Profile: Artifact Inventory + +Status: draft for Hill 1 implementation + +Related: + +- [Hill 1 Semantic Bootstrap Spec](../h1-semantic-bootstrap.md) +- issue [#306](https://github.com/flyingrobots/git-mind/issues/306) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent entering an unfamiliar repository. + +Job to be done: + +- When Git Mind scans a repo, identify the artifacts worth reasoning about and + ignore noise without requiring custom configuration first. + +Hill: + +- Hill 1: Zero-input semantic bootstrap. + +Playback evidence: + +- On a representative repo, the inventory correctly classifies source files, + Markdown docs, ADRs, key project files, commit history, and repo-local + references while excluding generated and vendored noise. + +## User Stories + +- As a user, I can run bootstrap without telling Git Mind where every source and + doc directory lives. +- As an agent, I can inspect inventory JSON before inference and understand what + the scanner considered. +- As a maintainer, I can see warnings for skipped or ambiguous artifacts. + +## Requirements + +### Functional + +- Walk the repository file tree using Git-aware boundaries. +- Respect `.gitignore` and internal scan excludes. +- Classify source files, Markdown docs, ADR docs, key project files, package + manifests, and binary/unsupported files. +- Extract basic metadata: path, kind, size, language, hash, and reason. +- Capture recent commit metadata needed by later inference. +- Surface skipped artifacts with reason codes. + +### Non-Functional + +- Inventory order must be deterministic. +- Scanner must avoid loading huge files into memory by default. +- Scan policy must be explainable in JSON output. +- The first version must be local-only and credential-free. + +## Classification Model + +Initial artifact kinds: + +- `source` +- `doc` +- `adr` +- `manifest` +- `config` +- `test` +- `generated` +- `vendor` +- `binary` +- `unsupported` + +## Test Plan + +Fixtures: + +- `minimal-doc-code` +- `adr-linked-service` +- `polyglot-service` with JS, Python, Rust, and Markdown. +- `noisy-repo` with `node_modules`, `dist`, vendored code, lockfiles, and + generated docs. + +Golden path: + +- Inventory classifies README, docs, ADRs, source, tests, and manifests. +- JSON output contains stable counts by artifact kind. +- Ignored files do not enter the inferred artifact set. + +Edge cases: + +- Uppercase `README`, nested ADR directories, empty files, very small files. +- Extensionless executable scripts. +- Markdown files with no headings. +- Binary files with misleading extensions. +- Repos with submodules or nested Git directories. + +Known failures: + +- Unreadable files must be reported with a warning or typed error. +- Broken symlinks must not crash inventory. +- Paths outside repo root must be rejected. +- Huge files over the policy limit must be skipped with a reason. + +Fuzz: + +- Generate file names with spaces, unicode-like escaped sequences, dots, and + deeply nested directories. +- Generate random binary/text prefix data to test MIME or text detection. +- Generate random ignore patterns and verify excluded paths stay excluded. + +Stress: + +- 100k path entries in a synthetic repo tree. +- 10k Markdown/source files with bounded content reads. +- Deep directory tree near platform path limits. + +Regression: + +- No traversal into `.git`. +- No inclusion of `node_modules` by default. +- No nondeterministic ordering from filesystem traversal. +- No hidden dependency on current shell working directory. + +Golden artifacts: + +- Inventory JSON for `minimal-doc-code`, `adr-linked-service`, and + `noisy-repo`. +- Skipped-artifact reason-code catalog. + +Playback: + +- The user can read the inventory summary and say, "Yes, Git Mind scanned the + repo I care about and ignored the obvious noise." diff --git a/docs/design/feature-profiles/bootstrap-command.md b/docs/design/feature-profiles/bootstrap-command.md new file mode 100644 index 0000000..2c1a87e --- /dev/null +++ b/docs/design/feature-profiles/bootstrap-command.md @@ -0,0 +1,171 @@ +# Feature Profile: Bootstrap Command + +Status: draft for Hill 1 implementation + +Related: + +- [Hill 1 Semantic Bootstrap Spec](../h1-semantic-bootstrap.md) +- [Git Mind Product Frame](../git-mind.md) +- [ROADMAP.md](../../../ROADMAP.md) +- issue [#305](https://github.com/flyingrobots/git-mind/issues/305) +- issue [#310](https://github.com/flyingrobots/git-mind/issues/310) + +## IBM Design Thinking Frame + +Sponsor user: + +- A technical lead, staff engineer, architect, or autonomous coding agent + entering an unfamiliar repository. + +Job to be done: + +- When I point Git Mind at a repo, help me get a useful first semantic map + before I have to model the graph by hand. + +Hill: + +- Hill 1: Zero-input semantic bootstrap. + +Playback evidence: + +- On a representative unfamiliar repository, `git mind bootstrap --dry-run + --json` reports scanned artifacts, inferred entities, inferred + relationships, confidence bands, and follow-up review guidance without + writing graph state. +- The same command without `--dry-run` writes those entities and relationships + to the graph and the follow-up `git mind status`, `git mind nodes`, and + `git mind view architecture` commands show useful structure. + +## User Stories + +- As a maintainer entering a new repo, I can run one command and see what Git + Mind found before committing to the graph writes. +- As an agent, I can request JSON output and receive a schema-stable summary + that distinguishes artifacts scanned, entities found, relationships inferred, + and weak suggestions. +- As a reviewer, I can see which inferred items need review and move directly + into the review flow. +- As a skeptical user, I can run `--dry-run` repeatedly and get deterministic + output for unchanged repo state. + +## Requirements + +### Functional + +- `git mind bootstrap` must initialize or open the repo graph. +- `git mind bootstrap --dry-run` must run the same scan and inference pipeline + without writing graph state. +- `--json` must emit a stable machine-readable summary. +- Human output must be terse and must point at follow-up inspection commands. +- Default mode must persist high, medium, and low-confidence inferred + relationships with provenance and confidence metadata. +- The command must be idempotent over unchanged inputs. +- The command must separate scan warnings from fatal errors. + +### Non-Functional + +- The command must be local-first and must not require hosted API credentials. +- Output order must be deterministic. +- The first implementation must favor understandable rules over broad + speculative inference. +- The command must run acceptably on medium repos before stress tuning begins. + +## CLI Contract Sketch + +```bash +git mind bootstrap +git mind bootstrap --dry-run +git mind bootstrap --json +git mind bootstrap --dry-run --json +``` + +Initial JSON shape: + +```json +{ + "schemaVersion": 1, + "dryRun": true, + "artifacts": { "scanned": 0, "byKind": {} }, + "entities": { "created": 0, "unchanged": 0, "byPrefix": {} }, + "relationships": { "created": 0, "unchanged": 0, "byType": {} }, + "confidence": { "high": 0, "medium": 0, "low": 0 }, + "warnings": [], + "followUp": [] +} +``` + +## Out Of Scope + +- Hosted GitHub, Jira, or Linear ingestion. +- Semantic embeddings. +- AI summarization. +- Cross-repo bootstrap. +- Interactive terminal review UI. + +## Test Plan + +Fixtures: + +- `minimal-doc-code`: README, one source file, one doc with an explicit file + reference, simple commit history. +- `adr-linked-service`: ADRs that mention modules and source paths. +- `noisy-repo`: ambiguous references, generated directories, vendored files, + and weak signals. +- `history-shaped`: recent commits touching files that appear in docs. + +Golden path: + +- `bootstrap --dry-run --json` on `minimal-doc-code` returns deterministic + counts and writes no WARP refs. +- `bootstrap --json` on `minimal-doc-code` writes graph state and returns the + same summary with `dryRun: false`. +- Running bootstrap twice creates no duplicate nodes or edges. + +Edge cases: + +- Empty Git repo. +- Repo with docs but no source files. +- Repo with source files but no docs. +- Repo with ignored directories, binary files, symlinks, and nested packages. +- Existing graph with manually authored edges that overlap inferred edges. + +Known failures: + +- Outside a Git repo must fail with a typed error. +- Malformed Git state must fail before partial writes. +- Unknown flags must fail through the normal CLI flag parser. +- Permission-denied files must warn or fail according to scan policy, never + crash with an unhandled exception. + +Fuzz: + +- Generate file paths with unusual but valid characters. +- Generate Markdown references with nested brackets, issue-like numbers, and + invalid links. +- Generate random flag ordering and ensure parser output is stable. + +Stress: + +- 10k files with realistic ignore patterns. +- 5k Markdown links and references. +- 2k commits in history range. +- Repeated dry-run loop to detect nondeterministic output. + +Regression: + +- No hidden network calls. +- No writes in `--dry-run`. +- No graph duplicates on repeated runs. +- No output contract drift without schema version bump. + +Golden artifacts: + +- JSON summary fixture for each base repo. +- Human output transcript for the golden path. +- Graph export after default write mode. + +Playback: + +- A new maintainer can run bootstrap on the fixture repo and answer: what docs + explain this area, what files look central, and what relationships need + review? diff --git a/docs/design/feature-profiles/content-on-node.md b/docs/design/feature-profiles/content-on-node.md new file mode 100644 index 0000000..47332e4 --- /dev/null +++ b/docs/design/feature-profiles/content-on-node.md @@ -0,0 +1,111 @@ +# Feature Profile: Content On Node + +Status: active supporting-lane profile + +Related: + +- [Git Mind Product Frame](../git-mind.md) +- [CLI Contracts](../../contracts/CLI_CONTRACTS.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent attaching source material, notes, or generated evidence + to graph nodes. + +Job to be done: + +- When a node needs attached content, store and retrieve that content through + Git-backed graph semantics with metadata. + +Lane: + +- Supporting lane: content. + +Playback evidence: + +- A user can attach content to a node, inspect metadata, retrieve raw content, + and delete it with JSON contracts. + +## User Stories + +- As a maintainer, I can attach a design excerpt or supporting file to a node. +- As an agent, I can read content metadata before fetching full content. +- As a user, I can delete attached content without deleting the node. + +## Requirements + +### Functional + +- `content set` attaches file content to an existing node. +- `content show` retrieves content. +- `content meta` reports content state and metadata. +- `content delete` removes content metadata and blob reference. +- JSON output must validate against content schemas. + +### Non-Functional + +- Missing node and missing content errors must be distinct. +- Large content limits and warnings need explicit policy. +- Binary content support needs explicit encoding policy before expansion. + +## Test Plan + +Fixtures: + +- `content-basic` +- `content-large` +- `content-binary` +- `content-missing-node` + +Golden path: + +- Attach text content from file. +- Show raw and metadata-wrapped content. +- Metadata includes MIME, size, hash, and presence. +- Delete removes content and is idempotent where specified. + +Edge cases: + +- Empty content. +- MIME override. +- File extension MIME detection. +- Node without content. +- Replacing existing content. + +Known failures: + +- Nonexistent file fails. +- Nonexistent node fails. +- Missing blob fails with clear error. +- Oversized content follows policy. + +Fuzz: + +- Generate file names, MIME types, and content bytes. +- Generate malformed node IDs. +- Generate random text encodings if binary support expands. + +Stress: + +- Large text content near limit. +- Many nodes with content. +- Repeated overwrite/delete loop. + +Regression: + +- Content JSON schemas remain valid. +- Delete does not remove node. +- Missing content reports no-content, not node-not-found. + +Golden artifacts: + +- JSON schema canaries. +- Metadata snapshots. +- Raw content transcripts. + +Playback: + +- Content enriches repository meaning where useful without turning Git Mind into + a separate document authoring system. diff --git a/docs/design/feature-profiles/doctor-integrity.md b/docs/design/feature-profiles/doctor-integrity.md new file mode 100644 index 0000000..75bfc72 --- /dev/null +++ b/docs/design/feature-profiles/doctor-integrity.md @@ -0,0 +1,110 @@ +# Feature Profile: Doctor And Integrity + +Status: active supporting-lane profile + +Related: + +- [Architecture Laws](../../ARCHITECTURE.md) +- [Review Rubric](../../REVIEW_RUBRIC.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent deciding whether graph state can be trusted. + +Job to be done: + +- When graph state looks suspicious, diagnose integrity problems and safely fix + repairable issues. + +Hill or lane: + +- Supporting lane: foundation. +- Supports all Hills by protecting trust. + +Playback evidence: + +- `git mind doctor` identifies dangling edges, malformed metadata, and repairable + graph issues without damaging valid state. + +## User Stories + +- As a maintainer, I can run doctor and know if the graph is healthy. +- As an agent, I can run doctor in JSON mode before trusting a repo map. +- As a maintainer, I can apply safe fixes with `--fix`. + +## Requirements + +### Functional + +- Detect dangling edges, malformed system nodes, invalid confidence values, + orphaned nodes, and schema-like property issues where possible. +- `--fix` must only repair issues with deterministic safe remediation. +- JSON output must list issue type, severity, affected nodes/edges, and fix + status. +- Doctor must respect time-travel and observer contexts where meaningful. + +### Non-Functional + +- No destructive repair without explicit `--fix`. +- Doctor must never hide unfixable issues. +- Repair operations must be atomic. + +## Test Plan + +Fixtures: + +- `healthy-graph` +- `dangling-edges` +- `malformed-system-nodes` +- `invalid-confidence` +- `large-corrupt-graph` + +Golden path: + +- Healthy graph reports clean. +- Dangling edge is detected. +- `--fix` removes repairable dangling edge. +- JSON output validates against schema. + +Edge cases: + +- Orphan nodes that are valid standalone entities. +- Malformed decision nodes. +- Historical graph with issues not present at HEAD. +- Observer-filtered graph hiding one endpoint. + +Known failures: + +- Unfixable issue remains and reports `fixed: false`. +- Invalid graph storage fails with typed error. +- Repair conflict fails without partial commit. + +Fuzz: + +- Generate malformed node properties. +- Generate random edge endpoint deletion. +- Generate invalid confidence values and timestamps. + +Stress: + +- 100k edges with 10k dangling references. +- Large graph doctor run under memory bound. +- Repeated doctor/fix loop idempotency. + +Regression: + +- `--fix` skips non-fixable issues. +- Doctor JSON contract remains stable. +- Repair commits do not remove valid edges. + +Golden artifacts: + +- Doctor JSON snapshots for each issue type. +- Before/after graph exports for fixable issues. + +Playback: + +- A user can decide whether the semantic map is trustworthy before relying on + query answers or bootstrap output. diff --git a/docs/design/feature-profiles/entity-extraction.md b/docs/design/feature-profiles/entity-extraction.md new file mode 100644 index 0000000..8200704 --- /dev/null +++ b/docs/design/feature-profiles/entity-extraction.md @@ -0,0 +1,129 @@ +# Feature Profile: Entity Extraction + +Status: draft for Hill 1 implementation + +Related: + +- [Hill 1 Semantic Bootstrap Spec](../h1-semantic-bootstrap.md) +- issue [#304](https://github.com/flyingrobots/git-mind/issues/304) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent trying to understand repo artifacts without manually + naming every node. + +Job to be done: + +- When Git Mind inventories a repo, synthesize useful semantic nodes from the + artifacts so later inference has stable graph endpoints. + +Hill: + +- Hill 1: Zero-input semantic bootstrap. + +Playback evidence: + +- Bootstrap creates useful `file:`, `doc:`, `adr:`, conservative `module:`, + `commit:`, `issue:`, and `pr:` nodes from repo-local evidence. + +## User Stories + +- As a user, I can see docs, ADRs, and source files as graph nodes after + bootstrap without writing frontmatter. +- As an agent, I can map a file path or ADR path to the node ID Git Mind chose. +- As a reviewer, I can distinguish inferred nodes from manually authored nodes. + +## Requirements + +### Functional + +- Generate stable node IDs for discovered files and docs. +- Extract ADR IDs from filename, title, or repo convention where possible. +- Infer conservative module nodes only from durable structure such as package + manifests or clear directory boundaries. +- Create placeholder `issue:` and `pr:` nodes only from repo-local textual + references. +- Preserve provenance for why each entity exists. +- Avoid overwriting manual node properties unless explicitly owned by bootstrap. + +### Non-Functional + +- Node IDs must be deterministic across machines. +- Extraction must prefer lower-level accurate nodes over fake abstractions. +- Unknown or ambiguous entities should be warnings, not invented truth. + +## Node Ownership + +Bootstrap-created properties should be namespaced or clearly identifiable so +manual curation can coexist with inferred metadata. + +Candidate properties: + +- `gitmind.inferred` +- `gitmind.extractor` +- `gitmind.sourceRef` +- `gitmind.lastSeen` +- `gitmind.kind` + +## Test Plan + +Fixtures: + +- `minimal-doc-code` +- `adr-linked-service` +- `monorepo-packages` +- `issue-pr-reference-docs` + +Golden path: + +- Source files become `file:` nodes. +- 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. +- `#123` and `PR #45` references create placeholder `issue:` and `pr:` nodes. + +Edge cases: + +- Duplicate basenames in different directories. +- ADR filenames with several numbering conventions. +- Docs with explicit IDs that collide with generated IDs. +- Package manifests in nested workspaces. +- Issue-like numbers in code comments that should not become issue nodes. + +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. + +Fuzz: + +- Generate random paths and ensure generated IDs are valid or rejected. +- Generate ADR naming variants. +- Generate issue/PR reference strings with false positives. + +Stress: + +- 50k file entities. +- 5k docs with titles and references. +- Monorepo with hundreds of packages. + +Regression: + +- Manual node properties survive repeated bootstrap runs. +- Node ID casing is stable. +- Entity extraction does not depend on filesystem order. + +Golden artifacts: + +- Entity extraction JSON for each base repo. +- Graph export after entity-only bootstrap. +- Collision warning snapshots. + +Playback: + +- A maintainer can ask "what did Git Mind decide exists in this repo?" and see + a useful first-pass entity map before relationship inference. diff --git a/docs/design/feature-profiles/extensions-runtime.md b/docs/design/feature-profiles/extensions-runtime.md new file mode 100644 index 0000000..58f4f47 --- /dev/null +++ b/docs/design/feature-profiles/extensions-runtime.md @@ -0,0 +1,112 @@ +# Feature Profile: Extensions Runtime + +Status: active supporting-lane profile + +Related: + +- [Git Mind Product Frame](../git-mind.md) +- issue [#261](https://github.com/flyingrobots/git-mind/issues/261) +- issue [#269](https://github.com/flyingrobots/git-mind/issues/269) + +## IBM Design Thinking Frame + +Sponsor user: + +- A tool builder or team adapting Git Mind to repo-specific workflows. + +Job to be done: + +- When core Git Mind does not know a local workflow, let an extension add + validated behavior without weakening core contracts. + +Lane: + +- Supporting lane: extensions. + +Playback evidence: + +- A valid extension manifest can be validated, registered, listed, and used in a + predictable way across command invocations. + +## User Stories + +- As a tool builder, I can validate an extension manifest before registration. +- As a maintainer, I can list registered extensions. +- As an agent, I can load an extension for one command or use persisted + registration once implemented. +- As a reviewer, I can reject unsafe or malformed extension manifests. + +## Requirements + +### Functional + +- Validate extension manifest against schema. +- Register and unregister extensions. +- List registered extensions in human and JSON forms. +- Define persistence semantics for registration. +- Define one-shot extension loading semantics. + +### Non-Functional + +- Extensions must not bypass core validation. +- Manifest errors must be typed and actionable. +- Extension loading must not create hidden network or host coupling. + +## Test Plan + +Fixtures: + +- `valid-extension` +- `invalid-manifest` +- `ephemeral-extension` +- `persistent-extension` + +Golden path: + +- Validate manifest succeeds. +- Add/register extension and list it. +- Remove extension and list no longer includes it. +- JSON outputs validate. + +Edge cases: + +- Duplicate extension name. +- Version mismatch. +- Missing entrypoint. +- Relative and absolute paths. +- Extension path removed after registration. + +Known failures: + +- Invalid manifest fails. +- Unsafe path escapes fail. +- Persistence not implemented must be explicit until fixed. + +Fuzz: + +- Generate manifest field combinations. +- Generate path variants. +- Generate extension names and versions. + +Stress: + +- Many registered extensions. +- Repeated add/remove/list loop. +- Parallel command invocation with extension registry reads. + +Regression: + +- Extension registration semantics do not silently change. +- Invalid manifests cannot partially register. +- JSON contract remains stable. + +Golden artifacts: + +- Valid and invalid manifests. +- Registry JSON snapshots. +- Error envelope snapshots. + +Playback: + +- Extensions make local workflows possible without turning core Git Mind into an + unsafe plugin free-for-all. diff --git a/docs/design/feature-profiles/graph-substrate.md b/docs/design/feature-profiles/graph-substrate.md new file mode 100644 index 0000000..7ffcbd7 --- /dev/null +++ b/docs/design/feature-profiles/graph-substrate.md @@ -0,0 +1,115 @@ +# Feature Profile: Graph Substrate + +Status: active supporting-lane profile + +Related: + +- [git-warp Upgrade Audit](../git-warp-upgrade-audit.md) +- [Repo Fixture Strategy](../repo-fixture-strategy.md) +- issue [#312](https://github.com/flyingrobots/git-mind/issues/312) +- issue [#320](https://github.com/flyingrobots/git-mind/issues/320) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent relying on Git Mind facts across branches, history, and + clones. + +Job to be done: + +- When semantic facts are stored, keep them Git-native, replayable, mergeable, + and testable without an external database. + +Lane: + +- Supporting lane: foundation. + +Playback evidence: + +- Graph state survives init, mutation, reload, historical materialization, + export, and upgrade fixture migration on the current git-warp substrate. + +## User Stories + +- As a maintainer, I can store graph meaning inside Git. +- As an agent, I can rely on deterministic reads after reload. +- As a reviewer, I can inspect semantic changes as Git-backed state. +- As a maintainer, I can upgrade the substrate with fixture proof. + +## Requirements + +### Functional + +- Initialize and open the Git Mind graph idempotently. +- Create patches and commit graph mutations. +- Support materialized reads, observer reads, and historical ceilings. +- Preserve compatibility over git-warp major upgrades through explicit tests. +- Provide clear errors when required substrate surfaces are missing. + +### Non-Functional + +- No external database. +- Deterministic replay and branch semantics remain core assumptions. +- Compatibility wrappers must be small and covered by tests. +- Upgrade fixtures must run isolated from the checkout. + +## Test Plan + +Fixtures: + +- `fresh-empty-repo` +- `round-trip-reload` +- `observer-filtered` +- `upgrade-v14-to-v17-bundle` +- `historical-materialization` + +Golden path: + +- Init creates usable graph. +- Patch writes node/edge and reload sees it. +- Historical materialization hides later edges. +- Observer returns read-compatible filtered graph. +- Upgrade fixture migrates and reads frozen graph. + +Edge cases: + +- Missing optional graph methods on observer surfaces. +- Empty graph. +- Repeated init. +- Multiple commits with same semantic endpoints. + +Known failures: + +- Missing required substrate method fails with informative message. +- Corrupt Git object state fails during fixture validation. +- Upgrade fixture checksum mismatch fails before migration. + +Fuzz: + +- Generate graph mutations with random valid nodes and edges. +- Generate optional-surface combinations for compatibility wrappers. +- Generate repeated commit/reload cycles. + +Stress: + +- Large graph materialization. +- Many patch commits. +- Upgrade fixture repeated in isolated Docker. + +Regression: + +- No substrate downgrade in package manifests. +- Observer compatibility remains lazy for unsupported optional methods. +- Upgrade fixture uses `--network none` and audited lockfile install. + +Golden artifacts: + +- Frozen Git bundle upgrade fixture. +- Graph export snapshots. +- Substrate surface compatibility tests. + +Playback: + +- Git Mind can keep semantic knowledge in Git without making users operate a + separate persistence service. diff --git a/docs/design/feature-profiles/import-export-interchange.md b/docs/design/feature-profiles/import-export-interchange.md new file mode 100644 index 0000000..6b3c967 --- /dev/null +++ b/docs/design/feature-profiles/import-export-interchange.md @@ -0,0 +1,116 @@ +# Feature Profile: Import Export Interchange + +Status: active feature profile + +Related: + +- [GRAPH_SCHEMA.md](../../../GRAPH_SCHEMA.md) +- [Git Mind Product Frame](../git-mind.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer, agent, or tool integrating graph data with external workflows. + +Job to be done: + +- When repository meaning needs to move between tools, let me import and export + graph state through stable, validated interchange formats. + +Hill or lane: + +- Hill 2: Queryable answers with receipts. +- Supporting lane: foundation. + +Playback evidence: + +- A graph exported from one repo state can be reviewed, validated, imported, and + compared without losing important semantic data. + +## User Stories + +- As a maintainer, I can export graph data for review or archival. +- As an agent, I can import a proposed semantic map in dry-run mode before + writing it. +- As a tool author, I can rely on schema-stable JSON/YAML. +- As a reviewer, I can round-trip export/import and detect drift. + +## Requirements + +### Functional + +- Export must support YAML and JSON. +- Import must validate node IDs, edge types, confidence, and references. +- Dry-run import must validate without writes. +- Markdown frontmatter import must remain a supported bootstrap-adjacent path. +- Import/export must preserve supported node properties, edge properties, + confidence, and rationale. + +### Non-Functional + +- Output order must be deterministic. +- Invalid imports must fail before partial writes. +- Schema drift must be intentional and documented. + +## Test Plan + +Fixtures: + +- `minimal-graph-yaml` +- `rich-properties-json` +- `markdown-frontmatter-docs` +- `invalid-imports` + +Golden path: + +- Export to YAML and JSON. +- Import dry-run validates without writing. +- Import writes expected graph. +- Export/import/export round-trip is stable for supported data. +- Markdown frontmatter imports nodes and edges. + +Edge cases: + +- Empty graph. +- Node properties with strings, numbers, booleans, and nulls. +- Duplicate nodes or edges in import. +- Unknown prefixes that warn but are allowed. +- Unsupported edge types. + +Known failures: + +- Invalid YAML/JSON fails with parse error. +- Invalid node IDs fail validation. +- Edge references to missing nodes follow documented policy. +- Confidence outside range fails. + +Fuzz: + +- Generate YAML/JSON with random valid graph records. +- Generate malformed graph records. +- Generate Markdown frontmatter variants. + +Stress: + +- Import/export 100k edges. +- Very large property payloads within and beyond policy. +- Many repeated imports to test idempotency. + +Regression: + +- Round-trip stability. +- No partial writes on failed imports. +- Frontmatter import remains idempotent. +- JSON metadata schema remains stable. + +Golden artifacts: + +- YAML and JSON export snapshots. +- Invalid import error snapshots. +- Markdown frontmatter fixture docs. + +Playback: + +- A user can move graph knowledge through reviewable files without losing trust + in the graph contract. diff --git a/docs/design/feature-profiles/living-map-updates.md b/docs/design/feature-profiles/living-map-updates.md new file mode 100644 index 0000000..03f0a69 --- /dev/null +++ b/docs/design/feature-profiles/living-map-updates.md @@ -0,0 +1,110 @@ +# Feature Profile: Living Map Updates + +Status: future Hill 3 profile + +Related: + +- [Git Mind Product Frame](../git-mind.md) +- [ROADMAP.md](../../../ROADMAP.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A team or agent workflow that wants the semantic map to stay useful as the + repository changes. + +Job to be done: + +- When repo artifacts evolve, update the semantic map and surface reviewable + semantic deltas without making me maintain a second wiki. + +Hill: + +- Hill 3: Living map with low manual upkeep. + +Playback evidence: + +- New commits produce semantic deltas, confidence updates, and reviewable + suggestions rather than leaving the map stale. + +## User Stories + +- As a maintainer, I can refresh the map after changes and see what changed. +- As an agent, I can identify semantic drift before editing related files. +- As a reviewer, I can review new low-confidence updates after a PR. + +## Requirements + +### Functional + +- Detect changed artifacts since a prior bootstrap or commit. +- Re-run relevant extractors incrementally where possible. +- Add, update, or deprecate inferred relationships with provenance. +- Surface semantic deltas for review. +- Track last-seen metadata for inferred entities and relationships. + +### Non-Functional + +- Upkeep cost must stay low. +- Incremental updates must be deterministic. +- Stale inferred facts must not silently masquerade as current truth. + +## Test Plan + +Fixtures: + +- `living-map-base` +- `artifact-renamed` +- `doc-updated` +- `relationship-obsoleted` +- `branching-evolution` + +Golden path: + +- Change a doc reference and map update changes relationship provenance. +- Rename a file and map update records replacement or stale relationship policy. +- New commit touching a file creates or updates `touches`. +- Removed evidence lowers confidence or marks inferred edge stale by policy. + +Edge cases: + +- File renamed and edited. +- Commit reverts prior evidence. +- Branch merge introduces conflicting inferred relationships. +- Manual review decision exists for an edge now inferred again. + +Known failures: + +- Missing prior state fails with bootstrap-required message. +- Uncommitted work policy is explicit. +- Stale relationship handling is explicit and tested. + +Fuzz: + +- Generate sequences of file edits, renames, and deletes. +- Generate alternating evidence and evidence removal. +- Generate random update order and assert deterministic graph state. + +Stress: + +- Incremental update across 10k changed files. +- Long-lived repo with many stale inferred facts. +- Parallel update attempts fail or serialize predictably. + +Regression: + +- Reviewed decisions are not overwritten silently. +- Stale facts remain inspectable. +- No duplicate inferred relationships across refresh cycles. + +Golden artifacts: + +- Semantic delta JSON. +- Graph export before and after update. +- Stale fact policy examples. + +Playback: + +- The map evolves alongside the repo and exposes what needs review, rather than + decaying into a stale knowledge base. diff --git a/docs/design/feature-profiles/packaging-adoption.md b/docs/design/feature-profiles/packaging-adoption.md new file mode 100644 index 0000000..3217c4f --- /dev/null +++ b/docs/design/feature-profiles/packaging-adoption.md @@ -0,0 +1,114 @@ +# Feature Profile: Packaging And Adoption + +Status: supporting-lane profile + +Related: + +- [README.md](../../../README.md) +- [ROADMAP.md](../../../ROADMAP.md) +- issue [#286](https://github.com/flyingrobots/git-mind/issues/286) +- issue [#287](https://github.com/flyingrobots/git-mind/issues/287) +- issue [#288](https://github.com/flyingrobots/git-mind/issues/288) + +## IBM Design Thinking Frame + +Sponsor user: + +- A new user or agent trying Git Mind in a real repository. + +Job to be done: + +- When I decide to try Git Mind, make installation, version discovery, and first + run boring and trustworthy. + +Lane: + +- Supporting lane: packaging. + +Playback evidence: + +- A user can install Git Mind, run `git mind --help`, initialize a repo, and run + the first Hill 1 command without reading source setup instructions. + +## User Stories + +- As a new user, I can install globally through npm. +- As an agent, I can check the version and command availability. +- As a maintainer, I can publish only intended package files. +- As a user, I can uninstall or install to `~/.local/bin` where supported. + +## Requirements + +### Functional + +- Package metadata must expose the intended CLI binary. +- Published package must include only necessary runtime files. +- `--version` must be available. +- Install and uninstall scripts must avoid unsafe shell evaluation. +- Update checks, if added, must be non-blocking and privacy-conscious. + +### Non-Functional + +- First-run errors must be actionable. +- Packaging must not depend on local monorepo paths. +- Install docs must match shipped reality. + +## Test Plan + +Fixtures: + +- `npm-pack-fixture` +- `global-install-smoke` +- `local-bin-install` +- `minimal-user-repo` + +Golden path: + +- `npm pack` contains expected files and excludes tests/fixtures where policy + requires. +- Packed CLI runs `--help` and `--version`. +- Global install smoke initializes a temporary repo. +- Uninstall removes installed binary in supported mode. + +Edge cases: + +- Existing binary in target path. +- Missing Node version. +- Read-only install directory. +- Package run from packed tarball instead of checkout. + +Known failures: + +- Unsupported Node version fails with clear message. +- Unsafe install target fails. +- Missing runtime dependency fails in CI before publish. + +Fuzz: + +- Generate install paths with spaces and special characters. +- Generate package file allowlist comparisons. +- Generate semver strings for update-check parsing. + +Stress: + +- Repeated install/uninstall loop. +- Pack and smoke test under clean temp home. +- Cross-OS install matrix where CI supports it. + +Regression: + +- No local path dependency sneaks into package. +- No dependency downgrade. +- No unsafe eval in install scripts. +- Packed fixture harness still installs from lockfile. + +Golden artifacts: + +- `npm pack --dry-run` file manifest. +- Install smoke transcript. +- Version output snapshot. + +Playback: + +- A new user reaches first repo value without becoming a contributor to the + build system. diff --git a/docs/design/feature-profiles/provenance-confidence.md b/docs/design/feature-profiles/provenance-confidence.md new file mode 100644 index 0000000..c0d0583 --- /dev/null +++ b/docs/design/feature-profiles/provenance-confidence.md @@ -0,0 +1,124 @@ +# Feature Profile: Provenance And Confidence + +Status: draft for Hill 1 and Hill 2 implementation + +Related: + +- [Hill 1 Semantic Bootstrap Spec](../h1-semantic-bootstrap.md) +- [Git Mind Product Frame](../git-mind.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer, reviewer, or agent deciding whether to trust an inferred + relationship. + +Job to be done: + +- When Git Mind asserts a relationship, show me why it believes the assertion + and how confident it is. + +Hills: + +- Hill 1: Semantic bootstrap. +- Hill 2: Queryable answers with receipts. + +Playback evidence: + +- Every inferred edge can be traced to source artifacts, extractor rule, evidence + text or path, confidence band, and inference time. + +## User Stories + +- As a reviewer, I can reject low-confidence edges without losing the evidence + that caused them. +- As an agent, I can choose different behavior for high, medium, and low + confidence facts. +- As a maintainer, I can audit how a relationship changed over time. + +## Requirements + +### Functional + +- Every inferred edge must carry a provenance envelope. +- Provenance must include `sourceKind`, `sourceRef`, `extractor`, `evidence`, + and `inferredAt`. +- Confidence must be rule-derived in v0 and expose both a numeric score and a + band where practical. +- Manual edges must remain distinguishable from inferred edges. +- Review decisions must be able to update confidence or mark an assertion as + accepted/rejected. + +### Non-Functional + +- Provenance payloads must be compact enough for Git-backed storage. +- Evidence must avoid storing unnecessary large document excerpts. +- Confidence rules must be documented and deterministic. +- Schema changes must bump output contract versions. + +## Confidence Bands + +- High: explicit structured evidence, exact path match, or explicit + relationship syntax. +- Medium: strong lexical evidence or unambiguous reference. +- Low: fuzzy association, weak convention, or ambiguous but plausible signal. + +## Test Plan + +Fixtures: + +- `explicit-frontmatter` +- `markdown-path-reference` +- `ambiguous-reference` +- `reviewed-suggestions` + +Golden path: + +- Each inferred relationship includes required provenance fields. +- Confidence band matches extractor rule. +- JSON output exposes provenance and confidence consistently. +- Accepted review updates are reflected in later graph reads. + +Edge cases: + +- Multiple evidence sources for one relationship. +- Evidence text longer than storage limit. +- Relationship inferred by two extractors with different confidence. +- Manual edge overlaps inferred edge. + +Known failures: + +- Missing provenance rejects write or records a fatal invariant failure. +- Invalid confidence value fails validation. +- Evidence that points outside repo root is rejected. + +Fuzz: + +- Generate provenance envelopes with missing, wrong-type, and oversized fields. +- Generate confidence scores around band boundaries. +- Generate evidence spans with unusual characters. + +Stress: + +- 100k inferred relationships with provenance. +- Many-to-one evidence fan-in for a central module. +- Repeated review cycles over the same relationship. + +Regression: + +- Provenance survives export/import. +- Provenance survives time-travel materialization. +- Confidence is stable across repeated bootstrap runs. +- Reviewed low-confidence items do not reappear as new unrelated suggestions. + +Golden artifacts: + +- Provenance envelope samples. +- Confidence rules fixture table. +- Graph export with reviewed and unreviewed inferred edges. + +Playback: + +- The user can inspect one surprising relationship and answer: what produced + this, what evidence supports it, and should I trust it? diff --git a/docs/design/feature-profiles/query-receipts.md b/docs/design/feature-profiles/query-receipts.md new file mode 100644 index 0000000..3f2521b --- /dev/null +++ b/docs/design/feature-profiles/query-receipts.md @@ -0,0 +1,127 @@ +# Feature Profile: Query Receipts + +Status: draft for Hill 2 implementation + +Related: + +- [Git Mind Product Frame](../git-mind.md) +- [ROADMAP.md](../../../ROADMAP.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer, reviewer, or agent asking a concrete repository question. + +Job to be done: + +- When I ask what implements, explains, blocks, or changed an artifact, give me + an answer backed by graph facts, provenance, confidence, and history. + +Hill: + +- Hill 2: Queryable answers with receipts. + +Playback evidence: + +- A user asks a small set of day-one questions and receives answers with + machine-readable receipts instead of only graph dumps. + +## User Stories + +- As a maintainer, I can ask what implements a spec and see the file/module + evidence. +- As a reviewer, I can ask what ADR explains a module and see the source + relationship and confidence. +- As an agent, I can consume answer JSON that cites graph edges, provenance, and + relevant commit history. +- As a skeptical user, I can distinguish direct graph evidence from inferred or + low-confidence evidence. + +## Requirements + +### Functional + +- Define an initial question set tied to real repository-understanding jobs. +- Return answer payloads that include answer items, receipts, confidence, + provenance, and graph refs. +- Support JSON output first; human output can be terse but must cite receipts. +- Handle no-answer and low-confidence-answer cases explicitly. +- Reuse existing views, diff, provenance, and node/edge APIs rather than + inventing a second query substrate. + +### Non-Functional + +- Answers must be inspectable, not magical. +- Query contracts must be schema-versioned. +- The first question set should be narrow and excellent. +- Query runtime must be bounded on medium graphs. + +## Initial Question Set + +- What implements this spec? +- What docs or ADRs explain this module or file? +- What changed semantically in this area? +- What is blocked by this task? +- What issue or PR references shaped this path? +- What weak or missing connections should I review? + +## Test Plan + +Fixtures: + +- `query-receipts-service`: known docs, ADRs, specs, files, and commits. +- `low-confidence-map`: same graph with mixed confidence edges. +- `no-answer-map`: valid graph with missing relationships. +- `history-shaped`: graph with semantic changes across refs. + +Golden path: + +- Query returns direct answer with receipt edge IDs 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. + +Edge cases: + +- Multiple equally valid answers. +- Conflicting high and low-confidence relationships. +- Cycles in dependency/blocker paths. +- Query target missing from graph. +- Time-scoped query at historical ref. + +Known failures: + +- Unknown question type fails with typed error. +- Missing provenance on an inferred edge produces degraded receipt warning. +- Invalid node ID fails before graph read. + +Fuzz: + +- Generate valid and invalid node IDs. +- Generate random graph shapes with cycles and disconnected components. +- Generate answer payloads against schema with missing receipt fields. + +Stress: + +- 100k edges with question-specific indexes absent. +- Large fan-in/fan-out around central specs. +- Repeated query loop for deterministic ordering. + +Regression: + +- Answer ordering stays stable. +- Receipts survive export/import. +- No answer should not exit as a crash. +- Query output schema does not drift without version bump. + +Golden artifacts: + +- JSON answer snapshots for each initial question. +- Human output transcripts for common questions. +- No-answer and low-confidence-answer fixtures. + +Playback: + +- Repository archaeology becomes a query with receipts rather than manual grep, + commit browsing, and memory reconstruction. diff --git a/docs/design/feature-profiles/relationship-inference.md b/docs/design/feature-profiles/relationship-inference.md new file mode 100644 index 0000000..e650e0d --- /dev/null +++ b/docs/design/feature-profiles/relationship-inference.md @@ -0,0 +1,121 @@ +# Feature Profile: Relationship Inference + +Status: draft for Hill 1 implementation + +Related: + +- [Hill 1 Semantic Bootstrap Spec](../h1-semantic-bootstrap.md) +- issue [#307](https://github.com/flyingrobots/git-mind/issues/307) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent trying to understand how repo artifacts connect. + +Job to be done: + +- When Git Mind has artifacts and entities, infer a small set of useful + relationships with visible evidence instead of asking me to author every edge. + +Hill: + +- Hill 1: Zero-input semantic bootstrap. + +Playback evidence: + +- Bootstrap produces useful `documents`, `references`, `touches`, `groups`, and + conservative `implements` edges with provenance and confidence. + +## User Stories + +- As a user, I can see which docs or ADRs appear to explain a file or module. +- As an agent, I can inspect why a relationship exists before acting on it. +- As a reviewer, I can accept, reject, or adjust weak inferred relationships. + +## Requirements + +### Functional + +- Infer `documents` from explicit path mentions, doc frontmatter, ADR patterns, + and strong naming conventions. +- Infer `references` from explicit artifact, issue, PR, and commit references. +- Infer `touches` from commit history. +- Infer `groups` from conservative package or directory boundaries. +- Infer `implements` only from strong explicit cues. +- Attach provenance and confidence to every inferred edge. +- Avoid duplicate edges across repeated runs. + +### Non-Functional + +- Inference rules must be explainable. +- Weak relationships must not be hidden. +- The first version must avoid opaque ML or embedding dependency. +- False positives should bias toward low confidence and reviewability. + +## Relationship Policy + +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. + +## Test Plan + +Fixtures: + +- `adr-linked-service` +- `history-shaped` +- `issue-pr-reference-docs` +- `noisy-repo` + +Golden path: + +- Explicit doc path mentions produce `documents`. +- Markdown links and text references produce `references`. +- Recent commits touching files produce `touches`. +- Package directory membership produces `groups`. +- Explicit "implements spec:auth" style cues produce `implements`. + +Edge cases: + +- Multiple docs mention the same file. +- One doc references many issue IDs. +- Renamed files in commit history. +- Ambiguous lexical matches with common words. +- Generated docs that mention every file. + +Known failures: + +- No inferred edge may be written without provenance. +- Weak evidence must not become high confidence. +- Commit ranges that cannot resolve must fail predictably. +- Relationship endpoints missing from entity extraction must be reported. + +Fuzz: + +- Generate Markdown links, issue references, and path mentions. +- Generate random commit messages with directive-like text. +- Generate near-match filenames to test false positives. + +Stress: + +- 100k candidate artifact pairs with bounded inference time. +- 10k commits with file touches. +- Docs with very large reference lists. + +Regression: + +- Repeated bootstrap creates no duplicate edges. +- Inference output order is stable. +- Review decisions suppress or update future weak suggestions as designed. + +Golden artifacts: + +- Relationship JSON summary by type and confidence. +- Graph export containing inferred edge properties. +- False-positive fixtures with expected low or no inference. + +Playback: + +- A user can answer: what docs explain this area, what commits touched it, and + what inferred relationships need review? diff --git a/docs/design/feature-profiles/repo-fixture-builder.md b/docs/design/feature-profiles/repo-fixture-builder.md new file mode 100644 index 0000000..6ddcc57 --- /dev/null +++ b/docs/design/feature-profiles/repo-fixture-builder.md @@ -0,0 +1,122 @@ +# Feature Profile: Repo Fixture Builder + +Status: draft for supporting lane implementation + +Related: + +- [Repo Fixture Strategy](../repo-fixture-strategy.md) +- [ADR-0006](../../adr/ADR-0006.md) +- issue [#311](https://github.com/flyingrobots/git-mind/issues/311) +- issue [#316](https://github.com/flyingrobots/git-mind/issues/316) + +## IBM Design Thinking Frame + +Sponsor user: + +- A Git Mind contributor or agent implementing repository-shaped behavior. + +Job to be done: + +- When I write tests for repository understanding, give me readable, reusable + repo fixtures so tests describe product scenarios instead of shell plumbing. + +Hill or lane: + +- Supporting lane: foundation. It enables Hill 1 bootstrap tests. + +Playback evidence: + +- A bootstrap acceptance test can build a believable repo with docs, ADRs, + commits, branches, and ambiguous references in a few readable lines. + +## User Stories + +- As a contributor, I can create a repo fixture without duplicating `mkdtemp`, + `git init`, identity config, file writes, and commits. +- As a reviewer, I can read a test fixture setup and understand the repository + story it represents. +- As an agent, I can compose base repos and overlays without relying on hidden + local state. +- As a maintainer, I can migrate old one-off repo tests gradually. + +## Requirements + +### Functional + +- Provide a fluent helper for temporary Git repo creation. +- Support file write, update, delete, chmod where needed, commit, branch, + checkout, merge, tag, and ref helpers. +- Provide named base repos for Hill 1 scenarios. +- Provide overlays for ADR references, issue references, noisy docs, history, + branching, and generated files. +- Return handles for repo root, file paths, commit SHAs, and expected semantic + facts. +- Clean up temporary directories reliably. + +### Non-Functional + +- Fixture setup must be deterministic. +- Fixture names must describe the repository story. +- Archived binary snapshots must be exceptional and justified. +- Helpers must not hide meaningful semantic setup behind magic defaults. + +## Test Plan + +Fixtures: + +- `fixture-builder-selftest`: a repo produced by the builder itself. +- `minimal-doc-code`: base repo for bootstrap. +- `branching-evolution`: base plus branch and merge overlay. +- `noisy-repo`: generated, vendored, ignored, and ambiguous inputs. + +Golden path: + +- Builder initializes a repo, writes files, commits, and returns stable SHAs. +- Base repo plus overlays produces expected file tree and commit graph. +- Cleanup removes temp repos after tests. + +Edge cases: + +- Empty commit attempts. +- File deletion followed by commit. +- Branch checkout with uncommitted changes must be rejected by helper policy. +- Merge conflicts can be intentionally created for failure-case fixtures. +- Symlinks and executable bits are supported or explicitly skipped per platform. + +Known failures: + +- Invalid overlay order fails with a clear error. +- Missing Git binary fails early. +- Invalid path escaping cannot write outside fixture root. + +Fuzz: + +- Generate random valid file paths and content. +- Generate overlay order permutations and assert declared dependencies are + enforced. +- Generate commit messages with issue and PR references. + +Stress: + +- Build repos with 10k files. +- Build histories with 2k commits. +- Build repeated fixtures in parallel to detect temp path collisions. + +Regression: + +- No fixture writes outside temp root. +- No leaked temp directories after passing or failing tests. +- No reliance on global Git config. +- No reliance on host branch name or current working tree. + +Golden artifacts: + +- Expected `git log --graph --oneline` snapshots for key base repos. +- Expected file tree manifests. +- Expected semantic facts emitted by base repos and overlays. + +Playback: + +- A bootstrap test reads like: "given an ADR-linked service with noisy docs, + when bootstrap runs, it infers these relationships." The setup is product + language, not shell ceremony. diff --git a/docs/design/feature-profiles/review-refinement.md b/docs/design/feature-profiles/review-refinement.md new file mode 100644 index 0000000..be51d3a --- /dev/null +++ b/docs/design/feature-profiles/review-refinement.md @@ -0,0 +1,114 @@ +# Feature Profile: Review Refinement + +Status: draft for Hill 1 and Hill 3 implementation + +Related: + +- [Git Mind Product Frame](../git-mind.md) +- [Hill 1 Semantic Bootstrap Spec](../h1-semantic-bootstrap.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent refining inferred repository meaning. + +Job to be done: + +- When Git Mind suggests weak or uncertain relationships, help me accept, + reject, or adjust them without rebuilding the map manually. + +Hills: + +- Hill 1: Semantic bootstrap. +- Hill 3: Living map with low manual upkeep. + +Playback evidence: + +- Low-confidence bootstrap output flows into `git mind review`, review decisions + persist atomically, and future pending suggestions reflect those decisions. + +## User Stories + +- As a reviewer, I can accept a suggestion and promote its confidence. +- As a reviewer, I can reject a bad suggestion and stop seeing it as pending. +- As a reviewer, I can adjust type, rationale, or confidence in one operation. +- As an agent, I can batch accept or reject pending suggestions using JSON + contracts. + +## Requirements + +### Functional + +- Pending suggestions must be derived from low-confidence unreviewed edges. +- Review decisions must be stored as graph nodes with source, target, edge type, + action, confidence, reviewer, rationale, and timestamp. +- Accept, reject, adjust, and batch operations must commit atomically. +- Review history must skip malformed decision nodes safely. +- JSON output must distinguish pending suggestions from review history. + +### Non-Functional + +- Review should refine the map, not require users to build it from scratch. +- Batch operations must be deterministic. +- Failed review operations must not leave partial graph state. + +## Test Plan + +Fixtures: + +- `bootstrap-low-confidence` +- `reviewed-suggestions` +- `malformed-decisions` +- `batch-review` + +Golden path: + +- Accept promotes confidence and records decision. +- Reject removes or suppresses edge and records decision. +- Adjust changes edge type or properties and records decision in one patch. +- Batch accept/reject processes all pending suggestions deterministically. + +Edge cases: + +- Suggestion already reviewed. +- Edge removed between listing and review action. +- Adjustment changes type to an existing edge. +- Multiple pending suggestions for same source and target. + +Known failures: + +- Invalid review action fails. +- Invalid edge type fails before write. +- Malformed decision nodes are ignored in history, not fatal. +- Concurrent stale review attempts fail predictably. + +Fuzz: + +- Generate pending suggestions with random valid node IDs and edge types. +- Generate malformed decision nodes. +- Generate reviewer/rationale strings around size limits. + +Stress: + +- 10k pending suggestions. +- Batch review with many source/target collisions. +- Long review history over repeated bootstrap cycles. + +Regression: + +- Adjust remains single-patch atomic. +- Rejected suggestions do not reappear as unreviewed. +- Batch JSON contract stays schema-stable. +- Review history sorting remains deterministic. + +Golden artifacts: + +- Pending suggestions JSON. +- Review history JSON. +- Graph export after accept, reject, adjust, and batch flows. + +Playback: + +- A maintainer can review the weak parts of a bootstrap map in minutes and see + the graph become more trustworthy rather than more cluttered. diff --git a/docs/design/feature-profiles/time-travel-diff.md b/docs/design/feature-profiles/time-travel-diff.md new file mode 100644 index 0000000..95c4a8b --- /dev/null +++ b/docs/design/feature-profiles/time-travel-diff.md @@ -0,0 +1,112 @@ +# Feature Profile: Time Travel And Semantic Diff + +Status: active feature profile + +Related: + +- [Git Mind Product Frame](../git-mind.md) +- [ROADMAP.md](../../../ROADMAP.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent investigating how repository meaning changed. + +Job to be done: + +- When code and docs change over time, show me the semantic graph as of a ref + and what changed between two refs. + +Hill: + +- Hill 2: Queryable answers with receipts. + +Playback evidence: + +- A user can compare two commits and see semantic additions, removals, and + summaries that explain graph evolution. + +## User Stories + +- As a reviewer, I can see semantic changes in a PR range. +- As an agent, I can query graph state at `HEAD~10` before planning changes. +- As a maintainer, I can detect when relationships disappeared or new blockers + appeared. + +## Requirements + +### Functional + +- `--at ` must materialize read commands at historical graph state. +- `git mind diff ..` must compare graph snapshots. +- Diff output must include added/removed nodes, added/removed edges, and summary + by prefix and edge type. +- Historical lookup must use recorded epoch metadata and safe nearest-ancestor + fallback where designed. +- JSON output must be schema-stable. + +### Non-Functional + +- Historical reads must not mutate current graph state. +- Missing or malformed epoch data must degrade predictably. +- Diff order must be deterministic. + +## Test Plan + +Fixtures: + +- `history-shaped` +- `branching-evolution` +- `malformed-epochs` +- `nearest-ancestor-history` + +Golden path: + +- `at HEAD~1 --json` returns older graph state. +- Diff reports added and removed nodes/edges. +- Prefix filtering scopes diff correctly. +- Merge history with nearest fallback yields deterministic output. + +Edge cases: + +- Both refs resolve to same graph tick. +- Ref with no direct epoch but ancestor epoch exists. +- Deleted branch ref. +- Non-linear history. +- Graph changes with identical working tree files. + +Known failures: + +- Invalid ref fails with typed error. +- Malformed epoch nodes are ignored or reported by policy. +- Missing graph state fails predictably. + +Fuzz: + +- Generate commit DAGs with random semantic changes. +- Generate malformed ref strings. +- Generate random graph snapshots and compare diff symmetry properties. + +Stress: + +- Large graph diff with 100k edges. +- Deep history with thousands of epochs. +- Branch/merge-heavy repo. + +Regression: + +- Historical materialization does not leak later edges. +- Diff excludes system nodes where specified. +- Prefix filters do not include edges with removed endpoints. + +Golden artifacts: + +- Diff JSON snapshots. +- Historical graph export snapshots. +- Commit graph diagrams for branch fixtures. + +Playback: + +- A reviewer can explain what repository meaning changed in a PR without + manually comparing graph exports. diff --git a/docs/design/feature-profiles/trust-observers.md b/docs/design/feature-profiles/trust-observers.md new file mode 100644 index 0000000..df3e962 --- /dev/null +++ b/docs/design/feature-profiles/trust-observers.md @@ -0,0 +1,110 @@ +# Feature Profile: Trust And Observer Contexts + +Status: active and evolving profile + +Related: + +- [CLI Contracts](../../contracts/CLI_CONTRACTS.md) +- [Git Mind Product Frame](../git-mind.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer, reviewer, or agent that needs scoped or policy-filtered graph + reads. + +Job to be done: + +- When I inspect repository meaning, let me constrain what I see by time, + observer profile, or trust policy. + +Hills: + +- Hill 2: Queryable answers with receipts. +- Hill 3: Living map with low manual upkeep. + +Playback evidence: + +- Read commands can show graph state under a named observer or trust policy and + explain the context used. + +## User Stories + +- As a reviewer, I can inspect only task-related graph state. +- As an agent, I can ask for approved-only facts when planning a change. +- As a maintainer, I can compare open vs restricted trust views. + +## Requirements + +### Functional + +- Read commands must accept context flags consistently where supported. +- Observer surfaces must expose safe read APIs. +- Trust policies must be explicit and documented. +- JSON output should include context metadata. +- Missing observer support must fail with informative errors. + +### Non-Functional + +- Context filtering must not mutate graph state. +- Trust behavior must be deterministic. +- Unsupported context combinations must fail predictably. + +## Test Plan + +Fixtures: + +- `observer-task-map` +- `approved-and-unreviewed-map` +- `mixed-confidence-map` +- `historical-context-map` + +Golden path: + +- Observer filters nodes, edges, and properties as configured. +- Approved-only trust policy excludes unreviewed inferred edges. +- Context metadata appears in JSON output. +- Time-travel and observer combinations behave as documented. + +Edge cases: + +- Observer excludes an edge endpoint. +- Observer exposes a property subset. +- Trust policy removes all answers. +- Missing optional graph APIs on observer surfaces. + +Known failures: + +- Unknown observer fails with typed error. +- Unsupported trust policy fails. +- Context on unsupported command fails or is ignored only if documented. + +Fuzz: + +- Generate observer match patterns and property exposure lists. +- Generate mixed confidence/review states. +- Generate context flag ordering permutations. + +Stress: + +- Large graph filtered by observer. +- Many observer profiles. +- Repeated context reads under parallel command execution. + +Regression: + +- Observer compatibility wrapper does not require unsupported write APIs. +- Missing observer dispatch reports `git-warp surface missing observer()`. +- Trust filters do not leak hidden edges. + +Golden artifacts: + +- Context metadata JSON samples. +- Observer-filtered graph snapshots. +- Trust-policy answer snapshots. + +Playback: + +- A user can ask "what does the repo mean under this policy?" and understand + both the answer and the context boundary. diff --git a/docs/design/feature-profiles/views-lenses.md b/docs/design/feature-profiles/views-lenses.md new file mode 100644 index 0000000..04e3c44 --- /dev/null +++ b/docs/design/feature-profiles/views-lenses.md @@ -0,0 +1,115 @@ +# Feature Profile: Views And Lenses + +Status: active feature profile + +Related: + +- [Git Mind Product Frame](../git-mind.md) +- [ROADMAP.md](../../../ROADMAP.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A maintainer or agent who needs a focused projection of repository meaning. + +Job to be done: + +- When the full semantic graph is too broad, show me the subset that answers my + current workflow question. + +Hill or lane: + +- Hill 2: Queryable answers with receipts. +- Supporting lane: UX. + +Playback evidence: + +- A user can inspect architecture, backlog, roadmap, progress, and focused lens + views without learning raw graph traversal first. + +## User Stories + +- As an architect, I can view module/package dependencies. +- As a lead, I can view tasks, blockers, and progress. +- As an agent, I can request JSON for a view and use schema-stable output. +- As a reviewer, I can chain lenses such as incomplete and frontier to find + actionable work. + +## Requirements + +### Functional + +- Built-in views must map to clear repository-understanding questions. +- Lenses must be composable and deterministic. +- View output must support JSON and human formats. +- Views must respect context flags such as `--at`, `--observer`, and trust + policy where applicable. +- Custom view definitions must not compromise core graph invariants. + +### Non-Functional + +- View names must be stable. +- View outputs must be bounded and useful for humans. +- Lens composition must remain predictable under cycles and disconnected graphs. + +## Test Plan + +Fixtures: + +- `architecture-map` +- `roadmap-map` +- `blocked-backlog` +- `progress-status-map` +- `cyclic-dependencies` + +Golden path: + +- Architecture view shows module/pkg/crate nodes and dependency edges. +- Roadmap/backlog views show phase/task relationships. +- Progress view groups tasks/features by status. +- Lenses return expected incomplete, frontier, critical-path, blocked, and + parallel subsets. + +Edge cases: + +- Empty graph. +- Graph with only non-view-relevant nodes. +- Cycles in blockers or dependencies. +- Missing status properties. +- Mixed manual and inferred edges. + +Known failures: + +- Unknown view fails predictably. +- Unknown lens fails predictably. +- Invalid lens chain syntax fails before graph traversal. + +Fuzz: + +- Generate DAGs, cyclic graphs, and disconnected graphs. +- Generate random status values and prefixes. +- Generate lens chain permutations. + +Stress: + +- 100k node graph with sparse dependencies. +- Deep critical path. +- Large blocker fan-in and fan-out. + +Regression: + +- Built-in views remain registered. +- Lens output order remains stable. +- View JSON contracts do not drift without schema update. + +Golden artifacts: + +- JSON view snapshots. +- Human output transcripts. +- Lens result fixtures for graph shapes. + +Playback: + +- A new user can inspect a repo through named views and answer concrete + workflow questions without raw graph expertise. diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md index ebf8df1..8c1f5f1 100644 --- a/docs/design/h1-semantic-bootstrap.md +++ b/docs/design/h1-semantic-bootstrap.md @@ -6,6 +6,7 @@ Related: - [Git Mind Product Frame](./git-mind.md) - [ROADMAP.md](../../ROADMAP.md) +- [Feature Profiles](./feature-profiles/README.md) - [ADR-0005](../adr/ADR-0005.md) - [ADR-0006](../adr/ADR-0006.md) - issue [#303](https://github.com/flyingrobots/git-mind/issues/303) From c5cf9562e41668b8c46bb229ed55e1f9d3067e58 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 31 May 2026 21:40:31 -0700 Subject: [PATCH 2/5] docs: define graph data model (#322) --- GRAPH_SCHEMA.md | 1 + README.md | 1 + ROADMAP.md | 1 + docs/README.md | 1 + docs/design/feature-profiles/README.md | 13 + .../feature-profiles/agent-contracts.md | 14 + .../feature-profiles/artifact-inventory.md | 16 ++ .../feature-profiles/bootstrap-command.md | 16 ++ .../feature-profiles/content-on-node.md | 14 + .../feature-profiles/doctor-integrity.md | 15 + .../feature-profiles/entity-extraction.md | 15 + .../feature-profiles/extensions-runtime.md | 16 ++ .../feature-profiles/graph-substrate.md | 15 + .../import-export-interchange.md | 15 + .../feature-profiles/living-map-updates.md | 14 + .../feature-profiles/packaging-adoption.md | 15 + .../feature-profiles/provenance-confidence.md | 15 + .../design/feature-profiles/query-receipts.md | 16 ++ .../relationship-inference.md | 16 ++ .../feature-profiles/repo-fixture-builder.md | 14 + .../feature-profiles/review-refinement.md | 15 + .../feature-profiles/time-travel-diff.md | 14 + .../feature-profiles/trust-observers.md | 14 + docs/design/feature-profiles/views-lenses.md | 14 + docs/design/graph-data-model.md | 257 ++++++++++++++++++ docs/design/h1-semantic-bootstrap.md | 1 + 26 files changed, 558 insertions(+) create mode 100644 docs/design/graph-data-model.md diff --git a/GRAPH_SCHEMA.md b/GRAPH_SCHEMA.md index b055cf4..0cd8d4f 100644 --- 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 index 323594a..23bb032 100644 --- 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 index 0c3c83a..2f3e590 100644 --- 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 index eb33668..54d08b0 100644 --- 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 index 5f89254..a458e4f 100644 --- 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 index 0088df4..04512b3 100644 --- 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 index 2022161..b384d30 100644 --- 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 index 2c1a87e..bac0ea5 100644 --- 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 index 47332e4..a95cbcc 100644 --- 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 index 75bfc72..8cd4eb2 100644 --- 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 index 8200704..ca4571e 100644 --- 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 index 58f4f47..a7a1ec5 100644 --- 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 index 7ffcbd7..7a0ceb9 100644 --- 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 index 6b3c967..72ce56a 100644 --- 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 index 03f0a69..5767fb4 100644 --- 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 index 3217c4f..239f3e0 100644 --- 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 index c0d0583..da8786f 100644 --- 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 index 3f2521b..ba6b166 100644 --- 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 index e650e0d..8517678 100644 --- 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 index 6ddcc57..39eccaa 100644 --- 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 index be51d3a..bef152a 100644 --- a/docs/design/feature-profiles/review-refinement.md +++ b/docs/design/feature-profiles/review-refinement.md @@ -53,6 +53,21 @@ Playback evidence: - Batch operations must be deterministic. - Failed review operations must not leave partial graph state. +## Graph Data Model Usage + +Review refinement turns uncertain edges from +[Graph Data Model](../graph-data-model.md) into reviewed graph facts. Accepted +or adjusted suggestions update edge confidence and add `decision:` nodes that +record the reviewer action. + +```mermaid +flowchart LR + Candidate["file:src/bootstrap.js"] -->|implements| Spec["spec:bootstrap-json"] + Decision["decision:accept-bootstrap-edge"] -->|references| Candidate + Decision -->|references| Spec + Reviewer["person:maintainer"] -->|references| Decision +``` + ## Test Plan Fixtures: diff --git a/docs/design/feature-profiles/time-travel-diff.md b/docs/design/feature-profiles/time-travel-diff.md index 95c4a8b..f338576 100644 --- a/docs/design/feature-profiles/time-travel-diff.md +++ b/docs/design/feature-profiles/time-travel-diff.md @@ -52,6 +52,20 @@ Playback evidence: - Missing or malformed epoch data must degrade predictably. - Diff order must be deterministic. +## Graph Data Model Usage + +Time travel and semantic diff compare snapshots of +[Graph Data Model](../graph-data-model.md) across Git refs or WARP epochs. The +observable unit of change is a node, edge, or assertion property. + +```mermaid +flowchart LR + Before["epoch:before"] -->|references| OldSpec["spec:bootstrap-json"] + Change["commit:def4567"] -->|touches| File["file:src/bootstrap.js"] + File -->|implements| NewSpec["spec:bootstrap-json"] + After["epoch:after"] -->|references| NewSpec +``` + ## Test Plan Fixtures: diff --git a/docs/design/feature-profiles/trust-observers.md b/docs/design/feature-profiles/trust-observers.md index df3e962..7f13b9f 100644 --- a/docs/design/feature-profiles/trust-observers.md +++ b/docs/design/feature-profiles/trust-observers.md @@ -51,6 +51,20 @@ Playback evidence: - Trust behavior must be deterministic. - Unsupported context combinations must fail predictably. +## Graph Data Model Usage + +Trust and observer contexts scope reads and writes over +[Graph Data Model](../graph-data-model.md). Observer metadata should explain +which person, tool, or policy produced or filtered an assertion. + +```mermaid +flowchart LR + Observer["person:maintainer"] -->|references| Policy["spec:trust-policy"] + Tool["tool:bootstrap"] -->|references| Policy + File["file:src/bootstrap.js"] -->|implements| Spec["spec:bootstrap-json"] + Policy -->|documents| View["feature:observer-view"] +``` + ## Test Plan Fixtures: diff --git a/docs/design/feature-profiles/views-lenses.md b/docs/design/feature-profiles/views-lenses.md index 04e3c44..7209b1d 100644 --- a/docs/design/feature-profiles/views-lenses.md +++ b/docs/design/feature-profiles/views-lenses.md @@ -53,6 +53,20 @@ Playback evidence: - View outputs must be bounded and useful for humans. - Lens composition must remain predictable under cycles and disconnected graphs. +## Graph Data Model Usage + +Views and lenses are read-only projections over +[Graph Data Model](../graph-data-model.md). They select canonical node prefixes +and edge types without creating alternate semantics. + +```mermaid +flowchart LR + Architecture["feature:architecture-view"] --> 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"] +``` + ## Test Plan Fixtures: diff --git a/docs/design/graph-data-model.md b/docs/design/graph-data-model.md new file mode 100644 index 0000000..646c320 --- /dev/null +++ b/docs/design/graph-data-model.md @@ -0,0 +1,257 @@ +# Git Mind Graph Data Model + +Status: draft canonical product model for issue #322 + +Related: + +- [Graph Schema Specification](../../GRAPH_SCHEMA.md) +- [Git Mind Product Frame](./git-mind.md) +- [Hill 1 Semantic Bootstrap Spec](./h1-semantic-bootstrap.md) +- [Feature Profiles](./feature-profiles/README.md) + +## IBM Design Thinking Frame + +Sponsor user: + +- A technical lead, staff engineer, architect, or autonomous coding agent + entering an unfamiliar repository and needing a trustworthy semantic map + quickly. + +Job to be done: + +- When Git Mind records repository meaning, use a small, stable graph vocabulary + that can answer real engineering questions with receipts. + +Hills: + +- Hill 1: Zero-input semantic bootstrap. +- Hill 2: Queryable answers with receipts. +- Hill 3: Living map with low manual upkeep. + +Playback evidence: + +- A reviewer can inspect a bootstrap graph and understand why each node exists, + what each edge means, which edges are inferred, which edges are reviewed, and + which evidence supports query answers. + +## Relationship To `GRAPH_SCHEMA.md` + +`GRAPH_SCHEMA.md` is the current executable import and validation contract. +This document is the product-level graph model that feature design should use. + +The split is intentional: + +- `GRAPH_SCHEMA.md` defines what the current runtime accepts. +- this document defines the canonical vocabulary Git Mind should use for repo + intelligence. +- if this document proposes a convention not yet enforced by code, the follow-up + implementation must add tests before treating it as shipped behavior. + +No feature should silently invent a second graph vocabulary. If the vocabulary +here is wrong, update this document and the affected feature profile together. + +## Model Summary + +Git Mind stores repository meaning as directed assertions between canonical +nodes. + +```mermaid +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"] + Reviewer["person:reviewer"] -->|references| Decision["decision:review"] + Decision -->|documents| Assertion +``` + +The local Git repository is the graph scope. In v1, the local repository itself +does not need a regular `repo:` node. Cross-repo references use the existing +qualified ID form: + +```text +repo:owner/name:prefix:identifier +``` + +Example: + +```text +repo:flyingrobots/echo:module:wal +``` + +## Canonical Nodes + +Node IDs use the existing `prefix:identifier` grammar. Identifiers should be +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` | + +### 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` | + +### 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` | + +### 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` | + +## 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` | + +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 Properties + +The current runtime already uses these edge properties: + +| Property | Required | Meaning | +|----------|----------|---------| +| `confidence` | yes | Finite number from `0.0` to `1.0` | +| `createdAt` | yes for local edge creation | ISO timestamp for creation | +| `rationale` | optional | Human-readable explanation | +| `reviewedAt` | optional | ISO timestamp for accepted or adjusted suggestion | + +Feature work should converge on these additional conventions: + +| Property | Meaning | +|----------|---------| +| `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 | +| `observer` | Trust or observer context used when the edge was read or written | +| `schemaVersion` | Machine contract version for structured edge metadata | + +The exact shape of structured `evidence` should become a tested contract before +Hill 2 query receipts depend on it. + +## Confidence Bands + +| Band | Range | Product meaning | +|------|-------|-----------------| +| Verified | `1.0` | Human accepted or manually authored | +| High | `0.8` to `< 1.0` | Strong deterministic signal, not reviewed | +| Medium | `0.5` to `< 0.8` | Useful inference with visible evidence | +| Low | `0.0` to `< 0.5` | Review queue candidate | + +Low-confidence edges should be useful enough to inspect, but they should not be +presented as settled facts. + +## Core Patterns + +### Bootstrap Map + +```mermaid +flowchart LR + Readme["doc:README"] -->|documents| Cli["module:cli"] + Adr["adr:0006"] -->|documents| Bootstrap["feature:semantic-bootstrap"] + Cli -->|groups| Bin["file:bin/git-mind.js"] + Commit["commit:34636d3"] -->|touches| Readme + Readme -->|references| Issue["issue:322"] +``` + +### Query Receipt + +```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"] + Reviewer["person:maintainer"] -->|references| Answer +``` + +### Review Decision + +```mermaid +flowchart LR + Suggestion["file:src/bootstrap.js"] -->|implements| Contract["spec:bootstrap-json"] + Decision["decision:accept-bootstrap-edge"] -->|documents| Contract + Decision -->|references| Suggestion + Reviewer["person:reviewer"] -->|references| Decision +``` + +### Living Map Update + +```mermaid +flowchart LR + Old["epoch:before"] -->|references| Module["module:bootstrap"] + Change["commit:def4567"] -->|touches| File["file:src/bootstrap.js"] + Module -->|groups| File + New["epoch:after"] -->|references| Module +``` + +## Model Rules + +1. Prefer artifact-derived IDs over invented IDs. +2. Prefer specific edge types over `relates-to`. +3. Never claim an inferred edge without confidence and rationale. +4. Inferred edges need evidence that a user or agent can inspect. +5. Review decisions are graph facts, not out-of-band UI state. +6. Historical views must preserve the graph as it was at the selected ref or + epoch. +7. Extension-provided nodes and edges must declare their origin and should stay + inside the same vocabulary unless a profile explicitly extends it. +8. Unknown prefixes are allowed by the v1 schema, but product features should + not rely on unknown prefixes without updating this document and validators. + +## Test Implications + +Every feature that writes or reads graph meaning should test: + +- node ID stability for representative artifacts +- edge direction and type selection +- confidence band assignment +- provenance or evidence availability for inferred edges +- deterministic ordering in machine output +- round trip through export/import when the feature exposes a contract +- historical or observer-scoped behavior when relevant + +The feature-profile test plans define the concrete fixtures and golden artifacts +for those checks. diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md index 8c1f5f1..7935066 100644 --- a/docs/design/h1-semantic-bootstrap.md +++ b/docs/design/h1-semantic-bootstrap.md @@ -6,6 +6,7 @@ Related: - [Git Mind Product Frame](./git-mind.md) - [ROADMAP.md](../../ROADMAP.md) +- [Graph Data Model](./graph-data-model.md) - [Feature Profiles](./feature-profiles/README.md) - [ADR-0005](../adr/ADR-0005.md) - [ADR-0006](../adr/ADR-0006.md) From 9b5006c387d67655205cbc790b45b74c3b486777 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 31 May 2026 22:06:12 -0700 Subject: [PATCH 3/5] docs: address graph model review findings (#322) --- GRAPH_SCHEMA.md | 7 +- ROADMAP.md | 7 +- docs/README.md | 6 +- .../feature-profiles/doctor-integrity.md | 5 +- .../feature-profiles/entity-extraction.md | 18 +- .../import-export-interchange.md | 3 +- .../design/feature-profiles/query-receipts.md | 7 +- docs/design/feature-profiles/views-lenses.md | 2 +- docs/design/graph-data-model.md | 183 +++++++++++++----- docs/design/h1-semantic-bootstrap.md | 5 +- 10 files changed, 176 insertions(+), 67 deletions(-) diff --git a/GRAPH_SCHEMA.md b/GRAPH_SCHEMA.md index 0cd8d4f..b5e7056 100644 --- a/GRAPH_SCHEMA.md +++ b/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). --- diff --git a/ROADMAP.md b/ROADMAP.md index 2f3e590..405f039 100644 --- a/ROADMAP.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 54d08b0..a9a40ef 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/design/feature-profiles/doctor-integrity.md b/docs/design/feature-profiles/doctor-integrity.md index 8cd4eb2..522326d 100644 --- a/docs/design/feature-profiles/doctor-integrity.md +++ b/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"] ``` diff --git a/docs/design/feature-profiles/entity-extraction.md b/docs/design/feature-profiles/entity-extraction.md index ca4571e..7c14bd0 100644 --- a/docs/design/feature-profiles/entity-extraction.md +++ b/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: diff --git a/docs/design/feature-profiles/import-export-interchange.md b/docs/design/feature-profiles/import-export-interchange.md index 72ce56a..95ecd50 100644 --- a/docs/design/feature-profiles/import-export-interchange.md +++ b/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 ``` diff --git a/docs/design/feature-profiles/query-receipts.md b/docs/design/feature-profiles/query-receipts.md index ba6b166..27f9486 100644 --- a/docs/design/feature-profiles/query-receipts.md +++ b/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. diff --git a/docs/design/feature-profiles/views-lenses.md b/docs/design/feature-profiles/views-lenses.md index 7209b1d..62658e6 100644 --- a/docs/design/feature-profiles/views-lenses.md +++ b/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"] diff --git a/docs/design/graph-data-model.md b/docs/design/graph-data-model.md index 646c320..12ba408 100644 --- a/docs/design/graph-data-model.md +++ b/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 ``` diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md index 7935066..2d12e79 100644 --- a/docs/design/h1-semantic-bootstrap.md +++ b/docs/design/h1-semantic-bootstrap.md @@ -92,7 +92,8 @@ The bootstrap should extract or synthesize the following first-pass entities: - `doc:` for general Markdown documents - `adr:` for ADR documents - `module:` for inferred modules or packages where structure is obvious -- `commit:` for recent relevant commits already supported by the substrate +- system-owned `commit:` nodes for recent relevant commits when bootstrap + includes history - `issue:` only when referenced in repo-local artifacts - `pr:` only when referenced in repo-local artifacts @@ -101,6 +102,8 @@ Notes: - `module:` should be conservative in v0. - If module inference is weak, file-level output is preferable to a fake module abstraction. - `issue:` and `pr:` are placeholder semantic nodes backed by repo-local references, not API-enriched tracker records yet. +- `commit:` remains a reserved system prefix; YAML/frontmatter imports must not + author commit nodes directly. ## Relationship Types: v0 From 71f8601b6e34ac965364432df4ece674de079bf1 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 31 May 2026 22:22:10 -0700 Subject: [PATCH 4/5] docs: align upgrade audit completion (#322) --- docs/design/git-warp-upgrade-audit.md | 47 +++++++++++++++------------ test/design-docs.test.js | 21 ++++++++++++ 2 files changed, 47 insertions(+), 21 deletions(-) create mode 100644 test/design-docs.test.js diff --git a/docs/design/git-warp-upgrade-audit.md b/docs/design/git-warp-upgrade-audit.md index cadc4b1..a2c42d7 100644 --- a/docs/design/git-warp-upgrade-audit.md +++ b/docs/design/git-warp-upgrade-audit.md @@ -1,8 +1,9 @@ # git-warp Upgrade Audit -Status: active execution. The original 14.x audit ran on -`feat/git-warp-upgrade-audit`; the v17 continuation is running on -`feat/isolated-warp-upgrade-fixture`. +Status: completed. The original 14.x audit ran on +`feat/git-warp-upgrade-audit`; the v17 continuation completed in issue +[#320](https://github.com/flyingrobots/git-mind/issues/320) and PR +[#321](https://github.com/flyingrobots/git-mind/pull/321). Related: @@ -11,15 +12,16 @@ Related: - [ADR-0006](../adr/ADR-0006.md) - [Repo Fixture Strategy](./repo-fixture-strategy.md) - issue [#312](https://github.com/flyingrobots/git-mind/issues/312) +- issue [#320](https://github.com/flyingrobots/git-mind/issues/320) ## Purpose -Define the next enabling cycle before major Hill 1 implementation: +Record the completed enabling cycle before major Hill 1 implementation: > audit and upgrade Git Mind's `@git-stunts/git-warp` dependency so new Hill 1 work is not built on an outdated substrate by accident. -This is not a generic dependency bump. -It is a boundary audit plus upgrade cycle. +This was not a generic dependency bump. +It was a boundary audit plus upgrade cycle. ## Sponsor User @@ -51,23 +53,24 @@ It does mean Git Mind should not keep expanding Hill 1 behavior without auditing ## 2026-05-31 v17 Continuation -The original audit cycle moved Git Mind to the 14.x substrate. A follow-on -modernization is now needed because the live npm registry reports: +The original audit cycle moved Git Mind to the 14.x substrate. The follow-on +modernization moved Git Mind to: -- latest published `@git-stunts/git-warp` version: `17.0.0` -- latest published `@git-stunts/plumbing` version: `3.0.3` +- `@git-stunts/git-warp`: `17.0.0` +- `@git-stunts/plumbing`: `3.0.3` -`@git-stunts/git-warp@17.0.0` depends on `@git-stunts/plumbing@^3.0.3`, so -the next substrate upgrade should move those packages together. +`@git-stunts/git-warp@17.0.0` depends on `@git-stunts/plumbing@^3.0.3`, so the +upgrade moved those packages together. -This pass keeps the upgrade sequence explicit: +The completed pass kept the upgrade sequence explicit: 1. freeze a sanitized Git-native fixture from the current v5 / git-warp 14 state 2. include only `HEAD` and the relevant `refs/warp/gitmind/*` graph refs 3. test that fixture in Docker without mounting this checkout into the container 4. pack the current Git Mind package and copy it into the Docker context 5. run graph/status/export assertions with a scrubbed home and Git config -6. upgrade to git-warp 17 / plumbing 3 and prove the migrated fixture still reads +6. upgrade to git-warp 17 / plumbing 3 and prove the migrated fixture still + reads This fixture is intentionally a Git bundle rather than a raw working-directory archive. It preserves the exact Git object and WARP ref state under test while @@ -76,7 +79,7 @@ and host-specific paths. Related issue: [#320](https://github.com/flyingrobots/git-mind/issues/320) -The local playback command for this safety rail is: +The local playback command for this safety rail remains: ```bash npm run test:upgrade-fixture @@ -151,11 +154,12 @@ This cycle exposed one concrete runtime compatibility change: Git Mind must treat node property bags as a compatibility boundary rather than assuming a single container shape. -This cycle also started with contributor-facing docs that still claimed git-warp was installed via local path. Those docs should be corrected as part of the upgrade. +This cycle also started with contributor-facing docs that still claimed git-warp +was installed via local path. Those docs were corrected as part of the upgrade. ## Acceptance Criteria -This cycle succeeds when: +This cycle succeeded when: 1. Git Mind's actual git-warp dependency surface is documented and reviewed. 2. Compatibility-sensitive behaviors are protected by tests. @@ -165,7 +169,8 @@ This cycle succeeds when: ## Execution Model -Per [ADR-0006](../adr/ADR-0006.md), this cycle should follow the normal design-to-test flow: +Per [ADR-0006](../adr/ADR-0006.md), this cycle followed the normal +design-to-test flow: 1. finalize the upgrade-audit design artifact 2. translate the risky boundary into failing tests @@ -174,7 +179,7 @@ Per [ADR-0006](../adr/ADR-0006.md), this cycle should follow the normal design-t 5. run a playback / retrospective 6. update README and contributor docs if reality changed -## Recommended First Work Sequence +## Executed Work Sequence 1. Inventory git-warp touchpoints in `src/` and relevant tests. 2. Add or strengthen tests around: @@ -183,8 +188,8 @@ Per [ADR-0006](../adr/ADR-0006.md), this cycle should follow the normal design-t - content attachment - time-travel / epoch behavior - observer behavior if still relevant -3. Review upstream changes between `11.5.0` and the candidate target. -4. Upgrade the dependency and lockfile on a dedicated branch. +3. Review upstream changes between `11.5.0`, `14.16.2`, and `17.0.0`. +4. Upgrade the dependency and lockfile on dedicated branches. 5. Fix breakage explicitly rather than papering over it. ## Playback Questions diff --git a/test/design-docs.test.js b/test/design-docs.test.js new file mode 100644 index 0000000..df51637 --- /dev/null +++ b/test/design-docs.test.js @@ -0,0 +1,21 @@ +import { readFileSync } from 'node:fs'; + +import { describe, expect, it } from 'vitest'; + +describe('design docs integrity', () => { + it('keeps the git-warp upgrade audit aligned with completed dependency reality', () => { + const audit = readFileSync('docs/design/git-warp-upgrade-audit.md', 'utf8'); + const packageJson = JSON.parse(readFileSync('package.json', 'utf8')); + + expect(audit).toMatch(/^Status: completed\./m); + expect(audit).toContain( + `- \`@git-stunts/git-warp\`: \`${packageJson.dependencies['@git-stunts/git-warp']}\``, + ); + expect(audit).toContain( + `- \`@git-stunts/plumbing\`: \`${packageJson.dependencies['@git-stunts/plumbing']}\``, + ); + expect(audit).not.toMatch( + /active execution|is running on|modernization is now needed|the next substrate upgrade should/, + ); + }); +}); From 0380c4375dcc315b583b1a2db259a018985db7ad Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 31 May 2026 22:23:22 -0700 Subject: [PATCH 5/5] docs: tighten graph system id examples (#322) --- .../feature-profiles/graph-substrate.md | 2 +- .../feature-profiles/time-travel-diff.md | 4 +-- docs/design/graph-data-model.md | 4 +-- test/design-docs.test.js | 25 ++++++++++++++++++- 4 files changed, 29 insertions(+), 6 deletions(-) diff --git a/docs/design/feature-profiles/graph-substrate.md b/docs/design/feature-profiles/graph-substrate.md index 7a0ceb9..996afbe 100644 --- a/docs/design/feature-profiles/graph-substrate.md +++ b/docs/design/feature-profiles/graph-substrate.md @@ -65,7 +65,7 @@ higher-level features to trust them. 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 + Patch["commit:def4567"] -->|touches| Adapter Schema["doc:GRAPH_SCHEMA"] -->|documents| Graph ``` diff --git a/docs/design/feature-profiles/time-travel-diff.md b/docs/design/feature-profiles/time-travel-diff.md index f338576..5ec82fa 100644 --- a/docs/design/feature-profiles/time-travel-diff.md +++ b/docs/design/feature-profiles/time-travel-diff.md @@ -60,10 +60,10 @@ observable unit of change is a node, edge, or assertion property. ```mermaid flowchart LR - Before["epoch:before"] -->|references| OldSpec["spec:bootstrap-json"] + Before["epoch:34636d3"] -->|references| OldSpec["spec:bootstrap-json"] Change["commit:def4567"] -->|touches| File["file:src/bootstrap.js"] File -->|implements| NewSpec["spec:bootstrap-json"] - After["epoch:after"] -->|references| NewSpec + After["epoch:def4567"] -->|references| NewSpec ``` ## Test Plan diff --git a/docs/design/graph-data-model.md b/docs/design/graph-data-model.md index 12ba408..27355ac 100644 --- a/docs/design/graph-data-model.md +++ b/docs/design/graph-data-model.md @@ -308,10 +308,10 @@ flowchart LR ```mermaid flowchart LR - Old["epoch:before"] -->|references| Module["module:bootstrap"] + Old["epoch:34636d3"] -->|references| Module["module:bootstrap"] Change["commit:def4567"] -->|touches| File["file:src/bootstrap.js"] Module -->|groups| File - New["epoch:after"] -->|references| Module + New["epoch:def4567"] -->|references| Module ``` ## Model Rules diff --git a/test/design-docs.test.js b/test/design-docs.test.js index df51637..17753c6 100644 --- a/test/design-docs.test.js +++ b/test/design-docs.test.js @@ -1,4 +1,5 @@ -import { readFileSync } from 'node:fs'; +import { readdirSync, readFileSync } from 'node:fs'; +import { join } from 'node:path'; import { describe, expect, it } from 'vitest'; @@ -18,4 +19,26 @@ describe('design docs integrity', () => { /active execution|is running on|modernization is now needed|the next substrate upgrade should/, ); }); + + it('uses concrete system-owned commit and epoch IDs in graph-model examples', () => { + const files = [ + 'docs/design/graph-data-model.md', + ...readdirSync('docs/design/feature-profiles') + .filter((name) => name.endsWith('.md')) + .map((name) => join('docs/design/feature-profiles', name)), + ]; + const abstractIds = []; + + for (const file of files) { + const text = readFileSync(file, 'utf8'); + for (const match of text.matchAll(/\b(commit|epoch):([A-Za-z0-9._/-]+)/g)) { + const [, prefix, identifier] = match; + if (!/^[0-9a-f]{7,40}$/.test(identifier)) { + abstractIds.push(`${file}: ${prefix}:${identifier}`); + } + } + } + + expect(abstractIds).toEqual([]); + }); });