Skip to content

Add feature profiles and graph data model#323

Merged
flyingrobots merged 5 commits into
mainfrom
docs/feature-profiles-test-plans
Jun 1, 2026
Merged

Add feature profiles and graph data model#323
flyingrobots merged 5 commits into
mainfrom
docs/feature-profiles-test-plans

Conversation

@flyingrobots

@flyingrobots flyingrobots commented Jun 1, 2026

Copy link
Copy Markdown
Owner

PR Title

Add feature profiles and graph data model

Summary

  • Adds a feature-profile documentation set for the Git Mind product surface.
  • Defines the canonical product graph data model: node prefixes, edge directions, assertion properties, confidence bands, and core graph patterns.
  • Adds Graph Data Model Usage sections with Mermaid examples to every feature profile.
  • Updates canonical navigation in README, ROADMAP, docs index, H1 semantic bootstrap spec, and GRAPH_SCHEMA cross-reference.

Problem Statement

Git Mind has a mature graph substrate but needs sharper product-facing specifications before the next implementation wave. This PR turns the current product direction into reviewable design artifacts with explicit IBM Design Thinking framing, playback evidence, graph vocabulary, and test expectations.

ADR Compliance (Required)

Relevant ADR(s)

  • ADR-0002 (Worktree Independence and Materialization Architecture)
  • ADR-0003 (Graph-Native Content, Deterministic Materialization, and Workspace Bridge)
  • None

Compliance Declaration

  • This PR is fully compliant with all checked ADRs.
  • This PR intentionally deviates from one or more checked ADRs (complete Exception Request below).

Exception Request (Required if deviating)

  • ADR clause(s) deviated from: None.
  • Why deviation is necessary now: No deviation.
  • Risk introduced by deviation: None.
  • Mitigation and rollback plan: Revert this docs-only PR if needed.
  • Follow-up ADR/issue to reconcile architecture debt: None.

Architecture Laws Checklist (Hard Gates)

Canonical Truth & Context

  • Graph remains canonical truth (no dual truth with generated files).
  • No hidden worktree coupling introduced in core/domain/materialization paths.
  • Context-sensitive behavior is explicit (--at, --observer, --trust) or deterministically defaulted.
  • Resolved context is surfaced in output metadata where applicable.

Determinism & Provenance

  • Pure query/materialization paths remain deterministic for identical inputs.
  • Mutations/materializations include provenance receipts/envelopes where required.
  • Cache keys (if used) are derived only from semantic inputs + pinned versions.

Artifact Hygiene

  • No forbidden generated artifact paths are tracked.
  • Any generated artifacts intentionally tracked are in allowlisted publish paths only.
  • Pre-commit/CI policy checks updated or confirmed valid.

Contracts & Compatibility

  • Machine-facing outputs are schema-versioned.
  • Breaking contract changes include version bump + migration notes.
  • Backward compatibility impact is documented below.

Extension/Effects Safety (if applicable)

  • Extension behavior does not bypass capability restrictions.
  • Effectful operations use explicit plan/apply semantics and emit receipts.
  • Timeouts/resource bounds are defined for new script/effect paths.

Scope Control

  • PR is single-purpose/cohesive (no unrelated refactors).
  • Any non-essential refactor is split into separate PR(s) or explicitly justified.

Backward Compatibility

  • CLI/API contract changes: None.
  • Data model/storage changes: None. The new graph data model is design guidance only; runtime validators are unchanged.
  • Migration required?: No.
  • User-facing behavior changes: Documentation only; no runtime behavior changes.

Test Plan (Required)

Unit

  • Added/updated tests for changed logic
  • Commands:
# Not run; docs-only change with no runtime logic changes.

Integration

  • Added/updated integration tests
  • Commands:
# Not run; docs-only change with no integration behavior changes.

Determinism

  • Determinism assertions included for relevant paths
  • Method: one-off docs audit verifies links, feature-profile section structure, exactly one graph-model section per profile, and Mermaid presence.
  • Commands:
