FE-776: Graph Layer preps

[lunelson]

add pi dev posture doc

FE-776: Add Brunch Pi profile boundary

FE-776: Seal Brunch Pi settings policy

FE-776: Prove runtime state transcript contract

FE-776: Wire runtime state posture tests

docs(archive): prune legacy-carryover and preface plan history

archive/docs/ is reduced from a full pre-next docs/ tree carryover to
the single load-bearing reference (SPEC_WORKSPACE_GRAPHS.md, still
linked from docs/architecture/prd.md). Legacy copies whose canonical
form lives on the brunch main branch are deleted; nothing unique is
lost.

docs/archive/PLAN_HISTORY.md gains a preface preserving the 2026-05-20
'Pre-POC archive and reseed' origin entry and the 2026-05-22 sync
archive (web-shell initial/hardening/tie-off/judo-review slices and
the original walking-skeleton brief), which only existed in the
carryover PLAN_HISTORY.md before this commit. The doubled
archive/archive/... link inside the jsonl-session-viability entry is
replaced with a plain main-branch pointer.

Amp-Thread-ID: https://ampcode.com/threads/T-019e7d8c-ab82-7507-b2e5-8351c5821202
Co-authored-by: Amp amp@ampcode.com

graph(edges): lock and materialize Phase 1 edge model

Consolidates the edge layer into a single canonical reference and the
minimal type stubs that present-design-claim it. Nodes are deferred
to Phase 2 and called out as such in the doc.

Eight closed structural edge categories (dependency, proof, support,
realization, boundary, composition, association, supersession) with
endpoint roles, single stance enum required only for proof and
support, and a binary basis (explicit | accepted_review_set) — no
status field, no inferred basis, no named-relation catalogue. The
agent chooses category; tuple-specific labels are derived at
projection time and cannot change category policy.

ReconciliationNeed is a separate substrate that references edges
(default) or node-pairs (for not-yet-existing relations like possible
duplicates). It is not itself a graph edge.

Files:

• docs/design/GRAPH_MODEL.md canonical edge-layer reference
• src/graph/atoms.ts NodeId / EdgeId / Lsn
• src/graph/schema/edges.ts GraphEdge + closed enums
• src/graph/schema/reconciliation-need.ts ReconciliationNeed shape
• src/graph/policy/category-policy.ts per-category policy table
• src/graph/index.ts public graph-layer exports

Retirements:

• docs/design/GRAPH_EDGE_CATEGORIES.md moved to archive/ with a
  pointer to GRAPH_MODEL.md as canonical successor.
• docs/architecture/pi-seam-extensions.md §'Edge types' annotated as
  retired; the M4 named-relation catalogue (validates / instance_of /
  produces / discharges / depends_on / derived_from / counterexample_for /
  witnesses) maps into the eight categories per GRAPH_MODEL.md
  §'Worked examples'. The oracle-plane node schemas in that doc are
  not retired.

Drizzle table definitions, structural validators, the linkX command
surface, and projection builders all land in subsequent M4/M5 slices.

Verify: green (fmt:check, lint 0/0, typecheck, 253 tests, build).
Amp-Thread-ID: https://ampcode.com/threads/T-019e7d8c-ab82-7507-b2e5-8351c5821202
Co-authored-by: Amp amp@ampcode.com

docs(memory): ln-sync SPEC.md and PLAN.md to locked edge model

Reconcile memory/SPEC.md and memory/PLAN.md to the Phase 1 edge
lock-and-materialize landed at 100585a and the canonical edge
contract in docs/design/GRAPH_MODEL.md.

SPEC.md:

• A7-L: drop retired "relation policy" promotion path; reframe as
  Phase 2 node-shape concern.
• A14-L: edge-draft wording is now category-typed per GRAPH_MODEL.md;
  add D51-L dependency.
