# Typed Graph Agent Playbook Decantr's typed graph gives AI coding assistants a queryable model of the product contract, current route context, evidence, and repair surface. Use it when an agent needs structured context instead of prose-heavy markdown packs. ## Operating Model The graph is local to the app and generated by: ```bash decantr graph --project apps/web ``` That command writes: - `.decantr/graph/graph.snapshot.json` - `.decantr/graph/snapshots/.json` - `.decantr/graph/graph.manifest.json` - `.decantr/graph/graph.diff.json` - `.decantr/graph/contract-capsule.json` The Contract capsule is the cache-friendly session artifact. Route context and impact context are follow-up reads against the snapshot. Accepted project `behavior_obligations` from `.decantr/local-patterns.json` are projected into the graph as existing `LocalRule` nodes, not as a new UX schema. Their node ids follow `rule:behavior::`, with `payload.kind = "behavior-obligation"`, and they link back to the project, matching Pattern node when one exists, and the `.decantr/local-patterns.json` SourceArtifact. ## Default Agent Flow 1. Call `decantr_project` with `{ "action": "state" }` and inspect its `adoption_truth` projection before trusting app scope or provenance. 2. If graph artifacts are missing or stale, run `decantr graph --project apps/web`; task activation deliberately blocks until the graph is current. 3. Before route work, call `decantr_context` with `{ "action": "task", "route": "/feed", "task": "..." }`. The compact default is adapted from `TaskCapsuleV1`: it leads with the required rank-one implementation source and includes graph freshness, authority, changed-file impact, stable findings, content identity/digest provenance, stop conditions, and one verify command. Its canonical budget is 12,000 UTF-8 bytes / 4,000 deterministic estimated tokens. Use `"detail": "full"` only for expanded diagnostics outside the default capsule budget. 4. Call `decantr_contract` with `{ "action": "capsule" }` near session start when broader source handles are needed. 5. Before changing a shared node or known source file, call `decantr_graph` with `{ "action": "query", "node_ids": [...], "include_impact": true }` or a `file_path` query. 6. After edits, run the verify command returned by task context. Evidence Bundles include provenance for the graph snapshot, manifest, diff, and contract capsule. Treat a missing provenance entry with `present: false` as "the graph has not been generated for this repair loop yet," and treat changed graph hashes as a reason to refresh graph context before applying a repair. ## Route Context Use route context when the task is page-scoped: ```json { "project_path": "apps/web", "route": "/feed", "task": "improve recipe card loading" } ``` The response preserves the route, page, shell, composed patterns, components, tokens, local rules, behavior-obligation local rules, style bridge mappings, findings, evidence, provenance, and ranked nodes expected by existing integrations. CLI JSON identifies the canonical source with `taskCapsuleVersion: "task-capsule.v1"`; MCP uses `task_capsule_version: "task-capsule.v1"`. The capsule is not duplicated as a nested payload. Ranking combines deterministic weighted traversal, local personalized PageRank, and task-text boosts so central nodes and task-relevant nodes both rise. CLI equivalent: ```bash decantr graph --project apps/web --route /feed --task "improve recipe card loading" --json ``` MCP task context also surfaces accepted behavior obligations before an edit: ```json { "local_law": { "behavior_obligations": [ { "pattern_id": "confirmation-dialog", "role": "confirmation-dialog", "intent": "Confirm destructive account actions without accidental execution.", "obligations": [ { "id": "accessible-name", "label": "Dialog has an accessible name.", "severity": "error", "evidence": "static" } ], "risk_profile": ["accidental-destruction", "focus-loss"], "test_hints": ["keyboard path smoke test", "focus return assertion"] } ] } } ``` Agents should inspect these obligations before editing dialogs, forms, destructive actions, menus, or other interactive surfaces. They are app-owned local law: preserve project primitives and architecture first, then use WCAG tooling, Playwright, axe, Storybook, or project tests for behavioral evidence Decantr cannot prove statically. ## Impact Context Use impact context when the task touches a shared component, token, rule, finding, or source artifact: ```json { "project_path": "apps/web", "node_id": "cmp:button", "task": "change button disabled styling" } ``` When the agent knows a source path but not the internal graph node ID, pass `file_path`; Decantr resolves it to the matching `SourceArtifact` node: ```json { "project_path": "apps/web", "file_path": "src/app/page.tsx", "task": "edit page source" } ``` For query-first workflows, use the same impact extractor through `decantr_graph`: ```json { "action": "query", "project_path": "apps/web", "node_ids": ["cmp:button"], "include_impact": true, "task": "change button disabled styling" } ``` ```json { "action": "query", "project_path": "apps/web", "file_path": "src/app/page.tsx", "include_impact": true, "task": "edit page source" } ``` The response answers graph-shaped blast-radius questions: affected routes, pages, patterns, components, tokens, local rules, findings, evidence, repairs, and source artifacts. Use traversal when the agent needs a precise relation walk instead of a ranked impact subgraph. For example, this returns graph nodes that point at a route implementation file: ```json { "project_path": "apps/web", "file_path": "src/app/page.tsx", "direction": "in", "relations": ["NODE_DERIVED_FROM_SOURCE"] } ``` CLI equivalent: ```bash decantr graph --project apps/web --node cmp:button --impact --task "change button disabled styling" --json decantr graph --project apps/web --file src/app/page.tsx --impact --task "edit page source" --json ``` ## Historical Reads Use `snapshot_id` to query a previous graph reality: ```json { "project_path": "apps/web", "snapshot_id": "graph:previous", "route": "/feed" } ``` Use `compare_to` when the agent needs the diff between snapshots: ```json { "project_path": "apps/web", "compare_to": "graph:previous", "include_diff_ops": true, "limit": 50 } ``` This is graph-local temporal evidence. `GovernanceDeltaV1` composes it with a Git comparison base, compatible health baseline, stable finding occurrences, contract/content/source identities, and evidence freshness. Findings are partitioned into new, inherited, resolved, and unclassified; incomplete or incompatible evidence yields `not_proven` rather than an empty delta. Request that report explicitly with `decantr ci --report-version v3 --since --json`. ## Repair Plans When Project Health findings have graph anchors, `decantr_repair` with `{ "action": "repair_plan" }` includes the anchor and an impact context for the anchored node. Agents should use that impact context to preserve adjacent routes, components, tokens, local rules, and evidence while applying the typed repair action. Use `decantr_repair` with `{ "action": "health_loop" }` after verification when the agent needs the shared v2 loop verdict, authority resolution, and evidence tier before deciding whether to continue, repair, or ask a human.