FE-698: Agent mutation audit; tool surface design

[lunelson]

FE-698 audit agent mutation surface

FE-698 settle intent graph and changeset vocabulary

FE-698 document mutation operation vocabulary

[lunelson]

• FE-705: Plan agent capability CLI frontier #127
• FE-698: On more context pack + spec for agent CLI v1 #114
• FE-698: Prompt/context scenario substrate foundation #111
• FE-698: Agent mutation audit; tool surface design #104 👈 (View in Graphite)
• FE-698: Design/spec/plan augmentation #103
• FE-698: Scenario runner + observer scenario composition #102
• FE-698: Prompt registry + observer context-pack foundation #101
• FE-698: Prompt/context substrate planning #98
• main

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

[cursor]

PR Summary

Low Risk
Documentation-only changes that don’t affect runtime behavior; risk is limited to potential terminology drift or future implementation assumptions.

Overview
Adds a new design audit (docs/design/AGENT_MUTATION_SURFACE.md) that inventories current agent-originated/adjacent durable write paths, grades boundary strength, and proposes a canonical capability/mutation-surface operation vocabulary (authority classes, <noun>.<verb> ids, and a changeset-centered model for future intent-graph edits).

Updates memory/PLAN.md and memory/SPEC.md to align roadmap/spec language with the new terminology: intent graph/intent items and changeset/change (vs. knowledge/patch), and references the audit as input to the upcoming capability registry work.

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

[augmentcode]

🤖 Augment PR Summary

Summary: This PR documents Brunch’s current agent-originated mutation boundaries and aligns future-facing vocabulary around intent-graph and changeset-ledger semantics.

Changes:

• Adds docs/design/AGENT_MUTATION_SURFACE.md, an audit of agent-originated/adja­cent durable write paths with authority class + boundary-quality classification.
• Defines a semantic operation vocabulary (<noun>.<verb>) and maps current DB-helper primitives to proposed Brunch-owned handlers.
• Calls out pressure points (observer graph writes, interviewer tools writing durable state, thin graph-edit routes) and recommends next implementation slices.
• Updates memory/PLAN.md to treat “changeset/change” as the canonical mutation-ledger vocabulary (with “patch” as historical terminology).
• Updates memory/SPEC.md to prefer “intent graph / intent items / intent edges” as the product vocabulary, while keeping knowledge_* as transitional implementation names.

Technical Notes: Documentation-only change; intended as design input for a future capability registry and server-owned mutation handler surface.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[lunelson]

@kostandinang docs/design/SIDE_CHAT.md and docs/superpowers/specs/2026-05-05-side-chat-highlight-to-note-design.md are still present at this point, should they be deleted?

[kostandinang]

Thanks for flagging @lunelson, opened a PR with the cleanup for superpowers plan and archived the design one, as it may have some design notes that may need later.

Latest approval commit 3fef067 is not an ancestor of e431537, indicating rewritten history after approval

[graphite-app]

Merge activity

• May 8, 11:05 AM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.