• D7-L: add Phase 2 hook for framing_as carrier question.
• D8-L: recon-need targets {kind:'edge'} | {kind:'node_pair'};
  retire "concerns-edge" wiring; refined by D51-L.
• D9-L: note decision stays a plain node (not hyper-edge) for POC.
• D27-L: edge drafts use {category, sourceId, targetId, stance?,
  basis}, not free-form relation.
• D51-L (new): closed eight-category edge set + separate
  ReconciliationNeed substrate; canonical contract in
  docs/design/GRAPH_MODEL.md; supersedes pi-seam-extensions §Edge
  types, relation-policy registry, brainstormed edge taxonomy,
  concerns-edge wiring.
• I6-L: recon-need target shape; impasse-needs-two-nodes rule
  replaced by node_pair target.
• Lexicon: structural legality references closed edge categories
  and immutable accepted-edge identity; reconciliation need points
  at edge|node_pair target shape.

PLAN.md:

• A7-L: same wording fix as SPEC.
• A14-L: same wording fix as SPEC.
• graph-data-plane: add GRAPH_MODEL.md to design docs; current
  execution pointer reflects Phase 1 lock landed plus stubs under
  src/graph/; Phase 2 nodes still pending.
• Recently Completed: 2026-05-31 entry for Phase 1 edge lock.

Amp-Thread-ID: https://ampcode.com/threads/T-019e7d8c-ab82-7507-b2e5-8351c5821202
Co-authored-by: Amp amp@ampcode.com

docs(plan): ln-sync active frontier to prep envelope

• FE-744 / pi-ui-extension-patterns tied off; detailed definition moved
  to docs/archive/PLAN_HISTORY.md under a 2026-06-01 Sync archive section.
• sealed-pi-profile-runtime-state promoted to Active as the expanded
  M4 prep envelope on ln/fe-776-graph-layer-prep-profile, carrying two
  strands: (a) Pi harness sealing, (b) graph-model lock-and-materialize
  (Phase 1 edges landed; Phase 2 nodes + A20-L Drizzle spike remaining).
• graph-data-plane narrowed to M4 CRUD proper, queued as Next behind
  the prep envelope.
• Recently Completed trimmed to last three entries; dependencies block
  updated to match active sequencing.

Amp-Thread-ID: https://ampcode.com/threads/T-019e7d8c-ab82-7507-b2e5-8351c5821202
Co-authored-by: Amp amp@ampcode.com

Reconcile graph planning docs

Amp-Thread-ID: https://ampcode.com/threads/T-019e82ff-d6d1-74fb-a574-ec31f359b31e
Co-authored-by: Amp amp@ampcode.com

spec: record grill findings — source topology (D52-L), commitGraph batch tool (D53-L), propose-graph direct-commit path, strategy/lens axis split

New decisions:

• D52-L: source topology src/{.pi, agents, db, graph, session, rpc, web}
  with directed layer dependencies
• D53-L: commitGraph atomic batch mutation with intra-batch refs

Updated decisions:

• D25-L: strategy/lens axis split (interaction shape × topical focus)
• D26-L: three commitment mechanisms (single-exchange, review-set, direct-commit)
• A14-L: commitGraph as primary proof target

New invariants:

• I34-L: commitGraph all-or-nothing batch validation
• I35-L: multi-level graph context snapshots

Lexicon: commitGraph, propose-graph, project-graph
Future direction: agents/ axis layout (modes/strategies/lenses/contexts)

Amp-Thread-ID: https://ampcode.com/threads/T-019e830f-381b-755a-9437-cbed9c54d22e
Co-authored-by: Amp amp@ampcode.com

plan: integrate grill findings into graph-data-plane and agent-graph-integration

• Context: add architecture grill summary (D52-L, D53-L, D26-L, D25-L)
• A14-L: rename to graph-mutation structural legality, commitGraph as
  primary proof target, flag as highest-stakes assumption
• graph-data-plane: add commitGraph batch tool (D53-L, I34-L), D52-L
  source topology, graph snapshot readers (I35-L), numbered execution
  pointer steps