node --input-type=module <<'NODE'
// Local docs audit over README.md, ROADMAP.md, GRAPH_SCHEMA.md,
// docs/README.md, docs/design/graph-data-model.md,
// docs/design/h1-semantic-bootstrap.md, and every feature profile.
// Checks: local links exist, required feature-profile sections exist,
// exactly one Graph Data Model Usage section per profile, and at least one
// Mermaid block per profile.
NODE

Contract/Schema

  • Schema validation updated/passing
  • Commands:
# Not applicable; no machine schema changed.

Policy Gates

  • Mechanical architecture gates pass
  • Commands:
git diff --check
npm run lint
node --input-type=module <<'NODE'
// Rendered every Mermaid block in docs/design/graph-data-model.md and all
// feature profiles through mmdc. Result: validated 24 Mermaid block(s).
NODE

Security / Trust Impact

  • Threat surface changed?: No.
  • Trust policy impact: None.
  • Provenance/audit impact: Documentation clarifies future graph assertion, provenance, confidence, review, and observer expectations; no runtime change.
  • New failure modes introduced: None.

Performance Impact

  • Hot path affected?: No.
  • Expected impact (latency/memory/io): None.
  • Benchmarks or profiling evidence: Not applicable for docs-only change.

Observability / Debuggability

  • Errors are actionable and include context.
  • Logs/diagnostics added or updated where needed.
  • git mind status / diagnostics updated if writeback/eventing behavior changed.

Operational Notes

  • Feature flag (if any): None.
  • Rollback strategy: Revert the docs commits.
  • Operational caveats: None.

Linked Issues / Milestones


Reviewer Quick Verdict Block (for maintainers)

MUST (Hard Gates)

* PASS

SHOULD (Quality)

* PASS

Verdict

* APPROVE

@coderabbitai

coderabbitai Bot commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 29 minutes and 15 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 115a00b9-02f0-47dc-8e3f-60e3670d28af

📥 Commits

Reviewing files that changed from the base of the PR and between ce1509a and 0380c43.

📒 Files selected for processing (28)
  • GRAPH_SCHEMA.md
  • README.md
  • ROADMAP.md
  • docs/README.md
  • docs/design/feature-profiles/README.md
  • docs/design/feature-profiles/agent-contracts.md
  • docs/design/feature-profiles/artifact-inventory.md
  • docs/design/feature-profiles/bootstrap-command.md
  • docs/design/feature-profiles/content-on-node.md
  • docs/design/feature-profiles/doctor-integrity.md
  • docs/design/feature-profiles/entity-extraction.md
  • docs/design/feature-profiles/extensions-runtime.md
  • docs/design/feature-profiles/graph-substrate.md
  • docs/design/feature-profiles/import-export-interchange.md
  • docs/design/feature-profiles/living-map-updates.md
  • docs/design/feature-profiles/packaging-adoption.md
  • docs/design/feature-profiles/provenance-confidence.md
  • docs/design/feature-profiles/query-receipts.md
  • docs/design/feature-profiles/relationship-inference.md
  • docs/design/feature-profiles/repo-fixture-builder.md
  • docs/design/feature-profiles/review-refinement.md
  • docs/design/feature-profiles/time-travel-diff.md
  • docs/design/feature-profiles/trust-observers.md
  • docs/design/feature-profiles/views-lenses.md
  • docs/design/git-warp-upgrade-audit.md
  • docs/design/graph-data-model.md
  • docs/design/h1-semantic-bootstrap.md
  • test/design-docs.test.js

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@flyingrobots flyingrobots changed the title Add feature profile test plans Add feature profiles and graph data model Jun 1, 2026
@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex Self-Code Review findings for PR #323.

