Epic: Graphify local repository context for v1.4.1

[jeffhuber]

Part of roadmap #900.

Graphify local repository-context provider for v1.4.1

Problem

Code Mower has a provider-neutral private-context packet and delivery path, but repository structure still comes from ordinary agent inspection. Graphify may improve dependency, impact, and related-test discovery. A preliminary evaluation also shows material risks: it can scan untracked working-copy content, its graph does not bind itself to a Git revision/build time, and broad natural-language results can be noisy. Support must begin with evidence and an immutable local boundary.

Outcome

Complete #876 as a bounded adopt/defer spike. If adopted, provide an optional local Graphify connection that builds a deterministic code-only graph from an immutable tracked-file checkout, records Code Mower-owned revision provenance, performs explicit refreshes, returns bounded cited packet evidence, and delivers the same packet to Claude, Codex, and Devin. No hosted Graphify, model-backed semantic extraction, hooks, watcher, shared HTTP MCP server, or default dependency is introduced.

Delivery sequence

1. G1 / Context: evaluate official Graphify as a local repository provider for v1.4.1 #876: pinned compatibility spike, clean-checkout experiment, comparative benchmark, sanitized decision record.
2. G2: private graph lifecycle: optional pin, clean materialization, environment/network boundary, atomic artifact/manifest, build/refresh/status/remove, doctor.
3. G3: strict bounded graph reader/query adapter, path/line validation, confidence and completeness mapping, revision-bound context packets and guided-session delivery.
4. G4: optional setup, documentation, isolation/staleness/package qualification, sanitized scorecard, v1.4.1 release, and CodeMower.com metadata upload.

Spike contract

Evaluate the official Graphify-Labs package from an exact reviewed version and hash. Use a fixed public Code Mower commit and a small synthetic fixture; cap tracked files, time, graph bytes, and response bytes. Run code-only extraction with query logging disabled, no provider API keys, no installation hooks, no network during extraction/query, and graph state outside the repository. Compare graph answers with rg/ordinary inspection for callers, dependents, related tests, cross-module paths, configuration coupling, blast radius, and exact-text negative controls.

Adopt only if no out-of-scope/private file is indexed, every citation remains inside the immutable checkout, at least 90% of line citations resolve, truncation/completeness is explicit, and useful incremental relationships appear on at least half the graph-suited questions. Otherwise record a defer decision and close the epic without runtime integration.

Revision and privacy contract

Code Mower owns code_mower.graphifyBuild.v1: full source commit and tree SHA, Graphify version/options, build time, tracked-file census/digest, graph digest/bytes, and completeness. Artifacts are immutable per repository/revision/options. Every read rechecks permissions, schema, digest, and requested revision. Required stale/unknown context blocks dependent work; optional context degrades explicitly. Graph content, local paths, queries, citations, and hashes remain local. CodeMower.com receives only explicitly allowlisted provider/state/count/timing metadata.

Dependencies

G1/G2 are complete. G3 #914 is active in draft #982 and uses the shared context-recipient contract. G4 #915 requires #914 and the fully completed stabilization epic #979, including #965/#967/#976 and all remaining stabilization children; Devin release #912 is already complete.

Publish and qualify Graphify v1.4.1 before Board #952, or record an explicit evidence-backed deferral in #915 and this epic. No automatic deferral or change of release order is authorized by delay. Slack implementation may proceed independently; final Slack acceptance waits for released Board. Stabilization #979 runs alongside this epic without coupling #914 to takeover work.

Scorecard

Child	Builder	PR/head	Peer audit	Benchmark/tests	Gate	State
G1 #876	Code Mower Claude	#924 / b5c77b3	Codex exact-head PASS; P0/P1/P2=0	adopt decision; 429-file clean-room benchmark; Python 3.12–3.14 CI	pass	merged; adopted
G2 lifecycle #913	Code Mower Claude	#926 / 1149b76	Codex exact-head PASS; P0/P1/P2=0	3,249 tests; Linux/macOS graph containment; Python 3.12–3.14 CI	pass	merged
G3 query/packet #914	Code Mower Claude	draft #982	Code Mower Codex; fixes under review	consuming revision and pinned raw extraction compatibility checks in progress	pending final head	active; not accepted
G4 release #915	planned Code Mower Codex	planned release PR	pending	candidate/published package, headless cold install/upgrade, benchmark and fresh cloud evidence	pending	blocked by #914 and remaining #979

