diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 00000000..6adc2e9c --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,44 @@ +name: CodeQL + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '21 7 * * 1' + +permissions: + actions: read + contents: read + security-events: write + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + runs-on: ubuntu-24.04 + timeout-minutes: 60 + strategy: + fail-fast: false + matrix: + include: + - language: javascript-typescript + build-mode: none + - language: actions + build-mode: none + + steps: + - name: Checkout + uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 + + - name: Initialize CodeQL + uses: github/codeql-action/init@38697555549f1db7851b81482ff19f1fa5c4fedc + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + queries: security-extended,security-and-quality + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@38697555549f1db7851b81482ff19f1fa5c4fedc + with: + category: /language:${{ matrix.language }} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..6f341fe5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,98 @@ +# OPERATIONAL ORDERS FOR Codex + +## CROSS-REFERENCE + +- Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md) +- Documentation map and canonical docs: [docs/README.md](docs/README.md) +- CLI/user reference: [GUIDE.md](GUIDE.md) + +## FORBIDDEN ACTIONS + +- **NEVER** circumvent git hooks +- **NEVER** use `git add -A` — always stage changes intentionally +- **NEVER** commit files that contain secrets (.env, credentials, etc.) +- **NEVER** commit directly to `main` — always work on a feature branch and merge via PR + +## ENCOURAGED ACTIONS + +- **USE SEQUENTIAL THINKING** if you're planning, doing recon, or find yourself thrashing +- **DROP A DEVLOG** as often as you'd like +- **PRESENT A SITREP** as situations evolve +- **SEEK CLARITY** if you are given confusing orders +- **SPEAK FREELY** at all times + +## REQUIRED BEHAVIOR + +- **YOU MUST** tag all memories saved to your memory banks with at least `#git-mind` +- **YOU MUST** include the POSIX timestamp (via `$(date +%s)`) in memory file names +- **YOU MUST** document significant decisions or events +- **YOU MUST** reference a GitHub issue in every commit message + +--- + +## 1. BOOT UP SEQUENCE + +1. Access your memory banks and scan for recent activity (latest SITREP or relevant notes) +2. Read the README +3. State your current understanding of what we last worked on and your next moves +4. **AWAIT ORDERS** after you deliver your initial SITREP + +--- + +## 2. JOBS + +> All work should have a GitHub issue associated with it. If there isn't one, find or create one. Every commit message must reference an issue. + +### 2.1. PLAN THE JOB + +1. Before starting, use sequential thinking to make a plan +2. Explain your plan to the user and await approval +3. Commit your approved plan to your memory banks +4. **Create a feature branch** — `git checkout -b feat/` — before writing any code + +### 2.2. DO THE JOB + +1. Green the builds, green the tests +2. Drop micro-commits as you complete steps — always use conventional commit format +3. Drop a SITREP if you hit a snag or need input +4. Drop a DEVLOG for ideas, observations, or anything you want to remember +5. Use your memory banks freely + +> **ALWAYS** overwrite files, **NEVER** create secondary copies — that creates confusion and tech debt. + +### 2.3. FINISH THE JOB + +1. Green the builds, green the tests +2. Git commit (do NOT use `git add -A`) +3. Ask the user if they want you to push and open a PR +4. Drop a SITREP as you finish + +--- + +## 3. SITREPs + +A briefing covering: +- Current tasks and situation understanding +- Relevant stats, files, issues, PRs +- Intel the user can use to make decisions +- Options and recommendations, then await orders + +## 4. DEVLOGs + +Your space. Write about whatever you want: +- Ideas that came up while working +- Problems you notice +- Insights about collaboration +- Anything you want to remember later + +--- + +## 5. TECH STACK REFERENCE + +- **Runtime**: Node.js >= 20, ES modules +- **Core dependency**: `@git-stunts/git-warp` (local path, CRDT graph on Git) +- **Plumbing**: `@git-stunts/plumbing` (must be installed as direct dependency) +- **Tests**: vitest +- **Style**: Plain JS with JSDoc, no TypeScript +- **CLI**: Manual argv parsing, no CLI frameworks +- **Formatting**: chalk + figures for terminal output diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ffd058d..253db6f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ All notable changes to this project will be documented in this file. +This is release history, not the canonical product frame. +Older entries will naturally reflect prior roadmap eras and product language. + The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). diff --git a/CLAUDE.md b/CLAUDE.md index 0d67e55f..00c6bad3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,7 +3,8 @@ ## CROSS-REFERENCE - Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md) -- User-facing documentation: [GUIDE.md](GUIDE.md) +- Documentation map and canonical docs: [docs/README.md](docs/README.md) +- CLI/user reference: [GUIDE.md](GUIDE.md) ## FORBIDDEN ACTIONS diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b14ab65..57b33379 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,19 @@ Thanks for your interest in contributing. This document covers the essentials. +Before changing product-facing behavior or docs, read these first: + +- [README.md](README.md) +- [docs/README.md](docs/README.md) +- [docs/design/git-mind.md](docs/design/git-mind.md) +- [ROADMAP.md](ROADMAP.md) + +Current product frame: + +- `git-mind` is a Git-native semantic intelligence layer for software repositories +- current work should be judged against low-input semantic bootstrap, provenance-backed query, and living-map upkeep +- personal cognition tooling belongs in `think`, not here + ## Prerequisites - Node.js >= 20.0.0 diff --git a/GRAPH_SCHEMA.md b/GRAPH_SCHEMA.md index d0a1280e..72945ed1 100644 --- a/GRAPH_SCHEMA.md +++ b/GRAPH_SCHEMA.md @@ -3,6 +3,9 @@ > **Authoritative contract for git-mind's knowledge graph.** > All validators, importers, and views implement against this document. > 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. --- diff --git a/GUIDE.md b/GUIDE.md index 2f554db3..645e043b 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,6 +1,11 @@ # git-mind Guide -Everything you need to know — from zero to power user. +> Status: transitional document. +> +> The CLI reference in this guide is still useful, but parts of the framing and examples reflect Git Mind's earlier manual graph-authoring story. +> For the current product direction, start with [README.md](README.md), [ROADMAP.md](ROADMAP.md), [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md), and [docs/design/git-mind.md](docs/design/git-mind.md). + +CLI reference and usage guide. --- @@ -26,6 +31,9 @@ Everything you need to know — from zero to power user. git-mind adds a **semantic knowledge graph** to any Git repository. You create **nodes** (files, concepts, tasks, modules — anything) and connect them with **typed edges** (implements, depends-on, documents, etc.). The graph lives inside Git — no external databases, no servers. +Manual graph authoring is still supported, but it is no longer the primary product story. +The current direction is inference-first semantic repository intelligence: Git Mind should increasingly extract and surface repository meaning before it asks users to model the graph by hand. + **Why?** Code tells a computer what to do. Comments tell a human what the code does. But neither captures *why* things are connected — which spec does this file implement? What does this module depend on? What task does this commit address? diff --git a/README.md b/README.md index 253a4352..10f60739 100644 --- a/README.md +++ b/README.md @@ -1,208 +1,145 @@ # git-mind -> Version your thoughts. Branch your ideas. Merge understanding. +> Queryable repository meaning with receipts. -**git-mind** turns any Git repository into a causally-versioned semantic knowledge graph. Link code, specs, decisions, and tasks with typed, confidence-scored edges. Query with composable views and lenses. Travel back in time to see what you understood then. +`git-mind` is a Git-native semantic intelligence layer for software repositories. -No servers. No databases. Just `git push`. +It exists to establish, infer, review, and surface semantic relationships between project artifacts such as: ---- +- code +- docs +- ADRs +- tasks +- reviews +- issues +- commits -## Quick start +It keeps that knowledge in Git/WARP so it can be replayed, diffed, reviewed, and queried over time. -```bash -# Install -npm install -g git-mind +`git-mind` is not a personal thought-capture tool. +That thesis now lives in `think`. -# Initialize in any Git repo -cd /path/to/your/repo -git mind init +## What Git Mind Is For -# Create semantic edges -git mind link file:src/auth.js spec:auth --type implements -git mind link task:login spec:auth --type belongs-to -git mind link task:login task:setup --type depends-on +`git-mind` is for the moment when you need to answer questions like: -# See the graph -git mind list -git mind status +- what implements this spec? +- what ADR explains this module? +- what issues and reviews shaped this area? +- what changed semantically between these two points in time? +- what does this repository actually mean, beyond its files? -# Query with views and lenses -git mind view roadmap -git mind view roadmap:incomplete -git mind view roadmap:incomplete:frontier -``` +Its job is to make repository meaning more explicit and less dependent on tribal knowledge, grep archaeology, and memory. ---- +## Current Product Direction -## What it does +Today, `git-mind` already provides a substantial graph substrate: -### Typed, confidence-scored edges +- repo-native graph storage on top of Git/WARP +- typed relationships and node metadata +- views and lenses over the graph +- import/export paths +- time-travel and semantic diff +- AI-assisted suggestion and review workflows +- content-on-node +- extension support -Every relationship has a type and a confidence score. Human-created edges default to 1.0. AI-suggested edges start low and get promoted through review. +The next hill is not "more graph features." -```bash -git mind link spec:auth crate:jwt --type depends-on --confidence 0.9 -git mind link file:src/auth.js spec:auth --type implements -git mind link adr:0007 task:M11 --type blocks -``` +The next hill is: -| Edge type | Meaning | -|-----------|---------| -| `implements` | Source implements the target spec/design | -| `augments` | Source extends or enhances the target | -| `relates-to` | General semantic relationship | -| `blocks` | Source blocks progress on target | -| `belongs-to` | Source is a member/child of target | -| `consumed-by` | Source is consumed/used by target | -| `depends-on` | Source depends on target | -| `documents` | Source documents/describes target | +- point `git-mind` at a repository and get an immediately useful semantic map with provenance-backed answers, with as little manual input as possible -### Views and composable lenses +That is the make-or-break product test from here. -Views project the graph into focused surfaces. Lenses filter those projections further. Chain them with colons. +## Quick Start ```bash -# Built-in views -git mind view roadmap # milestones, tasks, blockers -git mind view architecture # specs, ADRs, crates, relationships -git mind view backlog # open tasks -git mind view suggestions # low-confidence edges for review - -# Compose with lenses -git mind view roadmap:incomplete # only unfinished nodes -git mind view roadmap:incomplete:frontier # unfinished with no dependents (ready to start) -git mind view roadmap:critical-path # longest dependency chain -git mind view backlog:blocked # tasks that are stuck -git mind view backlog:parallel # tasks with no mutual dependencies (run concurrently) -``` - -Available lenses: `incomplete`, `frontier`, `critical-path`, `blocked`, `parallel` - -### Import from YAML or Markdown - -Seed the graph from structured files. Import is atomic and idempotent — safe to re-run. +# Install +npm install -g git-mind -```bash -# YAML import -git mind import graph.yaml -git mind import graph.yaml --dry-run # preview without writing -git mind import graph.yaml --validate # schema check only +# Initialize in a Git repository +cd /path/to/your/repo +git mind init -# Pull relationships out of Markdown frontmatter +# Seed relationships from existing markdown docs where possible git mind import --from-markdown "docs/**/*.md" -``` - -YAML format: - -```yaml -version: 1 -nodes: - - id: spec:auth - props: { title: "Authentication spec", status: in-progress } - - id: task:login - props: { status: todo } -edges: - - source: task:login - target: spec:auth - type: implements - confidence: 0.9 -``` -### Time-travel - -The graph has a full causal history. Travel to any commit and see what you knew then. - -```bash -git mind at main~100 # graph as it was 100 commits ago -git mind at v1.0.0 # graph at a tagged release -git mind diff HEAD~10..HEAD --prefix task # what changed in tasks -``` +# Inspect the semantic graph +git mind nodes +git mind view architecture +git mind status -### Graph health +# Surface candidate relationships for review +git mind suggest +git mind review -```bash -git mind doctor # detect dangling edges, orphan nodes, duplicates -git mind doctor --fix # auto-fix safe issues -git mind status # node/edge counts, blocked items, low-confidence edges +# Compare repository meaning over time +git mind diff HEAD~10..HEAD ``` -### AI-assisted curation +Manual edge creation remains supported, but it should increasingly be treated as refinement or override rather than the only path to value: ```bash -git mind suggest --ai # LLM-suggested edges based on recent commits -git mind review # interactive accept/reject/adjust loop -git mind review --batch # non-interactive batch review +git mind link file:src/auth.js spec:auth --type implements +git mind link adr:0007 task:auth-rollout --type blocks ``` -### Multi-repo federation - -```bash -# Cross-repo edges -git mind link spec:auth repo:org/other-repo:crate:jwt --type depends-on - -# Merge another repo's graph into this one -git mind merge --from ../other-repo -``` +## Product Doctrine -### Commit directives +- Low-input semantic bootstrap matters. +- Inference should precede heavy manual curation. +- Provenance must back meaningful assertions. +- Review should refine the map, not create it from scratch. +- The graph is the substrate, not the user's main mental model. +- Queryable value matters more than graph elegance. -Add edges directly from commit messages — no CLI required: +## What Git Mind Is Not -``` -feat: add JWT validation +`git-mind` is not: -gm: task:login implements spec:auth -gm: task:login depends-on task:setup -``` +- a personal capture product +- a reflective journal +- a manually maintained project wiki +- a generic PKM system +- a graph toy with no clear engineering question behind it -### JSON output for scripting +## Built On git-warp -Every command supports `--json`. All outputs are schema-validated. +`git-mind` is built on [`@git-stunts/git-warp`](https://github.com/nicktomlin/git-warp), which gives it: -```bash -git mind status --json | jq '.totals.nodes' -git mind view roadmap:incomplete --json | jq '.nodes[]' -git mind diff HEAD~5..HEAD --json -``` +- causal history +- deterministic replay +- conflict-free graph merging +- branch and merge semantics for knowledge state +- Git-native persistence without an external database ---- +Those are not the product by themselves. +They are what make provenance-backed repository intelligence possible. -## Built on git-warp +## Status -git-mind is built on [`@git-stunts/git-warp`](https://github.com/nicktomlin/git-warp) — a multi-writer CRDT graph that lives in Git. This gives git-mind properties that no external database can match: +Current package version: `5.0.0`. -- **Causal history** — every write has a Lamport tick. `git mind at` isn't a snapshot lookup — it materializes the exact causal state of the graph at that point in history. -- **Conflict-free merging** — multiple writers, deterministic convergence. No merge conflicts in your knowledge graph, ever. -- **Branch and merge** — explore experimental relationships in a branch. Merge what works, discard what doesn't. Same workflow as your code. -- **Zero infrastructure** — the graph is stored in Git's object store. Invisible to normal workflows. No files cluttering your working tree. +The repository is in a stabilize-and-clarify phase: ---- +- the inward-facing cognition thesis has moved to `think` +- `git-mind` is being narrowed around semantic repository intelligence +- existing graph capabilities remain real and useful +- future work should be judged against the low-input semantic bootstrap hill ## Documentation -| Document | Purpose | -|----------|---------| -| [GUIDE.md](GUIDE.md) | Complete user guide — install, tutorial, all features | -| [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md) | Schema spec — node IDs, edge types, import format | -| [ROADMAP.md](ROADMAP.md) | Milestone history and upcoming work | -| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute | -| [CHANGELOG.md](CHANGELOG.md) | Release history | -| [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md) | Long-term direction | -| [docs/adr/](docs/adr/) | Architecture decision records | +Canonical docs: ---- - -## Status - -**v3.2.0** — M1–M10 shipped. 461 tests. JSON schema contracts on all `--json` outputs. - -The API is stabilising. Breaking changes will be noted in [CHANGELOG.md](CHANGELOG.md). - ---- +- [docs/README.md](docs/README.md) +- [GUIDE.md](GUIDE.md) +- [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md) +- [ROADMAP.md](ROADMAP.md) +- [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md) +- [docs/design/git-mind.md](docs/design/git-mind.md) +- [docs/adr/](docs/adr/) ## License [Apache-2.0](LICENSE) - -Copyright 2025–2026 James Ross diff --git a/ROADMAP.md b/ROADMAP.md index 29fccd3d..0bffdfbb 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,2238 +1,282 @@ -# ROADMAP — git-mind v2 +# ROADMAP -> **"A knowledge graph that thinks alongside you."** -> -> This roadmap is itself tracked as a DAG inside git-mind's own graph. -> Run `git mind view roadmap` to see it live. +> Git Mind should point at a repository and help explain what matters, how it connects, and how it evolved. ---- - -## Vision - -git-mind is a **project knowledge graph** built on git-warp. It turns any Git repository into a semantic graph of relationships between files, specs, milestones, crates, issues, and ideas — all stored in Git itself, powered by CRDTs. - -The first consumer is the [Echo](https://github.com/neuroglyph/echo) ecosystem, where git-mind tracks the relationships between milestones, specs, ADRs, crates, and issues across a multi-repo architecture. - ---- - -## Current State (v2.0.0-alpha.5) - -All **8 milestones** shipped on `main` — Feb 2026. 342 tests across 20 files. - -**v2.0.0-alpha.0** — Complete rewrite from C23 to Node.js on `@git-stunts/git-warp`. - -**Shipped features (17 CLI commands):** -- Graph core (init, load, checkpoint via WARP CRDT) -- Edge CRUD with 8 typed edges + confidence scores -- Node query API (`nodes`, `--prefix`, `--id`, `--json`) -- Graph status dashboard (`status`, `--json`) -- 10 observer views: `roadmap`, `architecture`, `backlog`, `suggestions`, `milestone`, `traceability`, `blockers`, `onboarding`, `coverage` + custom declarative views -- YAML import pipeline with schema validation, dry-run, atomic writes -- Markdown frontmatter import (`import --from-markdown`) -- Graph export (YAML/JSON, round-trip compatible) -- Runtime schema validators (node IDs, edge types, confidence, prefixes) -- Commit directive parser (auto-create edges from commit messages) -- Cross-repo edge protocol (`repo:owner/name:prefix:id`) -- Multi-repo graph merge (`merge --from`) -- Graph integrity doctor (`doctor`, `--fix`, `--json`) -- AI-powered edge suggestions (`suggest`, `--agent`, `--context`) -- Interactive review flow (`review`, `--batch`, decision provenance) -- Epoch-based time-travel (`at `, `--json`) -- Graph diff between commits (`diff ..`, `--prefix`, `--json`) -- GitHub Action for PR suggestions + slash command review -- 342 tests across 20 files, CI green - ---- - -## Milestones - -| # | Codename | Theme | Status | -|---|----------|-------|--------| -| 1 | **BEDROCK** | Schema & Node Foundations | DONE | -| 2 | **INTAKE** | Data Ingestion Pipeline | DONE | -| 3 | **PRISM** | Views & Value Surfaces | DONE | -| 4 | **WATCHTOWER** | Dashboard & Observability | DONE | -| 5 | **PROVING GROUND** | Dogfood Validation | DONE | -| 6 | **ORACLE** | AI Intelligence & Curation | DONE | -| 7 | **NEXUS** | Integration & Federation | DONE | -| 8 | **CHRONICLE** | Graph Diff & History | DONE | -| 9 | **IRONCLAD** | GA Hardening & Adoption | IN PROGRESS | - ---- - -# Milestone 1: BEDROCK - -> **"Before you build the cathedral, you lay the bedrock."** - -**Goal:** Establish the schema contract, runtime validators, and node query layer that everything else rests on. - -**Refs:** #180 - -**Milestone Dependencies:** None — this is the foundation. - ---- - -## Feature BDK-SCHEMA: Schema Contract - -> Define the grammar of the graph. What is a node? What is an edge? What are the rules? - -### Task BDK-001: Write GRAPH_SCHEMA.md Specification - -**User Story:** As a contributor, I want a single authoritative document that defines the graph schema so that I never have to guess what a valid node ID or edge looks like. - -**Requirements:** -- Define node ID grammar: `prefix:identifier` with allowed characters -- Define prefix taxonomy (milestone, feature, task, spec, adr, crate, issue, concept, decision, person, tool, event, metric) -- Define edge type semantics for all 8 types (implements, augments, relates-to, blocks, belongs-to, consumed-by, depends-on, documents) -- Define duplicate handling rules -- Define update semantics (upsert by default) -- Include examples for every rule - -**Acceptance Criteria:** -- [ ] Document exists at `GRAPH_SCHEMA.md` -- [ ] Every prefix in the taxonomy is defined with purpose and examples -- [ ] Every edge type has a definition, directionality, and valid source/target prefix constraints -- [ ] A "Non-Examples" section shows what's invalid and why -- [ ] The document is referenced from README.md - -**Scope:** -- *In:* Node ID grammar, prefix taxonomy, edge semantics, duplicate/update rules -- *Out:* Runtime validation code (that's BDK-002), import semantics (that's INTAKE) - -**Complexity:** ~200 LoC (markdown) -**Est. Human Hours:** 3 - -**Definition of Done:** -- Document reviewed and merged -- All edge types and prefixes documented -- Cross-referenced from README.md - -**Blocked By:** — -**Blocking:** BDK-002, BDK-003, INT-001, INT-005 - -**Test Plan:** -- *Golden Path:* N/A (documentation) -- *Failure Modes:* N/A -- *Edge Cases:* Ensure all 8 edge types are covered, no prefix collisions -- *Fuzz/Stress:* N/A - ---- - -### Task BDK-002: Implement Schema Runtime Validators - -**User Story:** As a developer, I want runtime validation functions that enforce the schema contract so that invalid data is rejected at the boundary. - -**Requirements:** -- `validateNodeId(id)` — returns `{ valid, prefix, identifier, error }` -- `validateEdgeType(type)` — returns `{ valid, error }` -- `validateEdge({ source, target, type, confidence })` — full edge validation -- `validatePrefix(prefix)` — checks against the taxonomy -- All validators must be pure functions (no side effects) -- Error messages must quote the invalid input and state the rule violated - -**Acceptance Criteria:** -- [ ] `src/schema.js` exports all four validators -- [ ] Valid inputs return `{ valid: true }` -- [ ] Invalid inputs return `{ valid: false, error: "..." }` with descriptive message -- [ ] Confidence must be a number in [0.0, 1.0] -- [ ] Unknown prefixes are rejected -- [ ] Unknown edge types are rejected - -**Scope:** -- *In:* Validation functions, error messages, prefix+edge-type enums -- *Out:* Graph writes (validators don't write), import logic - -**Complexity:** ~120 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- All validators implemented and exported -- Test suite passes (BDK-007) -- JSDoc on every exported function - -**Blocked By:** BDK-001 -**Blocking:** BDK-007, INT-005, INT-006 - -**Test Plan:** -- *Golden Path:* Valid node IDs (`milestone:BEDROCK`, `task:BDK-001`) pass validation -- *Failure Modes:* Missing prefix, empty identifier, unknown prefix, malformed confidence -- *Edge Cases:* Unicode identifiers, very long IDs (>256 chars), empty string, prefix-only (`milestone:`), colon-only (`:`) -- *Fuzz/Stress:* Fuzz validateNodeId with 10K random strings, expect no throws (only `{ valid: false }`) - ---- - -## Feature BDK-NODES: Node Query Layer - -> Nodes exist implicitly when edges reference them. This feature makes them first-class citizens. - -### Task BDK-003: Implement Node Query & Inspection API - -**User Story:** As a CLI user, I want to query and inspect nodes in the graph so that I can understand what exists without having to look at raw edges. - -**Requirements:** -- `getNodes(graph, filter)` — return all nodes, optionally filtered by prefix -- `getNode(graph, id)` — return a single node with all its properties and connected edges -- `getNodesByPrefix(graph, prefix)` — convenience wrapper -- `hasNode(graph, id)` — boolean existence check -- Return values include: `{ id, prefix, identifier, props, inEdges, outEdges }` - -**Acceptance Criteria:** -- [ ] `src/nodes.js` exports all four functions -- [ ] `getNodes()` with no filter returns all nodes -- [ ] `getNodes({ prefix: 'task' })` returns only task nodes -- [ ] `getNode(id)` returns full node detail with connected edges -- [ ] Non-existent node returns `null` (not throw) -- [ ] Works with the existing graph (backward compatible) - -**Scope:** -- *In:* Read-only query functions, prefix filtering, edge aggregation -- *Out:* Node creation (nodes are created implicitly via edges), node deletion, node property mutation - -**Complexity:** ~150 LoC -**Est. Human Hours:** 4 - -**Definition of Done:** -- All functions implemented and exported -- Test suite passes (BDK-008) -- Integrates with existing graph.js without breaking changes - -**Blocked By:** BDK-001 -**Blocking:** BDK-005, PRI-001, WTC-003 - -**Test Plan:** -- *Golden Path:* Create edges → query nodes → verify node list matches expected -- *Failure Modes:* Query empty graph returns `[]`, query nonexistent node returns `null` -- *Edge Cases:* Node referenced only as source vs. only as target, node with 0 edges after edge removal -- *Fuzz/Stress:* Create 1000 edges → verify getNodes() performance <100ms - ---- - -### Task BDK-004: Node Property Getters & Metadata - -**User Story:** As a developer, I want to attach and retrieve properties on nodes so that nodes carry meaningful metadata beyond just their ID. - -**Requirements:** -- `setNodeProps(graph, id, props)` — shallow merge properties onto a node -- `getNodeProps(graph, id)` — retrieve all properties of a node -- Properties are arbitrary key-value pairs (string keys, JSON-serializable values) -- Setting properties on a non-existent node is a no-op (returns error) - -**Acceptance Criteria:** -- [ ] `setNodeProps` and `getNodeProps` exported from `src/nodes.js` -- [ ] Properties persist across save/load cycle -- [ ] Shallow merge: existing props not mentioned are preserved -- [ ] Non-existent node returns `null` props - -**Scope:** -- *In:* Property get/set, shallow merge semantics -- *Out:* Deep merge, property deletion, property validation, property types - -**Complexity:** ~60 LoC -**Est. Human Hours:** 2 - -**Definition of Done:** -- Functions implemented -- Properties survive checkpoint/reload -- Test coverage in BDK-008 - -**Blocked By:** BDK-003 -**Blocking:** BDK-005, INT-002 - -**Test Plan:** -- *Golden Path:* Set props → get props → verify match -- *Failure Modes:* Set on nonexistent node → error, get on nonexistent → null -- *Edge Cases:* Overwrite existing prop, add new prop to node with existing props, empty props object -- *Fuzz/Stress:* Set 100 properties on a single node, verify all retrievable - ---- - -## Feature BDK-CLI: Node CLI Command - -> Give humans a way to ask "what's in this graph?" - -### Task BDK-005: Implement `git mind nodes` Command - -**User Story:** As a CLI user, I want to run `git mind nodes` to see all nodes in the graph so that I can quickly understand the graph's contents. - -**Requirements:** -- `git mind nodes` — list all nodes (ID + prefix) -- `git mind nodes --prefix ` — filter by prefix -- `git mind nodes --id ` — show detail for a single node -- `git mind nodes --json` — output as JSON array -- Default output: human-readable table with columns: ID, Prefix, # Edges - -**Acceptance Criteria:** -- [ ] Command registered in CLI entry point -- [ ] No-arg invocation lists all nodes -- [ ] `--prefix` filters correctly -- [ ] `--id` shows full detail (props + edges) -- [ ] `--json` outputs valid JSON -- [ ] Empty graph shows informative message, not error - -**Scope:** -- *In:* CLI command, flag parsing, formatted output, JSON output -- *Out:* Interactive mode, pagination, color customization - -**Complexity:** ~100 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- Command works end-to-end -- Help text updated -- JSON output parseable by `jq` - -**Blocked By:** BDK-003, BDK-004 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* Seed graph → run `git mind nodes` → verify output contains expected nodes -- *Failure Modes:* Uninitialized graph → helpful error, unknown prefix → empty result with message -- *Edge Cases:* Graph with only edges (no explicit nodes yet), very long node IDs -- *Fuzz/Stress:* Graph with 500 nodes → verify output completes in <2s - ---- - -### Task BDK-006: Node Command Flag Integration - -**User Story:** As a power user, I want the `--prefix`, `--id`, and `--json` flags to compose correctly so that I can script against git-mind output. - -**Requirements:** -- `--prefix` and `--id` are mutually exclusive (error if both provided) -- `--json` works with both `--prefix` and `--id` -- JSON output follows a stable schema (document in GRAPH_SCHEMA.md) -- Exit code 0 on success, 1 on error, 2 on no results - -**Acceptance Criteria:** -- [ ] `--prefix task --json` outputs JSON array of task nodes -- [ ] `--id milestone:BEDROCK --json` outputs JSON object with full detail -- [ ] Conflicting flags produce clear error message -- [ ] Exit codes are correct - -**Scope:** -- *In:* Flag composition, error handling, exit codes -- *Out:* New flags beyond prefix/id/json - -**Complexity:** ~40 LoC -**Est. Human Hours:** 1 - -**Definition of Done:** -- All flag combinations tested -- Exit codes verified in tests - -**Blocked By:** BDK-005 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* `--prefix task --json | jq length` returns correct count -- *Failure Modes:* `--prefix --id` together → error, `--prefix unknown` → exit 2 -- *Edge Cases:* `--json` with empty result → `[]`, `--id nonexistent` → exit 2 -- *Fuzz/Stress:* N/A - ---- - -## Feature BDK-TEST: Foundation Test Suite - -### Task BDK-007: Schema Validation Test Suite - -**User Story:** As a maintainer, I want comprehensive schema validation tests so that I can refactor with confidence. - -**Requirements:** -- Test every validator function from schema.js -- Test every prefix in the taxonomy -- Test every edge type -- Test boundary conditions for confidence scores -- Minimum 20 test cases - -**Acceptance Criteria:** -- [ ] Test file: `test/schema.test.js` -- [ ] All validators have positive and negative test cases -- [ ] Confidence boundaries tested: 0.0, 0.5, 1.0, -0.1, 1.1, NaN, null -- [ ] All tests pass in CI - -**Scope:** -- *In:* Unit tests for schema.js validators -- *Out:* Integration tests, CLI tests - -**Complexity:** ~200 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- All tests green -- Coverage: every validator, every prefix, every edge type - -**Blocked By:** BDK-002 -**Blocking:** INT-005 - -**Test Plan:** -- *Golden Path:* Each valid input passes -- *Failure Modes:* Each invalid input fails with correct error -- *Edge Cases:* Boundary values, empty strings, special characters -- *Fuzz/Stress:* Property-based testing with random inputs (if vitest supports it) - ---- - -### Task BDK-008: Node Query Test Suite - -**User Story:** As a maintainer, I want node query tests so that the query layer is reliable. - -**Requirements:** -- Test getNodes, getNode, getNodesByPrefix, hasNode -- Test with empty graph, single-node graph, multi-node graph -- Test prefix filtering -- Test node detail (edges included) -- Minimum 15 test cases - -**Acceptance Criteria:** -- [ ] Test file: `test/nodes.test.js` -- [ ] All query functions have positive and negative test cases -- [ ] Edge aggregation (inEdges, outEdges) verified -- [ ] All tests pass in CI - -**Scope:** -- *In:* Unit tests for nodes.js query functions -- *Out:* CLI tests, integration tests - -**Complexity:** ~180 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- All tests green -- Coverage: every query function, every branch - -**Blocked By:** BDK-003, BDK-004 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* Seed graph → query → verify results -- *Failure Modes:* Empty graph queries, nonexistent node queries -- *Edge Cases:* Node with only inbound edges, node with only outbound edges, self-referential edge -- *Fuzz/Stress:* Randomized graph with 100 nodes → verify consistency - ---- - -# Milestone 2: INTAKE - -> **"Data in, knowledge out. But only clean data gets through the gate."** - -**Goal:** Build a robust YAML import pipeline that ingests project structure into the graph — idempotent, validated, atomic. - -**Refs:** #180 - -**Milestone Dependencies:** BEDROCK (schema validators + node layer required) - ---- - -## Feature INT-ENGINE: YAML Import Engine - -> The core logic that reads YAML and writes graph operations. - -### Task INT-001: Implement Core Import Logic - -**User Story:** As a project maintainer, I want to import a YAML file describing my project's structure so that I can seed the knowledge graph without manually linking everything. - -**Requirements:** -- Parse YAML file with `nodes` and `edges` sections -- Nodes section: array of `{ id, props? }` objects -- Edges section: array of `{ source, target, type, confidence?, rationale? }` objects -- Validate all inputs against schema.js before writing -- Return a report: `{ nodesCreated, edgesCreated, errors }` - -**Acceptance Criteria:** -- [ ] `src/import.js` exports `importFromYAML(graph, yamlString, opts)` -- [ ] Valid YAML with nodes and edges creates the expected graph state -- [ ] Invalid YAML returns errors without writing anything -- [ ] Report includes counts of created nodes and edges - -**Scope:** -- *In:* YAML parsing, schema validation, graph writes, error reporting -- *Out:* File I/O (caller provides YAML string), CLI flags, export - -**Complexity:** ~200 LoC -**Est. Human Hours:** 5 - -**Definition of Done:** -- Core import works end-to-end -- All inputs validated -- Report is accurate - -**Blocked By:** BDK-002, BDK-003 -**Blocking:** INT-002, INT-003, INT-007 - -**Test Plan:** -- *Golden Path:* Import valid YAML → verify nodes and edges in graph -- *Failure Modes:* Malformed YAML → parse error, invalid node ID → validation error, unknown edge type → rejected -- *Edge Cases:* Empty nodes array, empty edges array, YAML with only nodes (no edges), YAML with only edges -- *Fuzz/Stress:* Import YAML with 500 nodes and 2000 edges → verify performance <5s - ---- - -### Task INT-002: Implement Idempotent Merge Semantics - -**User Story:** As a user, I want to re-import the same YAML file without creating duplicates so that import is safe to run repeatedly. - -**Requirements:** -- Re-importing a node with the same ID: shallow-merge properties -- Re-importing an edge with the same (source, target, type): update confidence and rationale -- The result of importing twice must equal the result of importing once -- Report distinguishes `created` vs `updated` counts - -**Acceptance Criteria:** -- [ ] Double-import produces identical graph state -- [ ] Updated edges reflect new confidence/rationale values -- [ ] Updated nodes reflect merged properties -- [ ] Report shows `{ nodesCreated: 0, nodesUpdated: N, edgesCreated: 0, edgesUpdated: M }` - -**Scope:** -- *In:* Idempotent upsert logic, merge semantics -- *Out:* `--no-overwrite` flag (future), conflict resolution - -**Complexity:** ~80 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- Double-import test passes -- Property merge verified -- Edge update verified - -**Blocked By:** INT-001, BDK-004 -**Blocking:** INT-008 - -**Test Plan:** -- *Golden Path:* Import → re-import → verify graph unchanged, report shows updates -- *Failure Modes:* N/A (idempotency doesn't fail, it converges) -- *Edge Cases:* Import with changed props → verify merge, import with changed confidence → verify update -- *Fuzz/Stress:* Import same file 100 times → verify graph state identical each time - ---- - -## Feature INT-CLI: Import CLI Command - -### Task INT-003: Implement `git mind import` Command - -**User Story:** As a CLI user, I want to run `git mind import graph.yaml` to import a YAML file into the graph. - -**Requirements:** -- `git mind import ` — import YAML file -- Read file from disk, parse, validate, import -- Print human-readable report after import -- Exit code 0 on success, 1 on validation errors - -**Acceptance Criteria:** -- [ ] Command registered in CLI entry point -- [ ] File path resolved relative to CWD -- [ ] Success prints report with counts -- [ ] Validation errors printed with line context if possible - -**Scope:** -- *In:* CLI command, file reading, report display -- *Out:* Stdin import, URL import, interactive mode - -**Complexity:** ~80 LoC -**Est. Human Hours:** 2 - -**Definition of Done:** -- Command works end-to-end with a test YAML file -- Help text updated - -**Blocked By:** INT-001 -**Blocking:** INT-004, PRV-002 - -**Test Plan:** -- *Golden Path:* Create YAML file → run import → verify graph state -- *Failure Modes:* File not found → error, file not YAML → parse error, invalid schema → validation error -- *Edge Cases:* Empty file, file with only comments, file with BOM -- *Fuzz/Stress:* N/A - ---- - -### Task INT-004: Import Command Flags (--dry-run, --validate, --json) - -**User Story:** As a power user, I want `--dry-run` to preview changes and `--validate` to check syntax without writing so that I can safely prepare imports. - -**Requirements:** -- `--dry-run` — parse, validate, compute changes, but don't write. Print what would happen. -- `--validate` — parse and validate only. Print validation result. Don't compute changes. -- `--json` — output report as JSON -- Flags compose: `--dry-run --json` outputs dry-run report as JSON - -**Acceptance Criteria:** -- [ ] `--dry-run` shows changes without writing to graph -- [ ] `--validate` only checks schema validity -- [ ] `--json` outputs machine-readable report -- [ ] Graph is unchanged after `--dry-run` and `--validate` - -**Scope:** -- *In:* Three flags, flag composition -- *Out:* `--force`, `--no-overwrite`, interactive confirmation - -**Complexity:** ~60 LoC -**Est. Human Hours:** 2 - -**Definition of Done:** -- All three flags work individually and composed -- Graph integrity verified after dry-run - -**Blocked By:** INT-003 -**Blocking:** PRV-002 - -**Test Plan:** -- *Golden Path:* `--dry-run` shows report, graph empty afterward. `--validate` on valid file → exit 0 -- *Failure Modes:* `--validate` on invalid file → exit 1 with errors -- *Edge Cases:* `--dry-run --validate` → validate takes precedence (least-write wins) -- *Fuzz/Stress:* N/A - ---- - -## Feature INT-GUARD: Schema Enforcement - -### Task INT-005: Version Field Enforcement - -**User Story:** As a maintainer, I want import files to declare a schema version so that we can evolve the format without breaking old files. - -**Requirements:** -- YAML must contain `version: 1` at root level -- Missing version → hard error with helpful message -- Unknown version (e.g., `version: 2`) → hard error: "Unknown schema version 2. This version of git-mind supports version 1." -- Version checked before any other validation - -**Acceptance Criteria:** -- [ ] Import rejects files without `version` field -- [ ] Import rejects files with unknown version -- [ ] Error messages are specific and actionable -- [ ] Version check runs before node/edge validation - -**Scope:** -- *In:* Version field checking, error messages -- *Out:* Version migration, multi-version support - -**Complexity:** ~30 LoC -**Est. Human Hours:** 1 - -**Definition of Done:** -- Version enforcement in import pipeline -- Test coverage for all version scenarios - -**Blocked By:** BDK-002, BDK-007 -**Blocking:** INT-008 - -**Test Plan:** -- *Golden Path:* `version: 1` → accepted -- *Failure Modes:* Missing version → error, `version: 0` → error, `version: 2` → error, `version: "one"` → error -- *Edge Cases:* `version: 1.0` (float) → should it pass? Decide and document. `version: null` → error -- *Fuzz/Stress:* N/A - ---- - -### Task INT-006: Reference Validation - -**User Story:** As a user, I want the import to verify that all edge targets exist (either in the import file or already in the graph) so that I don't create dangling edges. - -**Requirements:** -- Before writing, collect all node IDs (from import + existing graph) -- Every edge source and target must reference a known node -- Dangling references → hard error listing all unresolved refs -- Check runs after schema validation, before write phase - -**Acceptance Criteria:** -- [ ] Dangling edge source detected and reported -- [ ] Dangling edge target detected and reported -- [ ] Edges referencing nodes in the same import file pass -- [ ] Edges referencing existing graph nodes pass -- [ ] Error lists ALL dangling refs (not just first) - -**Scope:** -- *In:* Reference validation against import + existing graph -- *Out:* Auto-creating missing nodes (explicit is better than implicit) - -**Complexity:** ~60 LoC -**Est. Human Hours:** 2 - -**Definition of Done:** -- Reference validation integrated into import pipeline -- Test coverage for dangling refs - -**Blocked By:** BDK-002, INT-001 -**Blocking:** INT-007, INT-008 - -**Test Plan:** -- *Golden Path:* All refs resolve → import succeeds -- *Failure Modes:* Edge targets nonexistent node → error listing ref, multiple dangling → all reported -- *Edge Cases:* Self-referential edge (source == target), edge to node defined later in same file -- *Fuzz/Stress:* Import with 100 dangling refs → verify all 100 reported - ---- - -## Feature INT-ATOMIC: Atomic Writes - -### Task INT-007: Build-Validate-Write Pipeline - -**User Story:** As a user, I want imports to be all-or-nothing so that a failed import never leaves my graph in a partial state. - -**Requirements:** -- Phase 1: Parse YAML → build operation list -- Phase 2: Validate all operations (schema + refs) -- Phase 3: Execute all writes in a single patch -- If Phase 1 or 2 fails → zero writes -- Use `graph.createPatch()` to batch all operations - -**Acceptance Criteria:** -- [ ] Validation failure → graph unchanged -- [ ] Parse failure → graph unchanged -- [ ] Partial data (10 valid nodes, 1 invalid) → zero nodes written -- [ ] Successful import → all operations in single patch commit - -**Scope:** -- *In:* Three-phase pipeline, atomic batch via createPatch -- *Out:* Rollback (not needed if we don't write on failure), partial success mode - -**Complexity:** ~100 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- Pipeline implemented -- Atomicity verified by tests -- No partial writes possible - -**Blocked By:** INT-001, INT-006 -**Blocking:** INT-008 - -**Test Plan:** -- *Golden Path:* Valid import → all nodes and edges created in single patch -- *Failure Modes:* Import with 1 invalid node among 50 → zero writes, graph unchanged -- *Edge Cases:* Import that would update existing nodes + create new → all-or-nothing applies -- *Fuzz/Stress:* Import 1000 nodes atomically → verify single checkpoint created - ---- - -### Task INT-008: Import Test Suite - -**User Story:** As a maintainer, I want comprehensive import tests so that the pipeline is reliable. - -**Requirements:** -- Test happy path (valid YAML → expected graph) -- Test idempotency (double import → same result) -- Test determinism (same input → same output, regardless of order) -- Test rejection (invalid schema, dangling refs, missing version) -- Test dry-run (no writes) -- Minimum 25 test cases - -**Acceptance Criteria:** -- [ ] Test file: `test/import.test.js` -- [ ] All scenarios from above covered -- [ ] Test fixtures in `test/fixtures/` directory -- [ ] All tests pass in CI - -**Scope:** -- *In:* Unit + integration tests for import pipeline -- *Out:* CLI tests (covered by command-level tests), performance benchmarks - -**Complexity:** ~300 LoC -**Est. Human Hours:** 4 - -**Definition of Done:** -- All tests green -- Fixtures committed -- Coverage: every branch in import.js - -**Blocked By:** INT-001, INT-002, INT-005, INT-006, INT-007 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* Each test scenario as described -- *Failure Modes:* Tests themselves should be reviewed for false positives -- *Edge Cases:* Test ordering independence (tests don't depend on each other) -- *Fuzz/Stress:* Property-based: generate random valid YAML → import → export → re-import → verify identical - ---- - -# Milestone 3: PRISM - -> **"Raw data is noise. Views are signal. PRISM refracts the graph into actionable insight."** - -**Goal:** Replace the current hardcoded views with a declarative view engine, then build four high-value views. - -**Refs:** #180 - -**Milestone Dependencies:** BEDROCK (node query layer required for view rendering) - ---- - -## Feature PRI-ENGINE: Declarative View Engine - -### Task PRI-001: Refactor View System to Declarative Config - -**User Story:** As a developer, I want to define new views by writing a config object instead of code so that adding a view is a 5-minute task, not a 2-hour task. - -**Requirements:** -- View definition: `{ name, description, prefixes, edgeTypes, filter, sort, format }` -- `prefixes` — which node prefixes to include -- `edgeTypes` — which edge types to traverse -- `filter` — predicate function for additional filtering -- `sort` — sort order for results -- `format` — output template (human-readable) -- Existing 4 views (roadmap, architecture, backlog, suggestions) migrated to new format - -**Acceptance Criteria:** -- [ ] `src/views.js` refactored to consume config objects -- [ ] Existing 4 views work identically after refactor -- [ ] Adding a new view requires only a config object -- [ ] View configs exportable for inspection - -**Scope:** -- *In:* View engine refactor, config schema, migration of existing views -- *Out:* View composition, view inheritance, user-defined views - -**Complexity:** ~200 LoC -**Est. Human Hours:** 5 - -**Definition of Done:** -- All 4 existing views pass regression tests -- New view can be added with just a config object -- No behavioral changes to existing output - -**Blocked By:** BDK-003 -**Blocking:** PRI-003, PRI-004, PRI-005, PRI-006 - -**Test Plan:** -- *Golden Path:* Existing views produce identical output before and after refactor -- *Failure Modes:* Invalid config → helpful error at registration time -- *Edge Cases:* View with no matching nodes → empty but valid output, view with circular edges -- *Fuzz/Stress:* Register 50 views → verify no performance degradation - ---- - -### Task PRI-002: View Config Schema & Validation - -**User Story:** As a developer, I want view configs validated at registration time so that typos in config are caught immediately, not at render time. - -**Requirements:** -- Validate view name (non-empty string, unique) -- Validate prefixes (array of known prefixes) -- Validate edgeTypes (array of known edge types) -- Validation runs when view is registered, not when rendered -- Invalid config throws with specific error - -**Acceptance Criteria:** -- [ ] Invalid view name → error at registration -- [ ] Unknown prefix in config → error at registration -- [ ] Unknown edge type → error at registration -- [ ] Duplicate view name → error at registration - -**Scope:** -- *In:* View config validation -- *Out:* Dynamic view creation at runtime, user-provided configs - -**Complexity:** ~60 LoC -**Est. Human Hours:** 2 - -**Definition of Done:** -- Validation integrated into view registration -- Test coverage for all validation rules - -**Blocked By:** PRI-001, BDK-002 -**Blocking:** PRI-007 - -**Test Plan:** -- *Golden Path:* Valid config registers successfully -- *Failure Modes:* Each invalid field detected and reported -- *Edge Cases:* Config with empty arrays, config with all fields, config with only required fields -- *Fuzz/Stress:* N/A - ---- - -## Feature PRI-MILESTONE: Milestone View - -### Task PRI-003: Implement Milestone Progress View - -**User Story:** As a project lead, I want to see milestone progress (tasks done / total, blockers, timeline) so that I can track project health at a glance. - -**Requirements:** -- Show each milestone with: name, completion %, task counts (done/in-progress/blocked/total) -- Show blocking chains (what blocks this milestone) -- Sort by completion % ascending (least done first) -- Support `--json` output - -**Acceptance Criteria:** -- [ ] `git mind view milestone` shows milestone progress -- [ ] Completion % calculated from `belongs-to` edges -- [ ] Blockers identified via `blocks` edges -- [ ] JSON output includes all computed fields - -**Scope:** -- *In:* Milestone view config, completion calculation, blocker detection -- *Out:* Gantt charts, timeline estimation, burndown - -**Complexity:** ~80 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- View renders correctly against test fixture -- Matches expected output exactly - -**Blocked By:** PRI-001 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* Fixture graph with 2 milestones, 5 tasks each → verify output matches snapshot -- *Failure Modes:* Milestone with no tasks → shows 0% complete, not error -- *Edge Cases:* Milestone with all tasks complete → 100%, milestone with circular blockers -- *Fuzz/Stress:* 50 milestones, 500 tasks → verify renders in <1s - ---- - -## Feature PRI-TRACE: Traceability View - -### Task PRI-004: Implement Spec-to-Implementation Traceability - -**User Story:** As an architect, I want to see which specs have implementations and which don't so that I can identify gaps in coverage. - -**Requirements:** -- List all `spec:*` nodes -- For each spec, show `implements` edges → what implements it -- Flag specs with zero implementations as "unimplemented" -- Flag implementations with no spec as "undocumented" -- Sort: unimplemented first, then by spec name - -**Acceptance Criteria:** -- [ ] `git mind view traceability` shows spec coverage -- [ ] Unimplemented specs highlighted -- [ ] Undocumented implementations highlighted -- [ ] Bidirectional: specs → implementations AND implementations → specs - -**Scope:** -- *In:* Traceability view, gap detection, bidirectional linking -- *Out:* Auto-linking (suggesting implementations for specs), coverage percentages - -**Complexity:** ~80 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- View renders correctly against test fixture -- Gaps are clearly visible - -**Blocked By:** PRI-001 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* 3 specs, 2 implemented, 1 not → verify output shows gap -- *Failure Modes:* No specs in graph → informative message -- *Edge Cases:* Spec implemented by multiple things, implementation linked to multiple specs -- *Fuzz/Stress:* 100 specs, 200 implementations → verify renders in <1s - ---- - -## Feature PRI-BLOCK: Blockers View - -### Task PRI-005: Implement Blocker Analysis View - -**User Story:** As a project lead, I want to see all blocked items and their dependency chains so that I can identify and unblock critical paths. - -**Requirements:** -- List all nodes that have incoming `blocks` edges (i.e., are blocked) -- For each blocked item, show the full blocking chain (transitive) -- Identify "root blockers" — items that block others but aren't themselves blocked -- Sort by chain length descending (deepest blockers first) - -**Acceptance Criteria:** -- [ ] `git mind view blockers` shows all blocked items -- [ ] Transitive blocking chains shown (A blocks B blocks C → show full chain) -- [ ] Root blockers clearly identified -- [ ] Circular blocking detected and flagged (not infinite loop) - -**Scope:** -- *In:* Blocker view, transitive chain resolution, cycle detection -- *Out:* Automatic unblocking suggestions, priority calculation - -**Complexity:** ~120 LoC -**Est. Human Hours:** 4 - -**Definition of Done:** -- View renders correctly against test fixture -- Cycle detection works (no infinite loops) -- Critical path visible - -**Blocked By:** PRI-001 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* A→B→C blocking chain → verify full chain shown -- *Failure Modes:* No blockers → "No blocked items" message -- *Edge Cases:* Circular blocking (A blocks B blocks A), self-blocking (A blocks A), diamond dependency -- *Fuzz/Stress:* 20-deep blocking chain → verify renders without stack overflow - ---- - -## Feature PRI-ONBOARD: Onboarding View - -### Task PRI-006: Implement Onboarding Reading Order View - -**User Story:** As a new engineer joining the project, I want a recommended reading order so that I can get up to speed efficiently. - -**Requirements:** -- Traverse `documents` edges to find documentation nodes -- Order by dependency (read foundations before advanced topics) -- Include: specs, ADRs, guides, and onboarding-tagged nodes -- Show estimated reading time per item (from node props, if available) - -**Acceptance Criteria:** -- [ ] `git mind view onboarding` shows ordered reading list -- [ ] Dependency-aware ordering (topological sort on `depends-on` edges) -- [ ] Items without dependencies shown first -- [ ] Reading time shown if available - -**Scope:** -- *In:* Onboarding view, topological sort, reading time display -- *Out:* Interactive walkthrough, quiz/verification, personalized paths - -**Complexity:** ~100 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- View renders correctly against test fixture -- Topological order is correct - -**Blocked By:** PRI-001 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* 5 docs with dependencies → verify topological order -- *Failure Modes:* No documentation nodes → informative message -- *Edge Cases:* Circular dependencies → break cycle and warn, disconnected docs (no deps) → alphabetical -- *Fuzz/Stress:* 100 documentation nodes → verify topological sort <100ms - ---- - -### Task PRI-007: View Fixture Test Suite - -**User Story:** As a maintainer, I want every view tested against a known fixture graph with exact expected output so that view changes are intentional. - -**Requirements:** -- Create a fixture graph (YAML) with enough data to exercise all views -- Snapshot tests: render each view → compare to expected output -- Test both human-readable and JSON output -- Minimum 10 test cases (2+ per view) - -**Acceptance Criteria:** -- [ ] Test file: `test/views.test.js` -- [ ] Fixture graph in `test/fixtures/views-fixture.yaml` -- [ ] All 8 views tested (4 existing + 4 new) -- [ ] Both human and JSON output verified - -**Scope:** -- *In:* View snapshot tests, fixture graph, JSON output tests -- *Out:* Visual regression tests, performance benchmarks - -**Complexity:** ~250 LoC -**Est. Human Hours:** 4 - -**Definition of Done:** -- All tests green -- Fixtures committed -- Snapshot updates require explicit approval - -**Blocked By:** PRI-001, PRI-003, PRI-004, PRI-005, PRI-006 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* Each view renders expected output from fixture -- *Failure Modes:* Test detects unintentional output changes -- *Edge Cases:* Empty graph views, graph with only one node type -- *Fuzz/Stress:* N/A - ---- - -# Milestone 4: WATCHTOWER - -> **"You can't manage what you can't measure. WATCHTOWER gives you the numbers."** - -**Goal:** A single command that tells you the health of your knowledge graph. - -**Refs:** #180 - -**Milestone Dependencies:** BEDROCK (node queries), PRISM (view rendering for blockers) - ---- +This roadmap resets Git Mind around that core hill. -## Feature WTC-STATUS: Status Command - -### Task WTC-001: Implement `git mind status` Command - -**User Story:** As a project lead, I want to run `git mind status` and instantly see the health of my knowledge graph — node counts, edge counts, blockers, and quality signals. - -**Requirements:** -- Display: total nodes, total edges -- Display: nodes by prefix (table) -- Display: edges by type (table) -- Display: blocked items count -- Display: low-confidence edges count (confidence < 0.5) -- Display: orphan nodes count (nodes with 0 edges) - -**Acceptance Criteria:** -- [ ] `git mind status` shows all metrics -- [ ] Output is human-readable with clear section headers -- [ ] Empty graph shows zeros, not errors -- [ ] Metrics are accurate (verified by tests) - -**Scope:** -- *In:* Status command, metric computation, formatted output -- *Out:* Historical tracking, trend analysis, alerts - -**Complexity:** ~120 LoC -**Est. Human Hours:** 4 - -**Definition of Done:** -- Command works end-to-end -- All metrics verified against fixture -- Help text updated - -**Blocked By:** BDK-003, BDK-005 -**Blocking:** WTC-002, PRV-003 - -**Test Plan:** -- *Golden Path:* Known fixture → verify all counts match -- *Failure Modes:* Empty graph → all zeros, uninitialized graph → helpful error -- *Edge Cases:* Graph with only nodes (no edges), graph with only edges (implied nodes) -- *Fuzz/Stress:* Graph with 1000 nodes, 5000 edges → verify status completes in <2s - ---- - -### Task WTC-002: Status Command --json Flag - -**User Story:** As a CI pipeline, I want `git mind status --json` so that I can programmatically check graph health. - -**Requirements:** -- JSON output includes all metrics from WTC-001 -- Schema: `{ totals: { nodes, edges }, byPrefix: {...}, byType: {...}, blocked, lowConfidence, orphans }` -- JSON is valid and parseable by `jq` - -**Acceptance Criteria:** -- [ ] `git mind status --json` outputs valid JSON -- [ ] JSON schema matches documented format -- [ ] `git mind status --json | jq .totals.nodes` returns correct count - -**Scope:** -- *In:* JSON output format -- *Out:* Other output formats (YAML, CSV) - -**Complexity:** ~30 LoC -**Est. Human Hours:** 1 - -**Definition of Done:** -- JSON output works -- Schema documented -- Parseable by jq - -**Blocked By:** WTC-001 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* Parse JSON output, verify all fields present -- *Failure Modes:* N/A (if status works, JSON wrapping is trivial) -- *Edge Cases:* Empty graph → valid JSON with zeros -- *Fuzz/Stress:* N/A - ---- - -## Feature WTC-METRICS: Graph Metrics - -### Task WTC-003: Node Metrics by Prefix - -**User Story:** As a user, I want to see how many nodes exist per prefix so that I understand the graph's composition. - -**Requirements:** -- Count nodes by prefix -- Sort by count descending -- Show percentage of total for each prefix - -**Acceptance Criteria:** -- [ ] Prefix breakdown shown in status output -- [ ] Percentages sum to ~100% (rounding) -- [ ] Prefixes with 0 nodes omitted from display - -**Scope:** -- *In:* Prefix counting, percentage calculation -- *Out:* Historical comparisons, growth tracking - -**Complexity:** ~40 LoC -**Est. Human Hours:** 1 - -**Definition of Done:** -- Metrics accurate against fixture -- Integrated into status output - -**Blocked By:** BDK-003 -**Blocking:** WTC-005 - -**Test Plan:** -- *Golden Path:* Known fixture → verify counts match -- *Failure Modes:* No nodes → empty table -- *Edge Cases:* All nodes same prefix, each node different prefix -- *Fuzz/Stress:* N/A - ---- - -### Task WTC-004: Edge Metrics & Quality Signals - -**User Story:** As a project lead, I want to see edge quality signals (low confidence, blocked items) so that I can prioritize graph curation. - -**Requirements:** -- Count edges by type -- Identify low-confidence edges (< 0.5) -- Identify blocked items (nodes with incoming `blocks` edges) -- Identify orphan nodes (0 total edges) - -**Acceptance Criteria:** -- [ ] Edge type breakdown shown in status -- [ ] Low-confidence edges listed with current confidence -- [ ] Blocked items count shown -- [ ] Orphan nodes count shown - -**Scope:** -- *In:* Edge counting, quality signal detection -- *Out:* Confidence decay, automatic remediation suggestions - -**Complexity:** ~60 LoC -**Est. Human Hours:** 2 - -**Definition of Done:** -- All quality signals computed correctly -- Integrated into status output - -**Blocked By:** BDK-003 -**Blocking:** WTC-005 - -**Test Plan:** -- *Golden Path:* Fixture with mix of high/low confidence → verify counts -- *Failure Modes:* No edges → all zeros -- *Edge Cases:* All edges low confidence, no blocked items, all nodes orphaned -- *Fuzz/Stress:* N/A - ---- - -## Feature WTC-TEST: Dashboard Test Suite - -### Task WTC-005: Status Output Test Suite - -**User Story:** As a maintainer, I want status output verified against a known fixture so that metrics are trustworthy. - -**Requirements:** -- Test with known fixture graph -- Verify every metric count -- Test both human and JSON output -- Minimum 10 test cases - -**Acceptance Criteria:** -- [ ] Test file: `test/status.test.js` -- [ ] All metric counts verified -- [ ] JSON output schema verified -- [ ] All tests pass in CI - -**Scope:** -- *In:* Status output tests -- *Out:* Performance benchmarks, visual tests - -**Complexity:** ~150 LoC -**Est. Human Hours:** 2 - -**Definition of Done:** -- All tests green -- Every metric verified - -**Blocked By:** WTC-001, WTC-003, WTC-004 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* Known fixture → expected metrics -- *Failure Modes:* Test detects count mismatches -- *Edge Cases:* Empty graph, single-node graph -- *Fuzz/Stress:* N/A - ---- - -# Milestone 5: PROVING GROUND - -> **"Theory meets reality. We eat our own dogfood — in the Echo repo."** - -**Goal:** Validate that git-mind can answer 5 real project management questions about the Echo ecosystem in under 60 seconds total. - -**Refs:** #180 - -**Milestone Dependencies:** BEDROCK, INTAKE, PRISM, WATCHTOWER (all prior milestones) - ---- - -## Feature PRV-SEED: Echo Seed - -### Task PRV-001: Create Echo Project YAML Seed File - -**User Story:** As a validator, I want a YAML file that represents the Echo project's structure so that I can seed git-mind with real data. - -**Requirements:** -- Model Echo's milestones, specs, ADRs, crates, and issues -- Include at least: 5 milestones, 10 specs, 5 ADRs, 15 crates, 20 issues -- Include edges: implements, blocks, depends-on, documents, belongs-to -- Include realistic confidence scores -- Schema version 1 - -**Acceptance Criteria:** -- [ ] File: `docs/echo-seed.yaml` -- [ ] Validates against schema (version 1) -- [ ] Represents real Echo project structure (not fake data) -- [ ] Import succeeds with `git mind import docs/echo-seed.yaml` - -**Scope:** -- *In:* YAML seed file with realistic Echo data -- *Out:* Automated scraping from Echo repos, live sync - -**Complexity:** ~400 LoC (YAML) -**Est. Human Hours:** 4 - -**Definition of Done:** -- Seed file committed -- Import succeeds -- Data represents real Echo structure - -**Blocked By:** INT-003, INT-004 -**Blocking:** PRV-002, PRV-003 - -**Test Plan:** -- *Golden Path:* Import seed → verify node/edge counts match expected -- *Failure Modes:* N/A (seed file is hand-crafted, validated before commit) -- *Edge Cases:* N/A -- *Fuzz/Stress:* N/A - ---- - -### Task PRV-002: Import Seed into Echo Repo - -**User Story:** As a validator, I want the seed data imported into the Echo repo's git-mind graph so that I can run queries against it. - -**Requirements:** -- Run `git mind init` in Echo repo -- Run `git mind import docs/echo-seed.yaml` -- Verify import report matches expected counts -- Checkpoint the graph - -**Acceptance Criteria:** -- [ ] Graph initialized in Echo repo -- [ ] Import report shows expected counts -- [ ] `git mind status` shows correct totals -- [ ] Graph persists across sessions - -**Scope:** -- *In:* Import execution, verification -- *Out:* Automated seeding CI, graph updates - -**Complexity:** ~20 LoC (scripts/commands) -**Est. Human Hours:** 1 - -**Definition of Done:** -- Import complete and verified -- Status shows correct counts - -**Blocked By:** PRV-001, INT-003 -**Blocking:** PRV-003 - -**Test Plan:** -- *Golden Path:* Import → status → verify -- *Failure Modes:* Import errors → fix seed file -- *Edge Cases:* Re-import (idempotency check) -- *Fuzz/Stress:* N/A - ---- - -## Feature PRV-VALIDATE: Validation Suite - -### Task PRV-003: Answer 5 Echo Questions via CLI - -**User Story:** As a validator, I want to answer 5 specific project management questions using only git-mind CLI commands in under 60 seconds total. - -**Requirements:** - -The 5 questions: -1. **What blocks M2?** → `git mind view blockers` filtered for milestone:M2 -2. **Which ADRs lack implementation?** → `git mind view traceability` filtered for ADR nodes -3. **Which crates are unlinked to specs?** → `git mind nodes --prefix crate` + verify edges -4. **What should a new engineer read first?** → `git mind view onboarding` -5. **What's low-confidence and needs review?** → `git mind view suggestions` + `git mind status` - -**Acceptance Criteria:** -- [ ] Each question answered with a single CLI command (or pipeline) -- [ ] Answers are correct (verified against known truth) -- [ ] Total time for all 5 < 60 seconds -- [ ] Commands documented in transcript - -**Scope:** -- *In:* 5 specific questions, CLI commands, timing -- *Out:* Interactive exploration, ad-hoc queries, AI-assisted answers - -**Complexity:** ~50 LoC (script/transcript) -**Est. Human Hours:** 3 - -**Definition of Done:** -- All 5 questions answered correctly -- Total time under 60s -- Transcript committed - -**Blocked By:** PRV-002, BDK-005, WTC-001, PRI-003, PRI-004, PRI-005, PRI-006 -**Blocking:** PRV-004 - -**Test Plan:** -- *Golden Path:* Run all 5 commands → verify answers -- *Failure Modes:* Wrong answer → investigate and fix view/query logic -- *Edge Cases:* N/A (questions are fixed) -- *Fuzz/Stress:* Time all 5 sequentially, verify total < 60s - ---- - -### Task PRV-004: Validate Answers Against Known Truth - -**User Story:** As a validator, I want to verify that the CLI answers match independently verified truth so that we can trust git-mind's output. - -**Requirements:** -- For each of the 5 questions, establish ground truth independently -- Compare CLI output to ground truth -- Document discrepancies and resolutions -- All 5 must match - -**Acceptance Criteria:** -- [ ] Ground truth documented for each question -- [ ] CLI output matches ground truth for all 5 -- [ ] Any discrepancies resolved and documented - -**Scope:** -- *In:* Verification of 5 specific answers -- *Out:* Automated verification CI, regression testing - -**Complexity:** ~30 LoC (documentation) -**Est. Human Hours:** 2 - -**Definition of Done:** -- All 5 answers verified -- Discrepancies (if any) resolved - -**Blocked By:** PRV-003 -**Blocking:** PRV-005 - -**Test Plan:** -- *Golden Path:* All answers match -- *Failure Modes:* Mismatch → bug report and fix -- *Edge Cases:* N/A -- *Fuzz/Stress:* N/A - ---- - -## Feature PRV-DOCS: Demo Documentation - -### Task PRV-005: Record and Commit Demo Transcript - -**User Story:** As a stakeholder, I want a demo transcript showing git-mind answering real questions so that I can see the tool in action. - -**Requirements:** -- Full terminal session transcript -- Includes timing for each command -- Shows both command and output -- Includes commentary explaining what each answer means -- Committed as `docs/dogfood-session.md` - -**Acceptance Criteria:** -- [ ] Transcript committed at `docs/dogfood-session.md` -- [ ] All 5 questions and answers included -- [ ] Timing shown for each command -- [ ] Commentary explains results - -**Scope:** -- *In:* Terminal transcript, commentary -- *Out:* Video recording, interactive demo, web demo - -**Complexity:** ~200 LoC (markdown) -**Est. Human Hours:** 2 - -**Definition of Done:** -- Transcript committed and reviewed -- Results match validation (PRV-004) - -**Blocked By:** PRV-004 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* N/A (documentation) -- *Failure Modes:* N/A -- *Edge Cases:* N/A -- *Fuzz/Stress:* N/A - ---- - -# Milestone 6: ORACLE - -> **"The graph knows patterns you haven't seen yet. ORACLE finds them."** - -**Goal:** Add AI-powered edge suggestions, interactive review, and graph integrity checking. - -**Refs:** Future - -**Milestone Dependencies:** PROVING GROUND (validated graph must exist first) +It does not erase the capabilities already built in this repository. +It reinterprets them as substrate and enabling assets rather than as a complete product story. --- -## Feature ORC-SUGGEST: AI Suggestions +## Current Posture -### Task ORC-001: Implement `git mind suggest --ai` with LLM Integration +Git Mind already has meaningful graph capabilities: -**User Story:** As a developer, I want AI-suggested relationships between my code and specs so that I discover connections I've missed. +- graph storage on Git/WARP +- typed relationships +- query and inspection commands +- views and lenses +- semantic diff and time-travel +- suggestion and review flows +- content-on-node +- extension/runtime machinery -**Requirements:** -- Analyze git diff / recent commits for context -- Use LLM to suggest new edges (source, target, type, confidence, rationale) -- Present suggestions for human review (don't auto-commit) -- Support `--context ` to limit analysis scope -- Configurable LLM provider (environment variable) +What it does **not** yet prove is the strongest remaining product promise: -**Acceptance Criteria:** -- [ ] `git mind suggest --ai` produces edge suggestions -- [ ] Suggestions include rationale -- [ ] Suggestions are not committed automatically -- [ ] Context window is configurable +- low-input semantic bootstrap for an unfamiliar repository +- provenance-backed answers to high-value repository questions +- a living semantic map that stays useful without becoming a hand-maintained wiki -**Scope:** -- *In:* LLM integration, suggestion generation, context extraction -- *Out:* Auto-commit suggestions, training/fine-tuning, custom models - -**Complexity:** ~300 LoC -**Est. Human Hours:** 8 - -**Definition of Done:** -- Suggestions generated from real code context -- Rationale provided for each suggestion -- No auto-commits - -**Blocked By:** PRV-003 -**Blocking:** ORC-002, ORC-003 - -**Test Plan:** -- *Golden Path:* Run against known repo → verify suggestions are relevant -- *Failure Modes:* No LLM key → helpful error, LLM timeout → graceful retry/fail -- *Edge Cases:* Empty diff → "no suggestions", very large diff → context truncation -- *Fuzz/Stress:* Run against repo with 1000 files → verify completes in <30s - ---- - -### Task ORC-002: Context Extraction from Code & Commits - -**User Story:** As the AI subsystem, I need structured context from the codebase so that I can make relevant suggestions. - -**Requirements:** -- Extract file-level metadata (path, language, size, last modified) -- Extract commit-level metadata (message, files changed, author, date) -- Extract existing graph context (what nodes/edges exist near these files) -- Build LLM prompt from extracted context - -**Acceptance Criteria:** -- [ ] Context extraction produces structured data from git state -- [ ] Context includes existing graph relationships -- [ ] Prompt building produces well-formed LLM input -- [ ] Context size is bounded (truncation for large repos) - -**Scope:** -- *In:* Context extraction, prompt building, size management -- *Out:* Code parsing/AST analysis, cross-repo context - -**Complexity:** ~200 LoC -**Est. Human Hours:** 5 - -**Definition of Done:** -- Context extraction works against real repo -- Prompts are well-formed - -**Blocked By:** ORC-001 -**Blocking:** ORC-003 - -**Test Plan:** -- *Golden Path:* Extract context from test repo → verify structure -- *Failure Modes:* Empty repo → empty context, binary files → skipped -- *Edge Cases:* Renamed files, deleted files, merge commits -- *Fuzz/Stress:* Large repo (1000 files) → verify extraction <5s - ---- - -## Feature ORC-REVIEW: Interactive Review - -### Task ORC-003: Implement `git mind review` Interactive Flow - -**User Story:** As a developer, I want to interactively review suggested edges — accept, reject, or adjust each one — so that the graph stays curated by humans. - -**Requirements:** -- Present pending suggestions one at a time -- Options: accept (write to graph), reject (discard), adjust (modify and accept), skip (defer) -- Track review decisions in git-warp provenance -- `--batch` mode for non-interactive accept/reject - -**Acceptance Criteria:** -- [ ] Interactive review loop works in terminal -- [ ] Accepted edges written to graph -- [ ] Rejected edges recorded but not written -- [ ] Adjusted edges written with modifications -- [ ] Review history queryable - -**Scope:** -- *In:* Interactive review, decision tracking, batch mode -- *Out:* Web UI, collaborative review, review assignments - -**Complexity:** ~250 LoC -**Est. Human Hours:** 6 - -**Definition of Done:** -- Interactive review works -- Decisions tracked -- Batch mode works - -**Blocked By:** ORC-001, ORC-002 -**Blocking:** ORC-005 - -**Test Plan:** -- *Golden Path:* Suggest → review → accept → verify edge in graph -- *Failure Modes:* No pending suggestions → "nothing to review", interrupt during review → no partial writes -- *Edge Cases:* Review same suggestion twice → idempotent, adjust confidence to 0 → effectively reject -- *Fuzz/Stress:* Review 50 suggestions in batch mode → verify all processed - ---- - -### Task ORC-004: Accept/Reject/Adjust Edge Workflow - -**User Story:** As a reviewer, I want my decisions to have clear semantics so that the graph reflects intentional curation. - -**Requirements:** -- Accept: write edge with confidence from suggestion -- Reject: record as rejected, never re-suggest same edge -- Adjust: modify type/confidence/rationale, then write -- Skip: defer to next review session -- All decisions timestamped and attributed - -**Acceptance Criteria:** -- [ ] Accept writes edge immediately -- [ ] Reject prevents re-suggestion -- [ ] Adjust allows modification before writing -- [ ] Skip defers without action -- [ ] All decisions have timestamps and attribution - -**Scope:** -- *In:* Decision semantics, de-duplication, attribution -- *Out:* Undo/redo, decision appeals, team review - -**Complexity:** ~100 LoC -**Est. Human Hours:** 3 - -**Definition of Done:** -- All four decision types implemented -- De-duplication working (no re-suggest rejected) - -**Blocked By:** ORC-003 -**Blocking:** ORC-005 - -**Test Plan:** -- *Golden Path:* Each decision type → verify expected outcome -- *Failure Modes:* Decision on nonexistent suggestion → error -- *Edge Cases:* Reject then re-suggest manually → allowed (only auto-suggest blocked) -- *Fuzz/Stress:* 100 decisions in sequence → verify all recorded - ---- - -## Feature ORC-LEARN: Curation Loop - -### Task ORC-005: Review History Provenance in git-warp - -**User Story:** As the AI system, I want access to past review decisions so that future suggestions improve over time. - -**Requirements:** -- Store review decisions in git-warp (not just in edges) -- Query history: "what did the user accept/reject for this file/node?" -- Use history to weight future suggestions -- Provenance is append-only (decisions are never deleted) - -**Acceptance Criteria:** -- [ ] Review decisions persisted in git-warp -- [ ] History queryable by node, by file, by time range -- [ ] Suggestions incorporate past decisions -- [ ] History survives graph checkpoints - -**Scope:** -- *In:* Decision storage, history queries, suggestion weighting -- *Out:* ML model training, cross-user learning, decision analytics - -**Complexity:** ~150 LoC -**Est. Human Hours:** 5 - -**Definition of Done:** -- Provenance stored and queryable -- Suggestions improve with feedback - -**Blocked By:** ORC-003, ORC-004 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* Reject edge → re-run suggest → verify not re-suggested -- *Failure Modes:* Corrupted history → graceful degradation (suggest without history) -- *Edge Cases:* Conflicting decisions (accept then reject same edge), empty history -- *Fuzz/Stress:* 1000 decisions → verify query performance <100ms +That is what the roadmap now optimizes for. --- -## Feature ORC-DOCTOR: Integrity Checks - -### Task ORC-006: Implement `git mind doctor` Command - -**User Story:** As a maintainer, I want to run `git mind doctor` to find graph problems (dangling edges, orphans, duplicates) so that I can fix data quality issues. - -**Requirements:** -- Check for dangling edges (source or target doesn't exist as a node) -- Check for orphan milestones (milestones with no tasks) -- Check for duplicate IDs -- Check for low-confidence edges (< 0.3) -- Report all issues with severity (error, warning, info) - -**Acceptance Criteria:** -- [ ] `git mind doctor` runs all checks -- [ ] Issues reported with severity levels -- [ ] Exit code 0 if no errors, 1 if errors found -- [ ] `--json` output supported -- [ ] `--fix` flag auto-fixes safe issues (orphan cleanup, etc.) - -**Scope:** -- *In:* Integrity checks, issue reporting, auto-fix for safe issues -- *Out:* Graph repair for complex issues, schema migration - -**Complexity:** ~200 LoC -**Est. Human Hours:** 5 +## Planning Principles -**Definition of Done:** -- All checks implemented -- Auto-fix for safe issues -- Test coverage - -**Blocked By:** BDK-003, BDK-002 -**Blocking:** ORC-007 - -**Test Plan:** -- *Golden Path:* Clean graph → no issues, dirty graph → all issues found -- *Failure Modes:* Uninitialized graph → helpful error -- *Edge Cases:* Graph with only dangling edges, graph with only orphans -- *Fuzz/Stress:* Graph with 100 intentional issues → verify all detected in <2s +1. Low-input usefulness before ontology sprawl. +2. Inference before heavy manual curation. +3. Provenance must support real answers, not just architectural purity. +4. Review should refine the map, not build it from scratch. +5. Existing graph features should be reused as leverage, not treated as the product hill themselves. +6. If a planning artifact does not improve repository understanding, question it. --- -### Task ORC-007: Dangling Edge, Orphan, and Duplicate Detection - -**User Story:** As a developer, I want specific detection logic for each integrity issue type so that the doctor command is thorough. - -**Requirements:** -- Dangling edge: edge references node not in graph -- Orphan milestone: `milestone:*` node with no `belongs-to` children -- Orphan node: any node with zero edges -- Duplicate ID: same node ID appears with conflicting properties -- Each detector returns `{ type, severity, message, affected }` objects - -**Acceptance Criteria:** -- [ ] Each detector implemented as separate function -- [ ] Detectors composable (run individually or together) -- [ ] Affected items identified in reports -- [ ] All detectors have test coverage - -**Scope:** -- *In:* Individual detectors, composability -- *Out:* Custom detector plugins, detector configuration - -**Complexity:** ~150 LoC -**Est. Human Hours:** 4 - -**Definition of Done:** -- All detectors implemented -- Test suite for each detector +## Operating Model -**Blocked By:** ORC-006 -**Blocking:** — +Git Mind now uses: -**Test Plan:** -- *Golden Path:* Inject known issue → verify detection -- *Failure Modes:* False positive → fix detection logic -- *Edge Cases:* Node that's both orphan and has dangling edges, milestone that's also a task -- *Fuzz/Stress:* Graph with 500 nodes, inject 50 issues → verify all 50 detected +- IBM Hills to define the strategic outcomes +- Playbacks to assess whether recent work actually moved a Hill +- GitHub issues to track concrete implementation work ---- - -# Milestone 7: NEXUS +GitHub milestones are intentionally not the primary planning surface anymore. +The old milestone layer had drifted into theater: completed relics staying open while the real backlog lived elsewhere. -> **"The graph escapes the terminal. NEXUS connects git-mind to the world."** +This document should answer: -**Goal:** GitHub Actions integration, PR-level suggestions, markdown import, and multi-repo federation. +- what hill are we trying to climb? +- what evidence would prove progress? +- what work lanes support that hill? -**Refs:** Future +GitHub should answer: -**Milestone Dependencies:** ORACLE (AI suggestions required for PR integration) +- what concrete work items exist right now? ---- +Current GitHub planning labels: -## Feature NEX-ACTION: GitHub Action +- `hill:h1-bootstrap` +- `hill:h2-query-receipts` +- `hill:h3-living-map` +- `lane:foundation` +- `lane:content` +- `lane:extensions` +- `lane:packaging` +- `lane:ux` -### Task NEX-001: Create GitHub Action for PR Suggestions +## Current Focus: Stabilize And Clarify -**User Story:** As a team lead, I want git-mind to automatically suggest edges on every PR so that the knowledge graph stays current with code changes. +Status: -**Requirements:** -- GitHub Action runs on `pull_request` events -- Runs `git mind suggest --ai --context $PR_SHA_RANGE` -- Posts suggestions as PR comment -- Configurable via `.github/git-mind.yml` +- in progress -**Acceptance Criteria:** -- [ ] Action published to GitHub Marketplace -- [ ] Runs on PR open and update -- [ ] Posts formatted comment with suggestions -- [ ] Configurable (enable/disable, edge types, confidence threshold) +Goal: -**Scope:** -- *In:* GitHub Action, PR comments, configuration -- *Out:* Other CI platforms, auto-merge suggestions, PR blocking +- align the product story, sponsor user, backlog shape, and planning model around inference-first semantic repository intelligence -**Complexity:** ~200 LoC -**Est. Human Hours:** 6 +Deliverables: -**Definition of Done:** -- Action runs in test repo -- Comments appear on PRs -- Configuration works +- rewritten README +- rewritten north star +- new design frame +- roadmap reset around hills +- explicit boundary with `think` +- retirement of stale GitHub milestone machinery +- clear distinction between live control-plane docs and historical references -**Blocked By:** ORC-001 -**Blocking:** NEX-002 +Exit criteria: -**Test Plan:** -- *Golden Path:* Open PR → Action runs → comment appears with suggestions -- *Failure Modes:* No API key → skip with warning, Action timeout → graceful exit -- *Edge Cases:* PR with no code changes (docs only), PR with 100+ files -- *Fuzz/Stress:* Trigger on 10 PRs simultaneously → verify no race conditions +- top-level docs tell one coherent story +- the repo has a single primary sponsor user +- the backlog is no longer pretending to be release milestones +- the next hill is stated clearly enough to judge future work against it --- -### Task NEX-002: PR Reviewer Edge Display - -**User Story:** As a PR reviewer, I want to see suggested knowledge graph edges alongside the code diff so that I can understand the impact of changes. - -**Requirements:** -- Format suggestions as a clear table in PR comment -- Group by file changed -- Show: suggested edge, confidence, rationale -- Include "accept" and "reject" buttons (via comment reactions or slash commands) - -**Acceptance Criteria:** -- [ ] Suggestions grouped by file -- [ ] Table format with all fields -- [ ] Accept/reject mechanism works -- [ ] Reactions processed by follow-up Action run - -**Scope:** -- *In:* PR comment formatting, accept/reject via reactions -- *Out:* Inline diff comments, GitHub Check annotations, web UI - -**Complexity:** ~150 LoC -**Est. Human Hours:** 4 +## Hill Map -**Definition of Done:** -- Formatted comments appearing on PRs -- Accept/reject mechanism working - -**Blocked By:** NEX-001 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* Open PR → suggestions appear → react to accept → edge created -- *Failure Modes:* No suggestions → no comment posted (not empty comment) -- *Edge Cases:* Multiple reviewers react differently, reaction on old comment -- *Fuzz/Stress:* PR with 50 suggestions → verify comment doesn't exceed GitHub limits +```mermaid +flowchart LR + C["Current Focus: Stabilize And Clarify"] --> H1["Hill 1: Semantic Bootstrap"] + H1 --> H2["Hill 2: Query And Receipts"] + H2 --> H3["Hill 3: Living Map Review Loop"] + H3 --> L["Supporting Lanes: adoption, content, extensions, workflow layers"] +``` --- -## Feature NEX-MARKDOWN: Markdown Import - -### Task NEX-003: Import from Markdown Frontmatter - -**User Story:** As a developer, I want git-mind to extract knowledge from markdown frontmatter (YAML headers) so that existing documentation automatically feeds the graph. - -**Requirements:** -- Scan `.md` files for YAML frontmatter -- Extract graph-relevant fields: `id`, `type`, `relates-to`, `implements`, `depends-on` -- Create nodes and edges from extracted data -- `git mind import --from-markdown ` command - -**Acceptance Criteria:** -- [ ] Frontmatter parsing works for standard YAML headers -- [ ] Nodes created with `doc:` prefix -- [ ] Edges created from relationship fields -- [ ] Glob pattern for file selection works -- [ ] Idempotent (re-import safe) - -**Scope:** -- *In:* Frontmatter parsing, node/edge creation, glob-based file selection -- *Out:* Markdown body parsing, link extraction, heading analysis +## Hill 1: Semantic Bootstrap -**Complexity:** ~200 LoC -**Est. Human Hours:** 5 +Goal: -**Definition of Done:** -- Markdown import works end-to-end -- Idempotent -- Test coverage +- make Git Mind useful on day one for an unfamiliar repository with low setup and low manual input -**Blocked By:** INT-001, INT-002 -**Blocking:** NEX-004 +Primary hill: -**Test Plan:** -- *Golden Path:* Markdown with frontmatter → import → verify nodes and edges -- *Failure Modes:* No frontmatter → skip file, invalid frontmatter → report and skip -- *Edge Cases:* Multiple documents in one file, frontmatter with non-graph fields (ignored) -- *Fuzz/Stress:* Scan 500 markdown files → verify import <10s +- point at a repo and get an immediately useful semantic map ---- - -## Feature NEX-FEDERATION: Multi-Repo Federation - -### Task NEX-004: Cross-Repo Edge Protocol - -**User Story:** As an architect working across multiple repos, I want to create edges that span repositories so that the knowledge graph reflects cross-repo dependencies. +Deliverables: -**Requirements:** -- Edge source/target can include repo qualifier: `repo:owner/name:prefix:id` -- Remote edges stored locally with remote qualifier -- `git mind link --remote ` flag -- Remote resolution: verify remote node exists (optional, `--no-verify`) +- defined bootstrap ingress model for the first artifact set +- initial artifact ingestion from repo-local sources +- first-pass entity extraction +- first-pass relationship inference +- confidence and provenance model for inferred associations +- one or more commands or flows that produce a useful bootstrap result -**Acceptance Criteria:** -- [ ] Cross-repo edge syntax works -- [ ] Remote edges stored with full qualifier -- [ ] `--no-verify` skips remote existence check -- [ ] Remote edges visible in views +Suggested first artifact set: -**Scope:** -- *In:* Edge syntax extension, remote qualifiers, local storage of remote edges -- *Out:* Remote graph queries, cross-repo graph merge, federated views +- code files and module/package structure +- markdown docs +- ADRs +- commit history +- issue and review references discoverable from repo artifacts -**Complexity:** ~200 LoC -**Est. Human Hours:** 6 +Playback: -**Definition of Done:** -- Cross-repo edges creatable and queryable -- Views include remote edges +- on an unfamiliar repository, Git Mind produces a first semantic map without asking the user to manually build one +- the result is incomplete but useful +- the user can see why a relationship was suggested -**Blocked By:** BDK-002, NEX-003 -**Blocking:** NEX-005 +Exit criteria: -**Test Plan:** -- *Golden Path:* Link local node to remote node → verify edge stored with qualifier -- *Failure Modes:* Invalid remote syntax → helpful error, remote repo not found → error (unless --no-verify) -- *Edge Cases:* Same node ID in different repos, cross-repo circular dependency -- *Fuzz/Stress:* 100 cross-repo edges → verify query performance +- the bootstrap produces value before the user feels like they are doing graph data entry +- provenance and confidence are visible enough to support trust --- -### Task NEX-005: Multi-Repo Graph Merge - -**User Story:** As a team lead, I want to merge knowledge graphs from multiple repos into a unified view so that I can see cross-cutting concerns. - -**Requirements:** -- `git mind merge --from ` imports another repo's graph -- Nodes are prefixed with repo qualifier to avoid ID collisions -- Edges between repos preserved -- Merge is additive (never deletes) - -**Acceptance Criteria:** -- [ ] Merge imports nodes with repo qualifier -- [ ] Cross-repo edges resolved -- [ ] No ID collisions -- [ ] Merged graph queryable with standard commands - -**Scope:** -- *In:* Graph merge, ID namespacing, edge resolution -- *Out:* Continuous sync, conflict resolution, merge policies +## Hill 2: Query And Receipts -**Complexity:** ~200 LoC -**Est. Human Hours:** 6 +Goal: -**Definition of Done:** -- Merge works between two repos -- Merged graph is correct and queryable +- let humans and agents ask high-value repository questions and get provenance-backed answers -**Blocked By:** NEX-004 -**Blocking:** — +Primary hill: -**Test Plan:** -- *Golden Path:* Two repos → merge → verify unified graph -- *Failure Modes:* Missing repo → error, incompatible schema versions → error -- *Edge Cases:* Merge with overlapping node IDs, merge empty repo -- *Fuzz/Stress:* Merge 5 repos with 100 nodes each → verify result integrity +- repository archaeology becomes a query with receipts ---- - -## Feature NEX-EXPORT: Round-Trip Export - -### Task NEX-006: Implement `git mind export` - -**User Story:** As a user, I want to export my graph to YAML or JSON so that I can back it up, share it, or process it with other tools. +Deliverables: -**Requirements:** -- `git mind export --format yaml` → export entire graph as YAML -- `git mind export --format json` → export as JSON -- Export format matches import format (round-trip compatible) -- `git mind export --prefix ` → export subset +- defined top question set for unfamiliar repos +- query surfaces oriented around those questions +- answer payloads with provenance and confidence +- historical comparison where it materially improves answers +- machine-readable contracts that agents can consume reliably -**Acceptance Criteria:** -- [ ] YAML export produces valid, re-importable YAML -- [ ] JSON export produces valid JSON -- [ ] Round-trip: export → import → export → compare (identical) -- [ ] Prefix filtering works +Candidate day-one questions: -**Scope:** -- *In:* YAML and JSON export, prefix filtering, round-trip compatibility -- *Out:* GraphML, DOT, Mermaid export formats (future) +- what implements this spec? +- what ADR explains this module? +- what changed semantically in this area? +- what is weakly connected or missing? +- what tasks, reviews, or issues shaped this path? -**Complexity:** ~150 LoC -**Est. Human Hours:** 4 +Exit criteria: -**Definition of Done:** -- Export works for both formats -- Round-trip verified -- Prefix filtering works - -**Blocked By:** INT-001 -**Blocking:** — - -**Test Plan:** -- *Golden Path:* Seed graph → export → re-import → verify identical -- *Failure Modes:* Empty graph → valid empty export -- *Edge Cases:* Nodes with special characters in IDs, very large graph export -- *Fuzz/Stress:* Export graph with 1000 nodes, 5000 edges → verify <5s and file size reasonable +- Git Mind can answer a small set of real repository questions better than grep plus memory +- answers are inspectable rather than magical --- -# Dependency DAG Summary - -``` -BEDROCK ──────────────────────────────────────────────────┐ - BDK-001 ──→ BDK-002 ──→ BDK-007 │ - BDK-001 ──→ BDK-003 ──→ BDK-004 ──→ BDK-005 ──→ BDK-006 │ - BDK-003 ──→ BDK-008 │ - BDK-004 ──→ BDK-008 │ - │ -INTAKE ←── BEDROCK │ - INT-001 ──→ INT-002 ──→ INT-008 │ - INT-001 ──→ INT-003 ──→ INT-004 │ - INT-001 ──→ INT-006 ──→ INT-007 ──→ INT-008 │ - INT-005 ──→ INT-008 │ - │ -PRISM ←── BEDROCK │ - PRI-001 ──→ PRI-002 ──→ PRI-007 │ - PRI-001 ──→ PRI-003 ──→ PRI-007 │ - PRI-001 ──→ PRI-004 ──→ PRI-007 │ - PRI-001 ──→ PRI-005 ──→ PRI-007 │ - PRI-001 ──→ PRI-006 ──→ PRI-007 │ - │ -WATCHTOWER ←── BEDROCK, PRISM │ - WTC-001 ──→ WTC-002 │ - WTC-003 ──→ WTC-005 │ - WTC-004 ──→ WTC-005 │ - │ -PROVING GROUND ←── ALL ABOVE │ - PRV-001 ──→ PRV-002 ──→ PRV-003 ──→ PRV-004 ──→ PRV-005│ - │ -ORACLE ←── PROVING GROUND │ - ORC-001 ──→ ORC-002 ──→ ORC-003 ──→ ORC-004 ──→ ORC-005│ - ORC-006 ──→ ORC-007 │ - │ -NEXUS ←── ORACLE │ - NEX-001 ──→ NEX-002 │ - NEX-003 ──→ NEX-004 ──→ NEX-005 │ - NEX-006 (independent) │ -``` - ---- +## Hill 3: Living Map Review Loop -# Key Design Decisions - -| Decision | Choice | Rationale | -|----------|--------|-----------| -| Node ID format | `prefix:identifier` | Enables prefix-based filtering and view matching | -| Prefix casing | lowercase prefix, case-preserving identifier | `milestone:BEDROCK` not `Milestone:bedrock` | -| Edge uniqueness | `(source, target, type)` tuple | Re-adding same edge updates props, doesn't duplicate | -| Import semantics | Node props: shallow merge; Edge: update if exists | Idempotent by default | -| Import failure mode | All-or-nothing (default) | Validate everything before writing anything | -| Schema versioning | `version: 1` required, unknown → hard error | Fail closed, not best-effort | -| View definitions | Declarative config objects | Adding a view = config patch, not code change | -| Output format | Human-readable default, `--json` flag | Both humans and machines are first-class consumers | -| AI suggestions | Never auto-commit | Humans curate, machines suggest | -| Cross-repo edges | Repo-qualified node IDs | Namespacing prevents collisions | +Goal: ---- +- keep the semantic map alive as the repository changes without turning maintenance into a second job -# Milestone 9: IRONCLAD — GA Hardening +Primary hill: -> **"You're done with more features. Now win trust."** +- the map evolves with the repo instead of decaying beside it -**Mission:** Convert git-mind from "feature complete" to "production undeniable." -**Non-goal:** New features unless they reduce risk or adoption friction. -**Success metric:** New team can install, model, validate, and enforce policy in under 60 minutes. +Deliverables: ---- +- update ingestion over new commits and artifact changes +- suggested semantic deltas +- review and refinement loop for inferred associations +- semantic drift detection or confidence decay where appropriate +- measures of map freshness and weak spots -## Phase A — Contract Lockdown (P0) +Playback: -### A1) CLI JSON Schema Contracts (#205) -- JSON Schema files for every `--json` command output -- `schemaVersion` field in every JSON output -- CI validates all `--json` output against schemas +- new changes produce reviewable semantic updates +- maintainers refine the map when needed, but do not rebuild it by hand -### A2) API Stability Surface (#206) -- Public API export audit + snapshot -- Automated API diff check in CI -- Deprecation protocol: warning + migration note +Exit criteria: -### A3) Error Taxonomy + Exit Codes (#207) -- Structured errors: `GMIND_E_*` error codes -- Consistent exit code table -- JSON mode includes `errorCode`, `hint`, `docsRef` +- upkeep cost remains low +- semantic quality improves over time instead of flattening into noise --- -## Phase B — Reliability Gauntlet (P0) - -### B1) Cross-OS CI Matrix (#208) -- ubuntu-latest, macos-latest, windows-latest -- Node active LTS bands -- smoke / integration / long-run suite split +## Supporting Lanes -### B2) Fuzz & Adversarial Inputs (#209) -- Targets: YAML import, frontmatter parser, directive parser, validators -- Zero unhandled exceptions across corpus +These lanes should support the active Hill, not replace it as the product center: -### B3) Corruption & Recovery Drills (#210) -- Missing refs, malformed payloads, partial merges, stale locks -- `git mind doctor --strict` -- Deterministic behavior, no silent data mutation - ---- +- platform hardening and contracts +- packaging and install ergonomics +- content and content UX +- extension/runtime ergonomics +- workflow adoption layers +- richer workflow-specific views +- trust-aware surfaces -## Phase C — Data Safety + Atomicity (P0) +Examples of work that may live here: -### C1) Transactional Writes (#211) -- Write to temp ref → verify checksum → atomic ref swap -- No partial write states observable +- graph-backed authored content where it clearly improves repo workflows +- materialized outputs +- multi-repo expansion +- operational hardening for agent-facing use +- adoption polish once zero-input repo understanding is real -### C2) Backup / Restore (#212) -- `git mind backup [--out file]` -- `git mind restore [--dry-run]` +Exit criteria: ---- +- each added layer measurably improves real repository understanding or operational use +- Git Mind still does not feel like a hand-maintained wiki or ontology project -## Phase D — Adoption Engine (P1) +## Playback Cadence -### D1) 30-Minute Zero-to-Value Tutorial (#213) -- Fresh user reaches: imported graph, usable view, doctor clean, CI policy in <60 min +Use playbacks to judge progress against the Hills. -### D2) Opinionated Team Starter + CI Policy Gate (#214) -- `git mind init --preset engineering` -- Strict mode: fail on dangling edges, blocked tasks, low-confidence edges +Good playback questions: ---- +1. Did recent work improve zero-input repository understanding? +2. Did it make provenance-backed answers more useful or more trustworthy? +3. Did it reduce upkeep cost instead of pushing more manual curation onto the user? +4. Did it strengthen an active supporting lane without stealing focus from the Hill? +5. If this work landed, would a new user or agent feel more capable in an unfamiliar repo? -## Phase E — Performance Envelope (P1/P2) +Recommended rhythm: -### E1) Benchmark Harness (#215) -- Small/medium/large graph bench packs -- p50/p95 latency, memory ceiling, cold vs warm -- Regressions >10% fail benchmark gate +- use issues and PRs for day-to-day work +- use periodic playbacks to review movement against the active Hill +- update this roadmap and `docs/design/git-mind.md` when the product frame changes +- avoid reopening milestone theater unless there is a real release-management need --- -## GA Release Candidate (#216) +## What Stops Work -**GA Checklist (must all be green):** -- [ ] All `--json` outputs schema-validated in CI -- [ ] Public API snapshot unchanged (or semver-major justified) -- [ ] Typed errors + stable exit codes everywhere -- [ ] Atomic writes proven under injected failures -- [ ] Doctor strict catches all known corruption classes -- [ ] Fresh-user tutorial validated by non-authors -- [ ] CI policy gate docs + working example -- [ ] Performance baseline + regression alarms active - ---- +Work should pause and be questioned if: -## Do Not Cut -- JSON schema contracts -- Typed error codes -- Atomic writes -- Corruption drills +- setup gets heavier while first-use value stays flat +- inference remains too weak to be useful +- provenance is invisible to users +- the system requires too much manual graph building +- the product starts drifting back into personal cognition or generic PKM --- -# Backlog (Unscheduled) - -These items are not assigned to a milestone yet. They'll be scheduled based on user feedback and priorities. - -### Extension persistence & ephemeral loading (deferred from M12 polish) - -Two issues were filed during the M12 extension polish pass and intentionally deferred: - -- **#261 — Ephemeral registration: extension add doesn't persist across invocations.** - `git mind extension add ` registers for the current process only. The fix requires a persistence mechanism — a lockfile (`.git/git-mind/extensions.yaml`), graph-stored config, or git-config entries. Each option has different tradeoffs for portability, discoverability, and merge semantics. This also changes the CLI boot sequence for ALL commands (startup must load user extensions after built-ins), so it needs careful design. - -- **#269 — `--extension ` flag for single-invocation loading.** - A workaround for #261: load an extension for one command only (`git mind view my-view --extension ./ext.yaml`). Useful for CI/CD pipelines that inject custom domain logic. Deferred because this is cleaner to design after #261's persistence exists — the flag would be "like `extension add` but ephemeral", which is only meaningful once `add` is actually persistent. - -**Recommended slot:** H2 (CONTENT + MATERIALIZATION) planning. Both issues naturally fall into the extension lifecycle story — persistence is a prerequisite for the extension marketplace vision (H4). Design the persistence mechanism during H2 kickoff, implement as the first H2 deliverable so that all subsequent extension work (content system extensions, materializer extensions) benefits from proper registration. - -### Content system enhancements (from M13 VESSEL review) - -- **`git mind content list`** — Query all nodes that have `_content` properties. Currently there's no way to discover which nodes carry content without inspecting each one individually. -- **Binary content support** — Add base64 encoding for non-text MIME types. Currently the content system is text-only (UTF-8); WARP stores blobs natively but `readContent()` always calls `.toString('utf-8')`, so binary round-trips are lossy. Requires returning a `Buffer` for non-text MIME types and reintroducing encoding metadata. -- **`content meta --verify` flag** — Verify the content blob OID exists in the git object store without dumping the full body. Useful for bulk health checks across all content-bearing nodes. - -### Codebase hardening (from M13 VESSEL review) - -- **Standardize all git subprocess calls to `execFileSync`** — `src/content.js` eliminated all subprocess calls via WARP-native migration, but other modules (e.g. `processCommitCmd` in `commands.js`) still use `execSync` with string interpolation. Audit and migrate for consistency and defense-in-depth. - -### Content module error handling (from #284 CodeRabbit review) - -- **Establish error message conventions** — Content module errors lack a consistent prefix/format. Consider a `[content] failed: ` convention or a `ContentError` class hierarchy for typed catch handling. -- **Audit `try/catch` blocks for cause preservation** — The `readContent()` catch now chains `{ cause: err }`, but other modules may swallow root causes. Audit all catch blocks in domain code for cause propagation. -- **Integration test for `error.cause` chain** — Verify callers of `readContent()` can access `error.cause` when blob retrieval fails. Currently only the error message is tested. -- **`--verbose` flag for content CLI** — Dump the full `error.cause` chain when content operations fail. Helps diagnose infrastructure vs. missing-blob issues. - -### CI/CD & release hygiene (from #285 merge experience) - -- **Version consistency gate** — Add a CI check that `package-lock.json` top-level version matches `package.json` version. During #285 the lock file was stale at `3.2.0` while `package.json` was `4.0.0` — only caught manually. -- **Changelog entry validation** — Add a CI check that `CHANGELOG.md` contains a heading matching the current `package.json` version. The `[4.0.0]` entry was missing until manually added during the PR. - -### Content system UX (from #284/#285 post-merge review) - -- **`content set` from stdin** — Allow piping content via `echo "..." | git mind content set `. Currently only `--from ` is supported, limiting scriptability. -- **Content health checks in `git mind doctor`** — Detect nodes with stale MIME types, orphaned content properties (OID present but blob missing), and size/OID mismatches. Extends the existing doctor detectors. -- **`--as-of` guard for content commands** — Emit a clear error or warning if `--as-of` is used with `content show|meta|set|delete`. WARP ticks are independent of git commit history; time-travel for content is intentionally excluded but not enforced at the CLI boundary. -- **Content CLI fast-path unit tests** — The current content CLI tests shell out to `bin/git-mind.js` (~700ms each). Add a parallel set of fast tests that invoke command handlers directly with a mock graph for faster feedback loops. -- **WARP-native migration guide** — `src/content.js` is the first module to eliminate all git subprocess calls via WARP's native API. Document the migration pattern (before/after, gotchas, WARP null semantics) as a reference for migrating other modules. - -### Other backlog items - -- `git mind onboarding` as a guided walkthrough (not just a view) -- Confidence decay over time (edges rot if not refreshed) -- View composition (combine multiple views) -- Wesley-generated typed graph accessors -- Mermaid diagram export (`git mind export --format mermaid`) -- GraphQL API for web frontends -- Real-time file watcher for automatic edge updates -- Git blame integration (who created this edge?) -- Edge provenance visualization - ---- +## Decision Rule -> **This roadmap is tracked in git-mind's own graph.** -> The task DAG above is materialized as nodes and edges in this repo's git-mind graph. -> Run `git mind view roadmap` to see it live. -> -> Maintainers: update this file AND the graph when priorities shift or phases complete. +When a tradeoff is unclear, prefer the option that increases low-input repository understanding and provenance-backed answers, even if it delays broader platform ambitions. diff --git a/TECH-PLAN.md b/TECH-PLAN.md index c175669e..0a707583 100644 --- a/TECH-PLAN.md +++ b/TECH-PLAN.md @@ -1,6 +1,10 @@ # Technical Deep Dive: git-mind -> **"A knowledge graph that thinks alongside you."** +> Historical note: +> +> This document is a deep technical artifact from an earlier planning era. +> It still contains useful substrate and architecture detail, but it is not the active product roadmap or control plane. +> The current product frame lives in [README.md](README.md), [ROADMAP.md](ROADMAP.md), and [docs/design/git-mind.md](docs/design/git-mind.md). A technical analysis of git-mind's architecture, data model, runtime behavior, invariants, and roadmap trajectory. This is a reference artifact — not a changelog, not a tutorial. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index df1f70a2..c710bc94 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -3,6 +3,9 @@ _Last updated: 2026-02-15_ This document defines non-negotiable engineering laws for Git Mind. +These laws are canonical engineering guardrails. +They are not the product roadmap, and some of the terms here come from broader platform work that predates the current product narrowing. + --- ## Law 1: Graph Truth Is Canonical diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..8a70ee24 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,62 @@ +# Documentation Map + +This file defines which documents are canonical, which are transitional, and which are historical references. + +Use it to avoid treating old planning artifacts as the active product story. + +## Canonical Product Docs + +These describe what Git Mind is now and how work should be judged: + +- [README.md](../README.md) — current product summary +- [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 +- [Git Mind North Star](./VISION_NORTH_STAR.md) — longer-form strategic articulation + +## Canonical Engineering Guardrails + +These define constraints and contracts that remain in force: + +- [GRAPH_SCHEMA.md](../GRAPH_SCHEMA.md) — graph contract +- [Architecture Laws](./ARCHITECTURE.md) — non-negotiable engineering laws +- [Review Rubric](./REVIEW_RUBRIC.md) — architectural review gates +- [ADRs](./adr/README.md) — durable architecture decisions +- [Contracts](./contracts/CLI_CONTRACTS.md) and related schemas — machine-facing contracts + +## Transitional Docs + +These are still useful, but they carry some older framing and should not be treated as the primary product narrative: + +- [GUIDE.md](../GUIDE.md) — CLI and usage reference; still contains manual graph-authoring examples +- [CONTRIBUTING.md](../CONTRIBUTING.md) — contributor workflow with current frame pointers added + +## Historical Reference Docs + +These should not drive planning or product identity without explicit review: + +- [CHANGELOG.md](../CHANGELOG.md) — release history, not product strategy +- [TECH-PLAN.md](../TECH-PLAN.md) — deep technical artifact from an earlier planning era +- [Risk Register](./RISK_REGISTER.md) — bridge/platform-era risk control document +- [Risk Review Checklist](./RISK_REVIEW_CHECKLIST.md) — bridge/platform-era operating checklist +- [Strategic Conversation Summary](./notes/Git%20Mind%20Strategic%20Conversation%20Summary.md) — historical context +- [Dogfood Session](./notes/dogfood-session.md) — historical evidence, not current plan + +## Practical Rule + +When documents disagree: + +1. trust the canonical product docs first +2. then trust canonical engineering guardrails +3. treat transitional docs as implementation help, not product truth +4. treat historical docs as reference only + +## Planning Rule + +GitHub issues are the execution backlog. + +Hills and Playbacks live in: + +- [ROADMAP.md](../ROADMAP.md) +- [Git Mind Product Frame](./design/git-mind.md) + +GitHub milestones are not the primary planning system for this repository. diff --git a/docs/REVIEW_RUBRIC.md b/docs/REVIEW_RUBRIC.md index 15017366..40e38e24 100644 --- a/docs/REVIEW_RUBRIC.md +++ b/docs/REVIEW_RUBRIC.md @@ -1,7 +1,9 @@ # Git Mind Review Rubric _Last updated: 2026-02-15_ -Use this rubric for PR reviews, design reviews, and milestone gate checks. +Use this rubric for PR reviews and design reviews when changes touch core graph, determinism, provenance, contracts, or materialization concerns. + +This is an engineering guardrail document, not the product roadmap or playback control plane. --- diff --git a/docs/RISK_REGISTER.md b/docs/RISK_REGISTER.md index 96c8c9d4..4973b2a7 100644 --- a/docs/RISK_REGISTER.md +++ b/docs/RISK_REGISTER.md @@ -1,9 +1,14 @@ # Git Mind Risk Register **Version:** 1.0 **Date:** 2026-02-15 -**Status:** Active +**Status:** Historical / dormant pending future workflow-adoption work **Applies to:** M10–M18 roadmap execution +> Historical note: +> +> This register was written for the earlier bridge/platform roadmap. +> It remains useful as a reference for future workflow-adoption layers, but it is not the active planning control plane for the current Hills. + --- ## 0) Purpose diff --git a/docs/RISK_REVIEW_CHECKLIST.md b/docs/RISK_REVIEW_CHECKLIST.md index 285f2577..a190298e 100644 --- a/docs/RISK_REVIEW_CHECKLIST.md +++ b/docs/RISK_REVIEW_CHECKLIST.md @@ -3,6 +3,11 @@ **Cadence:** Weekly (mandatory) **Goal:** Detect existential drift early and force corrective action +> Historical note: +> +> This checklist belongs to the earlier bridge/platform roadmap and its risk regime. +> Keep it as reference material, not as the active operating cadence for the current product hills. + --- ## 0) Pre-Read (5 min max, async) diff --git a/docs/VISION_NORTH_STAR.md b/docs/VISION_NORTH_STAR.md index ad2a88a2..609ae71b 100644 --- a/docs/VISION_NORTH_STAR.md +++ b/docs/VISION_NORTH_STAR.md @@ -1,404 +1,178 @@ # Git Mind North Star -## Verifiable Knowledge Operations on WARP Graphs +## Queryable Repository Meaning With Receipts --- ## 1) North Star Statement -Git Mind is a **WARP-native knowledge operating system** for teams and autonomous agents. -It models work as cryptographically causal graph entities (nodes/edges/properties), supports domain-specific workflows via extensions, and materializes human-readable artifacts (Markdown, HTML, PDF, etc.) on demand from graph state — at any point in time, for any observer/trust policy. +Git Mind is a Git-native semantic intelligence layer for software repositories. -**Source of truth is the graph, not checked-in files.** +It should let a human or agent point at a repository and obtain useful, reviewable, provenance-backed knowledge about how code, docs, ADRs, tasks, reviews, issues, commits, and other project artifacts relate over time. + +The system should make repository meaning explicit without requiring an external database or heavy manual curation before value appears. --- ## 2) Identity **Git Mind is:** -- A domain-agnostic knowledge graph engine -- A WARP-powered causal/provenance runtime -- An extension platform for domain workflows -- A materialization engine for file-like outputs without file-centric truth -- A trust-aware audit substrate (authorship, approvals, policy) + +- a repo-semantic inference and association engine +- a provenance-aware graph substrate +- a query surface over repository meaning +- a review loop for inferred semantic relationships +- a deterministic contract layer for humans and agents **Git Mind is not:** -- A generic note app -- A static markdown repo -- A thin wrapper over GitHub issues/docs -- A plugin free-for-all without deterministic contracts + +- a personal thought-capture tool +- a reflective dialogue product +- a manually maintained project wiki +- a generic note app +- a provenance demo without a concrete repository job to do --- ## 3) Core Product Thesis -Traditional tools separate planning, docs, tickets, architecture, and audit trails into disconnected silos. -Git Mind unifies them into one causal graph where: - -1. Every fact has provenance. -2. Every state is replayable. -3. Every domain is an extension. -4. Every document is materialized from graph truth. -5. Every query can be observer- and trust-scoped. - ---- - -## 4) Platform Model +Repository understanding is usually reconstructed from: -### 4.1 Substrate (WARP / git-warp) -- Cryptographic causal history -- Multi-writer/fork/merge semantics -- Time-travel and deterministic replay -- Observer-relative projections -- Trust-aware verification (approved authorship, delegation, revocation) - -### 4.2 Semantic Runtime (Git Mind Core) -- Generic node/edge/property model -- Query engine -- View/lens composition -- Rule execution -- Materialization pipeline - -### 4.3 Extension Layer - -Extensions declare domain semantics: -- Schemas (node/edge types) -- Views -- Lenses -- Rules -- Sync adapters -- Workflow actions -- Materializers/templates +- file layout +- grep +- issue links +- commit history +- naming conventions +- memory ---- +Git stores history well, but not the semantic structure of a project. -## 5) Terminology Decision +Git Mind should close that gap by: -Use **Extensions** as user-facing term (clear and product-friendly). -Optionally keep "packs" as internal implementation name during migration. +1. ingesting repository artifacts +2. inferring entities and relationships +3. surfacing high-value semantic views and answers +4. attaching provenance and confidence to what it claims +5. letting humans and agents review and refine the map over time -- CLI: `git mind extension ...` -- Manifest: `extension.yaml` -- Registry: extension registry -- SDK: extension SDK +If Git Mind cannot provide useful understanding of a repository with low setup and low ongoing manual effort, it is not doing its job. --- -## 6) Key Product Capabilities - -### A) Graph-native domain workflows - -Examples: -- **Roadmap workflow**: task/feature/milestone graphs -- **ADR workflow**: decision nodes + rationale + consequences -- **PR workflow**: contributors/reviews/approvals/dependencies -- **Incident workflow**: timeline, blast radius, corrective actions - -### B) Content-on-node (not file-first) - -Any rich content (ADR body, spec text, policy memo, postmortem narrative) is stored as graph-linked content, not as canonical checked-in docs. - -Content becomes: -- versioned -- provenance-backed -- observer-aware -- trust-filterable -- materializable on demand - -### C) Materialization engine - -Render graph state into: -- Markdown -- HTML -- PDF -- JSON -- static site outputs - -at: -- current head -- historical head (`--as-of`) -- specific observer/trust policy - -### D) Provenance slicing + explainability - -For any node/edge/property: -- full mutation lineage -- causal ancestry -- author/trust chain -- policy/rule receipts -- "why this value?" explanation - -### E) Trust-aware operations +## 4) Platform Model -With git-warp trust features: -- approved-authorship modes -- delegated trust -- revocation impact analysis -- trust-scoped views and rules -- signed evidence/certification outputs +### 4.1 Substrate ---- +Git + WARP provide: -## 7) The ADR Vision (concrete example) +- causal history +- deterministic replay +- mergeable graph state +- time-scoped materialization +- provenance-carrying mutation history -Instead of writing ADRs in external docs: +### 4.2 Git Mind Core -**1. Create ADR node:** -```bash -git mind node add adr:0007 --type adr --title "Adopt extension runtime" -``` +Git Mind adds: -**2. Attach content directly to node (graph-backed CAS payload):** -```bash -git mind content set adr:0007 --from ./adr-0007.md -# or interactive editor -git mind content edit adr:0007 -``` +- artifact ingestion +- entity extraction +- relationship inference +- query and view surfaces +- reviewable suggestion flows +- semantic diff and historical replay -**3. Link to impacted architecture/tasks:** -```bash -git mind edge add adr:0007 decides module:runtime -git mind edge add adr:0007 affects task:M11 -``` +### 4.3 Supporting Layers -**4. Materialize when needed:** -```bash -git mind materialize adr:0007 --format md --out ./dist/adr-0007.md -git mind materialize adr:0007 --format html --out ./dist/adr-0007.html -git mind materialize adr:0007 --format pdf --out ./dist/adr-0007.pdf -``` +These remain important, but they are supporting layers, not the center of the product story: -**5. Time travel:** -```bash -git mind materialize adr:0007 --as-of main~30 --format md -``` +- graph-backed authored content +- extension/runtime machinery +- materialization +- trust-aware operations -Same node, many renderings, full provenance. +They matter when they make repo understanding and workflow adoption better. --- -## 8) Content Storage Architecture - -### Option A: Git Notes-backed content - -**Pros:** -- Native git primitive -- Easy inspection -- Familiar ecosystem +## 5) Primary Product Promise -**Cons:** -- Scaling/format constraints -- Harder to enforce richer contracts -- Less control for advanced CAS policies +The strongest promise Git Mind can make is: -### Option B: git-cas-backed content (recommended default) +> Point me at a repository and help me understand what matters, how it connects, and how it evolved. -**Pros:** -- Content-addressed durability -- Natural dedupe/chunking potential -- Strong integrity linkage to WARP receipts -- Cleaner path for encryption/policy/capability controls -- Better for large/structured content evolution +That promise should be testable through questions like: -**Cons:** -- More initial implementation work -- Needs good tooling for inspectability - -### Recommended stance -- **Canonical content store**: git-cas-backed -- **Optional import/export bridges** for git notes interop -- Treat notes as compatibility channel, not primary substrate +- what implements this spec? +- what ADR explains this area? +- what tasks and reviews shaped this code path? +- what changed semantically between these commits? +- where are the missing or weakly connected parts of the project knowledge graph? --- -## 9) Materialization Model +## 6) Key Capabilities -Materialization should be explicit and reproducible. +### A) Low-Input Semantic Bootstrap -### 9.1 Inputs -- entityId or view -- asOf (rev/receipt/tick) -- observerContext -- trustPolicy -- extensionSet + lock -- template/profile +Ingest repository artifacts and produce a useful first-pass semantic map without expecting users to hand-author everything. -### 9.2 Output envelope +### B) Queryable Semantic Answers -Every materialized artifact includes provenance header: -- graph head / frontier hash -- observer hash -- trust policy hash -- extension lock hash -- render hash -- timestamp of render (non-semantic metadata) +Let humans and agents ask repository questions and receive provenance-backed answers with visible confidence. -### 9.3 Rules -- Rendering must be deterministic given same semantic inputs -- Generated files are artifacts, not canonical truth -- Artifacts may be cached, always reproducible +### C) Reviewable Inference ---- +Inferred structure should be reviewable, refinable, and capable of improving over time without requiring users to build the map from scratch. -## 10) Feature Catalog - -### 10.1 Core Engine -- Generic graph operations -- Deterministic serialization and query execution -- Time-travel/as-of query semantics -- Fork/merge aware reasoning - -### 10.2 Extension Runtime -- Extension manifest v1 -- Registry/activation/deactivation -- Namespacing and collision policy -- Capability-scoped scripts (pure/effect) -- Extension compatibility checks - -### 10.3 View/Lens System -- Named views per extension -- Composable lenses (`view:a:b:c`) -- Cross-extension projections -- Causal/observer-aware filtering - -### 10.4 Rules/Policy -- Rule execution with severities -- Doctor policy gates -- CI-ready contracts -- Trust policy integration - -### 10.5 Sync/Automation -- Plan/apply split -- Idempotent sync receipts -- Source snapshot hashing -- Replayable ingest pipelines - -### 10.6 Content System -- Entity-attached content bodies -- Rich metadata (mime, language, template hints) -- Multi-revision content lineage -- Content linking + embedding primitives - -### 10.7 Materialization -- Markdown/HTML/PDF/JSON renderers -- Template engine per extension -- Static site/export packs -- As-of materialization and comparison - -### 10.8 Provenance & Audit -- Holographic slice explorer -- trace/prove/certify commands -- Evidence bundles -- Chain-of-custody certificates -- Trust drift and revocation impact - -### 10.9 Observer Intelligence -- Observer profiles -- Observer diff / disagreement maps -- Rulial-distance metrics (operational v1) -- Policy simulation across historical windows - -### 10.10 Distribution & Governance -- Extension lockfile -- Signing/integrity policy -- Conformance test suite -- Maturity levels (experimental/stable/trusted) +### D) Historical Replay ---- +The system should support semantic diff and time-aware inspection so repository meaning can be examined across change, not just at the latest state. -## 11) Long-term Roadmap - -### Horizon 1: Deterministic Extension Foundation -- Extension spec v1 -- Registry + namespaces -- Lens ABI -- Built-in domains migrated to extensions -- Contracts/schema lock - -### Horizon 2: Graph-native Content + Materialization -- Content subsystem (CAS-backed) -- ADR/doc workflows on nodes -- Materialize MD/HTML/PDF -- As-of rendering + reproducible headers - -### Horizon 3: Trust + Audit Intelligence -- Approved authorship integration -- Trust-aware views/rules -- Certify/evidence bundle workflows -- Revocation and policy simulation - -### Horizon 4: Ecosystem + Knowledge OS -- Extension marketplace/distribution -- Signed trusted extensions -- Federated multi-domain workflows -- Enterprise governance/audit suites +### E) Agent-Native Contracts ---- - -## 12) Design Invariants (hard gates) - -1. **Determinism > convenience** -2. **Graph truth > file truth** -3. **Extensions cannot bypass trust/provenance contracts** -4. **Side effects always plan/apply** -5. **Observer/trust context is explicit** for materialization and views -6. **Every machine interface is schema-versioned** -7. **Reproducibility requires extension lock + provenance envelope** +Machine-readable interfaces should make Git Mind useful as a contract boundary for autonomous agents, not just a human-facing dashboard. --- -## 13) Proposed CLI Surface (v1 direction) +## 7) Adoption Rule -```bash -# Extension lifecycle -git mind extension list -git mind extension add roadmap -git mind extension remove docs -git mind extension validate ./my-extension +Git Mind should not ask users to become graph curators before it becomes useful. -# Content-on-node -git mind content set adr:0007 --from ./adr.md -git mind content edit adr:0007 -git mind content show adr:0007 --as-of main~12 +Adoption depends on three things: -# Materialization -git mind materialize adr:0007 --format md --out ./dist/adr.md -git mind materialize view:roadmap --format html --out ./site/roadmap.html -git mind materialize adr:0007 --format pdf --as-of release/1.0 +1. low setup +2. immediate semantic value +3. trustworthy receipts -# Provenance/trust -git mind trace adr:0007 --property status -git mind prove adr:0007 --trust approved-only -git mind certify adr:0007 --bundle audit --out ./evidence/ -``` +If it behaves like a project wiki with extra steps, it will fail. --- -## 14) Immediate Next Decisions +## 8) Boundary With Think -1. **Choose canonical content store** - Recommend: git-cas-backed, with optional git-notes bridge. +This boundary should remain explicit. -2. **Freeze extension manifest v1** - Don't build runtime before spec discipline. +`think` owns: -3. **Define materialization contract v1** - Input/output envelope + provenance headers. +- personal capture +- re-entry +- reflection dialogue +- x-ray over a person's own evolving thought -4. **Define content entity model** - Node-linked content object schema (revisioning, mime, origin, trust tags). +Git Mind owns: -5. **Decide observer/trust defaults** - Prevent hidden ambiguity in CLI behavior. +- semantic extraction from repository artifacts +- repository-scoped relationship inference +- provenance and replay over project meaning +- queryable repository intelligence --- -## 15) The Narrative +## 9) Strategic Consequence + +The next meaningful hill for Git Mind is not more platform breadth. -> "Git Mind turns organizational knowledge into a verifiable causal graph. -> You work in domain workflows through extensions. -> You write decisions and specs directly to graph entities. -> Files are generated views, not source of truth. -> Everything is replayable, auditable, and trust-aware." +It is proving that low-input semantic bootstrap and provenance-backed repository querying are genuinely useful on real repositories. -That's a category statement, not a feature list. +Everything else should be judged by whether it helps that hill land. diff --git a/docs/adr/README.md b/docs/adr/README.md index 2f4fc8bf..cde6ba4b 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -2,6 +2,9 @@ This directory captures durable architecture decisions for Git Mind. +These ADRs are architecture references, not the canonical product narrative. +Some of them were written during a broader platform and bridge planning phase, but they still matter where they establish substrate or invariants that remain in force. + Use ADRs for decisions that are hard to reverse, cross-cut multiple subsystems, or define platform invariants. --- @@ -108,4 +111,4 @@ Prevents git-mind from duplicating CRDT, time-travel, observer, and provenance g - Keep ADRs concise but specific. - Avoid ambiguous wording (“usually”, “maybe”) in core invariants. - Include explicit consequences and operational impact. -- Link milestone(s), contracts, and tooling gates affected by the decision. \ No newline at end of file +- Link relevant Hill(s), issue(s), contracts, and tooling gates affected by the decision. diff --git a/docs/design/git-mind.md b/docs/design/git-mind.md new file mode 100644 index 00000000..39804b7b --- /dev/null +++ b/docs/design/git-mind.md @@ -0,0 +1,386 @@ +# Git Mind Product Frame + +Status: draft for review + +## Purpose + +Reframe `git-mind` using an IBM Design Thinking style structure after the split that produced `think`. + +This document exists to answer two questions: + +1. What is left of `git-mind` now that the inward-facing cognitive capture thesis lives in `think`? +2. Is what remains a real product, or just leftover architecture? + +The answer proposed here is: + +`git-mind` is only worth continuing if it becomes a low-input, inference-first, provenance-backed semantic intelligence layer for Git repositories. + +## Context + +`think` now owns the personal cognition loop: + +- raw personal capture +- re-entry +- reflection dialogue +- x-ray over a person's own evolving thought + +That means `git-mind` no longer needs to carry personal cognition at all. + +If `git-mind` continues, it should continue as a repository-facing product: + +- repo artifacts +- semantic extraction +- cross-artifact association +- provenance and replay +- queryable engineering knowledge + +## Problem Statement + +Repository meaning is fragmented across: + +- code +- docs +- ADRs +- tasks +- reviews +- pull requests +- issues +- commits +- CI and operational artifacts + +Git tracks files and history well, but it does not directly tell you: + +- which code implements which spec +- which ADR explains a given module +- which task, issue, or review drove a change +- which concepts recur across docs and code +- how those relationships changed over time + +Today, people and agents reconstruct this from: + +- filenames +- grep +- issue links +- commit messages +- tribal knowledge +- memory + +That reconstruction is slow, lossy, and inconsistent. + +`git-mind` exists to establish and surface semantic relationships between project artifacts, with provenance and history, directly from a Git repository and the artifacts around it. + +## Sponsor User + +Primary sponsor user: + +- A technical lead, staff engineer, architect, or autonomous coding agent dropped into a repository who needs a trustworthy mental model of how the project's artifacts relate, with as little setup and manual curation as possible. + +This user does not want: + +- another hosted SaaS +- another hand-maintained project wiki +- another dashboard that drifts away from the repo +- another ontology exercise before the product becomes useful + +They want: + +- to point a tool at a repo and immediately get useful semantic structure +- to ask high-value questions and get provenance-backed answers +- to review and refine inferred associations when needed +- to trust that the map evolves with the repo instead of rotting beside it + +## Jobs To Be Done + +Primary job: + +- When I point `git-mind` at a repository, help me quickly understand how its code, docs, decisions, tasks, reviews, and artifacts relate, and how those relationships changed over time. + +Secondary jobs: + +- Help me establish a useful semantic map with little to no manual input. +- Help me query repo meaning instead of reconstructing it from scratch every time. +- Help me trust the system's assertions by showing provenance, confidence, and historical receipts. +- Help me keep that semantic map current as the repository evolves, without turning maintenance into a second job. +- Help autonomous agents operate on repo knowledge through deterministic contracts instead of prompt folklore. + +## Product Thesis + +`git-mind` is a Git-native semantic inference and provenance layer for software repositories. + +It should point at a repository and produce useful, reviewable, queryable knowledge about how code, specs, decisions, tasks, reviews, issues, and other project artifacts relate over time. + +If it cannot do that with low setup and low ongoing manual labor, it is probably not a compelling product. + +## What Git Mind Is + +`git-mind` is: + +- a repo-native semantic extraction and association engine +- a provenance-aware graph substrate for project artifacts +- a query surface over repository meaning and change over time +- a reviewable inference system for cross-artifact relationships +- a deterministic contract layer for humans and agents operating on repo knowledge + +## What Git Mind Is Not + +`git-mind` is not: + +- a personal thought capture tool +- a reflection product +- a project wiki you manually maintain forever +- a generic PKM system +- a graph toy for enthusiasts +- a provenance tool in search of a use case +- a product that should require users to hand-author a full ontology before it becomes useful + +## Product Doctrine + +- Low-input semantic bootstrap is non-negotiable. +- Inference should precede manual modeling. +- Provenance must back every meaningful assertion. +- Confidence should be inspectable. +- Review should refine the map, not create the map from scratch. +- The graph is the substrate, not the main user mental model. +- Queryable value matters more than abstract graph elegance. +- `git-mind` should surface hidden project structure, not ask users to become librarians. + +## Experience Principles + +1. Favor extraction over manual entry. +2. Favor a useful first-pass map over a perfect ontology. +3. Favor provenance-backed confidence over opaque AI magic. +4. Favor reviewable suggestions over required curation. +5. Favor repo-native workflows over external knowledge silos. +6. Favor answers to real engineering questions over generic dashboard novelty. + +## Conceptual Product Loop + +```mermaid +flowchart LR + A["Point git-mind at a repo"] --> B["Ingest code, docs, history, and adjacent artifacts"] + B --> C["Infer entities and semantic relationships"] + C --> D["Surface views, questions, and provenance-backed answers"] + D --> E["Human or agent reviews, accepts, rejects, or refines"] + E --> F["Semantic map evolves with the repo over time"] + F --> D +``` + +## Hills + +```mermaid +flowchart LR + H1["Hill 1: Zero-input semantic bootstrap"] --> H2["Hill 2: Queryable answers with receipts"] + H2 --> H3["Hill 3: Living map with low manual upkeep"] +``` + +### Hill 1: Zero-Input Semantic Bootstrap + +Who: + +- A developer or agent entering an unfamiliar repository. + +What: + +- They can point `git-mind` at the repo and get an immediately useful semantic map extracted from code, docs, ADRs, issues, reviews, commits, and other available project artifacts, without having to model the graph by hand first. + +Wow: + +- "I pointed it at a repo and it actually gave me a map of what matters." + +### Hill 2: Queryable Answers With Receipts + +Who: + +- A maintainer, reviewer, or coding agent trying to answer a concrete repository question. + +What: + +- They can ask things like what implements this spec, what decision explains this module, what changed semantically in this area, what is blocked, or what reviews and issues shaped this code path, and get provenance-backed answers with confidence and history. + +Wow: + +- Repository archaeology becomes a query with receipts instead of a manual investigation. + +### Hill 3: Living Map With Low Manual Upkeep + +Who: + +- A team or agent workflow that wants the semantic map to remain useful as the repo changes. + +What: + +- `git-mind` continuously or periodically ingests new repo changes, updates inferred associations, and surfaces reviewable deltas so the map stays alive without becoming a hand-maintained wiki. + +Wow: + +- The repository's semantic map evolves alongside the repo instead of decaying beside it. + +## Playback Questions + +These questions should be used in design reviews and playbacks: + +1. If I point `git-mind` at a repo today, does it produce useful structure without asking too much of me? +2. Does the first useful answer arrive before the user feels like they are doing data entry? +3. Can the system answer high-value engineering questions across code, docs, decisions, tasks, reviews, and issues? +4. Are assertions backed by provenance and confidence, or are they just vibes? +5. Are humans reviewing and refining inferred structure, or manually building the whole thing by hand? +6. Have we accidentally turned the product into a project wiki, dashboard, or ontology exercise? +7. Does the system get more useful as repo history accumulates? +8. Would an autonomous agent benefit from this as a contract boundary rather than just as prompt context? + +## Repo Hygiene Findings + +Repository hygiene work on 2026-03-24 exposed four important facts: + +1. The GitHub issue backlog is real, but the GitHub milestone layer was not. + - There were 31 open issues and none of them were assigned to a milestone. + - There were also 10 open GitHub milestones, all of them 100% complete leftovers from earlier planning eras. + - Those stale milestones were retired because they were no longer acting as a real control plane. + +2. The open issue backlog clusters into a few real work lanes: + - foundation and hardening + - content and content UX + - extension/runtime ergonomics + - packaging and install polish + - dogfooding and presentation polish + +3. The repository still had multiple competing planning surfaces. + - `README.md`, `ROADMAP.md`, `docs/VISION_NORTH_STAR.md`, and this design doc now describe the clarified product frame. + - `GUIDE.md` still reflects an earlier manual graph-authoring story. + - `TECH-PLAN.md`, `docs/RISK_REGISTER.md`, and `docs/RISK_REVIEW_CHECKLIST.md` still reflect the older milestone-driven platform and bridge roadmap. + - Historical notes remain useful, but they should not compete with active product planning. + +4. The backlog and the product strategy were being mixed together. + - Open issues contain useful implementation work. + - Old milestones were pretending to be the product strategy. + - IBM Design Thinking works better here if strategy is expressed as Hills and evaluated through Playbacks, while GitHub issues remain the unit of execution. + +## Recommended Operating Model + +`git-mind` should no longer use GitHub milestones as its primary planning system. + +Recommended split: + +- IBM Hills define the product outcomes that matter. +- Playbacks review whether recent work actually moved one of those Hills. +- GitHub issues track concrete work items. +- Docs capture the current product frame and playback conclusions. + +In practice: + +- Keep a small set of active Hills in `ROADMAP.md` and this design doc. +- Use GitHub issues for implementation and bug work. +- Triage issues by Hill or lane, not by faux-release milestone. +- Record playback outcomes in issue comments, PRs, or doc updates rather than reopening milestone theater. +- Treat historical milestone-era docs as references, not control planes. + +This keeps the backlog honest: + +- issues answer "what work exists?" +- hills answer "what outcome are we trying to create?" +- playbacks answer "did the recent work move us toward that outcome?" + +## Boundary With Think + +This boundary should remain explicit. + +`think` owns: + +- personal capture +- personal reflection +- brainstorm and re-entry +- x-ray over a person's evolving thought + +`git-mind` owns: + +- semantic extraction from repository artifacts +- repository-scoped relationship inference +- provenance and replay over project meaning +- queryable project knowledge +- reviewable semantic association across artifact types + +If a proposed feature sounds like personal cognition tooling, it belongs in `think`, not here. + +## Current Reading After The Split + +What still feels real: + +- queryable knowledge about how code, specs, decisions, tasks, reviews, and artifacts relate over time +- semantic relationship extraction across project artifacts +- provenance and replay over that semantic layer +- deterministic contracts for agent-facing repo knowledge + +What should lose status: + +- "version your thoughts" framing when it suggests personal cognition +- manual graph curation as the primary path to value +- authoring-heavy framing as the main product center +- platform ambition that gets ahead of immediate repo usefulness + +## Non-Goals + +Not the job of `git-mind`: + +- personal capture +- personal reflection dialogue +- generic brainstorm tooling +- becoming a manually curated wiki first +- forcing users to build the semantic graph from scratch +- ontology complexity before product usefulness + +Not the first priority from here: + +- more abstract graph sophistication without better inference value +- broad extension-platform sprawl before the core repo-understanding hill lands +- dashboard-first product surfaces +- provenance features with no semantic question they help answer + +## Risks + +- The product becomes a juiced-up project wiki with extra steps. +- The system requires too much manual input before it becomes interesting. +- Inference quality is too weak or too opaque to trust. +- Provenance becomes a technical flex instead of a user-facing advantage. +- The product overlaps with other graph/provenance efforts without a clear boundary. +- Docs and roadmap keep telling different stories. + +## Decision Rule + +When a design tradeoff is unclear, prefer the option that improves zero- or low-input repo understanding and provenance-backed answers, even if it delays broader platform ambition. + +## What We Found Out + +After the split, `git-mind` still has a valid product thesis, but it is narrower and sharper than before. + +It is not the inward-facing cognition system. + +It is also probably not best framed as graph-backed authoring first. + +The strongest remaining product shape is: + +- automatic or low-input semantic association and surfacing for software repositories +- backed by provenance, history, and reviewable confidence + +That is the part that still feels distinct, useful, and worth testing. + +## Immediate Stabilize And Clarify Plan + +1. Rewrite the root story so README, roadmap, and long-term vision all describe `git-mind` as an inference-first semantic repo intelligence product. +2. Remove or sharply narrow language that implies personal cognition is the center of the product. +3. Identify the top repository questions `git-mind` must answer on day one for an unfamiliar repo. +4. De-emphasize manual edge authoring as the primary product story; treat it as override, curation, or refinement. +5. Define the first zero-input bootstrap path: what artifacts are ingested, what entities are extracted, and what associations are inferred. +6. Retire stale planning machinery so the repo has one active operating model. +7. Decide whether the repo remains in active development once that sharpened hill is evaluated honestly. + +## Recommended Next Hill + +If `git-mind` continues as an active product line, the next hill should be: + +- point at a repo and get an immediately useful semantic map with provenance-backed answers + +That is the make-or-break test now. + +If `git-mind` cannot create useful understanding from the repo with low setup, then the remaining product thesis is much weaker. + +If it can, then there is still something real here. diff --git a/docs/notes/Git Mind Strategic Conversation Summary.md b/docs/notes/Git Mind Strategic Conversation Summary.md index 1dc031db..73f29bb7 100644 --- a/docs/notes/Git Mind Strategic Conversation Summary.md +++ b/docs/notes/Git Mind Strategic Conversation Summary.md @@ -3,6 +3,11 @@ **Scope:** End-to-end summary of this chat session **Purpose:** Capture all major topics, decisions, rationale, and resulting direction for Git Mind +> Historical note: +> This file is preserved as strategic history. +> It should not be treated as the active product frame, roadmap, or backlog control plane. +> For the current direction, use [README.md](../../README.md), [ROADMAP.md](../../ROADMAP.md), [docs/VISION_NORTH_STAR.md](../VISION_NORTH_STAR.md), and [docs/design/git-mind.md](../design/git-mind.md). + --- ## Executive Summary diff --git a/docs/notes/dogfood-session.md b/docs/notes/dogfood-session.md index 1b0c0903..c631b57b 100644 --- a/docs/notes/dogfood-session.md +++ b/docs/notes/dogfood-session.md @@ -3,6 +3,10 @@ > **Date**: 2026-02-11 > **Seed**: `test/fixtures/echo-seed.yaml` — Echo ecosystem (55 nodes, 70 edges) > **Runtime**: Node.js 20, vitest 3.2.4 +> +> Historical note: +> This transcript captures an earlier dogfood pass against a roadmap-oriented graph model. +> It is useful as historical evidence, but it is not the active product plan or canonical workflow description. ## Setup