-
Notifications
You must be signed in to change notification settings - Fork 1
Add feature profiles and graph data model #323
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.
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
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
34636d3
docs: add feature profile test plans (#322)
flyingrobots c5cf956
docs: define graph data model (#322)
flyingrobots 9b5006c
docs: address graph model review findings (#322)
flyingrobots 71f8601
docs: align upgrade audit completion (#322)
flyingrobots 0380c43
docs: tighten graph system id examples (#322)
flyingrobots File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| # Git Mind Feature Profiles | ||
|
|
||
| Status: draft planning set for issue #322 | ||
|
|
||
| This directory breaks the Git Mind product surface into feature profiles. Each | ||
| profile uses the same IBM Design Thinking frame: | ||
|
|
||
| - sponsor user | ||
| - job to be done | ||
| - relevant Hill or supporting lane | ||
| - user stories | ||
| - requirements | ||
| - graph data model usage | ||
| - playback evidence | ||
| - test plan | ||
|
|
||
| The intent is to keep future implementation work from starting as an | ||
| architecture exercise. A feature is ready to implement only when the profile can | ||
| explain who it helps, what repository-understanding job it improves, and which | ||
| tests prove the claim. | ||
|
|
||
| ## Sponsor User | ||
|
|
||
| The shared sponsor user for this profile set is a technical lead, staff | ||
| engineer, architect, or autonomous coding agent entering an unfamiliar | ||
| repository and needing a trustworthy semantic map quickly. | ||
|
|
||
| ## Product Hills | ||
|
|
||
| - Hill 1: Zero-input semantic bootstrap | ||
| - Hill 2: Queryable answers with receipts | ||
| - Hill 3: Living map with low manual upkeep | ||
|
|
||
| Supporting lanes exist to strengthen those Hills. They are not product centers | ||
| by themselves. | ||
|
|
||
| ## Profile Catalog | ||
|
|
||
| ### Hill 1: Semantic Bootstrap | ||
|
|
||
| - [Bootstrap Command](./bootstrap-command.md) | ||
| - [Repo Fixture Builder](./repo-fixture-builder.md) | ||
| - [Artifact Inventory](./artifact-inventory.md) | ||
| - [Entity Extraction](./entity-extraction.md) | ||
| - [Relationship Inference](./relationship-inference.md) | ||
| - [Provenance And Confidence](./provenance-confidence.md) | ||
| - [Review Refinement](./review-refinement.md) | ||
|
|
||
| ### Hill 2: Queryable Answers With Receipts | ||
|
|
||
| - [Query Receipts](./query-receipts.md) | ||
| - [Views And Lenses](./views-lenses.md) | ||
| - [Time Travel And Semantic Diff](./time-travel-diff.md) | ||
| - [Import Export Interchange](./import-export-interchange.md) | ||
| - [Agent Contracts](./agent-contracts.md) | ||
|
|
||
| ### Hill 3: Living Map With Low Manual Upkeep | ||
|
|
||
| - [Living Map Updates](./living-map-updates.md) | ||
| - [Doctor And Integrity](./doctor-integrity.md) | ||
| - [Trust And Observer Contexts](./trust-observers.md) | ||
|
|
||
| ### Supporting Lanes | ||
|
|
||
| - [Graph Substrate](./graph-substrate.md) | ||
| - [Content On Node](./content-on-node.md) | ||
| - [Extensions Runtime](./extensions-runtime.md) | ||
| - [Packaging And Adoption](./packaging-adoption.md) | ||
|
|
||
| ## Common Test Plan Taxonomy | ||
|
|
||
| Each profile should name tests in these buckets. | ||
|
|
||
| - Fixtures: repository or graph shapes needed to test the feature. | ||
| - Golden path: expected behavior on representative clean inputs. | ||
| - Edge cases: valid but tricky inputs. | ||
| - Known failures: invalid inputs, ambiguity, missing dependencies, or blocked | ||
| features that must fail predictably. | ||
| - Regression cases: bugs or review findings that must not return. | ||
| - Fuzz cases: generated or randomized inputs that probe parser, scanner, or | ||
| graph assumptions. | ||
| - Stress cases: large or deep scenarios that protect performance and memory | ||
| behavior. | ||
| - Golden artifacts: stable snapshots, schema samples, or CLI output contracts | ||
| that can be compared over time. | ||
| - Playback evidence: the human or agent demonstration that proves the Hill | ||
| moved, not just that code ran. | ||
|
|
||
| ## Shared Graph Model | ||
|
|
||
| All feature profiles use the canonical vocabulary in | ||
| [Graph Data Model](../graph-data-model.md). Feature-specific graph sections | ||
| should show: | ||
|
|
||
| - which node prefixes the feature reads or writes | ||
| - which edge types the feature creates, updates, filters, or cites | ||
| - where confidence, provenance, review, or observer metadata enters the model | ||
| - a Mermaid example that a reviewer can compare against the feature's test | ||
| fixtures and golden artifacts | ||
|
|
||
| ## Fixture Strategy | ||
|
|
||
| Repository-shaped behavior should use the canonical fixture strategy: | ||
|
|
||
| 1. fluent repo builder first | ||
| 2. reusable base repos second | ||
| 3. scenario overlays for history, ambiguity, and references | ||
| 4. archived snapshots only when exact Git object state is the subject | ||
|
|
||
| Feature profiles may request new base repos or overlays. They should not | ||
| invent one-off setup patterns unless the risk is truly local to the test. | ||
|
|
||
| ## Implementation Sequencing | ||
|
|
||
| The recommended next implementation sequence remains: | ||
|
|
||
| 1. Bootstrap command contract and JSON output | ||
| 2. Fixture builder support needed by bootstrap tests | ||
| 3. Artifact inventory | ||
| 4. Entity extraction | ||
| 5. Relationship inference | ||
| 6. Provenance and confidence surfacing | ||
| 7. Review refinement and query receipts | ||
|
|
||
| That sequence keeps Hill 1 executable before expanding into richer query and | ||
| living-map work. | ||
|
|
||
| ## Review Rule | ||
|
|
||
| When a feature profile and implementation disagree, update the profile or stop | ||
| the implementation. Silent divergence is product debt. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| # Feature Profile: Agent Contracts | ||
|
|
||
| Status: draft for Hill 2 implementation | ||
|
|
||
| Related: | ||
|
|
||
| - [CLI Contracts](../../contracts/CLI_CONTRACTS.md) | ||
| - [Git Mind Product Frame](../git-mind.md) | ||
|
|
||
| ## IBM Design Thinking Frame | ||
|
|
||
| Sponsor user: | ||
|
|
||
| - An autonomous coding agent operating on repository knowledge. | ||
|
|
||
| Job to be done: | ||
|
|
||
| - When I use Git Mind as a machine-facing contract boundary, give me stable | ||
| commands, schemas, error behavior, and receipts I can trust. | ||
|
|
||
| Hill: | ||
|
|
||
| - Hill 2: Queryable answers with receipts. | ||
|
|
||
| Playback evidence: | ||
|
|
||
| - An agent can call Git Mind commands, parse JSON responses, handle typed | ||
| errors, and cite receipts without prompt-specific guesswork. | ||
|
|
||
| ## User Stories | ||
|
|
||
| - As an agent, I can request JSON for every read-oriented command. | ||
| - As an agent, I can validate responses against schemas. | ||
| - As an agent, I can tell no-answer, low-confidence answer, and command failure | ||
| apart. | ||
| - As a maintainer, I can detect contract drift in CI. | ||
|
|
||
| ## Requirements | ||
|
|
||
| ### Functional | ||
|
|
||
| - Every machine-facing JSON output must include `schemaVersion`. | ||
| - CLI commands must have predictable exit codes and typed error envelopes. | ||
| - Schemas must exist for stable command families. | ||
| - Contract tests must exercise representative command output. | ||
| - Agent-facing docs must state which commands are stable, transitional, or | ||
| experimental. | ||
|
|
||
| ### Non-Functional | ||
|
|
||
| - Contracts must be deterministic. | ||
| - Breaking changes require versioning. | ||
| - Human formatting changes must not break JSON contracts. | ||
|
|
||
| ## Graph Data Model Usage | ||
|
|
||
| Agent contracts expose [Graph Data Model](../graph-data-model.md) through | ||
| machine-readable payloads. Agents should receive canonical node IDs, edge | ||
| types, confidence, evidence, and graph refs rather than prose-only context. | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| Agent["tool:codex"] -->|references| Contract["spec:agent-answer-contract"] | ||
| Contract -->|documents| Query["feature:query-receipts"] | ||
| Answer["doc:answer-json"] -->|references| Node["module:bootstrap"] | ||
| Answer -->|references| Evidence["doc:h1-semantic-bootstrap"] | ||
| ``` | ||
|
|
||
| ## Test Plan | ||
|
|
||
| Fixtures: | ||
|
|
||
| - `contract-canary-repo` | ||
| - `no-answer-repo` | ||
| - `invalid-command-repo` | ||
| - `large-output-repo` | ||
|
|
||
| Golden path: | ||
|
|
||
| - JSON outputs validate against schemas. | ||
| - Error outputs distinguish usage, validation, graph, and environment failures. | ||
| - Contract canaries cover status, nodes, views, export, import, review, diff, | ||
| content, and future query responses. | ||
|
|
||
| Edge cases: | ||
|
|
||
| - Empty graph. | ||
| - Large graph. | ||
| - No-answer query. | ||
| - Low-confidence answers. | ||
| - Observer/trust-filtered contexts. | ||
|
|
||
| Known failures: | ||
|
|
||
| - Missing `schemaVersion` fails CI. | ||
| - Unknown JSON field policy is explicit. | ||
| - Invalid command args return typed error. | ||
|
|
||
| Fuzz: | ||
|
|
||
| - Generate valid and invalid command arguments. | ||
| - Generate schema-valid and schema-invalid payloads. | ||
| - Generate random graph state and validate JSON stability. | ||
|
|
||
| Stress: | ||
|
|
||
| - Large JSON output with bounded memory. | ||
| - Repeated command invocation from clean environment. | ||
| - Parallel command reads. | ||
|
|
||
| Regression: | ||
|
|
||
| - Contract snapshots remain stable. | ||
| - Error taxonomy does not collapse into generic failures. | ||
| - JSON mode never prints decorative human text. | ||
|
|
||
| Golden artifacts: | ||
|
|
||
| - JSON schema files. | ||
| - Golden command outputs. | ||
| - Error envelope snapshots. | ||
|
|
||
| Playback: | ||
|
|
||
| - A coding agent can use Git Mind as a deterministic repo-knowledge API instead | ||
| of relying on fragile prompt context. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.