• agent-graph-integration: add propose-graph direct-commit path,
  commit-graph tool in layout, D52-L directory references, A14-L proof
  as primary objective

Amp-Thread-ID: https://ampcode.com/threads/T-019e830f-381b-755a-9437-cbed9c54d22e
Co-authored-by: Amp amp@ampcode.com

stub: D52-L source topology with README docs and commitGraph in GRAPH_MODEL

New directories with README.md files documenting layer ownership,
dependency direction, target file layout, and migration notes:

• src/README.md — top-level topology diagram and dependency arrows
• src/agents/README.md — strategy×lens table, context building diagram
• src/db/README.md — persistence substrate scope and constraints
• src/session/README.md — session domain with migration table
• src/graph/README.md — current vs target state, commitGraph description

GRAPH_MODEL.md: add commitGraph §Agent-facing command surface with
tool call shape, intra-batch/existing ref modes, CommandExecutor
processing steps, and all-or-nothing invariant (I34-L)

Amp-Thread-ID: https://ampcode.com/threads/T-019e830f-381b-755a-9437-cbed9c54d22e
Co-authored-by: Amp amp@ampcode.com

Phase 2 node lock: 10 intent kinds in 3 categories, common node shape with detail JSON column, provenance retired from edges and nodes, framing_as retired

GRAPH_MODEL.md:

• Promote nodes from deferred to locked
• GraphNode shape: id, plane, kind, title, body, basis, source, detail, LSN fields
• Per-plane kind enums (intent: 10 kinds in basic/structural/reasoning)
• Per-kind detail schemas (decision, term, constraint)
• Drop provenance from GraphEdge (change_log owns audit)
• Retire framing_as section
• Update commitGraph example with detail field

SPEC.md:

• D54-L: node shape locked
• D55-L: provenance retired from edges and nodes
• D56-L: intent kind categories (basic/structural/reasoning)
• D57-L: grounding gate (LLM-judged + count floor)
• I36-L: kind enum + category derivation invariant
• I37-L: detail per-kind validation invariant
• A7-L retired (framing_as absorbed)
• D7-L retired (framing_as modality)
• I7-L retired (framing_as matrix)
• Lexicon: thesis, term, node source, node detail, intent kind category, posture
• Future direction: framing_as resolved, posture noted as spec-level

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

graph: Phase 2 node stubs, retire EdgeProvenance

• Create src/graph/schema/nodes.ts with GraphNode, NodePlane, NodeKind,
  IntentKind/OracleKind/DesignKind/PlanKind, IntentKindCategory,
  DecisionDetail/TermDetail/ConstraintDetail, and intentKindCategory().
• Remove EdgeProvenance interface and provenance field from GraphEdge
  (change_log owns audit trail).
• Export all new node types from src/graph/index.ts.

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

Promote invariant to first-class kind, drop ConstraintDetail, add modality/source-question rubric

• invariant promoted from constraint subtype to structural-category kind
• ConstraintDetail/ConstraintSubtype removed (body text carries subtlety)
• GRAPH_MODEL.md: modality-of-claim + source-question table for agent prompting
• GRAPH_MODEL.md: prompting guidance section (requirement duality, invariant vs constraint, thesis role)
• D54-L, D56-L, I37-L updated to reflect invariant promotion and detail simplification
• nodes.ts: IntentKind adds invariant, intentKindCategory maps it to structural
• index.ts: ConstraintDetail/ConstraintSubtype exports removed

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

Add context as basic-category intent kind with promotion heuristic

• context: descriptive claim, last-resort basic bucket with promotion table
• 11 intent kinds total (4 basic, 4 structural, 3 reasoning)
• GRAPH_MODEL.md: kind table, promotion heuristic in prompting guidance
• SPEC.md: D56-L updated, context lexicon entry added
• nodes.ts: IntentKind + intentKindCategory updated

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