ID Severity File:Line(s) Type Finding Recommended agent prompt
CL-001 P2 High docs/design/feature-profiles/query-receipts.md:96, GRAPH_SCHEMA.md:251-255 Contract ambiguity Query Receipts requires “receipt edge IDs,” but the current graph contract identifies edges by (source, target, type) tuple and the new graph data model does not introduce a stable edge ID. This will either make the test plan unimplementable or force a later implementation to invent ad hoc receipt IDs outside the model. Update the graph data model and Query Receipts profile to define receipt identity explicitly. Either use (source, target, type) as the canonical assertion key everywhere, or introduce a deliberate edgeId/assertion-id contract with schema/test implications. Then replace “receipt edge IDs” wording and update Mermaid/examples accordingly.
CL-002 P2 High docs/design/graph-data-model.md:63-65, docs/design/graph-data-model.md:200-207, docs/design/feature-profiles/import-export-interchange.md:65-67, docs/design/feature-profiles/doctor-integrity.md:63-66 Model contradiction The canonical model repeatedly reifies edge assertions as ordinary Mermaid nodes (Edge assertion, EdgeA, Edge) even though the documented graph vocabulary has no canonical edge:/assertion node type. This directly undercuts the document’s rule that features must not invent a second graph vocabulary. Remove pseudo-edge nodes from graph examples or add an explicit assertion identity model. Rewrite examples so receipts cite canonical tuple keys/properties, not unlabeled synthetic nodes, unless the PR intentionally adds a canonical assertion-node prefix and explains how it coexists with current WARP edges.
CL-003 P3 Medium docs/design/graph-data-model.md:135, docs/design/graph-data-model.md:63-65, docs/design/graph-data-model.md:210-217 Edge semantics misuse documents is defined as “explainer -> subject,” but the examples use decision: nodes as documents sources for an assertion/spec. A review decision is not a documentation artifact under this model; this teaches the wrong edge direction/type in the canonical model doc. Rewrite review-decision diagrams to use references from decision: to the affected source/target/spec and document decision metadata as node properties. Reserve documents for doc:/adr:/spec: style explainer artifacts unless the model explicitly broadens the edge semantics.
CL-004 P3 Medium GRAPH_SCHEMA.md:138-150, docs/design/graph-data-model.md:87-97, docs/design/feature-profiles/entity-extraction.md:26-29, docs/design/feature-profiles/entity-extraction.md:96-101 Schema/model mismatch commit: and epoch: are reserved system-generated prefixes in the schema, but the new graph data model lists them as normal artifact nodes and the Entity Extraction profile says bootstrap produces commit: nodes. Without a stated writer boundary, implementers can easily build import/manual flows that conflict with reserved-prefix rules. Add a “system-owned nodes” subsection to the graph data model. State that commit:/epoch: may only be created by Git Mind system writers, not YAML/frontmatter/manual import, and update Entity Extraction tests to assert both allowed bootstrap/system creation and import rejection.
CL-005 P4 Low docs/design/feature-profiles/entity-extraction.md:76-83, docs/design/feature-profiles/views-lenses.md:62-68 Diagram style / graph vocabulary The new Graph Data Model Usage sections include unlabeled Mermaid arrows (-->) even though the model says edges are directed typed assertions. In graph-model sections, unlabeled arrows read as untyped graph edges and weaken the canonical edge vocabulary. Replace unlabeled arrows in graph-model examples with canonical edge labels (references, documents, groups, etc.) or explicitly caption those diagrams as pre-graph extraction mappings rather than graph data model examples.
CL-006 P4 Low ROADMAP.md:127-136; gh issue view 312 reports issue #312 closed on 2026-03-27 and #320 closed on 2026-06-01 Planning accuracy The current Hill 1 deliverables still list the git-warp audit/upgrade cycle as future/current work even though the upgrade path has already landed and the related issues are closed. For a roadmap updated by this PR, this is stale planning state. Update the roadmap to separate completed enabling work from remaining Hill 1 deliverables. Mark the git-warp audit/upgrade as completed, reference #312/#320 as closed evidence, and leave only active bootstrap work in the current deliverables list.
CL-007 P5 Nit GRAPH_SCHEMA.md:9, docs/README.md:16, docs/design/graph-data-model.md:106, docs/design/graph-data-model.md:137-138, docs/design/graph-data-model.md:143 Markdown style New lines exceed 120 characters, and several are table rows in a new canonical document. This is not currently enforced by repo CI, but the branch is creating long-lived design docs and the style debt is avoidable. Wrap the added prose lines and consider replacing the widest graph-model tables with definition lists or narrower tables so canonical docs stay readable in terminal review.

