Merge pull request #308 from flyingrobots/feat/h1-bootstrap-spec

Resolved 1 lingering review-thread issue; docs/spec alignment for Hill 1 Semantic Bootstrap.

Author: flyingrobots

GRAPH_SCHEMA.md

@@ -98,6 +98,7 @@ Node prefixes are grouped into five categories. **Unknown prefixes produce a war
 | `feature:` | Feature grouping within a milestone | `feature:BDK-SCHEMA` |
 | `task:` | Atomic unit of work | `task:BDK-001` |
 | `issue:` | GitHub/tracker issue | `issue:180` |
+| `pr:` | Pull request referenced from repo artifacts | `pr:308` |
 | `phase:` | Project phase (alias for milestone in views) | `phase:alpha` |
 
 ### Knowledge
@@ -138,23 +139,30 @@ Node prefixes are grouped into five categories. **Unknown prefixes produce a war
 | Prefix | Purpose | Example |
 |--------|---------|---------|
 | `commit:` | Git commit (auto-generated by hooks) | `commit:934b6e3` |
+| `repo:` | Cross-repo qualifier namespace for remote node IDs | `repo:owner/name:crate:echo-core` |
+| `epoch:` | System-generated temporal/version marker for time-travel | `epoch:934b6e3` |
 
 **System prefix rules:**
 - `commit:` nodes are created automatically by the post-commit hook.
 - User-provided `commit:` nodes in import files are **rejected** (hard error).
+- `repo:` is reserved for system-managed cross-repo qualification and should not be introduced ad hoc in import files.
+- `epoch:` nodes are created automatically by the epoch/timeline machinery and are not authored directly in import files.
 - Future system prefixes will use the `sys-` namespace (e.g., `sys-audit:`).
 
 ---
 
 ## 4. Edge Types
 
-Eight directed edge types are defined. Unknown edge types are a **hard error**.
+Eleven directed edge types are defined. Unknown edge types are a **hard error**.
 
 | Type | Definition | Direction | Example |
 |------|-----------|-----------|---------|
 | `implements` | Source implements the target | task → feature, code → spec | `task:BDK-002 → feature:BDK-SCHEMA` |
 | `augments` | Source extends or enhances target | extension → base | `module:auth-oauth → module:auth` |
 | `relates-to` | General semantic association | either direction | `concept:zero-trust → adr:001` |
+| `references` | Source explicitly references target | artifact → referenced artifact | `doc:release-notes → issue:180` |
+| `touches` | Source changes or directly touches target | commit → file | `commit:934b6e3 → file:src/auth.js` |
+| `groups` | Source groups or contains target | parent → child | `module:auth → file:src/auth.js` |
 | `blocks` | Source blocks progress on target | blocker → blocked | `task:BDK-001 → task:BDK-002` |
 | `belongs-to` | Source is a child/member of target | child → parent | `feature:BDK-SCHEMA → milestone:BEDROCK` |
 | `consumed-by` | Source is consumed/used by target | resource → consumer | `pkg:chalk → module:format` |
@@ -261,7 +269,7 @@ Applying the same valid import file twice produces identical graph state. The se
 | `Milestone:BEDROCK` | Lowercase prefix | Use `milestone:BEDROCK` — prefix is always lowercase |
 | `my node` | No whitespace | Whitespace is not allowed in node IDs |
 | `commit:abc123` (in import) | System prefix | `commit:` nodes cannot be created via import |
-| `task:A --[explodes]--> task:B` | Known edge type | `explodes` is not one of the 8 valid edge types |
+| `task:A --[explodes]--> task:B` | Known edge type | `explodes` is not one of the 11 valid edge types |
 | `task:X blocks task:X` | Self-edge | `blocks` does not allow self-edges |
 | `confidence: 1.5` | Confidence range | Must be in [0.0, 1.0] |
 | `confidence: NaN` | Finite number | NaN, Infinity, and non-numbers are rejected |