Definition of done

• The adopt/defer decision is reproducible and evidence-backed.
• If adopted, clean-checkout, revision binding, explicit refresh, stale detection, bounded queries, context delivery, no-provider fallback, fresh installation, and package matrix all pass.
• v1.4.1 is published and qualified before Slack release, with sanitized scorecard and metadata-only CodeMower.com ingestion evidence.

Delivery checklist

• Context: evaluate official Graphify as a local repository provider for v1.4.1 #876 — G1 compatibility spike
• Graphify: private revision-bound local graph lifecycle #913 — G2 private graph lifecycle
• Graphify: bounded query normalization and context packets #914 — G3 bounded query/packet adapter
• Release: qualify and publish optional Graphify context in v1.4.1 #915 — G4 v1.4.1 release

Completion PR map and release evidence

#914 → draft OSS query/packet PR #982 (actual builder Code Mower Claude, independent Code Mower Codex); #915 → one planned OSS release PR (planned builder Code Mower Codex, independent eligible peer review). #914 is active; #915 remains a planned assignment. Existing #924/#926 remain completed foundation evidence.

#915 records the exact release commit, all post-v1.4.0 fixes included in the wheel/sdist (including #935/#973 if present), published installation, no-provider fallback, Board observation, ingest receipt, and separately observed aggregate freshness. Missing settlement remains unavailable. #974 tracks the previously accepted upload's freshness without replaying it. Final roadmap #900 requires fresh aggregate evidence by v1.5.0.

[jeffhuber]

G1 complete: #876 merged through PR #924 at b5c77b32b31010b2f419d611f2929f0b28aea477 (merge ce720f971eb9cdbe6a431404325e2b28b1d52d1b).

Decision: adopt Graphify as an opt-in, bounded local repository-context provider. The spike pins the official package/hash, records isolated performance and query-quality evidence, and adds fail-closed citation/revision scope validation. CI passed on Python 3.12/3.13/3.14, exact-head Codex audit passed after two P2 fixes, and code-mower/gate passed.

G2 #913 is now dispatched to Claude. It must implement private immutable revision-bound graph lifecycle without changing the default Claude + Codex setup.

Cloud posture remains metadata-only; no source, graph contents, prompts, transcripts, private context, credentials, or raw provider output are eligible for upload.

[jeffhuber]

G2 review status

• G1 Context: evaluate official Graphify as a local repository provider for v1.4.1 #876 / PR context: adopt Graphify as an optional bounded local provider and prove the graph contract offline #924: merged; bounded offline adoption spike.
• G2 Graphify: private revision-bound local graph lifecycle #913 / PR context: bind a local graph to its revision and fail closed on everything else #926: active at exact head 9f3099a533d9.
• CI is green after rebasing onto current main.
• Exact-head Codex review remains BLOCKED on three P2 findings: require affirmative completion evidence, reject pre-existing tracked provider state, and bound report reads before allocation.
• Code Mower Claude correction round is active. A new exact-head review and normal gate remain required.

[jeffhuber]

Lineage convergence pivot before v1.4.1

The owner questioned the serial repair trajectory. A deterministic checkpoint at unaccepted #989 head 0706c53922f67168dfbb6d2a6493a031a9b0f205 confirmed a cross-surface inconsistency: configured branch conflict fails closed in gate/status/controller/Board, but both Greptile structural requeue failure paths still mutate labels when episodes are empty. The #989 repair loop is stopped and the PR remains draft/unmerged as superseded source/review evidence.

Completion of the sole remaining #979 outcome, #963, is now staged:

1. Lineage stage 1: extract and qualify the pure exact-head contract #990 — dependency-free pure exact-head lineage/parsing/identity/trust contract and isolated fixtures, without live policy activation.
2. Lineage stage 2: trusted delivery persistence and semantic publication #991 — trusted recording/publication and semantic readback, consuming Lineage stage 1: extract and qualify the pure exact-head contract #990; automatic label reconciliation remains deferred.
3. Lineage stage 3: converge admission, status and label mutations atomically #992 — atomically converge all admission/status/labeler/gate consumers and activate runner/CLI reconciliation, consuming Lineage stage 1: extract and qualify the pure exact-head contract #990/Lineage stage 2: trusted delivery persistence and semantic publication #991.