ln-plan/ln-sync: Phase 2 node lock reflected in PLAN execution pointer and sequencing

• Sequencing summary: both phases locked, only A20-L spike remains
• Execution pointer: Phase 2 commits referenced, remaining items updated
• Acceptance: Phase 2 marked done with commit range
• A7-L assumption pressure: retired
• Design doc reference: Phase 1 + Phase 2 locked

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

Add decision-capture criteria to prompting guidance, fix commitGraph example residue

• Decision guardrails: 5-point criteria + rejected.length >= 1 enforcement
• Fix commitGraph example: constraint no longer carries subtype detail
• Add invariant node to commitGraph example

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

Stub strategies/ and lenses/ READMEs with M5 prompt-pack inputs

• strategies/README.md: observer classification guide, translation table
• lenses/README.md: topology-driven question ranking heuristics
• Both reference archived INTENT_GRAPH_SEMANTICS.md as source material

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

GRAPH_MODEL.md: add pointers to strategies/ and lenses/ for prompt-level guidance

Amp-Thread-ID: https://ampcode.com/threads/T-019e835d-11aa-70d5-8095-d4531afe9c94
Co-authored-by: Amp amp@ampcode.com

A20-L spike: validate Drizzle persistence seam for M4 CRUD

Spike validated the persistence toolchain for graph-data-plane:

• drizzle-orm@0.45.2 + drizzle-kit@0.31.10 + better-sqlite3@12.8.0
• drizzle-typebox@0.3.3 + @sinclair/typebox@0.34.14 for row schemas
• Batch commitGraph-shaped transaction (multi-node, ref resolution,
  multi-edge, LSN allocation, change-log) atomic with full rollback
• Pi tool params (typebox v1.x) and Drizzle row schemas (@sinclair/
  typebox v0.34) serve different roles; shared enum arrays bridge both

A20-L promoted to validated in SPEC. D16-L updated with settled stack.
PLAN execution pointer updated; session display names is the sole
remaining item before prep envelope tie-off.

Amp-Thread-ID: https://ampcode.com/threads/T-019e83af-1293-769a-a02e-a0df221c7318
Co-authored-by: Amp amp@ampcode.com

Session display names: generate, persist via session_info, render in chrome

New sessions get a display name derived from spec title + session ordinal
(e.g. 'My spec — session 2'). The name is persisted as a Pi session_info
entry so it survives reload. chromeStateForWorkspace populates session.label
from the name, falling back to session id when absent. Resumed sessions
preserve their existing display name.

This is the last item in the sealing strand of sealed-pi-profile-runtime-state
(FE-776). The prep envelope is ready to tie off.

Amp-Thread-ID: https://ampcode.com/threads/T-019e83af-1293-769a-a02e-a0df221c7318
Co-authored-by: Amp amp@ampcode.com

Plan: tie off sealed-pi-profile-runtime-state (FE-776), unblock graph-data-plane

Frontier marked done. Both strands complete. graph-data-plane (M4 CRUD)
status updated to next/unblocked. Recently Completed entry added.

Amp-Thread-ID: https://ampcode.com/threads/T-019e83af-1293-769a-a02e-a0df221c7318
Co-authored-by: Amp amp@ampcode.com

Stub db/ persistence substrate; derive graph/ enum types from single source

Stub db/schema.ts (Drizzle tables for nodes, edges, graph_clock,
change_log, reconciliation_need), db/connection.ts (better-sqlite3
lifecycle), and db/row-schemas.ts (drizzle-typebox derived schemas).

Graph domain types in graph/schema/edges.ts and graph/schema/nodes.ts
now derive EdgeCategory, EdgeStance, EdgeBasis, IntentKind, OracleKind,
DesignKind, PlanKind, and NodeBasis from db/schema.ts const arrays
instead of redeclaring string literal unions. Single enum source flows
from db/ → graph/ → Pi tool params (via typebox v1.x separately).

Amp-Thread-ID: https://ampcode.com/threads/T-019e83af-1293-769a-a02e-a0df221c7318
Co-authored-by: Amp amp@ampcode.com

Document enum-flow topology in db/README.md

Amp-Thread-ID: https://ampcode.com/threads/T-019e83af-1293-769a-a02e-a0df221c7318
Co-authored-by: Amp amp@ampcode.com

M4 skeleton: CommandExecutor with single-node proof-of-life

Stand up the CommandExecutor as the single public mutation boundary
for graph truth (D4-L, D20-L). One SQLite transaction per command:
structural validation → LSN allocation from graph_clock → node insert
→ change_log append → structured result return.

Acceptance:

• createNode for all four planes with kind-per-plane validation
• decision/term detail schema validation (closed, per GRAPH_MODEL.md)
• CommandResult discriminants: success, structural_illegal, needs_human,
  policy_blocked, version_conflict (last three are M6 placeholders)
• graph_clock seeded at lsn=0; monotonic increment per command
• change_log entry per successful command with operation + payload
• Transaction atomicity: validation failure writes nothing
• I26-L architectural boundary test: no src/ outside graph/ imports db/

Schema corrections:

• NodeId/EdgeId: string → number (matches SQLite auto-increment)
• edges table: add missing updated_at_lsn column (per GRAPH_MODEL.md)
• connection.ts: initSchema pushes DDL + seeds graph_clock

Verified: npm run verify (check + test + build) — 279 tests pass.
Amp-Thread-ID: https://ampcode.com/threads/T-019e83d7-3670-767f-b9b0-aa7e611abdc1
Co-authored-by: Amp amp@ampcode.com

Plan: update graph-data-plane execution pointer — steps 1-2 landed

Amp-Thread-ID: https://ampcode.com/threads/T-019e83d7-3670-767f-b9b0-aa7e611abdc1
Co-authored-by: Amp amp@ampcode.com

commitGraph: atomic batch mutation with intra-batch ref resolution (D53-L, I34-L)

Add CommandExecutor.commitGraph — the propose-graph strategy's
load-bearing tool. One tool call creates an entire subgraph (nodes
and edges) in a single transaction with one LSN.

Processing pipeline:

1. Validate all batch nodes structurally (reuses createNode validation)
2. Check for duplicate batch refs
3. Transaction: allocate LSN → insert nodes (build ref→id map) →
   verify existing-node refs → validate + resolve edges →
   insert edges → append change_log → return success
4. On any failure: entire batch rejected, transaction rolled back

Acceptance (22 new tests, 44 total):

• Intra-batch refs ("n1", "n2") resolve to real NodeIds
• Existing refs ({ existing: id }) verified against database
• Edge structural validation: closed category set, stance required
  iff proof/support, stance forbidden for other categories,
  self-loop rejection, missing ref rejection
• I34-L all-or-nothing: edge validation failure rolls back inserted
  nodes — no partial writes, no LSN bump
• Edge-only batches, node-only batches, empty batch rejection
• Mixed intra-batch + existing refs in same edge
• One LSN per batch, one change_log entry per batch

New types: CommitGraphInput, CommitGraphSuccess, CommitGraphResult,
BatchNodeInput, BatchEdgeInput, BatchEdgeRef.

Verified: npm run verify (check + test + build) — 301 tests pass.
Amp-Thread-ID: https://ampcode.com/threads/T-019e83d7-3670-767f-b9b0-aa7e611abdc1
Co-authored-by: Amp amp@ampcode.com

Plan: update graph-data-plane execution pointer — steps 1-4 landed

Amp-Thread-ID: https://ampcode.com/threads/T-019e83d7-3670-767f-b9b0-aa7e611abdc1
Co-authored-by: Amp amp@ampcode.com

add graph snapshot readers: cursory overview + node neighborhood (I35-L)

Two read functions in graph/snapshot.ts:

• getGraphOverview: full-graph cursory overview with all nodes/edges,
  current LSN, and superseded-predecessor exclusion
• getNodeNeighborhood: BFS traversal with configurable hop depth,
  supersession filtering, and not_found error shape

Types re-exported through graph/index.ts. 10 new tests (311 total).

Amp-Thread-ID: https://ampcode.com/threads/T-019e83f6-44c9-741a-a90a-9e9535774b3d
Co-authored-by: Amp amp@ampcode.com

plan: mark step 5 (I35-L snapshot readers) done in execution pointer

Amp-Thread-ID: https://ampcode.com/threads/T-019e83f6-44c9-741a-a90a-9e9535774b3d
Co-authored-by: Amp amp@ampcode.com

add reconciliation-need substrate: create, resolve, and query open needs

CommandExecutor gains createReconciliationNeed (validates edge/node_pair
target existence, allocates LSN, appends change_log) and
resolveReconciliationNeed (rejects non-existent or already-resolved).
getOpenReconciliationNeeds reader in snapshot.ts returns typed domain
objects. Oracle-plane stub acceptance already met by existing createNode

• ORACLE_KINDS. 11 new tests (322 total).

Amp-Thread-ID: https://ampcode.com/threads/T-019e83f6-44c9-741a-a90a-9e9535774b3d
Co-authored-by: Amp amp@ampcode.com

plan: mark graph-data-plane (M4) done, advance sequencing to agent-graph-integration (M5)

Amp-Thread-ID: https://ampcode.com/threads/T-019e83f6-44c9-741a-a90a-9e9535774b3d
Co-authored-by: Amp amp@ampcode.com

sync: update invariant coverage (I26/34/35/36/37-L), trim PLAN recently-completed, add FE-785 for M5

Amp-Thread-ID: https://ampcode.com/threads/T-019e83f6-44c9-741a-a90a-9e9535774b3d
Co-authored-by: Amp amp@ampcode.com

[lunelson]

• FE-795: Track live graph observer frontier #166
• FE-785: M5 agent-graph-integration #163
• FE-776: Graph Layer preps #162 👈 (View in Graphite)
• 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

High Risk
Introduces the authoritative graph write path, persistence schema, and contract changes that all future agent/UI mutations depend on; mistakes in batch atomicity or structural validation would corrupt graph truth.

Overview
FE-776 closes the M4 prep envelope and graph-data-plane: Brunch now treats docs/design/GRAPH_MODEL.md as the canonical graph contract (closed edge categories, locked intent node kinds, separate ReconciliationNeed substrate) and retires the old named-relation / relation-policy direction—GRAPH_EDGE_CATEGORIES is archived with a successor pointer; pi-seam-extensions edge-type catalogue is annotated retired.

Runtime/graph layer: Adds src/db/ (Drizzle + SQLite) with enums flowing db/ → graph/, and CommandExecutor as the sole mutation boundary—createNode, atomic commitGraph with intra-batch refs (D53-L, I34-L), reconciliation-need create/resolve, and getGraphOverview / getNodeNeighborhood readers (I35-L). memory/SPEC.md and memory/PLAN.md are ln-sync’d (D52-L source topology, grill decisions, Phase 2 node lock, A20-L spike validated); prep frontier tied off and M5 agent-graph-integration queued next.

Pi harness: Adds .pi/POSTURE.md, sealed profile/runtime-state work (including session display names in chrome), and README stubs under src/{agents,db,session,graph}/ documenting layer ownership.

Docs hygiene: Shrinks archive/docs/ carryover (legacy design/plan history deleted or consolidated; PLAN_HISTORY preface for pre-POC reseed entries where applicable).

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

[augmentcode]

This pull request is abnormally large and would use a significant amount of tokens to review. If you still wish to review it, comment "augment review" and we will review it.

[graphite-app]

Merge activity

• Jun 2, 6:30 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.