@@ -332,26 +340,26 @@ const NODE_ID = /^[a-z][a-z0-9-]*:[A-Za-z0-9._\/@-]+$/;
 
 ```js
 const CANONICAL_PREFIXES = [
-  'milestone', 'feature', 'task', 'issue', 'phase',
+  'milestone', 'feature', 'task', 'issue', 'pr', 'phase',
   'spec', 'adr', 'doc', 'concept', 'decision',
   'crate', 'module', 'pkg', 'file',
   'person', 'tool',
   'event', 'metric',
-  'commit',
 ];
 ```
 
 ### Edge Type Array
 
 ```js
 const EDGE_TYPES = [
-  'implements', 'augments', 'relates-to', 'blocks',
+  'implements', 'augments', 'relates-to', 'references',
+  'touches', 'groups', 'blocks',
   'belongs-to', 'consumed-by', 'depends-on', 'documents',
 ];
 ```
 
 ### System Prefixes
 
 ```js
-const SYSTEM_PREFIXES = ['commit'];
+const SYSTEM_PREFIXES = ['commit', 'repo', 'epoch'];
 ```

ROADMAP.md

@@ -89,40 +89,56 @@ Before significant work is accepted into an active Hill or supporting lane, we s
 
 If those answers are fuzzy, the work is not ready for planning commitment yet.
 
-## Current Focus: Stabilize And Clarify
+## Current Focus: Hill 1 Semantic Bootstrap
 
 Status:
 
 - in progress
 
+Sponsor user:
+
+- technical lead / staff engineer / architect, or autonomous coding agent, entering an unfamiliar repository
+
+Job to be done:
+
+- quickly produce a trustworthy first-pass semantic map of repository artifacts with minimal manual input
+
 Goal:
 
-- align the product story, sponsor user, backlog shape, and planning model around inference-first semantic repository intelligence
+- deliver the first runnable `git mind bootstrap` flow for unfamiliar repositories
 
 Deliverables:
 
-- 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
+- bootstrap command contract with default write behavior and `--dry-run`
+- repo-local artifact inventory and scan boundaries
+- first-pass entity extraction for files, docs, ADRs, modules, commits, and repo-local issue/PR references
+- first-pass relationship inference for `documents`, `references`, `touches`, `groups`, and conservative `implements`
+- provenance and confidence surfacing for inferred assertions
+- a reviewable follow-up path for weak-confidence bootstrap output
+- implementation issues `#304` through `#307` moved into merged runnable behavior
 
 Exit criteria:
 
-- 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
+- `git mind bootstrap` runs end-to-end on a representative unfamiliar repository
+- the command emits useful human-readable and JSON summary output
+- inferred assertions carry provenance and confidence
+- weak-confidence inferences are visible and reviewable
+- day-one value appears before the user has to hand-author the graph
+
+Primary references:
+
+- [docs/design/git-mind.md](docs/design/git-mind.md)
+- [docs/design/h1-semantic-bootstrap.md](docs/design/h1-semantic-bootstrap.md)
+- issue [#303](https://github.com/flyingrobots/git-mind/issues/303)
+- issues [#304](https://github.com/flyingrobots/git-mind/issues/304), [#305](https://github.com/flyingrobots/git-mind/issues/305), [#306](https://github.com/flyingrobots/git-mind/issues/306), [#307](https://github.com/flyingrobots/git-mind/issues/307)
 
 ---
 
 ## Hill Map
 
 ```mermaid
 flowchart LR
-    C["Current Focus: Stabilize And Clarify"] --> H1["Hill 1: Semantic Bootstrap"]
+    C["Current Focus: Hill 1 Semantic Bootstrap"] --> 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"]
@@ -155,7 +171,7 @@ Suggested first artifact set:
 - markdown docs
 - ADRs
 - commit history
-- issue and review references discoverable from repo artifacts
+- issue, PR, and commit references discoverable from repo artifacts
 
 Playback:
 

docs/README.md

@@ -11,6 +11,7 @@ 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
+- [Hill 1 Semantic Bootstrap Spec](./design/h1-semantic-bootstrap.md) — first executable Hill 1 slice
 - [Git Mind North Star](./VISION_NORTH_STAR.md) — longer-form strategic articulation
 - [ADR-0005](./adr/ADR-0005.md) — official planning and governance model