Each stage has one independently reviewed PR, focused and exact CI-style full tests, privacy/package guards, CI and authoritative gate. Stage 1 is constrained to a reviewable 15-file/250 KB envelope; crossing it requires another decomposition decision rather than silent expansion. The preserved matrix passed 1,111 tests/1,410 subtests, one expected optional sandbox skip, guards/readiness and remote CI, but passing counts do not override the invariant failure. Actual spend remains unavailable; caps are ceilings, not billing.

Graphify #914/#982 remains feature-qualified and waits for the accepted staged outcome, then refreshes onto final main once. #915 still owns candidate/artifact/cold-install/upgrade/scorecard/publication/post-install qualification. Board v1.4.2 follows published/qualified v1.4.1; Slack v1.5.0 remains later. No new hosted Devin create allowance, no Graphify scope reduction, and no release criterion was waived.

[jeffhuber]

#915 source preparation is delivered as draft PR #998 at 288ba2ace7a7e68ba3ee4089d14c8aebf2ff77a5, sole writer Code Mower Codex, based on accepted main 6e880e982248dbfdcef63ed9afc345cb0b60cbda. Independent exact-head Claude audit is requested with needs-claude-audit; review and canonical full suite/CI/gate remain supervisor-owned.

Source validation: 127 release/runbook tests, 72 Devin setup tests, 20 adoption/doc checks, 10 cold-init tests, 7 command-doc tests, 4 guidance/installed-wheel tests and 4 scoped lineage artifact tests passed; readiness 20/20, Ruff/privacy/package guards passed. The installed lineage takeover/readback hook still needs temporary state outside Git; the Mac lane's temporary storage was inside its checkout and correctly refused. This is explicitly not a qualification pass.

State boundaries: source PR is draft/unmerged; v1.4.1 is not published or installed-qualified; #876 scorecard, campaign, Board, stored metadata receipt and fresh authenticated aggregate remain pending. No release mutation, hosted session or cloud upload occurred. Accepted main fixes are recorded separately from future wheel/sdist and canonical publication inclusion. v1.4.0 history is preserved unchanged.

The issue handoff records the runner/owner linkage conflict: the draft's runner-required closing reference must be removed before a source-only merge, consistent with the owner's Refs #915 instruction. Keep #915 open until all release acceptance passes. Board release priority remains after that acceptance.

[jeffhuber]

Graphify v1.4.1 epic complete

All four delivery stages are accepted:

Stage	Delivery	Outcome
G1	#876 / PR #924	Optional-provider adoption decision with pinned clean-room experiment.
G2	#913 / PR #926	Private revision-bound lifecycle and containment.
G3	#914 / PR #982, merged as 6e880e982248dbfdcef63ed9afc345cb0b60cbda	Bounded query normalization, cited packets, revision binding, and no-provider behavior; independent exact-head Codex PASS, CI/gate green.
G4	#915 / PR #998, merged/released as d52bc68396397edfeae782d08a768386f89a00f2 / v1.4.1	Canonical artifacts published and installed-qualified; independent exact-head Claude PASS, 4,245-test suite, CI/gate, headless upgrade, campaign, three-Board restart, metadata-only upload, and fresh aggregate visibility passed.

The release-specific Graphify scorecard indexed 746 tracked files with zero unsupported inputs in 22.138 seconds. Four of six graph-suited questions gained useful incremental relationships, all 58 sampled line citations resolved inside the immutable checkout, and negative/stale/no-provider controls passed. Raw graph, query, citation, path, and source content remained local.

The accepted operating boundary is unchanged: Graphify is optional, separately installed, explicitly built/refreshed, local and revision-bound. It adds no default dependency, hosted service, watcher, hook, background indexing, tracker authority, or cloud content field.

The Board v1.4.2 dependency is now satisfied. Closing #902 as complete.