Skip to content

docs: define Hill 1 semantic bootstrap slice #308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
flyingrobots merged 6 commits into from
Mar 25, 2026
Merged

docs: define Hill 1 semantic bootstrap slice #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
248c33d
docs: define Hill 1 semantic bootstrap slice (#303)
flyingrobots Mar 25, 2026
873fbab
docs: align hill map current focus (#303)
flyingrobots Mar 25, 2026
45914c7
feat: extend bootstrap schema contracts (#303)
flyingrobots Mar 25, 2026
d011b92
docs: align bootstrap spec and roadmap (#303)
flyingrobots Mar 25, 2026
5fcb6ad
docs: address bootstrap review feedback (#303)
flyingrobots Mar 25, 2026
903ca3e
docs: reconcile schema review feedback (#303)
flyingrobots Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions GRAPH_SCHEMA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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` |
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Vague description: epoch: "time-travel" semantics are undefined.

Line 143 describes epoch: as a "System-generated temporal/version marker for time-travel" but never defines:

  • What "time-travel" means in this context
  • How epoch: differs from commit: (both examples use hash-like identifiers)
  • When epoch nodes are created
  • What they represent (snapshots? checkpoints? version boundaries?)

The phrase "epoch/timeline machinery" (line 149) is equally opaque.

Impact:

  • Readers cannot understand the purpose or semantics of epoch nodes
  • Implementers have no guidance on when to create epoch: nodes
  • The spec fails to define this reserved prefix clearly

Expand the description with concrete semantics:

-| `epoch:` | System-generated temporal/version marker for time-travel | `epoch:934b6e3` |
+| `epoch:` | System-generated snapshot marker for graph state at a point in time | `epoch:2026Q1-release` |

And expand line 149:

-- `epoch:` nodes are created automatically by the epoch/timeline machinery and are not authored directly in import files.
+- `epoch:` nodes are created automatically when capturing graph snapshots (e.g., for versioning, rollback, or historical queries) and are not authored directly in import files.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@GRAPH_SCHEMA.md` at line 143, The description of the `epoch:` prefix is too
vague—update the GRAPH_SCHEMA.md entry for `epoch:` to provide concrete
semantics: define "time-travel" as immutable, monotonic version checkpoints
(snapshots) distinct from `commit:` (where `commit:` denotes a specific
change/merge event and `epoch:` denotes broader snapshot boundaries), state when
epoch nodes are created (e.g., on snapshot, release, or compaction events),
explain what they represent (read-only snapshot ID, wall-clock and logical
timestamp, and optional metadata), and give example lifecycle rules for
epoch/timeline machinery (how epochs relate to commits, retention, and lookup).
Also expand the "epoch/timeline machinery" section to list responsibilities
(create/retire epochs, map commits to epochs, query semantics for time-travel
reads) and provide an example showing `epoch:` vs `commit:` usage and canonical
formats (hash + timestamp).


**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:`).
Comment on lines 145 to 150
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check how system prefixes are enforced in import logic

echo "=== Search for commit: validation/rejection logic ==="
rg -n "commit:" src/import.js src/validators.js -B2 -A2

echo -e "\n=== Search for system prefix enforcement ==="
rg -n "SYSTEM_PREFIXES|system.*prefix|classifyPrefix" src/ -B2 -A2 | head -50

echo -e "\n=== Search for hard error conditions ==="
rg -n "hard error|reject.*prefix|system.*reject" src/ -B1 -A1

Repository: flyingrobots/git-mind

Length of output: 2539

Documentation falsely promises system prefix enforcement that doesn't exist in code.

Lines 147-149 claim system prefixes are controlled:

  • commit: nodes are "rejected (hard error)"
  • repo: "should not be introduced ad hoc"
  • epoch: "are not authored directly"

None of this is enforced. The code has zero runtime protection against any of these prefixes appearing in user-authored nodes.

Evidence from src/validators.js:

  • classifyPrefix() (lines 93-96) is a read-only classifier, not an enforcer—it returns classification strings but takes no action
  • Edge validation (lines 186-196) only warns about unknown prefixes; system prefixes are silently accepted
  • The SYSTEM_PREFIXES array (line 27) documents what exists, but no code rejects or errors on them

Result: Users CAN currently create commit:, repo:, and epoch: nodes in import files without any error, warning, or rejection, directly contradicting what the spec promises.

Required: Either enforce the restrictions with actual rejection logic, or remove the false claims from the documentation. Claiming "hard error" and "rejected" while the code accepts them is a contract violation.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@GRAPH_SCHEMA.md` around lines 145 - 150, The docs claim system prefixes
(commit:, repo:, epoch:) are rejected but the code only classifies them; update
src/validators.js to enforce this: in the import/node validation path (where
classifyPrefix() and the edge validation run) detect prefixes that match
SYSTEM_PREFIXES and throw/reject with a clear error (use classifyPrefix() to
identify system prefixes), ensuring user-authored import nodes and edges
containing commit:, repo:, or epoch: produce a hard error; add unit tests for
the import validation path that assert rejection and update any warning-only
branches to raise errors instead of silently accepting these prefixes.


---

## 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` |
Comment on lines +165 to 168
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Semantic overlap: groups and belongs-to are inverse relationships with no disambiguation guidance.

Line 165 defines groups as "Source groups or contains target" (parent → child), while line 167 defines belongs-to as "Source is a child/member of target" (child → parent). These are semantic inverses of the same relationship.

Impact:

  • Users must choose between module:auth --groups--> file:src/auth.js and file:src/auth.js --belongs-to--> module:auth
  • The spec provides zero guidance on which direction to prefer
  • Graph queries will need to check both directions to find containment relationships
  • Inconsistent usage across the codebase will fragment the knowledge graph

Add a guidance note to Section 4 clarifying when to use each direction, or consider deprecating one in favor of the other. For example:

**Directionality note:** `groups` and `belongs-to` are inverse relationships. By convention, use `belongs-to` when authoring manual edges (child → parent), and reserve `groups` for system-generated containment edges (parent → child).
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@GRAPH_SCHEMA.md` around lines 165 - 168, Add a short "Directionality note" to
Section 4 clarifying that `groups` and `belongs-to` are inverse containment
relationships and specify a convention: use `belongs-to` for manually authored
child→parent edges and reserve `groups` for system-generated parent→child
containment edges (or explicitly state deprecation of one if preferred);
reference the symbols `groups` and `belongs-to` and update any examples in the
schema to reflect the convention so authors and queries have a single canonical
direction to rely on.

Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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'];
```
46 changes: 31 additions & 15 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down Expand Up @@ -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:

Expand Down
1 change: 1 addition & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading