FE-824: Role-safe graph mutations and completion of full stack graph tools

[lunelson]

Completes the role-safe graph mutation migration across the graph command layer, Pi graph tools, review sets, capture, seed fixtures, dev RPC, probes, fixtures, and docs.

• Makes mutateGraph / mutate_graph the canonical authored mutation grammar.
• Uses role-named edge drafts at authored boundaries and normalizes to storage geometry internally.
• Retires exposed commitGraph / commit_graph residue and updates current probe/docs evidence.

Verification: npm run verify.

[lunelson]

• Remodel elicitation_backlog into elicitation_gaps obligation register #197
• Suppress Pi startup updates in Brunch TUI #196
• Align web view with structured spec patterns; scope web to TUI sidecar #195
• review skill promotions #189
• FE-830: Align with design params of main branch #187
• FE-824: Role-safe graph mutations and completion of full stack graph tools #186 👈 (View in Graphite)
• FE-825: Plan first-class developer feedback loops over the pi harness #180
• FE-811: Ship-gate rename residue and live mention autocomplete #179
• FE-823: Elicitation backlog substrate and agenda read-back #178
• FE-811: Elicitor cross-cut groundwork and read/project/render cleanup #177
• FE-809: Project-graph review-set proposal and atomic acceptance #175
• FE-807: Structured response capture into selected-spec graph truth #173
• FE-808: Broaden direct graph-tool proof beyond the A14 happy path #171
• FE-806: Agent prompt-resource composition, runtime manifests, and snapshot contexts #169
• FE-795: Live selected-spec graph observer over web RPC #166
• FE-785: M5 agent-graph-integration #163
• FE-776: Graph Layer preps #162
• FE-744: Document Pi command containment evidence #150
• FE-737: Web shell over the same host (M3) #147
• FE-736: JSONL session viability proof (M2) #146
• FE-735: Mode shell and fixture driver (M1) #144
• FE-702: Walking skeleton — brunch binary + TUI over pi (M0) #142
• next

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
Documentation, fixture metadata, and planning registers only; no runtime or mutation-path code in this diff.

Overview
Closes the commitGraph / commit_graph → mutateGraph / mutate_graph migration in docs, fixtures, and product memory so the canonical authored mutation grammar matches what the codebase already ships.

Grammar and API naming — References across docs/design/GRAPH_MODEL.md, testing guides, architecture notes, and memory/SPEC.md now describe mutateGraph / mutate_graph with { createBasis, ops }, role-named create_edge endpoints (e.g. dependency/dependent, support/claim), and change_log / dry-run wording aligned to mutate_graph and dryRunAcceptReviewSet. Dev harness docs switch from dev.graph.commitGraph to dev.graph.mutateGraph.

Planning and cross-cut status — memory/PLAN.md and memory/CROSS_CUT_PLAN.md mark role-safe-graph-mutations done (2026-06-09), retire exposed commitGraph residue in capability tables, and point follow-on work (capture, probes) at the new grammar. The superseded semantic-mutations card notes the frontier is complete.

Fixtures and evidence — Seed READMEs, port scripts, and self-spec graph copy use mutateGraph for loader validation; the checked-in 2026-06-05 fixture-curation run is labeled historical pre-migration commit_graph evidence; fresh probes should use mutate_graph. Minor hygiene: capture-quality report cwd placeholder, workbench observer smoke text.