Summary: 7 issues found (P2: 2, P3: 2, P4: 2, P5: 1). No P0/P1 runtime blockers found; the branch is docs-only, but the graph model should be corrected before it becomes the implementation contract.

@chatgpt-codex-connector

Copy link
Copy Markdown

Summary

Commit / PR

Testing

  • git diff --check
  • npm run lint
  • node --input-type=module local docs link audit / review wording checks
  • ⚠️ npm test failed in this environment with widespread Git command failed with code 128 failures and one Vitest hook timeout; the change set is docs-only and did not modify runtime code.

View task →

@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex Code Lawyer re-audit findings for PR #323.

ID Severity File:Line(s) Type Finding Recommended agent prompt
CL-008 P3 Medium docs/design/git-warp-upgrade-audit.md:3-5, docs/design/git-warp-upgrade-audit.md:52-70 Planning accuracy / stale contract This PR updates ROADMAP.md and docs/README.md to treat issues #312/#320 as completed enabling work, but the linked audit document still says the v17 continuation is active and describes git-warp 17 as the next upgrade. That makes the canonical docs disagree about whether the dependency modernization is done or pending. Update the git-warp upgrade audit document to mark the v17 continuation completed, record the installed substrate versions, keep the historical v14 context explicitly historical, and add a regression check so docs cannot simultaneously call the audit completed and active.
CL-009 P4 Low docs/design/graph-data-model.md:311-314, docs/design/feature-profiles/time-travel-diff.md:63-66, docs/design/feature-profiles/graph-substrate.md:68 Graph-model example drift The graph model now correctly says commit: and epoch: are system-owned, but some examples still use abstract IDs such as epoch:before, epoch:after, and commit:graph-patch. That weakens the writer-boundary rule and teaches implementers to invent system-owned IDs manually. Replace abstract system-owned example IDs with concrete SHA/ref-shaped examples or non-system feature/task nodes where appropriate. Add a docs regression check that rejects abstract commit:/epoch: examples in the canonical graph model and feature profiles.

Summary: 2 new issues found in this re-audit (P3: 1, P4: 1). No unresolved GitHub review threads were present; these are self-discovered issues from origin/main...HEAD plus linked canonical-doc consistency checks.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9b5006c387

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/README.md
Comment thread docs/design/graph-data-model.md Outdated
@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex Activity Summary for PR #323 Code Lawyer re-audit.

ID Severity Source File Commit Outcome
CL-008 P3 Medium Self docs/design/git-warp-upgrade-audit.md, test/design-docs.test.js 71f8601 Added a docs-integrity regression and updated the git-warp upgrade audit to record the completed #320/#321 v17 outcome and installed substrate versions.
CL-009 P4 Low Self docs/design/graph-data-model.md, docs/design/feature-profiles/time-travel-diff.md, docs/design/feature-profiles/graph-substrate.md, test/design-docs.test.js 0380c43 Added a docs-integrity regression rejecting abstract commit:/epoch: IDs in graph examples and replaced the offending examples with SHA-shaped system IDs.

Verification:

Check Result
git diff --check origin/main...HEAD Pass
npm run lint Pass
npm test Pass: 33 files, 602 tests
Docs link/feature-profile/graph anti-pattern audit Pass: 27 docs, 19 feature profiles
Mermaid render audit Pass: 25 blocks
npm run test:upgrade-fixture Pass: isolated Docker fixture, 128 nodes, 227 edges

Unresolved GitHub review threads: 0.

@chatgpt-codex-connector

Copy link
Copy Markdown

Summary

Testing

  • ⚠️ git diff --check origin/main...HEAD && npm run lint && npm test failed immediately because this local checkout has no origin/main ref.
  • ⚠️ git diff --check HEAD && npm run lint && npm test passed diff-check and lint, then failed in npm test with existing widespread Git command failed with code 128 failures plus one Vitest hook timeout.
  • npx vitest run test/design-docs.test.js

View task →

@flyingrobots flyingrobots merged commit 6aeec3b into main Jun 1, 2026
8 checks passed
@flyingrobots flyingrobots deleted the docs/feature-profiles-test-plans branch June 1, 2026 05:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add feature profiles and test plans for Git Mind product surface

1 participant