From 248c33dfa2b3d18914e2c7a1d13b5e9b1db41a23 Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 24 Mar 2026 22:29:33 -0700 Subject: [PATCH 1/6] docs: define Hill 1 semantic bootstrap slice (#303) --- ROADMAP.md | 32 +-- docs/README.md | 1 + docs/design/h1-semantic-bootstrap.md | 282 +++++++++++++++++++++++++++ 3 files changed, 302 insertions(+), 13 deletions(-) create mode 100644 docs/design/h1-semantic-bootstrap.md diff --git a/ROADMAP.md b/ROADMAP.md index 3a50d35..b6da463 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -89,7 +89,7 @@ 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: @@ -97,24 +97,30 @@ Status: Goal: -- align the product story, sponsor user, backlog shape, and planning model around inference-first semantic repository intelligence +- define and implement the first low-input semantic bootstrap slice 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 +- canonical Hill 1 bootstrap spec +- repo-local artifact inventory model +- first-pass entity extraction +- first-pass relationship inference +- provenance and confidence model for inferred assertions +- bootstrap command / output contract +- follow-on implementation issues cut directly from the accepted spec 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 has a concrete first-slice spec for unfamiliar-repo bootstrap +- the backlog contains direct Hill 1 implementation work, not only supporting work +- the first slice is narrow enough to build without falling back into platform sprawl +- playback evidence is defined before implementation begins + +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) --- diff --git a/docs/README.md b/docs/README.md index bea8e42..1a6ed46 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md new file mode 100644 index 0000000..cf6cd85 --- /dev/null +++ b/docs/design/h1-semantic-bootstrap.md @@ -0,0 +1,282 @@ +# Hill 1 Semantic Bootstrap Spec + +Status: draft for execution + +Related: + +- [Git Mind Product Frame](./git-mind.md) +- [ROADMAP.md](../../ROADMAP.md) +- [ADR-0005](../adr/ADR-0005.md) +- issue [#303](https://github.com/flyingrobots/git-mind/issues/303) + +## Purpose + +Define the first executable slice of Hill 1: + +> point `git-mind` at an unfamiliar repository and get an immediately useful semantic map with low manual input. + +This document turns the Hill into a concrete engineering target so implementation work can be scoped against one coherent first slice instead of spreading across packaging, content, and hardening work without a visible product center. + +## Sponsor User + +- A technical lead, staff engineer, architect, or autonomous coding agent dropped into an unfamiliar repository who needs a trustworthy mental model quickly. + +## Job To Be Done + +- When I point `git-mind` at a repository, help me understand how its code, docs, ADRs, and recent changes relate without making me manually author the graph first. + +## Playback Standard + +The first slice succeeds if, on a representative unfamiliar repository: + +1. Git Mind produces a useful first semantic map before the user feels like they are doing graph data entry. +2. At least a small set of inferred relationships are surfaced with visible provenance and confidence. +3. The user can answer a few repository-understanding questions faster than they could with filenames, grep, and commit browsing alone. +4. The system is obviously incomplete, but already worth using. + +## First-Slice Scope + +This first slice is intentionally narrow. + +It should define and implement: + +- the first repo-local artifact set +- the first extracted entity types +- the first inferred relationship types +- the first provenance receipt shape for inferred assertions +- the first confidence model +- the first user-visible bootstrap commands / outputs + +It should not try to solve: + +- hosted issue tracker ingestion +- PR API ingestion +- autonomous reflection loops +- broad ontology design +- multi-repo graphing +- content authoring UX +- extension ecosystems + +## Artifact Set: v0 Bootstrap Inputs + +The first slice should operate only on repo-local inputs that are already present in a checked-out repository: + +1. Repository file tree +2. Source files +3. Markdown documentation +4. ADR markdown files +5. Git commit history +6. Repo-local textual references to issues / PRs / commits + +This keeps the first slice: + +- local-first +- deterministic +- reproducible in CI +- usable on any repo without needing external API setup + +## Entity Types: v0 + +The bootstrap should extract or synthesize the following first-pass entities: + +- `file:` for source files and key project files +- `doc:` for general markdown documents +- `adr:` for ADR documents +- `module:` for inferred modules or packages where structure is obvious +- `commit:` for recent relevant commits already supported by the substrate +- `issue:` only when referenced in repo-local artifacts +- `pr:` only when referenced in repo-local artifacts + +Notes: + +- `module:` should be conservative in v0. +- If module inference is weak, file-level output is preferable to a fake module abstraction. +- `issue:` and `pr:` are placeholder semantic nodes backed by repo-local references, not API-enriched tracker records yet. + +## Relationship Types: v0 + +The first slice should infer only a small, legible set of relationship types: + +1. `documents` + - doc/adr describes or explains a file/module/path + +2. `references` + - artifact explicitly references another artifact or ticket/PR/commit + +3. `touches` + - commit changes a file + +4. `groups` + - module groups file(s) when structure is obvious + +5. `implements` + - only when evidence is strong enough from explicit textual cues or durable repo conventions + +Non-goal: + +- Do not infer a large taxonomy in the first slice. +- A small number of understandable relationships is better than broad weak semantics. + +## Provenance Model: v0 + +Every inferred relationship should carry a provenance payload that answers: + +- what artifact(s) produced the assertion? +- what extraction rule produced it? +- what text span, path match, or commit evidence supports it? + +Minimum provenance fields: + +- `sourceKind` +- `sourceRef` +- `extractor` +- `evidence` +- `inferredAt` + +Examples: + +- markdown frontmatter path match +- explicit mention of `src/auth.js` in `docs/auth.md` +- ADR title or filename convention +- commit touching a file +- textual mention of `#123` in a changelog or ADR + +## Confidence Model: v0 + +Confidence should be deliberately simple and inspectable. + +Suggested bands: + +- `high` + - explicit structured evidence + - exact path / identifier match + - explicit frontmatter or strong convention + +- `medium` + - strong lexical evidence + - unambiguous file/doc references + +- `low` + - fuzzy heuristic association + - similarity-based guesses that are not yet reviewed + +Rules: + +- high-confidence edges may be shown directly in bootstrap output +- low-confidence edges should be clearly marked and easy to filter +- confidence should be rule-based in v0, not ML-derived + +## User Surface: v0 + +The first slice should introduce one clear bootstrap flow. + +Suggested command shape: + +```bash +git mind bootstrap +``` + +Possible compatible aliases later: + +- `git mind analyze` +- `git mind ingest` + +But the first slice should pick one and make it real. + +The command should: + +1. scan the repo-local artifact set +2. infer first-pass entities and relationships +3. persist them into the graph +4. emit a summary of what was found +5. point the user at a follow-up inspection flow + +Example follow-up flows: + +```bash +git mind status +git mind view architecture +git mind nodes --prefix doc +git mind review +``` + +## Bootstrap Output Requirements + +At minimum, `git mind bootstrap` should report: + +- artifacts scanned +- entities created +- inferred relationships created +- relationship counts by type +- confidence counts +- notable weak-confidence suggestions + +JSON output should include machine-readable counts and summary structure. + +## Day-One Questions + +This first slice should materially help with at least these five questions: + +1. What docs or ADRs appear to explain this area of the repo? +2. What files or modules seem central to this part of the project? +3. What recent commits touched the artifacts I care about? +4. What issue / PR references are embedded in the repo’s own artifacts? +5. Where are the obvious weakly connected or undocumented parts of the repo? + +## Out of Scope For First Slice + +Do not expand the first slice into: + +- hosted GitHub / Jira / Linear ingestion +- semantic embeddings +- AI summarization +- fully automated query answering +- review workflow redesign +- extension/plugin APIs +- authored content UX +- cross-repo merge / federation work + +If a feature does not improve the first unfamiliar-repo bootstrap experience, it does not belong in the first slice. + +## Implementation Slices + +This spec suggests the following sequence: + +### Slice A: Bootstrap Command Contract + +- define CLI contract for `git mind bootstrap` +- define summary output and JSON shape +- define dry-run / write behavior if needed + +### Slice B: Repo-Local Artifact Inventory + +- discover and classify candidate source files, docs, ADRs, and key project files +- define repo scanning boundaries and defaults + +### Slice C: First-Pass Entity Extraction + +- create `file:`, `doc:`, `adr:`, and conservative `module:` nodes + +### Slice D: First-Pass Relationship Inference + +- infer `documents`, `references`, `touches`, `groups` +- add conservative `implements` only where evidence is strong + +### Slice E: Provenance + Confidence Surfacing + +- attach provenance metadata +- attach rule-based confidence +- expose summary and weak-confidence review path + +## Exit Criteria + +This spec is complete when: + +1. the first-slice artifact/entity/relationship set is accepted +2. the bootstrap command surface is defined +3. provenance/confidence rules are explicit enough to implement +4. follow-on implementation issues can be created directly from the slices above + +## Decision Rule + +If a tradeoff is unclear, choose the option that makes the first unfamiliar-repo bootstrap more useful, more inspectable, and less dependent on manual graph authoring. From 873fbab85853b4afa2f4fd9ddc64fae8f93b55ab Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 24 Mar 2026 23:05:26 -0700 Subject: [PATCH 2/6] docs: align hill map current focus (#303) --- ROADMAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ROADMAP.md b/ROADMAP.md index b6da463..46440d6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -128,7 +128,7 @@ Primary references: ```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"] From 45914c788ba608da1ec5481e61534777fc22d15e Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 24 Mar 2026 23:18:31 -0700 Subject: [PATCH 3/6] feat: extend bootstrap schema contracts (#303) --- src/validators.js | 5 ++++- test/edges.test.js | 5 ++++- test/validators.test.js | 10 ++++++---- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/src/validators.js b/src/validators.js index 223ea00..1d5b608 100644 --- a/src/validators.js +++ b/src/validators.js @@ -16,7 +16,7 @@ export const NODE_ID_MAX_LENGTH = 256; /** @type {string[]} User-facing canonical prefixes (excludes system prefixes) */ export 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', @@ -31,6 +31,9 @@ export const EDGE_TYPES = [ 'implements', 'augments', 'relates-to', + 'references', + 'touches', + 'groups', 'blocks', 'belongs-to', 'consumed-by', diff --git a/test/edges.test.js b/test/edges.test.js index 5fac1c6..543eccf 100644 --- a/test/edges.test.js +++ b/test/edges.test.js @@ -24,8 +24,11 @@ describe('edges', () => { expect(EDGE_TYPES).toContain('implements'); expect(EDGE_TYPES).toContain('augments'); expect(EDGE_TYPES).toContain('relates-to'); + expect(EDGE_TYPES).toContain('references'); + expect(EDGE_TYPES).toContain('touches'); + expect(EDGE_TYPES).toContain('groups'); expect(EDGE_TYPES).toContain('depends-on'); - expect(EDGE_TYPES.length).toBe(8); + expect(EDGE_TYPES.length).toBe(11); }); it('createEdge creates an edge and both nodes', async () => { diff --git a/test/validators.test.js b/test/validators.test.js index 596ec09..afe8252 100644 --- a/test/validators.test.js +++ b/test/validators.test.js @@ -110,6 +110,7 @@ describe('classifyPrefix', () => { it('classifies canonical prefixes', () => { expect(classifyPrefix('milestone')).toBe('canonical'); expect(classifyPrefix('task')).toBe('canonical'); + expect(classifyPrefix('pr')).toBe('canonical'); expect(classifyPrefix('file')).toBe('canonical'); }); @@ -263,9 +264,10 @@ describe('constants', () => { expect(NODE_ID_MAX_LENGTH).toBe(256); }); - it('CANONICAL_PREFIXES has 18 user-facing entries', () => { - expect(CANONICAL_PREFIXES.length).toBe(18); + it('CANONICAL_PREFIXES has 19 user-facing entries', () => { + expect(CANONICAL_PREFIXES.length).toBe(19); expect(CANONICAL_PREFIXES).toContain('milestone'); + expect(CANONICAL_PREFIXES).toContain('pr'); expect(CANONICAL_PREFIXES).not.toContain('commit'); }); @@ -280,7 +282,7 @@ describe('constants', () => { expect(ALL_PREFIXES).toContain('commit'); }); - it('EDGE_TYPES has 8 entries', () => { - expect(EDGE_TYPES.length).toBe(8); + it('EDGE_TYPES has 11 entries', () => { + expect(EDGE_TYPES.length).toBe(11); }); }); From d011b924c519da48903a948a4c2bc91d8279e6c3 Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 24 Mar 2026 23:18:39 -0700 Subject: [PATCH 4/6] docs: align bootstrap spec and roadmap (#303) --- GRAPH_SCHEMA.md | 14 +++++++++----- ROADMAP.md | 28 +++++++++++++++------------- docs/design/h1-semantic-bootstrap.md | 10 ++++++++-- 3 files changed, 32 insertions(+), 20 deletions(-) diff --git a/GRAPH_SCHEMA.md b/GRAPH_SCHEMA.md index 72945ed..b9df89c 100644 --- a/GRAPH_SCHEMA.md +++ b/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 @@ -148,13 +149,16 @@ Node prefixes are grouped into five categories. **Unknown prefixes produce a war ## 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` | @@ -332,12 +336,11 @@ 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', ]; ``` @@ -345,7 +348,8 @@ const CANONICAL_PREFIXES = [ ```js const EDGE_TYPES = [ - 'implements', 'augments', 'relates-to', 'blocks', + 'implements', 'augments', 'relates-to', 'references', + 'touches', 'groups', 'blocks', 'belongs-to', 'consumed-by', 'depends-on', 'documents', ]; ``` @@ -353,5 +357,5 @@ const EDGE_TYPES = [ ### System Prefixes ```js -const SYSTEM_PREFIXES = ['commit']; +const SYSTEM_PREFIXES = ['commit', 'repo', 'epoch']; ``` diff --git a/ROADMAP.md b/ROADMAP.md index 46440d6..12320d7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -97,30 +97,32 @@ Status: Goal: -- define and implement the first low-input semantic bootstrap slice for unfamiliar repositories +- deliver the first runnable `git mind bootstrap` flow for unfamiliar repositories Deliverables: -- canonical Hill 1 bootstrap spec -- repo-local artifact inventory model -- first-pass entity extraction -- first-pass relationship inference -- provenance and confidence model for inferred assertions -- bootstrap command / output contract -- follow-on implementation issues cut directly from the accepted spec +- 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: -- Git Mind has a concrete first-slice spec for unfamiliar-repo bootstrap -- the backlog contains direct Hill 1 implementation work, not only supporting work -- the first slice is narrow enough to build without falling back into platform sprawl -- playback evidence is defined before implementation begins +- `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) --- @@ -161,7 +163,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: diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md index cf6cd85..6863547 100644 --- a/docs/design/h1-semantic-bootstrap.md +++ b/docs/design/h1-semantic-bootstrap.md @@ -183,11 +183,17 @@ Possible compatible aliases later: But the first slice should pick one and make it real. +Command contract: + +- `git mind bootstrap` should persist inferred entities and relationships into the graph by default. +- `git mind bootstrap --dry-run` should run the same scan and inference path, emit the same summary structure, and avoid writing to the graph. +- low-confidence inferred relationships should still be written in default mode with confidence and provenance attached so they can flow into review rather than disappearing into a preview-only side channel. + The command should: 1. scan the repo-local artifact set 2. infer first-pass entities and relationships -3. persist them into the graph +3. persist them into the graph by default 4. emit a summary of what was found 5. point the user at a follow-up inspection flow @@ -246,7 +252,7 @@ This spec suggests the following sequence: - define CLI contract for `git mind bootstrap` - define summary output and JSON shape -- define dry-run / write behavior if needed +- define default write behavior and `--dry-run` preview contract ### Slice B: Repo-Local Artifact Inventory From 5fcb6ad22c53c6a71cf817ec13284724a032c0c5 Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 24 Mar 2026 23:45:56 -0700 Subject: [PATCH 5/6] docs: address bootstrap review feedback (#303) --- ROADMAP.md | 8 ++++++++ docs/design/h1-semantic-bootstrap.md | 6 ++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 12320d7..7752986 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -95,6 +95,14 @@ 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: - deliver the first runnable `git mind bootstrap` flow for unfamiliar repositories diff --git a/docs/design/h1-semantic-bootstrap.md b/docs/design/h1-semantic-bootstrap.md index 6863547..1e06f53 100644 --- a/docs/design/h1-semantic-bootstrap.md +++ b/docs/design/h1-semantic-bootstrap.md @@ -80,7 +80,7 @@ This keeps the first slice: The bootstrap should extract or synthesize the following first-pass entities: - `file:` for source files and key project files -- `doc:` for general markdown documents +- `doc:` for general Markdown documents - `adr:` for ADR documents - `module:` for inferred modules or packages where structure is obvious - `commit:` for recent relevant commits already supported by the substrate @@ -135,7 +135,7 @@ Minimum provenance fields: Examples: -- markdown frontmatter path match +- Markdown frontmatter path match - explicit mention of `src/auth.js` in `docs/auth.md` - ADR title or filename convention - commit touching a file @@ -176,6 +176,8 @@ Suggested command shape: git mind bootstrap ``` +> Status: planned contract for Hill 1. This command is not implemented in the current CLI yet. + Possible compatible aliases later: - `git mind analyze` From 903ca3eaddb7b260a1f10980f3492ef1247d4aee Mon Sep 17 00:00:00 2001 From: James Ross Date: Wed, 25 Mar 2026 00:45:54 -0700 Subject: [PATCH 6/6] docs: reconcile schema review feedback (#303) --- GRAPH_SCHEMA.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/GRAPH_SCHEMA.md b/GRAPH_SCHEMA.md index b9df89c..b055cf4 100644 --- a/GRAPH_SCHEMA.md +++ b/GRAPH_SCHEMA.md @@ -139,10 +139,14 @@ 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:`). --- @@ -265,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 |