^{Reviewed by Cursor Bugbot for commit 987861d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

This PR completes the migration from the legacy commitGraph/commit_graph batch API to the canonical mutateGraph/mutate_graph authored mutation grammar, including role-named edge endpoints and a generalized (create/patch/delete) mutation engine, while updating docs, tests, probes, and dev RPC harnesses accordingly.

Changes:

• Introduces role-named edge draft normalization/utilities and updates review-set payload shapes to use role-named endpoints.
• Adds CommandExecutor.mutateGraph planning/writer infrastructure and ports callers/tests/docs from commitGraph/commit_graph.
• Hardens probe artifact path handling with assertPortableRunId and adds residue tests to prevent machine-local paths from leaking into committed fixtures.

Reviewed changes

Copilot reviewed 96 out of 98 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/web/README.md	Updates web-side semantics to reference mutateGraph instead of commitGraph.
src/session/runtime-affordances-coverage.test.ts	Tightens affordances-derived row coverage expectations.
src/rpc/web-host.test.ts	Ports graph write test setup to mutateGraph via a create-only helper.
src/rpc/README.md	Updates dev RPC and flow documentation for dev.graph.mutateGraph + ops grammar.
src/rpc/handlers.test.ts	Ports handler tests to dev.graph.mutateGraph and adds patch/delete coverage.
src/renderers/graph/commit-result.ts	Updates renderer docs to reflect mutate_graph results.
src/renderers/graph/previews/graph-slice-brunch-self-grouped-list.md	Updates preview text from commit_graph to mutate_graph.
src/renderers/exchanges/present-review-set.ts	Uses role-named endpoint extraction for edge drafts; stance rendering updated.
src/projections/graph/commit-result.ts	Updates projection docs/types to refer to mutate_graph results.
src/projections/exchanges/review-set-payload.ts	Converts review-set edges to role-named drafts and maps them per category.
src/projections/exchanges/present-review-set.ts	Projects role-named edge drafts into details payload using category roles.
src/probes/submit-message-capture-proof.ts	Adds portable run-id assertion before constructing artifact paths.
src/probes/submit-message-capture-proof.test.ts	Adds test guarding against unsafe runId path segments.
src/probes/public-rpc-parity-proof.ts	Adds portable run-id assertion for parity proof artifacts.
src/probes/public-rpc-parity-proof.test.ts	Adds test guarding against unsafe runId path segments.
src/probes/propose-graph-commit-proof.ts	Migrates probe parsing/prompting from commit_graph to mutate_graph + runId validation.
src/probes/propose-graph-commit-proof.test.ts	Updates probe tests for mutate_graph and adds unsafe runId artifact test.
src/probes/project-graph-review-cycle-proof.ts	Adds portable run-id assertion before artifact path creation; updates wording.
src/probes/project-graph-review-cycle-proof.test.ts	Adds unsafe runId artifact test; ports edges to role-named endpoints.
src/probes/portable-report.ts	Adds assertPortableRunId utility to enforce portable single-segment run IDs.
src/probes/portable-report.test.ts	New tests for assertPortableRunId.
src/probes/fixture-curation-loop.ts	Migrates transcript evidence parsing from commit_graph to mutate_graph + runId validation.
src/probes/fixture-curation-loop.test.ts	Updates tests for mutate_graph evidence and adds unsafe runId artifact test.
src/probes/fixture-contract-residue.test.ts	Expands residue checks to include machine-local cwd tokens.
src/probes/capture-response-to-graph-proof.ts	Adds portable run-id assertion before artifact path creation.
src/probes/capture-response-to-graph-proof.test.ts	Adds test guarding against unsafe runId path segments.
src/probes/capture-quality-loop.ts	Adds portable run-id assertion for artifact writing; refines verdict wording.
src/probes/capture-quality-loop.test.ts	Updates verdict assertion and adds unsafe runId artifact test.
src/graph/workspace-store.ts	Adds spec-scoped resolveEdgeId reader for edge ownership validation.
src/graph/test-support/create-only-mutation.ts	New helper bridging legacy create-only tests to mutateGraph ops.
src/graph/spec-ownership.test.ts	Ports spec ownership tests to create-only mutateGraph helper and updated result fields.
src/graph/seed-fixtures.ts	Seeds fixtures via mutateGraph ops (role-named edges); updates error messaging and counts.
src/graph/seed-fixtures.test.ts	Updates expectations for mutate_graph change-log operation naming.
src/graph/review-set.ts	Migrates review-set translation to mutateGraph ops with role-named endpoints + stricter validation.
src/graph/review-set.test.ts	Updates review-set translation tests for role-named edges and mutateGraph dry-run.
src/graph/README.md	Updates graph module docs/topology to describe mutateGraph planner/writer split.
src/graph/read-api.test.ts	Ports read API tests to create-only mutateGraph helper.
src/graph/queries.ts	Adds resolveGraphEdgeId for edge ownership validation by spec.
src/graph/queries.test.ts	Updates reconciliation need tests for new edge id result field naming.
src/graph/mutate-graph-edge-schema.test.ts	New schema tests ensuring role-named endpoint fields across tool + dev RPC boundaries.
src/graph/index.ts	Re-exports mutateGraph types and role-named edge helpers; removes legacy commitGraph exports.
src/graph/export-fixtures.test.ts	Ports fixture export tests to create-only mutateGraph helper.
src/graph/command-executor/role-named-edge-draft.ts	New role-named edge draft types + normalization utilities.
src/graph/command-executor/role-named-edge-draft.test.ts	New unit tests for role-named draft normalization and stance locality.
src/graph/command-executor/graph-mutation-writer.ts	New writer applying create/patch/delete plans and emitting change-log payload.
src/graph/command-executor/graph-mutation-types.ts	New canonical mutateGraph input/result/op types (create/patch/delete).
src/graph/command-executor/graph-mutation-planner.ts	New planner for mixed create/patch/delete batches (builds on create-only planner).
src/graph/command-executor/create-graph-batch.ts	Renames/ports create-only planner types to graph-mutation-types inputs.
src/graph/command-executor/commit-graph-types.ts	Removes legacy commitGraph type module.
src/graph/command-executor/accept-review-set.test.ts	Updates acceptReviewSet tests for role-named endpoints + mutateGraph payload keys.
src/graph/command-executor.ts	Replaces commitGraph with mutateGraph and extracted planner/writer; adds patch validation.
src/graph/command-executor.test.ts	Ports executor tests to create-only mutateGraph helper and updated result field naming.
src/graph/capture/structured-response.ts	Ports capture writes from commitGraph nodes/edges to mutateGraph create_node ops.
src/graph/capture/structured-response.test.ts	Updates capture tests for mutateGraph results and ops-only inputs.
src/dev/introspection-launcher.ts	Adds assertPortableRunId and turn-matched passive capture selection.
src/dev/introspection-launcher.test.ts	Adds unsafe runId test + stale-capture/base-report mismatch coverage.
src/db/README.md	Updates tool shape documentation to mutate_graph({ createBasis, ops }).
src/app/brunch.test.ts	Updates dev RPC discovery expectation from commitGraph to mutateGraph.
src/app/brunch-tui.test.ts	Updates tool registration and execution path to mutate_graph.
src/.pi/skills/strategies/step-wise-disambiguate.md	Updates strategy guidance to avoid mutate_graph (formerly commit_graph).
src/.pi/skills/strategies/README.md	Updates propose-graph description to call mutateGraph.
src/.pi/skills/strategies/propose-graph.md	Updates propose-graph flow to use mutate_graph create-only ops.
src/.pi/skills/strategies/project-graph.md	Updates project-graph guidance to avoid direct mutate_graph.
src/.pi/skills/methods/commit-graph.md	Updates method guidance from commit_graph to mutate_graph (create-only posture).
src/.pi/extensions/runtime/authority-matrix.test.ts	Updates registered tool list and expected mutateGraph success shape.
src/.pi/extensions/README.md	Updates extension bundle docs to mutate_graph/read_graph.
src/.pi/extensions/introspection/index.ts	Adds capture cursor APIs and makes report-building resilient to missing ctx methods.
src/.pi/extensions/graph/tool-schemas.ts	Replaces commit_graph schema with mutate_graph ops schema (role-named edge endpoints).
src/.pi/extensions/graph/index.ts	Renames tool registration and execution to mutate_graph; updates prompt guidance.
src/.pi/extensions/graph/command-adapter.ts	Translates mutate_graph ops (role-named) to internal mutateGraph input; updates formatting.
src/.pi/extensions/exchanges/schemas/README.md	Updates review_set edge contract docs to role-named endpoints.
src/.pi/extensions/exchanges/schemas/present.ts	Updates Zod schema to union of role-named edge drafts by category.
src/.pi/agents/state.ts	Updates method→tool mapping to mutate_graph.
src/.pi/agents/state.test.ts	Updates tool gating expectations to mutate_graph.
src/.pi/tests/structured-exchange-schemas.test.ts	Updates structured exchange schema tests to role-named review-set endpoints.
src/.pi/tests/structured-exchange-present-request.test.ts	Updates present/request tests to role-named review-set endpoints.
src/.pi/tests/prompting.test.ts	Updates active tool sets and readiness gating tests from commit_graph to mutate_graph.
src/.pi/tests/operational-mode.test.ts	Updates tool list expectations to include mutate_graph.
src/.pi/tests/graph-tools.test.ts	Ports tool adapter tests and end-to-end tool test to mutate_graph ops.
package-lock.json	Adjusts pi-ai bin path to be explicitly relative.
memory/PLAN.md	Marks role-safe mutateGraph frontier as done; updates narrative to mutateGraph.
memory/CROSS_CUT_PLAN.md	Updates cross-cut plan items for mutate_graph and dev mutation engine status.
memory/cards/graph--role-named-edge-surface.md	Updates supersession note after frontier completion.
memory/cards/dev-seed-fixtures--semantic-graph-mutations.md	Updates supersession note after frontier completion.
docs/testing/seeded-dev-rpc.md	Updates seeded dev RPC guide from dev.graph.commitGraph to dev.graph.mutateGraph.
docs/README.md	Updates docs index entry to reference dev.graph.mutateGraph.
docs/design/GRAPH_MODEL.md	Updates design doc examples and operation naming to mutateGraph/mutate_graph.
docs/architecture/pi-wrapper-comparative.md	Updates architecture doc to reference mutate_graph tool.
.fixtures/workbenches/live-graph-observer/README.md	Updates observer workbench doc to mutate_graph.
.fixtures/seeds/brunch-self/spec-graph.json	Updates seed titles referencing commitGraph to mutateGraph.
.fixtures/seeds/bilal-port/README.md	Updates seed README to reflect seeding via mutateGraph.
.fixtures/seeds/bilal-port/_port-script.ts	Updates script comments to refer to mutateGraph structural validation.
.fixtures/runs/capture-quality/2026-06-08-capture-quality-sample/report.json	Normalizes committed cwd to <ephemeral-workspace>.
.fixtures/README.md	Marks old fixture-curation run as historical commit_graph evidence and points to mutate_graph.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.