FE-806: Agent prompt-resource composition, runtime manifests, and snapshot contexts#169
Open
lunelson wants to merge 62 commits into
Open
FE-806: Agent prompt-resource composition, runtime manifests, and snapshot contexts#169lunelson wants to merge 62 commits into
lunelson wants to merge 62 commits into
Conversation
- Storage: scope cards live in memory/cards/<frontier-id>--<slug>.md (or dev--/tooling--/docs-- prefix when not a PLAN frontier) - File metadata header: Frontier, Status, Mode, Created - Multi-card scope files are a bias when conditions hold, not a sanctioned exception. Hard anti-speculation gate leads the section. - Overlap-as-independence-test: two proposed files for one frontier with overlapping primary write paths must be merged or reshaped. - Expected touched paths (tentative) section added to full cards (required) and light cards (when non-trivial), using pseudo tree with + ~ - ? markers. Doubles as a manifest for parallel-agent conflict-avoidance. - Routing updated to name scope file path explicitly when handing off to ln-build. Pairs with subsequent ln-build rewrite (Card 2) and cross-reference sweep (Card 3). Queue in memory/CARDS.md while the sweep is pending. Amp-Thread-ID: https://ampcode.com/threads/T-019e8c75-8051-73ee-a611-00c58c546cbe Co-authored-by: Amp <amp@ampcode.com>
- Hybrid selection policy: explicit path arg wins; single active file for current frontier → pick + announce; otherwise list active scope files and ask via tool-ask-question. Never scan or pick by mtime/alphabetical. - Stale-downstream invalidation: explicit re-orient checkpoint between each card in a chain. Even when ln-scope honored the hard anti-speculation gate, implementation can still surprise. Mark the rest of the chain stale and route back to ln-scope. - Per-file deletion under memory/cards/: literal paths only; never bulk on the directory or with globs. Honors AGENTS.md file-scoped-invocations rule. Partial-done files stay in place. Stale files get Status: superseded and survive for ln-sync. - Preserves: no-op commit suppression when card is already green; all 8 serial-execution stop conditions; canonical reconciliation discipline; cross-skill check before stopping. - Expected touched paths from scope card are tentative — divergence is allowed with a note; significant divergence triggers overlap-as-independence-test recheck against other active files for the same frontier. Pairs with ln-scope rewrite (Card 1, 76a2d9b). Cross-reference sweep (Card 3) follows. Amp-Thread-ID: https://ampcode.com/threads/T-019e8c75-8051-73ee-a611-00c58c546cbe Co-authored-by: Amp <amp@ampcode.com>
Mechanical update propagating the storage seam established by Cards 1+2 (ln-scope and ln-build rewrites). All 18 references to memory/CARDS.md across the family now point at scope files under memory/cards/ with consistent terminology. Touched files: - .agents/skills/ln-consult/SKILL.md (3 refs) - .agents/skills/ln-plan/SKILL.md (3 refs) - .agents/skills/ln-plan/assets/plan-template.md (1 ref) - .agents/skills/ln-handoff/SKILL.md (3 refs) - .agents/skills/ln-handoff/assets/handoff-template.md (1 ref) - .agents/skills/ln-sync/SKILL.md (5 refs; per-file deletion rule added so ln-sync respects AGENTS.md file-scoped-invocations) - .agents/skills/ln-oracles/SKILL.md (1 ref) - docs/praxis/ln-skills.md (1 ref) - docs/praxis/graphite-workflow.md (1 ref; clarified that multiple scope files for one frontier do not imply multiple branches) memory/CARDS.md (the queue file holding this work) is marked done. Cleanup of that file is the final step; surfacing as user decision per the card's 'user-call at execution time' wording. Amp-Thread-ID: https://ampcode.com/threads/T-019e8c75-8051-73ee-a611-00c58c546cbe Co-authored-by: Amp <amp@ampcode.com>
All three cards (ln-scope rewrite, ln-build rewrite, cross-reference sweep) landed in 76a2d9b, 98537ea, ee05769. Under the new regime this skill family established, scope files live under memory/cards/ and stale derivative queues are deleted per-file (ln-sync rule). This file held the work that defined that rule; honoring it here is the final tie-off. Rationale preserved in git history + thread T-019e8c75-8051-73ee-a611-00c58c546cbe. Amp-Thread-ID: https://ampcode.com/threads/T-019e8c75-8051-73ee-a611-00c58c546cbe Co-authored-by: Amp <amp@ampcode.com>
… workbench Mise-en-place Card 1 of live-graph-observer. Renames the npm package and its single bin entry to 'brunch-cli', bumps version to 0.1.0, and adds a reusable in-repo workbench cwd under .fixtures/workbenches/live-graph-observer/ so manual TUI/web smoke runs scaffold .brunch/ there rather than at the repo root. Adds src/package-identity.test.ts as a regression oracle for package name, version floor, single-bin discipline, and shim executability. Amp-Thread-ID: https://ampcode.com/threads/T-019e8cc3-ac62-7596-b46d-dee2e8be729c Co-authored-by: Amp <amp@ampcode.com>
Card 1 of live-graph-observer graph-rpc-spine. Establishes spec ownership
at storage, command, reader, tool, and runtime layers (D61-L). Every
graph projection and graph mutation now targets exactly one spec.
Storage:
nodes, edges, reconciliation_need all gain a NOT NULL spec_id FK to
specs.id. Initial drizzle migration regenerated as 0000_deep_maria_hill;
graph_clock seed re-added manually.
Domain:
GraphNode, GraphEdge, ReconciliationNeed carry specId. CommandExecutor
inputs (CreateNodeInput, CreateReconNeedInput, CommitGraphInput) now
require specId. commitGraph rejects existing refs whose spec_id differs
from the command spec (structural_illegal). validateAndResolveBatchEdge
emits explicit cross-spec diagnostics. createReconciliationNeed
validates that target edge / node-pair belongs to the command spec.
Readers:
getGraphOverview(db, specId), getNodeNeighborhood(db, specId, nodeId),
getOpenReconciliationNeeds(db, specId) are spec-scoped. Supersession
filtering is also spec-scoped. WorkspaceGraphRuntime.forSpec(specId)
returns SpecScopedReaders so callers bind once instead of threading
specId through every read.
Pi extension:
BrunchGraphDeps now requires {specId, commandExecutor, snapshots}.
Registrar binds specId from the selected session/spec at construction
time; commit_graph / read_graph tool schemas never receive specId from
the LLM. brunch-tui constructs graphDeps via graph.forSpec(workspace
.spec.id) before passing to the extension shell.
Tests:
New tracer src/graph/spec-ownership.test.ts proves the seven
acceptance criteria (ownership isolation, existing ref guard,
endpoint guard, reader guard, tool guard, schema guard).
command-executor.test.ts and snapshot.test.ts updated to seed a spec
in beforeEach and thread specId through all calls. Pi graph-tools and
review-set-proposal tests likewise updated.
Verified: npm run verify (358 tests, lint, fmt, build all green).
Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019e8cc3-ac62-7596-b46d-dee2e8be729c
Captures the comparison between howcode's 'wrap Pi as the product' Electron shell and Brunch's 'wrap Pi as infrastructure' posture. Surfaces risks already present in Brunch (private SessionManager flush dependency, RPC name drift, implicit Pi lifecycle coupling, read-model discipline pressure) with severity ratings and SPEC.md cross-references; lists rabbit holes to refuse by default; and orders prioritary debts to pay down. Amp-Thread-ID: https://ampcode.com/threads/T-019e8d96-8f2f-750c-82a9-30a18bc004ed Co-authored-by: Amp <amp@ampcode.com>
This was referenced Jun 4, 2026
Contributor
Author
|
Semgrep found 1 Detected a call to |
Adds ln-plan/references/{proving,earned}.md with posture-specific
sequencing doctrine and annotation field sets. ln-plan/SKILL.md gains
§Operating posture and Procedure Step 0 (read .pi/POSTURE.md + load
matching reference) in place of the old §Tracer-bullet sequencing.
ln-scope, ln-consult, and the praxis doc are updated to mirror the
posture split: Posture check / Posture-aware route override with
proving and earned branches.
The earned-mode reference introduces a closure move-set (materialize,
consolidate, name canonically, delete-as-progress, retire bridges,
take-the-bigger-step), a circling-recognition heuristic, sprawl
guardrails, and earned→proving regression handling. Boundaries with
ln-refactor (safe mechanics) and ln-sync (canonical GC) are explicit.
Plan-template adds mandatory Certainty: and Posture annotations:
fields to frontier definitions.
Amp-Thread-ID: https://ampcode.com/threads/T-019e91c8-a351-75ea-b7b0-29be68d448d2
Co-authored-by: Amp <amp@ampcode.com>
Pi parses slash command names as everything between the leading / and
the first whitespace, so a command registered with the literal name
'brunch:switch' is invocable as /brunch:switch -- the same trick the
built-in /skill:<name> registry uses.
Introduce src/.pi/extensions/commands.ts as the registration hub for
the /brunch:* namespace. It owns:
- /brunch:switch - opens the spec/session picker (delegates to the
runBrunchWorkspaceAction helper that still lives
in workspace-dialog.ts as private impl).
- /brunch:continue - notify-only stub for the recover/resume flow.
- /brunch:lens - notify-only stub.
- /brunch:strategy - notify-only stub.
- /brunch:mode - notify-only stub.
- ctrl+shift+b shortcut, preserved with a notify-only warning that
points at /brunch:switch (Pi shortcut contexts cannot switch
sessions yet).
workspace-dialog.ts is reduced to its private dialog action helpers
(runBrunchWorkspaceAction / runBrunchWorkspaceCommand). The retired
BRUNCH_WORKSPACE_COMMAND / BRUNCH_WORKSPACE_SHORTCUT constants,
registerBrunchWorkspaceDialog wrapper, and unused notify-only default
export are removed (pre-release posture - no compat shim).
pi-extension-shell.ts wires registerBrunchCommands in place of
registerBrunchWorkspaceDialog and updates re-exports.
Tests follow the new shape: the extension-registry smoke test now
points at commands.ts instead of workspace-dialog.ts and asserts the
full 5-command registration order; brunch-tui.test.ts uses the new
constants and exercises each stub handler to confirm the notify path.
Amp-Thread-ID: https://ampcode.com/threads/T-019e9276-ae38-770d-92de-a4dcff8b378b
Co-authored-by: Amp <amp@ampcode.com>
PR SummaryLow Risk Overview Adds Reviewed by Cursor Bugbot for commit 8a9ab43. Bugbot is set up for automated code reviews on this repo. Configure here. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 8a9ab43. Configure here.
| stance: mapping.stance, | ||
| basis: 'explicit', | ||
| rationale: edge.rationale, | ||
| }); |
There was a problem hiding this comment.
Port emits duplicate graph edges
Medium Severity
The Bilal port loop appends every mapped edge to brunchEdges without deduplicating. After decision collapse remaps multiple alternative UUIDs to one decision local_id, distinct source edges can become identical tuples (same source, target, category, and stance). Committed fixtures then contain duplicate rows, skewing edge counts and seed graph integrity.
Reviewed by Cursor Bugbot for commit 8a9ab43. Configure here.
There was a problem hiding this comment.
Pull request overview
This PR advances FE-806 by migrating Brunch prompting from the legacy src/.pi/context/ prompt-pack subtree into a new src/agents/ composition layer with code-owned resource manifests, typed selected-spec context renderers, and grade-gated tool policy. It also introduces namespaced /brunch:* commands, updates several tests and READMEs to match the new topology, and adds Bilal spec-graph ports as development seed fixtures.
Changes:
- Introduces
src/agents/prompt composition (compose.ts,state.ts) plus prompt resources (goals/strategies/lenses/methods/definitions) and context renderers (cwd/graph/node), and updates.piprompting to use these manifests and contexts. - Replaces the old
/brunchworkspace command with/brunch:switchand stubs additional namespaced commands; updates the Pi extension shell registry accordingly. - Adds
.fixtures/seed-specs/bilal-port/seed fixtures + port script, and syncs planning/docs to reflect the new delivery-cut state.
Reviewed changes
Copilot reviewed 86 out of 92 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/web/app.test.tsx | Improves RPC client disposal testing by injecting a close spy. |
| src/session/workspace-session-coordinator.ts | Exports WorkspacePostureState for use in prompt composition typing. |
| src/rpc/handlers.test.ts | Adds coverage for session.exchanges readiness behavior. |
| src/README.md | Updates repository topology notes for the new src/agents/ layout. |
| src/print-snapshot.test.ts | Fixes test typing for session manager state. |
| src/brunch-tui.ts | Wires selected-spec prompt context + dynamic graph deps into the runtime factory. |
| src/brunch-tui.test.ts | Updates command/shortcut expectations and tool activation assertions for /brunch:*. |
| src/agents/strategies/step-wise-disambiguate.md | Adds strategy resource markdown. |
| src/agents/strategies/step-wise-decision-tree.md | Adds strategy resource markdown. |
| src/agents/strategies/propose-graph.md | Adds strategy resource markdown. |
| src/agents/strategies/project-graph.md | Adds strategy resource markdown. |
| src/agents/state.ts | Implements readiness-gated manifests and elicit tool policy derivation. |
| src/agents/state.test.ts | Tests manifest/tool gating by readiness grade. |
| src/agents/README.md | Documents completed migration from .pi/context to src/agents. |
| src/agents/methods/run-structured-exchange.md | Adds method guidance resource markdown. |
| src/agents/methods/review-for-gaps.md | Adds method guidance resource markdown. |
| src/agents/methods/read-snapshot.md | Adds method guidance resource markdown. |
| src/agents/methods/infer-and-capture.md | Adds method guidance resource markdown. |
| src/agents/methods/generate-proposal.md | Renames/expands candidate proposal guidance as a method resource. |
| src/agents/methods/commit-graph.md | Adds method guidance resource markdown. |
| src/agents/lenses/oracle.md | Adds lens resource markdown. |
| src/agents/lenses/intent.md | Adds lens resource markdown. |
| src/agents/lenses/design.md | Adds lens resource markdown. |
| src/agents/index.ts | Exports new compose/state/context APIs from src/agents. |
| src/agents/goals/grounding-advance.md | Adds goal resource markdown. |
| src/agents/goals/elicit-expand.md | Adds goal resource markdown. |
| src/agents/goals/commit-converge.md | Adds goal resource markdown. |
| src/agents/goals/capture-posture.md | Adds goal resource markdown. |
| src/agents/definitions/reviewer.md | Adds agent definition resource markdown (future role). |
| src/agents/definitions/elicitor.md | Adds agent definition resource markdown (foreground agent). |
| src/agents/contexts/node.ts | Adds selected-spec node neighborhood context renderer. |
| src/agents/contexts/node.test.ts | Tests node context renderer output bounds and not-found behavior. |
| src/agents/contexts/index.ts | Barrel export for context renderers. |
| src/agents/contexts/graph.ts | Adds selected-spec graph overview context renderer with lens emphasis. |
| src/agents/contexts/graph.test.ts | Tests graph context renderer ordering/bounding. |
| src/agents/contexts/cwd.ts | Adds selected workspace/spec/session/posture context renderer. |
| src/agents/contexts/cwd.test.ts | Tests cwd context renderer content. |
| src/agents/compose.ts | Implements prompt composition output with manifests and routing rules. |
| src/agents/compose.test.ts | Tests compose output structure and manifest legality. |
| src/agents/architecture.test.ts | Enforces removal of legacy .pi/context and checks key resource content. |
| src/.pi/README.md | Updates .pi guidance: prompting is adapter-only; resources live in src/agents. |
| src/.pi/pi-extension-shell.ts | Switches shell registration to commands + prompting provider; exposes new exports. |
| src/.pi/extensions/workspace-dialog.ts | Updates messaging for /brunch:switch and trims command registration (moved). |
| src/.pi/extensions/prompting.ts | Replaces legacy prompt-pack composition with composeAgentPrompt + context renderers. |
| src/.pi/extensions/operational-mode.ts | Uses new activeToolNamesForPosture policy with readiness grade input. |
| src/.pi/extensions/graph/index.ts | Uses dynamic specId; returns typed details; uses renderNodeContext for neighborhood. |
| src/.pi/extensions/commands.ts | Adds /brunch:* namespaced commands and shortcut registration. |
| src/.pi/context/README.md | Deletes legacy prompt-pack README. |
| src/.pi/context/prompt-packs/structured-exchange.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/elicitor.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/elicit.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/capture-analysis.md | Deletes legacy prompt pack. |
| src/.pi/context/prompt-packs/brunch-base.md | Deletes legacy prompt pack. |
| src/.pi/context/compose-brunch-prompt.ts | Deletes legacy prompt-pack composer. |
| src/.pi/context/builders/structured-exchange-context.ts | Deletes legacy empty builder. |
| src/.pi/context/builders/README.md | Deletes legacy builder README. |
| src/.pi/context/builders/readiness-context.ts | Deletes legacy empty builder. |
| src/.pi/context/builders/graph-context.ts | Deletes legacy empty builder. |
| src/.pi/tests/prompting.test.ts | Updates tests to assert manifests + selected-spec context integration in prompts. |
| src/.pi/tests/operational-mode.test.ts | Updates tool policy expectations for elicit mode. |
| src/.pi/tests/mention-autocomplete.test.ts | Minor test typing/formatting update. |
| src/.pi/tests/graph-tools.test.ts | Adds end-to-end test for read_graph neighborhood content/details. |
| src/.pi/tests/extension-registry.test.ts | Updates registered commands list to new /brunch:* command set. |
| package.json | Updates build:pi-assets to package src/agents resources into dist/agents. |
| memory/PLAN.md | Syncs delivery-cut plan: marks FE-806 done; reshapes next priorities. |
| memory/cards/live-graph-observer--mise-en-place.md | Removes retired mise-en-place card. |
| memory/cards/graph-tool-resilience--graph-write-contract.md | Adds scoped chain card for graph write contract materialization. |
| docs/praxis/ln-skills.md | Adds certainty-posture sequencing guidance. |
| docs/design/REVIEW_SETS.md | Updates review-set payload description to match new graph contract direction. |
| docs/design/GRAPH_MODEL.md | Updates graph model doc (basis semantics, projections, interrogative normalization). |
| docs/archive/PLAN_HISTORY.md | Archives plan history for recently completed work. |
| .oxlintrc.json | Disables unicorn/no-empty-file. |
| .fixtures/workbenches/live-graph-observer/README.md | Updates browser feedback loop guidance to prefer agent-browser. |
| .fixtures/seed-specs/bilal-port/README.md | Documents Bilal port fixtures and mapping rules. |
| .fixtures/seed-specs/bilal-port/macro-view/spec.json | Adds seed spec metadata for Macro View. |
| .fixtures/seed-specs/bilal-port/explorer-ui/spec.json | Adds seed spec metadata for Explorer UI. |
| .fixtures/seed-specs/bilal-port/code-health/spec.json | Adds seed spec metadata for Code Health. |
| .fixtures/seed-specs/bilal-port/_port-script.ts | Adds the one-off porting script to generate Bilal seed fixtures. |
| .fixtures/runs/agents-composition-layer/runtime-posture-proof.md | Adds a deterministic proof note for FE-806 runtime posture. |
| .agents/skills/ln-scope/SKILL.md | Updates skill doc with certainty-posture handling. |
| .agents/skills/ln-plan/SKILL.md | Updates skill doc with posture-dependent sequencing rules. |
| .agents/skills/ln-plan/references/proving.md | Adds proving-posture reference. |
| .agents/skills/ln-plan/references/earned.md | Adds earned-posture reference. |
| .agents/skills/ln-plan/assets/plan-template.md | Updates frontier template to include certainty/posture annotations. |
| .agents/skills/ln-consult/SKILL.md | Updates consult routing with posture-aware guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+89
to
+93
| const METHOD_TOOL_NAMES: Partial<Record<MethodId, readonly string[]>> = { | ||
| 'run-structured-exchange': ['present_question', 'present_options'], | ||
| 'read-snapshot': ['read_graph'], | ||
| 'commit-graph': ['commit_graph'], | ||
| }; |
Comment on lines
+22
to
+25
| - **Current lock:** stable node reference codes, `basis` as | ||
| approval strength (`explicit | implicit`), non-exclusive | ||
| readiness bands, supersession acyclicity, and snapshot | ||
| graph-truth vs active-context separation. Locked. |
Comment on lines
+63
to
+82
| ## Graph basis — approval strength, not mutation path | ||
|
|
||
| ```ts | ||
| type GraphBasis = "explicit" | "implicit" | ||
| ``` | ||
|
|
||
| `basis` is shared by nodes and edges. It records whether the exact | ||
| accepted graph item was user-approved: | ||
|
|
||
| - **`explicit`** — the user directly stated the node/edge, or | ||
| approved that exact node/edge in a review set. | ||
| - **`implicit`** — the user accepted a concept/proposal, and the | ||
| agent materialized specific graph items to match it without | ||
| per-item review (the `propose-graph` direct-commit path). | ||
|
|
||
| `basis` does **not** record the mutation pathway. The pathway lives | ||
| in `change_log.operation` and payload (`commit_graph`, | ||
| `accept_review_set`, post-exchange capture, etc.). Low-confidence | ||
| inferred material still stays outside graph truth until clarified or | ||
| accepted. |
Comment on lines
+49
to
+58
| export function registerBrunchPrompting( | ||
| pi: ExtensionAPI, | ||
| promptContext: BrunchPromptContextProvider | undefined, | ||
| ): void { | ||
| if (!supportsPrompting(pi)) return; | ||
|
|
||
| pi.on('before_agent_start', async (event, ctx) => { | ||
| if (!promptContext) { | ||
| throw new Error('Brunch prompting requires selected spec and workspace context.'); | ||
| } |
lunelson
changed the title
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.
Summary
Builds the agent composition layer: prompt/runtime manifests, selected-spec snapshot context, structured-exchange posture wiring, and rich Bilal-port graph fixtures for exercising the graph-facing agent loop.
Verification
Covered by prompt composition, operational-mode, graph-tool, and seed-fixture tests; latest top-of-stack verification passed via
npm run verify.