FE-870: Renderer golden coverage and agent-context tools#217
Merged
Conversation
Contributor
Author
This stack of pull requests is managed by Graphite. Learn more about stacking. |
lunelson
changed the title
PR SummaryLow Risk Overview
Reviewed by Cursor Bugbot for commit d4a7050. Bugbot is set up for automated code reviews on this repo. Configure here. |
There was a problem hiding this comment.
Pull request overview
This PR advances the “renderer/context coverage frontier” by moving per-turn agent context seed rendering into session/ (so prompt composition consumes a prepared bundle), adding a cheap graph LSN read to avoid unnecessary graph/gap reads across mode/prompt recompositions, and updating the .pi/agents asset topology.
Changes:
- Introduces
composeAgentContextSeed/renderWorkspaceSeed/renderGraphSeedinsrc/session/agent-context-seed.tswith new golden-ish unit tests. - Adds
latestGraphLsnand threads alatestLsnread through graph reader interfaces, plus aWorldReadCachememo in prompt composition to reusequeryGraph/getElicitationGapswhen the LSN is unchanged. - Refactors CLI arg parsing to
node:utilparseArgs, and updates.pi/agentsmarkdown layout + build asset copy step accordingly.
Reviewed changes
Copilot reviewed 28 out of 32 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/web/app.test.tsx | Adds a window.scrollTo stub for jsdom-based web tests. |
| src/session/agent-context-seed.ts | New session-owned renderer for the per-turn pushed context blocks (workspace + selected-spec graph). |
| src/session/agent-context-seed.test.ts | Adds/adjusts tests covering workspace seed rendering and context seed composition. |
| src/graph/workspace-store.ts | Threads a cheap LSN read (latestLsn) into spec-scoped graph readers. |
| src/graph/queries.ts | Exposes latestGraphLsn and reuses it in queryGraph clock stamping. |
| src/dev/tier-2-harness.ts | Allows tier-2 harness boots to override agent services; adds a no-model services helper. |
| src/dev/faux-harness.test.ts | Updates harness stubs to satisfy the new latestLsn reader shape. |
| src/dev/brunch-dev.ts | Centralizes BRUNCH_DEV env gating in a dev utility module. |
| src/app/brunch.ts | Refactors CLI parsing to parseArgs; moves isBrunchDevEnabled import to src/dev/. |
| src/app/brunch.test.ts | Updates CLI tests to match the new boolean flag parsing behavior. |
| src/app/brunch-tui.ts | Moves isBrunchDevEnabled import and threads latestLsn into prompt graph reads. |
| src/app/brunch-tui.test.ts | Updates prompt graph read stubs with latestLsn. |
| src/.pi/extensions/system-prompts/world-reads.ts | Adds a memo/cache to reuse graph/gap reads when (specId, lsn) is unchanged. |
| src/.pi/extensions/system-prompts/world-reads.test.ts | Adds tests proving read reuse vs refresh based on LSN/spec changes. |
| src/.pi/extensions/system-prompts/seed/workspace.ts | Deleted (workspace seed rendering relocated to src/session/agent-context-seed.ts). |
| src/.pi/extensions/system-prompts/seed/workspace.test.ts | Deleted (tests relocated to src/session/agent-context-seed.test.ts). |
| src/.pi/extensions/system-prompts/seed/graph.ts | Deleted (graph seed rendering relocated to src/session/agent-context-seed.ts). |
| src/.pi/extensions/system-prompts/index.ts | Switches to WorldReadCache + composeAgentContextSeed for prompt context assembly. |
| src/.pi/extensions/system-prompts/compose.ts | Imports readiness estimate rendering/types from the new session context-seed module. |
| src/.pi/extensions/runtime/state.ts | Removes the definitions prompt-resource family path logic; simplifies resource locations to skills. |
| src/.pi/extensions/graph/index.ts | Extends GraphReaders with latestLsn(specId) for cheap change detection. |
| src/.pi/extensions/graph/command-adapter.ts | Cleans up unused graph-slice type import. |
| src/.pi/agents/reviewer.md | Adds a reviewer agent definition markdown at the new flat path. |
| src/.pi/agents/README.md | Updates topology docs for flat src/.pi/agents/{agent}.md layout. |
| src/.pi/agents/elicitor.md | Adds an elicitor agent definition markdown at the new flat path. |
| src/.pi/tests/prompting.test.ts | Updates prompt context stubs with latestLsn. |
| src/.pi/tests/graph-tools.test.ts | Wires latestGraphLsn into graph readers used by graph tool tests. |
| src/.pi/tests/extension-registry.test.ts | Updates extension registry stubs with latestLsn. |
| package.json | Updates build:pi-assets to copy flat agent markdown files (excluding README). |
| package-lock.json | Adjusts pi-ai bin path entry (likely from lock regeneration). |
| memory/SPEC.md | Updates spec text to reflect the new flat .pi/agents layout. |
| docs/archive/PLAN_HISTORY.md | Updates archived plan boundary text to reflect the new .pi/agents layout. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+31
to
+40
| const lsn = graphReads.latestLsn(specId); | ||
| if (cached && cached.specId === specId && cached.lsn === lsn) { | ||
| return cached.reads; | ||
| } | ||
| const reads: WorldReads = { | ||
| graph: graphReads.queryGraph(), | ||
| gaps: graphReads.getElicitationGaps(specId), | ||
| }; | ||
| cached = { specId, lsn, reads }; | ||
| return reads; |
Comment on lines
+157
to
+159
| beforeAll(() => { | ||
| Object.defineProperty(window, 'scrollTo', { value: vi.fn(), writable: true }); | ||
| }); |
Comment on lines
+124
to
+134
| async function collectTopology( | ||
| cwd: string, | ||
| shouldIgnore: (relativePath: string, isDirectory: boolean) => boolean, | ||
| ): Promise<WorkspaceTopologyEntry> { | ||
| return { | ||
| name: '.', | ||
| kind: 'directory', | ||
| fileCount: await countVisibleFiles(cwd, cwd, shouldIgnore), | ||
| children: await collectTopologyChildren(cwd, cwd, shouldIgnore, 0), | ||
| }; | ||
| } |
Comment on lines
+159
to
+163
| if (entry.isDirectory()) { | ||
| const fileCount = await countVisibleFiles(path, cwd, shouldIgnore); | ||
| const children = | ||
| depth < 1 ? await collectTopologyChildren(path, cwd, shouldIgnore, depth + 1) : undefined; | ||
| topologyEntries.push({ |
Comment on lines
+27
to
+43
| export function createWorldReadCache(): WorldReadCache { | ||
| let cached: { specId: number; lsn: number; reads: WorldReads } | null = null; | ||
| return { | ||
| read(graphReads, specId) { | ||
| const lsn = graphReads.latestLsn(specId); | ||
| if (cached && cached.specId === specId && cached.lsn === lsn) { | ||
| return cached.reads; | ||
| } | ||
| const reads: WorldReads = { | ||
| graph: graphReads.queryGraph(), | ||
| gaps: graphReads.getElicitationGaps(specId), | ||
| }; | ||
| cached = { specId, lsn, reads }; | ||
| return reads; | ||
| }, | ||
| }; | ||
| } |
graphite-app
Bot
changed the base branch from
ln/fe-869-runtime-topology-cleanup
to
graphite-base/217
The per-turn pushed context blocks (workspace + graph seeds) are a session-context-composition concern, not a system-prompt one. Relocate them and the AgentPrompt*Context types + renderSoftReadinessEstimate from .pi/extensions/system-prompts into src/session/agent-context-seed.ts, so the prompt layer consumes a context bundle it no longer owns. The Pi extension performs the PULL (queryGraph) and delegates RENDER/COMPOSE to composeAgentContextSeed. Verbatim move; output and tests unchanged. Amp-Thread-ID: https://ampcode.com/threads/T-019ecb11-98d3-716c-9224-f95c9e6b28ca Co-authored-by: Amp <amp@ampcode.com>
Per-turn prompt composition re-ran the expensive SQL pair queryGraph + getElicitationGaps every turn, even when the graph was unchanged (e.g. cycling operational modes / agent prompts). Add a cheap latestGraphLsn reader path and a world-read memo that gates those reads behind the per-spec graph clock: unchanged (spec, lsn) reuses prior reads, a changed LSN or spec refreshes. Lens-dependent seed rendering still happens fresh per prompt; only the underlying reads are cached. Amp-Thread-ID: https://ampcode.com/threads/T-019ecb11-98d3-716c-9224-f95c9e6b28ca Co-authored-by: Amp <amp@ampcode.com>
Move the command input/result contract types and the structural-validation subsystem out of command-executor.ts (1439 → 916 lines) into two semantically-named subtree modules, mirroring the existing graph-mutation-types split. The root keeps the CommandExecutor class, the seeded elicitation-gap floor, and the public re-export barrel, so the external API surface is unchanged. Topology README updated to register both modules.
…le battery Consolidate the scattered web-as-driver / streaming / subscriptions intentions into one Horizon frontier (web-driver-streaming) with topology A confirmed: relay the in-process AgentSession event stream over the existing Brunch WS, multiplexed with Brunch domain notifications, plus a web command-intake path. A' rejected (Pi ships no TUI-over-RPC); B documented as the isolation-only alternative. Records the oracle battery (stream<->transcript differential, domain-projection multiplexing, mid-stream exchange convergence, reconnect, fan-out) on the tier-2 faux substrate; render feel stays outer-loop manual. Relaxation: one driver, many observers (no concurrent multi-driver). SPEC Verification Design: new middle-loop oracle row; fire the subscription reconnect/resume blind spot; soften the staging decisions D49-L (polling -> streaming subscription), D72-L (web read-only -> driver), and D5-L (agent-as-user split: public-RPC contract probe vs tier-2 mission engine) with forward notes so they stop reading as permanent locks. memory/ only; src/** README revisions, Linear issue, and build branch deferred.
Port the layer import boundaries (db only from graph, renderers isolation, workspace leaf isolation) into .oxlintrc.json via no-restricted-imports, with graph/db and test files exempted. Delete the architecture/topology tests that merely restated these static checks, keeping only the content and seam invariants that lint cannot express. Amp-Thread-ID: https://ampcode.com/threads/T-019ecbe5-9952-77d9-ae20-374b0f9ad949 Co-authored-by: Amp <amp@ampcode.com>
Update I26-L coverage and the Verification Design architectural-boundary row to note the no-direct-db-imports-outside-graph boundary (plus renderers/workspace isolation) is now enforced by oxlint no-restricted-imports rather than grep tests. Add lint-first guidance and a completion note to the topology-readmes-and-boundaries frontier. Amp-Thread-ID: https://ampcode.com/threads/T-019ecbe5-9952-77d9-ae20-374b0f9ad949 Co-authored-by: Amp <amp@ampcode.com>
The claimed post-build:web drizzle/sqliteTable bundle assertion does not exist. Downgrade I44-L to partially covered: architecture.test.ts guards leaf purity, the db->graph kinds-only edge, and enum-array ownership, and oxlint now forbids non-graph modules from importing db/; the transitive dist-web-Drizzle-free claim is a structural expectation, not test-verified. Amp-Thread-ID: https://ampcode.com/threads/T-019ecbe5-9952-77d9-ae20-374b0f9ad949 Co-authored-by: Amp <amp@ampcode.com>
Move co-located *.test.ts(x) into per-directory __tests__/ folders so test topology is consistent and compatible with pi auto-discovery. Tests under src/.pi/extensions/*/ stay co-located by design; src/.pi/__tests__/ keeps the cross-extension suites. Consolidate test helpers under __tests__/support/ and drop re-export shims in favor of importing from canonical locations: - graph fixture-reads helper -> src/graph/__tests__/support/fixture-reads.ts (removes the renderers/graph re-export shim) - create-only-mutation -> src/graph/__tests__/support/ - tier-2-test-support -> src/dev/__tests__/support/ Repair relative imports and import.meta.url/HERE-relative filesystem paths (fixtures, drizzle migrations, source-reading assertions, repo-root reads) for the deeper test locations. Production projection present-review-set.ts stays in src/projections/exchanges/.
Fold dedicated previews.test.ts files into per-renderer co-located __tests__/, drop lockPreview/mkdirSync/HERE scaffolding for bare toMatchFileSnapshot, move system-prompts tests into __tests__/, repoint dead test:prompts script. Goldens regenerated (trailing-newline only). Signed-off-by: Lu Nelson <ln@hash.ai>
…clustering) Refine D60-L RENDER stage: agent context adopts one dialect — md-pen markdown frame, TOON for uniform record sets, stringify-tree for hierarchy, section-tag wrappers — clustered into workspace/specification/session scopes (D19-L). The md-pen substrate is shared across renderer audiences; workspace.state print stays a product-state projection. Lexicon and renderers README reconciled.
Frontier reshaped from 'lock existing renderers' to 'adopt the context-render house style (md-pen + TOON + stringify-tree) and rewrite the scope-clustered context renders, workspace + specification first, then migrate the rest'. Add FE-870 / branch, the new library dependencies, the countTurnEntries audit and brunch-print fork as acceptance, and supersede the old prepared chain card (Cards 2-5 locked the old flat shape; re-author via ln-scope).
…+ workspace + specification) Mode: chain. Card 1 substrate adoption (md-pen + TOON + stringify-tree + section helper) is buildable now; Cards 2-3 (workspace, specification context renders) are design-gated — structural scope settled, exact output shape awaits a collaborative design pass appended before build. Retire the superseded render-stage-chain card; repoint the frontier execution pointer.
Signed-off-by: Lu Nelson <ln@hash.ai>
…+ refine D83-L TOON rule Card 2 design APPROVED: bare Label: sections (Pi no-ATX-heading policy), Project as md bullets, Specifications as md table (always), Topology as an annotated file tree (all dirs to depth 2 with recursive counts, .md leaves). Status flipped to next; substrate API + cwd-inventory extension noted for the builder. D83-L refined: TOON for large/unbounded uniform sets, md tables for small bounded rosters (size-aware, not uniformity-alone).
…+ capture graph/session-name decisions Card 2 (workspace render) verified landed (d37c8a2). Card 3 design approved and flipped to next: Overview bullets / Sessions md-table (size-aware rule) / Gaps TOON (band-then-priority); graph block deferred to the graph-render-migration card. Captures: graph design-it-twice (overview G-D, neighborhood G-C); session auto-naming as a named adjacent capability with a revise-here obligation; countTurnEntries messages-vs-turns audit. Retire HANDOFF.md.
…(boundary, risks, posture, verification, build sequencing) Names the harness-as-false-proof risk: the specification scope block has no existing caller, so the card wires a read_specification_context tool entry (mirrors read_workspace_context) rather than shipping a golden-only render. Build sequence: countTurnEntries audit first (settles the turns value/label the golden inherits), then inspection + render + golden, then tool registration. Seed re-cluster named as deferred adjacent work.
…factor (latestSessionName exists vs auto-naming)
…erview, G-C neighborhood, retire dead formatGraphSlice) Scoping found the graph render surface is three renderers of differing live-ness, not one shared render: formatGraphOverview (read_graph only; stale shared docstring), formatNeighborhood (live), formatGraphSlice + variants (dead, zero non-test callers), renderGraphSeed (separate seed render). Chain: Card 0 retire dead formatGraphSlice (buildable now), Card 1 overview => G-D (design-gated), Card 2 specification graph block, Card 3 neighborhood => G-C (design-gated). Corrected the PLAN shared-render claim.
lunelson
force-pushed
the
graphite-base/217
branch
from
52dc938 to
c4e2b0b
Compare
lunelson
force-pushed
the
ln/fe-870-renderer-golden-context-tools
branch
from
76a6f6f to
d4a7050
Compare
Merge activity
|
lunelson
added a commit
that referenced
this pull request
Jun 17, 2026
* update agent system prompt paths * chore(cards): re-retire graph-render-migration card resurrected by squash merge The FE-870 squash merge (#217, e4a63fd) reintroduced the exhausted renderer-golden-coverage--graph-render-migration.md scope card in its stale pre-build form (Cards 0-3 shown blocked/not-done), though Cards 0-3 shipped and PLAN records the scope card as retired. Re-delete it so HEAD matches bkp/ln/fe-870-renderer-golden-context-tools and PLAN's "scope card retired" state. No other canonical-doc drift from the restack.
lunelson
added a commit
that referenced
this pull request
Jun 17, 2026
* update agent system prompt paths * chore(cards): re-retire graph-render-migration card resurrected by squash merge The FE-870 squash merge (#217, e4a63fd) reintroduced the exhausted renderer-golden-coverage--graph-render-migration.md scope card in its stale pre-build form (Cards 0-3 shown blocked/not-done), though Cards 0-3 shipped and PLAN records the scope card as retired. Re-delete it so HEAD matches bkp/ln/fe-870-renderer-golden-context-tools and PLAN's "scope card retired" state. No other canonical-doc drift from the restack. * FE-873: observer relay seam for live AgentSession event streaming (topology A) SessionEventRelay forwards the in-process AgentSession event stream over the existing TUI sidecar /rpc WebSocket as brunch.sessionEvent frames, multiplexed with brunch.updated. Ephemeral/process-local; no second canonical store (D19-L, D84-L). Battery claims 1-4 production-wired; claims 5-7 are follow-on slices. Signed-off-by: Lu Nelson <ln@hash.ai> * FE-873: reconcile web-driver plan after restack --------- Signed-off-by: Lu Nelson <ln@hash.ai>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Stack Context
This stack is a post-demo rehabilitation pass. The previous PRs stabilize runtime/tooling and clarify prompt/runtime topology; this PR starts the deferred renderer/context coverage frontier.
What?
Why?
Renderer output is lossy and LLM/user-facing, so it needs golden locks plus semantic invariants. This PR focuses on that RENDER-stage coverage without making it a ship gate.