diff --git a/AGENTS.md b/AGENTS.md index 14f9b20..2a41b63 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ Do not audit the repository by recursively walking the filesystem. Follow the au - **`docs/design/`**: Active and landed cycle design documents. ### 4. The Proof -- **`docs/CHANGELOG.md`**: Historical truth of merged behavior. +- **`CHANGELOG.md`**: Historical truth of merged behavior. - **`docs/audit/`**: Structural health and due diligence reports. ## Context Recovery Protocol diff --git a/CHANGELOG.md b/CHANGELOG.md index 2affef4..d55a36b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/). ## [Unreleased] +## [0.8.0] - 2026-05-06 + ### Added - **Top-level structural review CLI**: `graft review --base diff --git a/NORTHSTAR.md b/NORTHSTAR.md new file mode 100644 index 0000000..bc777ac --- /dev/null +++ b/NORTHSTAR.md @@ -0,0 +1,269 @@ +# NORTHSTAR + +Graft is the structural reading layer for codebases moving through witnessed +causal history. + +Its job is to answer code questions with evidence: + +- what changed structurally +- which symbols, references, tests, files, and review claims are implicated +- which basis the answer was read from +- which witness, receipt, shell, or retained artifact supports the answer +- what is stale, partial, plural, budget-limited, rights-limited, obstructed, + or unavailable + +The durable promise is: + +```text +Graft turns witnessed causal history into code-aware, machine-readable +structural readings. +``` + +## The Bet + +Agentic software work will not be governed by bigger context windows or larger +file dumps. It needs lawful readings: bounded, reproducible, basis-aware +answers that explain enough code structure for the next action without +pretending to expose a god's-eye repository state. + +Graft exists because code agents need more than text access: + +- They need policy-governed reads that refuse or degrade unsafe material. +- They need structural maps instead of raw-file flooding. +- They need review evidence that names support instead of vibes. +- They need symbol and reference continuity across commits, worktrees, and live + editor frontiers. +- They need machine-readable outputs that can be consumed without scraping + prose. +- They need honest residuals when the system cannot see, cannot afford, or + cannot lawfully reveal the full answer. + +The repository is not just a bag of files. It is a moving causal medium: +commits, working tree overlays, agent reads, staged transitions, test evidence, +review claims, editor buffers, speculative lanes, and runtime receipts. + +Graft's north star is to make that medium legible for code. + +## Stack Position + +Continuum's rule is Graft's rule too: + +```text +There is no privileged graph. +There is witnessed causal history, and graph-like structure is an +observer-relative reading over that history. +``` + +Graft must therefore stop treating any one materialized graph, cache, runtime, +or host projection as the primary ontology. The shared boundary is witnessed +causal history plus the Continuum-authored contract families that make that +history admissible, observable, exportable, and importable. + +The stack split is: + +| Layer | Owner | Responsibility | +| :--- | :--- | :--- | +| Shared semantics | Continuum | Shared contract families, witness language, admission and compatibility nouns, registry truth. | +| Compilation | Wesley | Generated artifacts, manifests, codecs, bundle identity, TTD surfaces, and witness tooling. | +| Hot runtime | Echo | Low-latency admission, observation, retained readings, receipts, replay, and live/frontier runtime machinery. | +| Cold runtime | `git-warp` | Git-backed, committed-history runtime implementation and durable structural history adapter. | +| Debugger/operator surface | `warp-ttd` | Wide-aperture navigation through lanes, frames, receipts, effects, sessions, delivery observations, and counterfactuals. | +| Structural intelligence | Graft | Code-aware readings, review truth, symbol/reference history, structural test signals, provenance hints, and agent-facing context governance. | + +Echo and `git-warp` are sibling Continuum runtime implementations. Neither is +the real graph. Neither is the subordinate half of the other. Runtime posture +can differ: hot, cold, browser-hosted, archival, offline-first, editor-native, +Git-backed. Shared meaning must still cross the Continuum boundary through +authored families and witnessed artifacts. + +## What Graft Owns + +Graft owns the code-aware observer layer: + +- policy-governed reads and explicit refusals +- structural outlines, diffs, and projections +- symbol, reference, rename, and removed-symbol evidence +- structural review summaries and review-readiness signals +- structural test-reference signals +- repository-local provenance hints for agent and human workflows +- Graft-local structural payloads until another repo needs the same semantics +- API, CLI, and MCP surfaces for consuming these readings + +Graft's native noun is the structural reading. + +A structural reading is not "the graph." It is an observer-relative, +basis-aware code artifact with enough support metadata for a human, agent, API +consumer, CLI caller, MCP client, or debugger view to understand what claim is +being made and what still remains unknown. + +## What Graft Must Not Become + +Graft must not become: + +- a runtime implementation competing with Echo or `git-warp` +- the semantic owner of Continuum shared families +- a hidden graph database API +- a debugger product replacing `warp-ttd` +- a permanent hand-normalization layer for incompatible host stories +- a prose-only review assistant whose claims cannot be inspected +- an agent context firehose + +When a structural payload is Graft-specific, Graft may own it locally. When the +same payload becomes shared across repos or runtimes, it should graduate into +Continuum through the normal family promotion path and be compiled by Wesley. + +## The Reading Contract + +Every serious Graft reading should converge on the same posture, even when the +surface differs between API, CLI, MCP, or debugger display. + +A reading should name: + +- **basis**: the commit, ref, lane, editor head, runtime coordinate, or witness + shell it was derived from +- **aperture**: the bounded scope of the question +- **request identity**: the observation question being answered +- **reading kind**: review summary, symbol history, reference map, test signal, + file outline, diff projection, provenance hint, or other structural payload +- **freshness**: current, stale, incomparable, unknown, or live-frontier +- **residual posture**: complete, partial, plural, budget-limited, + rights-limited, unavailable, obstructed, or intentionally degraded +- **support**: witness, receipt, shell, retained artifact, provenance payload, + or explicit absence of support +- **payload identity**: digest, version, schema, or generated artifact id +- **typed payload**: the actual Graft-owned structural answer + +That shape is what lets an agent consume Graft without guessing the basis, +scraping prose, or confusing an observer-side projection with canonical runtime +truth. + +## Integration Story + +The long-term path is: + +```text +Continuum shared family + -> Wesley-generated artifacts + -> Echo or git-warp runtime publication + -> ObservationRequest / ObserverPlan + -> ReadingEnvelope-backed runtime result + -> Graft structural payload + -> API / CLI / MCP / warp-ttd presentation +``` + +In practice: + +- `git-warp` remains the right adapter for cold, Git-backed committed history. +- Echo becomes the right adapter for hot, live, frontier-oriented histories. +- Continuum owns shared runtime-boundary nouns such as `ObserverPlan`, + `ObservationRequest`, `ReadingEnvelope`, `WitnessedSuffixShell`, + `CausalSuffixBundle`, and `ImportOutcome`. +- Wesley-generated artifacts replace shadow schemas and hand-normalized DTOs + where the boundary is shared. +- Graft owns the code-aware structural payload at the edge of the reading. +- `warp-ttd` may display Graft readings as observer artifacts, but should not + become the long-term owner of code-review meaning. + +The key relationship: + +```text +warp-ttd explains what happened in the causal runtime. +Graft explains what it means for the code. +``` + +Those views should meet over witnessed readings, not by forcing the debugger to +learn every Graft-specific code noun or forcing Graft to become a debugger. + +## Product Target + +Graft should be able to answer, through any official surface: + +- What structural fact is true at this basis? +- What changed, and why does that matter for code? +- Which symbols, references, tests, or review claims are implicated? +- Which witness, receipt, shell, or retained artifact supports the claim? +- Is the result current, stale, partial, plural, budget-limited, + rights-limited, obstructed, or unavailable? +- Can an agent act on the result without reading unrelated files? +- Can a human inspect the same claim without reconstructing hidden state? +- Can `warp-ttd` show the same reading as an artifact of causal observation + without owning the structural-review engine? + +The ideal outcome is not that every caller gets the same bytes. The ideal +outcome is that every caller gets the same truth posture. + +## Boundary Laws + +1. Graft must not treat any materialized graph as the primary ontology. +2. Graft must keep runtime admission, observation, import, export, and + settlement concerns behind explicit ports. +3. Graft must not mutate Echo state directly. +4. Graft must not make `warp-ttd` carry permanent host-normalization or + structural-review debt. +5. Graft must not re-author Continuum-owned shared nouns locally. +6. Graft may own app/tool-local structural payloads until a second repo needs + the same semantics. +7. Shared structural payloads should graduate to Continuum only when promotion + reduces drift rather than freezing confusion. +8. API, CLI, MCP, and debugger presentation should expose the same + structural-reading posture through their own appropriate contracts. +9. Observer-side summaries must not be presented as canonical runtime + admission unless the runtime actually admitted that collapse and can name + the corresponding support. +10. Every degraded or refused answer must say why. + +## Migration Principle + +The near-term move is not "rip out git-warp" or "make Graft call Echo +directly." + +The move is: + +```text +git-warp-shaped implementation + -> substrate-neutral structural reading port + -> git-warp adapter behind the port + -> Continuum runtime-boundary fixtures + -> Echo/live-frontier adapter + -> generated shared artifacts where the family is no longer Graft-local +``` + +This keeps the current Review Truth behavior shippable while making the next +architecture honest. + +## Near-Term Path + +1. Ship `v0.8.0` as the final git-warp-first Review Truth release. +2. Introduce a substrate-neutral structural reading port in Graft. +3. Keep the existing git-warp committed-history implementation behind that + port. +4. Add fixture-backed Continuum runtime-boundary coverage for `ObserverPlan`, + `ObservationRequest`, and `ReadingEnvelope`. +5. Prove one Echo or `jedit` live-frontier structural reading. +6. Shape Graft-owned structural payloads so they can be wrapped in + `ReadingEnvelope` posture without making Continuum own premature app nouns. +7. Let `warp-ttd` display Graft structural readings as observer artifacts, not + debugger-native facts. +8. Promote only the structural payloads that truly need cross-repo meaning into + Continuum. + +The first concrete post-`v0.8.0` slice is: + +- [CORE_continuum-structural-reading-port](./docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md) + +## Success State + +We know the north star is becoming real when these things are boring: + +- A PR review over committed Git history and a live editor reading over Echo + both return evidence-bearing structural readings. +- API, CLI, and MCP callers receive the same basis, freshness, residual, + support, and payload identity posture. +- `warp-ttd` can show a Graft structural reading alongside runtime receipts + without hand-normalizing host-specific stories. +- Continuum owns the shared families; Wesley generates the artifacts; runtimes + emit and admit witnessed history; Graft reads code meaning from that history. +- No one has to ask which graph is real. + +The answer is always: the graph is a chart. The work is witnessed causal +history. Graft makes the code chart useful. diff --git a/README.md b/README.md index 551017e..ed66752 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,7 @@ daemon control-plane posture. ## Documentation +- **[North Star](./NORTHSTAR.md)**: Long-term stack position and Continuum-shaped structural reading direction. - **[Guide](./GUIDE.md)**: Orientation, the fast path, and agent bootstrap. - **[Setup Guide](./docs/SETUP.md)**: Client-specific MCP setup, daemon posture, and workspace binding. - **[Advanced Guide](./ADVANCED_GUIDE.md)**: Deep dives into the pipeline, worldlines, and daemon mechanics. diff --git a/docs/BEARING.md b/docs/BEARING.md index 5272ab7..69266f9 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -61,25 +61,22 @@ publish guards. ## Next Target -The immediate focus is **v0.8.0 scope formation**, not feature work. +The immediate focus is **v0.8.0 release prep**, not more feature work. 1. Keep `main` release-clean after `v0.7.1`. -2. Shape `v0.8.0` around **Review Truth**: structural PR review - summaries, bounded provenance hints, symbol history, - removed-symbol evidence, structural test-reference signals, - automated review readiness, and local feedback-resolution evidence - that apply to any Git repository. -3. Do not add METHOD-specific backlog/status features to Graft. METHOD +2. Land `v0.8.0` as a **Review Truth** release: structural PR review + summaries, bounded provenance hints, symbol history, removed-symbol + evidence, structural test-reference signals, automated review + readiness, and the first language-breadth stack for Rust, GraphQL, + Python, Go, JSON, TOML, and YAML. +3. Treat remaining `docs/method/backlog/v0.8.0/` cards as follow-up + candidates unless release validation exposes a direct blocker. +4. Do not add METHOD-specific backlog/status features to Graft. METHOD backlog lanes, cards, retros, dependency DAGs, and release truth surfaces belong in Method MCP / Method CLI. -4. Treat `CORE_graft-doctor` as shipped baseline, not the next active - card to reopen. New doctor work needs a narrow follow-up card. 5. Keep `WARP_lsp-enrichment` and `CORE_migrate-to-slice-first-reads` - out of the opening v0.8.0 lane. LSP enrichment remains valid - optional scope; slice-first reads remain externally blocked until - git-warp observer geometry APIs land. + out of this release. LSP enrichment remains valid optional scope; + slice-first reads remain externally blocked until git-warp observer + geometry APIs land. 6. Treat daemon live refresh and daemon control-plane actions as a - separate daemon-operator lane, not the default v0.8.0 spine. -7. Use `docs/method/backlog/v0.8.0/` as the current scope lane, with - `CORE_pr-review-structural-summary` as the opening spine and the - two core hardening cards as release-quality gates. + separate daemon-operator lane, not part of the v0.8.0 cut. diff --git a/docs/method/backlog/dependency-dag.dot b/docs/method/backlog/dependency-dag.dot index a3715aa..baa7fa2 100644 --- a/docs/method/backlog/dependency-dag.dot +++ b/docs/method/backlog/dependency-dag.dot @@ -10,6 +10,12 @@ digraph backlog { ranksep=0.55 nodesep=0.2 + subgraph cluster_up_next { + label="up-next (1)" labeljust=l fontsize=9 fontcolor="#555555" + style=rounded color="#cccccc" bgcolor="#fafafa" + up_next_CORE_continuum_structural_reading_port [label="CORE-continuum-structural-reading-port - L" fillcolor="#E5E7EB" penwidth=2] + } + subgraph cluster_v0_8_0 { label="v0.8.0 (26)" labeljust=l fontsize=9 fontcolor="#555555" style=rounded color="#cccccc" bgcolor="#fafafa" diff --git a/docs/method/backlog/dependency-dag.svg b/docs/method/backlog/dependency-dag.svg index 1943e54..24b29f6 100644 --- a/docs/method/backlog/dependency-dag.svg +++ b/docs/method/backlog/dependency-dag.svg @@ -4,793 +4,804 @@ - + backlog - -Active backlog graph generated from docs/method/backlog/*/*.md + +Active backlog graph generated from docs/method/backlog/*/*.md -cluster_v0_8_0 - -v0.8.0 (26) +cluster_up_next + +up-next (1) -cluster_cool_ideas - -Cool Ideas (74) +cluster_v0_8_0 + +v0.8.0 (26) -cluster_external - -External blockers +cluster_cool_ideas + +Cool Ideas (74) -cluster_unresolved - -Unresolved internal refs +cluster_external + +External blockers +cluster_unresolved + +Unresolved internal refs + + cluster_legend - -Legend + +Legend - + +up_next_CORE_continuum_structural_reading_port + +CORE-continuum-structural-reading-port - L + + + v0_8_0_CORE_c_structural_parsing - -CORE-c-structural-parsing - M + +CORE-c-structural-parsing - M - + v0_8_0_CORE_cpp_structural_parsing - -CORE-cpp-structural-parsing - L + +CORE-cpp-structural-parsing - L - + v0_8_0_CORE_csharp_structural_parsing - -CORE-csharp-structural-parsing - M + +CORE-csharp-structural-parsing - M - + v0_8_0_CORE_go_structural_parsing - -CORE-go-structural-parsing - S + +CORE-go-structural-parsing - S - + v0_8_0_CORE_hcl_structured_config - -CORE-hcl-structured-config - M + +CORE-hcl-structured-config - M - + v0_8_0_CORE_java_structural_parsing - -CORE-java-structural-parsing - M + +CORE-java-structural-parsing - M - + v0_8_0_CORE_json_structured_config - -CORE-json-structured-config - S + +CORE-json-structured-config - S - + v0_8_0_CORE_jupyter_notebook_structure - -CORE-jupyter-notebook-structure - M + +CORE-jupyter-notebook-structure - M - + v0_8_0_CORE_kotlin_structural_parsing - -CORE-kotlin-structural-parsing - M + +CORE-kotlin-structural-parsing - M - + v0_8_0_CORE_php_structural_parsing - -CORE-php-structural-parsing - M + +CORE-php-structural-parsing - M - + v0_8_0_CORE_pr_review_structural_summary - -CORE-pr-review-structural-summary - M + +CORE-pr-review-structural-summary - M - + v0_8_0_CORE_python_structural_parsing - -CORE-python-structural-parsing - S + +CORE-python-structural-parsing - S - + v0_8_0_CORE_ruby_structural_parsing - -CORE-ruby-structural-parsing - M + +CORE-ruby-structural-parsing - M - + v0_8_0_CORE_shell_structural_parsing - -CORE-shell-structural-parsing - M + +CORE-shell-structural-parsing - M - + v0_8_0_CORE_sql_structural_parsing - -CORE-sql-structural-parsing - M + +CORE-sql-structural-parsing - M - + v0_8_0_CORE_structural_test_coverage_map - -CORE-structural-test-coverage-map - M + +CORE-structural-test-coverage-map - M - + v0_8_0_CORE_swift_structural_parsing - -CORE-swift-structural-parsing - M + +CORE-swift-structural-parsing - M - + v0_8_0_CORE_toml_structured_config - -CORE-toml-structured-config - S + +CORE-toml-structured-config - S - + v0_8_0_CORE_tool_context_injection_contracts - -CORE-tool-context-injection-contracts - M + +CORE-tool-context-injection-contracts - M - + v0_8_0_CORE_yaml_structured_config - -CORE-yaml-structured-config - M + +CORE-yaml-structured-config - M - + v0_8_0_SURFACE_git_graft_enhance_provenance_hints - -SURFACE-git-graft-enhance-provenance-hints + +SURFACE-git-graft-enhance-provenance-hints - + v0_8_0_SURFACE_pr_feedback_resolution_ledger - -SURFACE-pr-feedback-resolution-ledger - M + +SURFACE-pr-feedback-resolution-ledger - M - + v0_8_0_SURFACE_review_cooldown_status - -SURFACE-review-cooldown-status - S + +SURFACE-review-cooldown-status - S - + v0_8_0_TEST_bounded_subprocess_policy - -TEST-bounded-subprocess-policy - S + +TEST-bounded-subprocess-policy - S - + v0_8_0_WARP_dead_symbol_detection - -WARP-dead-symbol-detection - S + +WARP-dead-symbol-detection - S - + v0_8_0_WARP_symbol_history_timeline - -WARP-symbol-history-timeline - S + +WARP-symbol-history-timeline - S - + cool_ideas_WARP_temporal_structural_search - -WARP-temporal-structural-search - M + +WARP-temporal-structural-search - M v0_8_0_WARP_symbol_history_timeline->cool_ideas_WARP_temporal_structural_search - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_bounded_neighborhood_for_references - -bounded-neighborhood-for-references - S + +bounded-neighborhood-for-references - S - + cool_ideas_CI_001_causal_collapse_visualizer - -CI-001-causal-collapse-visualizer - L + +CI-001-causal-collapse-visualizer - L - + cool_ideas_CI_002_deterministic_scenario_replay - -CI-002-deterministic-scenario-replay - L + +CI-002-deterministic-scenario-replay - L - + cool_ideas_CI_003_mcp_native_diff_protocol - -CI-003-mcp-native-diff-protocol - M + +CI-003-mcp-native-diff-protocol - M - + cool_ideas_CLEAN_CODE_parallel_agent_merge_shared_file_loss - -CLEAN-CODE-parallel-agent-merge-shared-file-loss - M + +CLEAN-CODE-parallel-agent-merge-shared-file-loss - M - + cool_ideas_CORE_agent_handoff_protocol - -CORE-agent-handoff-protocol - M + +CORE-agent-handoff-protocol - M - + cool_ideas_CORE_auto_focus - -CORE-auto-focus - L + +CORE-auto-focus - L - + cool_ideas_CORE_capture_range - -CORE-capture-range - S + +CORE-capture-range - S - + cool_ideas_CORE_constructor_in_disguise_lint - -CORE-constructor-in-disguise-lint - M + +CORE-constructor-in-disguise-lint - M - + cool_ideas_CORE_context_budget_forecasting - -CORE-context-budget-forecasting - M + +CORE-context-budget-forecasting - M - + cool_ideas_CORE_conversation_primer - -CORE-conversation-primer - M + +CORE-conversation-primer - M - + cool_ideas_CORE_cross_session_resume - -CORE-cross-session-resume - S + +CORE-cross-session-resume - S - + cool_ideas_CORE_graft_as_teacher - -CORE-graft-as-teacher - S + +CORE-graft-as-teacher - S - + cool_ideas_CORE_graft_teach_learning_receipts - -CORE-graft-teach-learning-receipts - S + +CORE-graft-teach-learning-receipts - S - + cool_ideas_CORE_graft_tool_client - -CORE-graft-tool-client - M + +CORE-graft-tool-client - M - + cool_ideas_CORE_horizon_of_readability - -CORE-horizon-of-readability - M + +CORE-horizon-of-readability - M - + cool_ideas_CORE_lagrangian_policy - -CORE-lagrangian-policy - XL + +CORE-lagrangian-policy - XL - + cool_ideas_CORE_migrate_to_slice_first_reads - -CORE-migrate-to-slice-first-reads + +CORE-migrate-to-slice-first-reads - + cool_ideas_CORE_multi_agent_conflict_detection - -CORE-multi-agent-conflict-detection - L + +CORE-multi-agent-conflict-detection - L - + cool_ideas_CORE_policy_playground - -CORE-policy-playground - S + +CORE-policy-playground - S - + cool_ideas_CORE_policy_profiles - -CORE-policy-profiles - M + +CORE-policy-profiles - M - + cool_ideas_CORE_self_tuning_governor - -CORE-self-tuning-governor - M + +CORE-self-tuning-governor - M - + cool_ideas_CORE_session_knowledge_map - -CORE-session-knowledge-map - S + +CORE-session-knowledge-map - S - + cool_ideas_CORE_speculative_read_cost - -CORE-speculative-read-cost - S + +CORE-speculative-read-cost - S - + cool_ideas_CORE_structural_session_replay - -CORE-structural-session-replay - M + +CORE-structural-session-replay - M - + cool_ideas_CORE_wire_primitives_into_runtime - -CORE-wire-primitives-into-runtime - M + +CORE-wire-primitives-into-runtime - M - + cool_ideas_monitor_tick_ceiling_tracking - -monitor-tick-ceiling-tracking - S + +monitor-tick-ceiling-tracking - S - + cool_ideas_WARP_background_indexing - -WARP-background-indexing - M + +WARP-background-indexing - M cool_ideas_monitor_tick_ceiling_tracking->cool_ideas_WARP_background_indexing - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_SURFACE_active_causal_workspace_status - -SURFACE-active-causal-workspace-status - M + +SURFACE-active-causal-workspace-status - M - + cool_ideas_SURFACE_ide_native_graft_integration - -SURFACE-ide-native-graft-integration - XL + +SURFACE-ide-native-graft-integration - XL cool_ideas_SURFACE_active_causal_workspace_status->cool_ideas_SURFACE_ide_native_graft_integration - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_SURFACE_attach_to_existing_causal_session - -SURFACE-attach-to-existing-causal-session - M + +SURFACE-attach-to-existing-causal-session - M - + cool_ideas_SURFACE_bijou_daemon_control_plane_actions - -SURFACE-bijou-daemon-control-plane-actions - L + +SURFACE-bijou-daemon-control-plane-actions - L - + cool_ideas_SURFACE_bijou_daemon_status_live_refresh - -SURFACE-bijou-daemon-status-live-refresh - M + +SURFACE-bijou-daemon-status-live-refresh - M - + cool_ideas_SURFACE_git_graft_enhance_expanded_git_subcommands - -SURFACE-git-graft-enhance-expanded-git-subcommands + +SURFACE-git-graft-enhance-expanded-git-subcommands - + cool_ideas_SURFACE_graft_review_pr_number_adapter - -SURFACE-graft-review-pr-number-adapter - M + +SURFACE-graft-review-pr-number-adapter - M - + cool_ideas_SURFACE_init_dry_run - -SURFACE-init-dry-run - S + +SURFACE-init-dry-run - S - + cool_ideas_SURFACE_local_history_dag_render_mode_and_count_legend - -SURFACE-local-history-dag-render-mode-and-count-legend - S + +SURFACE-local-history-dag-render-mode-and-count-legend - S - + cool_ideas_SURFACE_non_codex_instruction_bootstrap_parity - -SURFACE-non-codex-instruction-bootstrap-parity - M + +SURFACE-non-codex-instruction-bootstrap-parity - M - + cool_ideas_SURFACE_offer_rename_refactor - -SURFACE-offer-rename-refactor - L + +SURFACE-offer-rename-refactor - L - + cool_ideas_SURFACE_terminal_activity_browser_tui - -SURFACE-terminal-activity-browser-tui - L + +SURFACE-terminal-activity-browser-tui - L - + cool_ideas_traverse_plus_query_hydration_helper - -traverse-plus-query-hydration-helper - S + +traverse-plus-query-hydration-helper - S - + cool_ideas_WARP_adaptive_projection_selection - -WARP-adaptive-projection-selection - L + +WARP-adaptive-projection-selection - L - + cool_ideas_WARP_agent_action_provenance - -WARP-agent-action-provenance - XL + +WARP-agent-action-provenance - XL cool_ideas_WARP_agent_action_provenance->cool_ideas_CI_001_causal_collapse_visualizer - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_causal_write_tracking - -WARP-causal-write-tracking - L + +WARP-causal-write-tracking - L cool_ideas_WARP_agent_action_provenance->cool_ideas_WARP_causal_write_tracking - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_intent_and_decision_events - -WARP-intent-and-decision-events - M + +WARP-intent-and-decision-events - M cool_ideas_WARP_agent_action_provenance->cool_ideas_WARP_intent_and_decision_events - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_provenance_dag - -WARP-provenance-dag - L + +WARP-provenance-dag - L cool_ideas_WARP_agent_action_provenance->cool_ideas_WARP_provenance_dag - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_auto_breaking_change_detection - -WARP-auto-breaking-change-detection - L + +WARP-auto-breaking-change-detection - L - + cool_ideas_WARP_budget_elasticity - -WARP-budget-elasticity - M + +WARP-budget-elasticity - M - + cool_ideas_WARP_causal_blame_for_staged_artifacts - -WARP-causal-blame-for-staged-artifacts - L + +WARP-causal-blame-for-staged-artifacts - L - + cool_ideas_WARP_codebase_entropy_trajectory - -WARP-codebase-entropy-trajectory - M + +WARP-codebase-entropy-trajectory - M - + cool_ideas_WARP_counterfactual_refactoring - -WARP-counterfactual-refactoring - XL + +WARP-counterfactual-refactoring - XL cool_ideas_WARP_codebase_entropy_trajectory->cool_ideas_WARP_counterfactual_refactoring - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_codebase_signature - -WARP-codebase-signature - L + +WARP-codebase-signature - L - + cool_ideas_WARP_structural_impact_prediction - -WARP-structural-impact-prediction - XL + +WARP-structural-impact-prediction - XL cool_ideas_WARP_counterfactual_refactoring->cool_ideas_WARP_structural_impact_prediction - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_degeneracy_warning - -WARP-degeneracy-warning - M + +WARP-degeneracy-warning - M - + cool_ideas_WARP_drift_sentinel - -WARP-drift-sentinel - M + +WARP-drift-sentinel - M - + cool_ideas_WARP_footprint_parallelism - -WARP-footprint-parallelism - XL + +WARP-footprint-parallelism - XL - + cool_ideas_WARP_graft_pack - -WARP-graft-pack - M + +WARP-graft-pack - M - + cool_ideas_WARP_grouped_aggregate_queries - -WARP-grouped-aggregate-queries - M + +WARP-grouped-aggregate-queries - M - + cool_ideas_WARP_intentional_degeneracy_privacy - -WARP-intentional-degeneracy-privacy - M + +WARP-intentional-degeneracy-privacy - M - + cool_ideas_WARP_minimum_viable_context - -WARP-minimum-viable-context - M + +WARP-minimum-viable-context - M - + cool_ideas_WARP_outline_diff_commit_trailer - -WARP-outline-diff-commit-trailer - S + +WARP-outline-diff-commit-trailer - S - + cool_ideas_WARP_projection_safety_classes - -WARP-projection-safety-classes - M + +WARP-projection-safety-classes - M cool_ideas_WARP_provenance_dag->cool_ideas_WARP_causal_blame_for_staged_artifacts - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_reasoning_trace_replay - -WARP-reasoning-trace-replay - M + +WARP-reasoning-trace-replay - M cool_ideas_WARP_provenance_dag->cool_ideas_WARP_reasoning_trace_replay - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_rulial_heat_map - -WARP-rulial-heat-map - L + +WARP-rulial-heat-map - L - + cool_ideas_WARP_semantic_drift_in_sessions - -WARP-semantic-drift-in-sessions - M + +WARP-semantic-drift-in-sessions - M - + cool_ideas_WARP_semantic_merge_conflict_prediction - -WARP-semantic-merge-conflict-prediction - L + +WARP-semantic-merge-conflict-prediction - L - + cool_ideas_WARP_session_filtration - -WARP-session-filtration - L + +WARP-session-filtration - L - + cool_ideas_WARP_shadow_structural_workspaces - -WARP-shadow-structural-workspaces - XL + +WARP-shadow-structural-workspaces - XL - + cool_ideas_WARP_speculative_merge - -WARP-speculative-merge - XL + +WARP-speculative-merge - XL - + cool_ideas_WARP_stale_docs_checker - -WARP-stale-docs-checker - M + +WARP-stale-docs-checker - M cool_ideas_WARP_stale_docs_checker->cool_ideas_WARP_drift_sentinel - - -blocked_by/blocking + + +blocked_by/blocking - + cool_ideas_WARP_structural_drift_detection - -WARP-structural-drift-detection - M + +WARP-structural-drift-detection - M - + cool_ideas_WARP_symbol_heatmap - -WARP-symbol-heatmap - M + +WARP-symbol-heatmap - M - + cool_ideas_WARP_technical_debt_curvature - -WARP-technical-debt-curvature - L + +WARP-technical-debt-curvature - L - + external_git_warp_observer_geometry_ladder__Rung_2_4_ - -git-warp observer geometry ladder (Rung 2-4) + +git-warp observer geometry ladder (Rung 2-4) external_git_warp_observer_geometry_ladder__Rung_2_4_->cool_ideas_CORE_migrate_to_slice_first_reads - - -blocked_by_external + + +blocked_by_external - + unresolved_CLEAN_CODE_export_diff_semver_signature_as_patch - -missing: CLEAN_CODE_export-diff-semver-signature-as-patch + +missing: CLEAN_CODE_export-diff-semver-signature-as-patch unresolved_CLEAN_CODE_export_diff_semver_signature_as_patch->cool_ideas_WARP_auto_breaking_change_detection - - -blocked_by + + +blocked_by unresolved_CLEAN_CODE_export_diff_semver_signature_as_patch->cool_ideas_WARP_semantic_merge_conflict_prediction - - -blocked_by + + +blocked_by - + leg_v08 - -v0.8.0 + +v0.8.0 - + leg_v07 - -v0.7.0 + +v0.7.0 - + leg_bad - -bad-code + +bad-code - + leg_idea - -cool-ideas + +cool-ideas - + leg_external - -external blocker + +external blocker - + leg_unresolved - -unresolved ref + +unresolved ref diff --git a/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md b/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md new file mode 100644 index 0000000..6d87607 --- /dev/null +++ b/docs/method/backlog/up-next/CORE_continuum-structural-reading-port.md @@ -0,0 +1,131 @@ +--- +title: "Continuum structural reading port" +feature: core +kind: architecture +legend: CORE +lane: up-next +priority: 1 +effort: L +requirements: + - "v0.8.0 Review Truth release branch remains release-focused" + - "Continuum runtime-boundary family: ObserverPlan, ObservationRequest, ReadingEnvelope, WitnessedSuffixShell, CausalSuffixBundle, ImportOutcome" + - "Existing Graft WARP/git-warp review, symbol-history, dead-symbol, provenance-hint, and structural-test-reference surfaces" + - "Existing API / CLI / MCP capability posture" +acceptance_criteria: + - "Graft exposes one substrate-neutral structural reading port that does not import Echo, git-warp, or warp-ttd concrete runtime types" + - "The existing git-warp-backed committed-history implementation sits behind that port without changing v0.8.0 review behavior" + - "At least one fixture-backed Continuum runtime-boundary reading drives a Graft structural projection test" + - "Structural reading results name basis, freshness, residual posture, witness or shell reference, and payload identity" + - "The design names Graft's proposed Continuum registry role without making Graft the semantic owner of shared families" +--- + +# Continuum structural reading port + +## Hill + +Make Graft's structural memory boundary Continuum-shaped instead of +`git-warp`-shaped. + +By the end of this slice, Graft should have one explicit structural reading +port that can support the current cold committed-history implementation while +preparing for Echo/live-frontier readings through Continuum-authored boundary +families. + +## Why + +Graft's `v0.8.0` Review Truth release proves useful structural review behavior: + +- structural PR summaries +- structural test-reference signals +- provenance hints +- symbol history +- dead-symbol evidence +- broader language/config parsing + +The implementation is still mostly shaped around `git-warp` as the durable +structural substrate. That is useful for cold Git history, but it creates +pressure when Graft needs to reason about hot editor frontiers, Echo-backed +contract heads, jedit buffers, speculative lanes, and cross-runtime suffix +exchange. + +The stack direction is now clearer: + +- Continuum owns shared contract families and witness language. +- Wesley compiles those families into generated artifacts. +- Echo and `git-warp` are sibling runtime implementations. +- `warp-ttd` is the debugger/operator surface. +- Graft is the structural-code observer and review engine. + +Graft should therefore consume and emit structural readings over witnessed +causal history, not treat a materialized graph as the primary ontology. + +## Proposed Continuum role + +This is the role Graft should propose for Continuum's repo role matrix: + +| Repo | Registry role | Must not become | +| :--- | :--- | :--- | +| Graft | Structural observer and review engine; consumes runtime-boundary, receipt, settlement, neighborhood, and observer families; produces code-aware structural reading payloads. | A runtime implementation, debugger product, shadow Continuum semantic owner, or permanent host-normalization layer. | + +Graft-local structural payloads may remain Graft-owned until a second repo needs +the same interchange semantics. If a structural payload family becomes shared +across tools, promote it into Continuum through the normal family promotion +rules instead of copying local DTOs. + +## Expected shape + +The first port should describe Graft's needs, not a generic graph database: + +- source/basis identity +- observation request identity +- structural reading kind +- current/stale/incomparable freshness +- complete/partial/plural/budget-limited/rights-limited/unavailable posture +- witness, receipt, shell, or hologram reference when present +- payload digest or identity +- typed payload for Graft-owned structural facts + +The current git-warp-backed implementation should become one adapter: + +```text +Graft review / symbol history / dead symbols / test references + -> StructuralReadingPort + -> git-warp committed-history adapter +``` + +A future Echo/live-frontier implementation should become another adapter: + +```text +Graft live frontier structural projection + -> StructuralReadingPort + -> Continuum runtime-boundary family + -> Echo or jedit head/frontier basis +``` + +`warp-ttd` should consume Graft structural readings as observer artifacts. It +should not become the long-term place where Graft-specific code meaning is +hand-normalized against Echo and `git-warp`. + +## Implementation path + +1. Define the structural reading port in `src/ports/` or the existing core + boundary that best matches the local architecture. +2. Model only the minimum basis, request, residual posture, witness reference, + and payload identity needed by current Review Truth behavior. +3. Move current git-warp-facing review/symbol/dead-symbol/test-reference reads + behind the port without changing their public output contracts. +4. Add a fixture-backed Continuum runtime-boundary test using the existing + GraphQL fixture posture as input evidence, then replace the fixture with + generated artifacts when the stack is ready. +5. Document the Graft/Continuum/warp-ttd split in the design packet and keep + [NORTHSTAR.md](../../../../NORTHSTAR.md) aligned. + +## Non-goals + +- Do not rewrite `v0.8.0` release scope. +- Do not replace git-warp in one step. +- Do not add a direct Echo dependency before the port boundary exists. +- Do not make Graft the owner of Continuum runtime-boundary nouns. +- Do not make `warp-ttd` the structural-review engine. +- Do not force Graft structural payloads into Continuum before another repo + needs the same semantics. diff --git a/docs/method/backlog/v0.8.0/CORE_pr-review-structural-summary.md b/docs/method/backlog/v0.8.0/CORE_pr-review-structural-summary.md index 4ca7d04..5a16972 100644 --- a/docs/method/backlog/v0.8.0/CORE_pr-review-structural-summary.md +++ b/docs/method/backlog/v0.8.0/CORE_pr-review-structural-summary.md @@ -58,6 +58,12 @@ a PR by checking out or fetching the PR branch and comparing refs locally. Direct `graft review ` resolution remains a future transport adapter, not part of the model boundary. +## Implementation status + +Shipped in `cycle/CORE_structural-test-coverage-map` as the top-level +`graft review --base [--head ]` CLI with human and JSON +rendering over the shared review model. + ## Related cards - **CORE_structural-test-coverage-map**: Both are review helpers. diff --git a/docs/method/backlog/v0.8.0/README.md b/docs/method/backlog/v0.8.0/README.md index f7fc3b6..c16ff9a 100644 --- a/docs/method/backlog/v0.8.0/README.md +++ b/docs/method/backlog/v0.8.0/README.md @@ -1,20 +1,21 @@ # v0.8.0 Backlog Lane: Review Truth -Status: forming +Status: release-prep Date: 2026-05-05 -This lane holds shaped candidate cards for the eventual v0.8.0 release. -It is a scope-formation lane, not a release packet, publish plan, or -promise to tag soon. +This lane holds shaped candidate cards for the v0.8.0 release and its +immediate follow-up queue. +It started as a scope-formation lane. The current cut line is now +captured in `docs/method/releases/v0.8.0/release.md`; cards below the +cut line remain valid follow-up candidates rather than blockers for the +release branch. -Release truth still belongs in `docs/method/releases/v0.8.0/` and -user-facing release notes still belong in `docs/releases/` when release -prep actually starts. Cards in this lane are simply the current answer -to: "What does v0.8.0 give users?" +Release truth lives in `docs/method/releases/v0.8.0/`, and +user-facing release notes live in `docs/releases/`. ## Release Thesis -The v0.8.0 candidate shape is **Review Truth**: +The v0.8.0 release shape is **Review Truth**: - tell PR authors and reviewers what changed structurally - show bounded symbol history for changed code @@ -29,7 +30,7 @@ The v0.8.0 candidate shape is **Review Truth**: ## User Outcomes -After v0.8.0, a user should be able to answer seven questions without +After v0.8.0, a user should be able to answer six questions without reading a whole diff blindly: 1. What files changed structurally, and which changes are likely @@ -43,8 +44,6 @@ reading a whole diff blindly: is visible? 6. Is the automated review loop ready for another pass, or is it still cooling down? -7. Which review feedback items were addressed by which commits, and - what summary can be rendered before posting back to GitHub? The release must not claim merge readiness, semantic correctness, or execution coverage. It should provide bounded structural evidence that a @@ -60,9 +59,9 @@ human or agent can inspect. | 4 | `WARP_symbol-history-timeline` | Per-symbol structural history for changed code. | | 5 | `WARP_dead-symbol-detection` | Removed-symbol evidence for cleanup and API-surface shrinkage review. | | 6 | `SURFACE_review-cooldown-status` | Review readiness helper for PR feedback loops. | -| 7 | `SURFACE_pr-feedback-resolution-ledger` | Local evidence ledger for unresolved feedback, fixes, SHAs, and markdown summaries. | -| 8 | `CORE_tool-context-injection-contracts` | Release hardening: prove review tools receive the resolved dependencies they were configured with. | -| 9 | `TEST_bounded-subprocess-policy` | Release hardening: prevent review tooling and tests from introducing unbounded subprocess hangs. | +| 7 | `SURFACE_pr-feedback-resolution-ledger` | Deferred follow-up: local evidence ledger for unresolved feedback, fixes, SHAs, and markdown summaries. | +| 8 | `CORE_tool-context-injection-contracts` | Deferred follow-up: prove review tools receive the resolved dependencies they were configured with. | +| 9 | `TEST_bounded-subprocess-policy` | Deferred follow-up: prevent review tooling and tests from introducing unbounded subprocess hangs. | ## Language Breadth Candidate Pull Order @@ -91,6 +90,15 @@ parity, real fixtures, and bounded degraded behavior for parse errors. | 25 | `CORE_kotlin-structural-parsing` | Android and JVM service repositories. | | 26 | `CORE_jupyter-notebook-structure` | Notebook-heavy AI/data repos with output-stripped structural projection. | +## Release Cut Line + +The release branch includes the Review Truth spine plus the first +language-breadth stack: Rust, GraphQL, Python, Go, JSON, TOML, and YAML. + +The remaining language cards, PR feedback ledger, ToolContext injection +contract sweep, and bounded subprocess policy sweep are intentionally +deferred unless release validation finds a direct blocker. + ## Baseline Already Shipped `CORE_graft-doctor` is part of the v0.8.0 context as shipped baseline, diff --git a/docs/method/releases/v0.8.0/release.md b/docs/method/releases/v0.8.0/release.md new file mode 100644 index 0000000..3c6ea56 --- /dev/null +++ b/docs/method/releases/v0.8.0/release.md @@ -0,0 +1,82 @@ +# Release Design: v0.8.0 + +## Included Work + +- Add the top-level `graft review --base [--head ]` + structural review summary surface. +- Add structural/reference test coverage reporting through the MCP tool + and CLI surface. +- Add bounded provenance hints to `git graft enhance --since `. +- Add symbol-history and dead-symbol review lenses. +- Add review cooldown status detection for automated reviewer loops. +- Add parser-backed structural support for Rust, GraphQL, Python, Go, + JSON, TOML, and YAML. +- Add lazy parser readiness through `ensureParserReady()`. +- Add Docker Desktop auto-start assistance for the isolated test runner + on macOS. +- Harden MCP invocation/server construction, governed read parity, WARP + symbol-id handling, Git version checks, and projection-bundle docs. + +## Deferred Work + +- PR feedback resolution ledger. +- ToolContext injection contract sweep. +- Repo-wide bounded subprocess policy sweep. +- SQL, shell, HCL, Java, C#, C, C++, PHP, Ruby, Swift, Kotlin, and + Jupyter parser breadth cards. +- GitHub PR-number resolution and automated PR comment posting for + `graft review`. +- Automatic breaking-change classification. + +These remain valid follow-up work, but they are not required to make +v0.8.0 coherent. + +## Hills Advanced + +- **Review Truth**: Users can inspect structural change signal, + bounded provenance, symbol history, removed-symbol evidence, and + structural test-reference signals from local Git ranges. +- **Language Breadth**: The review surface now applies to a wider set + of practical repositories: TypeScript/JavaScript, Rust, GraphQL, + Python, Go, JSON, TOML, YAML, and Markdown. +- **Runtime Robustness**: Parser loading, Docker preflight behavior, Git + version checks, and MCP orchestration are less brittle. + +## Sponsored Users + +- **PR authors** get compact local evidence before asking for another + review. +- **Reviewers** get structural signals that help focus attention on + meaningful changes and obvious test-reference gaps. +- **Agent hosts** get bounded parser-backed context across more file + types without depending on raw-file reads. +- **Maintainers** get hardened startup and invocation paths before the + review surfaces grow more transport adapters. + +## Version Justification + +**Minor** (`0.7.1` to `0.8.0`). + +This release adds new documented CLI and MCP review surfaces, new +parser-backed language support, and new package-root parser readiness +capability without intentionally breaking documented behavior. + +## Migration + +- No migration is required for normal CLI, MCP, or API usage. +- Hosts that need synchronous parser-backed projection immediately after + import can call `ensureParserReady()` explicitly before synchronous + structured-buffer use. + +## Release Acceptance + +This release is ready to tag when all of the following are true: + +- `package.json` is bumped to `0.8.0`. +- `CHANGELOG.md` has a dated `0.8.0` section. +- `docs/releases/v0.8.0.md` is final. +- `docs/method/releases/v0.8.0/verification.md` is filled with actual + preflight evidence. +- `pnpm release:check` passes on the final release commit. +- `main` is exactly synced with `origin/main` before tagging. +- The `v0.8.0` tag is pushed only from the merged main release commit. diff --git a/docs/method/releases/v0.8.0/scope.md b/docs/method/releases/v0.8.0/scope.md index 537c684..80b9a18 100644 --- a/docs/method/releases/v0.8.0/scope.md +++ b/docs/method/releases/v0.8.0/scope.md @@ -1,6 +1,6 @@ # v0.8.0 Scope Decision -Status: backlog lane formed +Status: release prep Date: 2026-05-05 ## Current State @@ -25,10 +25,9 @@ Date: 2026-05-05 ## Decision -Make v0.8.0 a **Review Truth** release candidate shape unless a stronger -blocker appears. +Make v0.8.0 a **Review Truth** release. -The opening spine should be repo-generic: +The release spine is repo-generic: 1. `CORE_pr-review-structural-summary` 2. `CORE_structural-test-coverage-map` @@ -36,20 +35,24 @@ The opening spine should be repo-generic: 4. `WARP_symbol-history-timeline` 5. `WARP_dead-symbol-detection` 6. `SURFACE_review-cooldown-status` -7. `SURFACE_pr-feedback-resolution-ledger` -8. release hardening through `CORE_tool-context-injection-contracts` - and `TEST_bounded-subprocess-policy` +7. first language-breadth stack: Rust, GraphQL, Python, Go, JSON, + TOML, and YAML +8. release hardening through parser readiness, Docker preflight, Git + version checks, governed read parity, WARP symbol IDs, and MCP + orchestration cleanup This gives users bounded review evidence: what changed structurally, which changed symbols have bounded provenance hints, what has obvious structural history, which symbols disappeared and were not re-added, what has obvious structural test references, whether the automated -review loop is ready for another pass, and which feedback items were -addressed by which commits. It keeps Graft repo-generic without making -it depend on METHOD project conventions. +review loop is ready for another pass, and whether the inspected files +can be navigated structurally across more common languages and config +formats. It keeps Graft repo-generic without making it depend on METHOD +project conventions. The shaped candidate lane lives at `docs/method/backlog/v0.8.0/`. It is -not a release packet and does not imply that v0.8.0 is ready to cut. +now the release scope ledger plus follow-up candidate queue. Release +truth lives in `docs/method/releases/v0.8.0/`. ## Candidate Matrix @@ -63,9 +66,9 @@ not a release packet and does not imply that v0.8.0 is ready to cut. | `WARP_symbol-history-timeline` | Commit-to-symbol edges with signatures are shipped and already support chronological per-symbol history. | Included v0.8.0 review lens. | Add a small query for the structural timeline of a changed symbol. | | `WARP_dead-symbol-detection` | Commit-to-symbol removal edges are shipped and can identify symbols removed and not re-added. | Included v0.8.0 review lens. | Add removed-symbol evidence without taking on full breaking-change automation. | | `SURFACE_review-cooldown-status` | PR feedback loops currently require manual parsing of automated reviewer cooldown comments. | Included v0.8.0 helper. | Pull after the structural review surfaces unless cooldown friction blocks review iteration first. | -| `SURFACE_pr-feedback-resolution-ledger` | Feedback processing currently stitches review threads, local commits, and PR replies by hand. | Included v0.8.0 evidence ledger. | Render local markdown summaries by default; require explicit confirmation or flags for GitHub mutation. | -| `CORE_tool-context-injection-contracts` | A prior review found that resolved composition-root dependencies can be bypassed by ToolContext wiring. | Release hardening gate. | Prove review tools receive the configured dependencies they are supposed to use. | -| `TEST_bounded-subprocess-policy` | Docker autostart and child-process tests exposed the risk of unbounded subprocess hangs. | Release hardening gate. | Add policy/regression coverage before review tooling grows more subprocess paths. | +| `SURFACE_pr-feedback-resolution-ledger` | Feedback processing currently stitches review threads, local commits, and PR replies by hand. | Defer. | Keep as the strongest follow-up review workflow card after v0.8.0. | +| `CORE_tool-context-injection-contracts` | A prior review found that resolved composition-root dependencies can be bypassed by ToolContext wiring. | Defer. | Keep as a hardening sweep after the release unless validation exposes a direct blocker. | +| `TEST_bounded-subprocess-policy` | Docker autostart and child-process tests exposed the risk of unbounded subprocess hangs. | Defer. | Keep as a hardening sweep after the release unless validation exposes a direct blocker. | | `SURFACE_git-graft-enhance-expanded-git-subcommands` | The broader enhance vision includes many Git-adjacent verbs. | Defer. | Keep v0.8.0 on review paths instead of broad command expansion. | | `CI-003-mcp-native-diff-protocol` | Richer MCP diff rendering would improve client UX but changes response protocol shape. | Defer. | Revisit after Review Truth surfaces are stable. | | `WARP_auto-breaking-change-detection` | Breaking-change detection is directly review-adjacent but depends on export-diff semver classification and dead-symbol detection. | Defer. | Revisit after the smaller dead-symbol primitive and export-diff fix exist. | @@ -75,7 +78,7 @@ not a release packet and does not imply that v0.8.0 is ready to cut. | `SURFACE_bijou-daemon-control-plane-actions` | Existing daemon mutation tools exist, but terminal action UX is sharp. | Defer. | Do not pull before live/status posture is boring. | | `CI-002-deterministic-scenario-replay` | Logging and ports exist; full replay is still large. | Valuable but too large for opening slice. | Save for later scope pass or a concrete regression. | -## Non-Goals For Opening v0.8.0 +## Non-Goals For v0.8.0 - No governed write expansion. - No native editor write interception. @@ -85,15 +88,23 @@ not a release packet and does not imply that v0.8.0 is ready to cut. - No METHOD-specific backlog/status surfaces in Graft. - No release tag or publish work. -## First Pull Recommendation +## Release Cut -Pull `CORE_pr-review-structural-summary` from -`docs/method/backlog/v0.8.0/` when implementation work resumes. +The v0.8.0 cut line is now the merged Review Truth and language-breadth +stack: -The first slice should compose existing structural diff facts into a -small review summary model and CLI surface. Do not start with GitHub -Action posting, do not claim merge readiness, and do not rebuild METHOD -backlog status inside Graft. +- structural PR review summaries +- structural/reference test coverage mapping +- bounded provenance hints +- symbol history timeline +- dead-symbol detection +- review cooldown status +- Rust, GraphQL, Python, Go, JSON, TOML, and YAML structural support +- lazy parser readiness, Docker preflight assistance, Git version + guardrails, governed read parity, and MCP orchestration hardening + +The remaining v0.8.0 lane cards are deferred follow-up candidates, not +release blockers for this cut. ## User-Facing Promise diff --git a/docs/method/releases/v0.8.0/verification.md b/docs/method/releases/v0.8.0/verification.md new file mode 100644 index 0000000..b90a431 --- /dev/null +++ b/docs/method/releases/v0.8.0/verification.md @@ -0,0 +1,63 @@ +# Release Witness: v0.8.0 + +This witness records release-branch preflight. Tagging and publish +verification are still pending until the release branch is merged to +`main` and the `v0.8.0` tag is pushed from the merged main commit. + +## Discovery + +- Repository type: JS/TS package (pnpm) +- Previous package version: `0.7.1` +- Planned version: `0.8.0` +- Branch: `release/v0.8.0` +- Release branch synced with origin: pending push after witness + finalization +- `main` release guard: pending; final release runbook requires main to + be exactly synced with `origin/main` before tag/publish + +## Validation + +| Step | Result | +|------|--------| +| `pnpm lint` | pass as part of `pnpm release:check`, 2026-05-06 11:58 PDT | +| `pnpm typecheck` | pass as part of `pnpm release:check`, 2026-05-06 11:58 PDT | +| `pnpm release:surface-gate` | pass, 2 files / 10 tests, 2026-05-06 11:58 PDT | +| `pnpm test` | pass, Docker isolated, 216 files / 1592 tests, 2026-05-06 11:58 PDT | +| `pnpm security:check` | pass, critical=0 high=0 moderate=0 low=0 info=0, 2026-05-06 11:58 PDT | +| `pnpm pack:check` | pass, dry-run tarball `flyingrobots-graft-0.8.0.tgz`, 2026-05-06 11:58 PDT | +| `pnpm release:check` | pass, 2026-05-06 11:58 PDT | +| `git diff --check` | pass, 2026-05-06 12:00 PDT | + +## Security Disposition + +Initial release prep found one moderate advisory: +`GHSA-v2v4-37r5-5v8g` / `CVE-2026-42338` for transitive +`ip-address@10.1.0` through +`@git-stunts/git-warp > roaring > node-gyp > make-fetch-happen > +@npmcli/agent > socks-proxy-agent > socks > ip-address`. + +The release branch pins `ip-address` to `10.2.0` through +`pnpm.overrides`. The final `pnpm security:check` reports zero +advisories. + +## Package Delivery Checks + +| Check | Result | +|-------|--------| +| package version is `0.8.0` | pass | +| tarball includes `bin/` and `dist/` | pass | +| tarball excludes `src/` | pass | +| `bin/graft.js` starts the built CLI | pass, package-shape gate | +| runtime dependencies exclude `tsx` | pass, package-shape gate | +| release note and changelog agree on user-facing scope | pass | + +## Tag and Publish + +- Release branch prep commit: `04c435b release: prepare v0.8.0` +- Final release commit: pending merged `main` release commit +- Tag: pending +- Tag push: pending +- Release workflow: pending +- GitHub Release created by workflow: pending +- npm publish by workflow: pending +- Direct npm registry verification: pending diff --git a/docs/releases/v0.8.0.md b/docs/releases/v0.8.0.md new file mode 100644 index 0000000..f324068 --- /dev/null +++ b/docs/releases/v0.8.0.md @@ -0,0 +1,74 @@ +# v0.8.0 + +## Summary + +v0.8.0 is a Review Truth release. It helps agents and humans review a +Git range by showing structural change summaries, bounded symbol +history, removed-symbol evidence, test-reference signals, feedback-loop +readiness, and wider parser-backed language coverage. + +This release does not claim merge readiness, semantic correctness, or +execution coverage. It gives reviewers compact structural evidence so +they can decide where to spend attention. + +## What Changed + +- `graft review --base [--head ]` now renders a local, + repo-generic structural review summary. `--json` keeps the + schema-validated agent payload. +- `graft_test_coverage` and `graft struct test-coverage` now report + exported source symbols with or without bounded test-directory + references. The report is explicitly structural/reference coverage, + not runtime execution coverage. +- `git graft enhance --since ` now includes bounded provenance + hints for changed symbols when WARP-backed blame facts are available. +- `graft symbol history [--path ]` now renders a + timeline-first symbol history view. +- `graft_dead_symbols` and `graft struct dead-symbols` now report + symbols removed from indexed history and not subsequently re-added. +- `graft review cooldown [--pr ]` now reports whether an + automated review loop appears ready, cooling down, or unknown. +- Parser-backed outlines, governed reads, structural diffs, and WARP + indexing now understand Rust, GraphQL, Python, Go, JSON, TOML, and + YAML in addition to the existing supported formats. +- The isolated test runner can attempt to launch Docker Desktop on + macOS before failing the Docker daemon preflight. +- Parser loading is now lazy through `ensureParserReady()`, reducing + cold-start pressure for hosts that do not parse immediately. +- MCP orchestration, governed read logic, WARP symbol IDs, Git version + checks, and projection-bundle documentation were hardened. + +## Why It Matters + +Reviewers can now ask sharper questions without opening an entire diff: + +- What changed structurally? +- Which symbols changed, disappeared, or moved through history? +- Which changed exports have obvious test references? +- Is the automated reviewer ready for another pass? +- Can an agent safely inspect more repositories without raw-file + sprawl? + +The result is a more useful review surface for TypeScript, Rust, +GraphQL, Python, Go, and common structured config repositories. + +## Breaking Changes + +No breaking changes are expected for documented CLI, MCP, or package API +usage. + +## Migration + +No migration required. + +Hosts that call synchronous structured-buffer APIs before any parser +warmup can optionally call `ensureParserReady()` from the package root +to make parser readiness explicit. + +## Links + +- [README](../../README.md) +- [Setup Guide](../SETUP.md) +- [CLI Guide](../CLI.md) +- [MCP Guide](../MCP.md) +- [CHANGELOG](../../CHANGELOG.md) diff --git a/package.json b/package.json index 350c5be..6cbe8d8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@flyingrobots/graft", - "version": "0.7.1", + "version": "0.8.0", "description": "Context governor and between-commit activity surface for coding agents", "type": "module", "packageManager": "pnpm@10.30.0", @@ -111,7 +111,9 @@ "onlyBuiltDependencies": [], "overrides": { "vite": "^8.0.5", - "hono": ">=4.12.18", + "hono": "4.12.18", + "fast-uri": "3.1.2", + "ip-address": "10.2.0", "postcss": "8.5.12" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index baa46b8..95c2695 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -6,7 +6,9 @@ settings: overrides: vite: ^8.0.5 - hono: '>=4.12.18' + hono: 4.12.18 + fast-uri: 3.1.2 + ip-address: 10.2.0 postcss: 8.5.12 importers: @@ -381,7 +383,7 @@ packages: resolution: {integrity: sha512-TsQLe4i2gvoTtrHje625ngThGBySOgSK3Xo2XRYOdqGN1teR8+I7vchQC46uLJi8OF62YTYA3AhSpumtkhsaKQ==} engines: {node: '>=18.14.1'} peerDependencies: - hono: '>=4.12.18' + hono: 4.12.18 '@humanfs/core@0.19.1': resolution: {integrity: sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA==} @@ -972,8 +974,8 @@ packages: fast-levenshtein@2.0.6: resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==} - fast-uri@3.1.0: - resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==} + fast-uri@3.1.2: + resolution: {integrity: sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==} fdir@6.5.0: resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} @@ -1110,8 +1112,8 @@ packages: inherits@2.0.4: resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==} - ip-address@10.1.0: - resolution: {integrity: sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==} + ip-address@10.2.0: + resolution: {integrity: sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==} engines: {node: '>= 12'} ipaddr.js@1.9.1: @@ -2358,7 +2360,7 @@ snapshots: ajv@8.18.0: dependencies: fast-deep-equal: 3.1.3 - fast-uri: 3.1.0 + fast-uri: 3.1.2 json-schema-traverse: 1.0.0 require-from-string: 2.0.2 @@ -2648,7 +2650,7 @@ snapshots: express-rate-limit@8.3.2(express@5.2.1): dependencies: express: 5.2.1 - ip-address: 10.1.0 + ip-address: 10.2.0 express@5.2.1: dependencies: @@ -2689,7 +2691,7 @@ snapshots: fast-levenshtein@2.0.6: {} - fast-uri@3.1.0: {} + fast-uri@3.1.2: {} fdir@6.5.0(picomatch@4.0.4): optionalDependencies: @@ -2830,7 +2832,7 @@ snapshots: inherits@2.0.4: {} - ip-address@10.1.0: {} + ip-address@10.2.0: {} ipaddr.js@1.9.1: {} @@ -3267,7 +3269,7 @@ snapshots: socks@2.8.7: dependencies: - ip-address: 10.1.0 + ip-address: 10.2.0 smart-buffer: 4.2.0 optional: true