Changelog - graph

August 4, 2026

Track review findings as living threads

The github pack now includes gh_pr_review_threads and gh_pr_thread_sync, letting plans read and sync GitHub PR review threads. graph_review_9000 findings are recorded as ongoing review threads rather than one-off comments, so review state stays current across plan runs.

Changelog docs are generated by graph itself

The release changelog page is now published in lockstep with each release, with summaries and migration prompts inferred by a graph plan and rendered as themed prose rather than raw commit dumps. The page now reuses changelog snippets instead of embedding duplicate content, and the old shell-script based changelog process has been replaced entirely by graph plans.

Smoother releases

The release script now keeps the docs release_version in step with the actual release, and the changelog_entry instruction no longer leaks literal template syntax into generated output.

Added

add gh_pr_review_threads and gh_pr_thread_sync to the github pack
track graph_review_9000 findings as living review threads

Documentation

publish a release changelog page, generated in lockstep with releases
correct the escaping-mechanism comment in cliff-docs.toml
infer a per-release summary and migration prompt via a graph plan
keep inferred summaries MDX-safe
drop the changelog page description and intro line
replace the changelog shell scripts with graph plans
place the migration prompt between summary and commit lists
restyle changelog summaries as themed prose
reference changelog snippets instead of embedding them

Fixed

release script keeps the docs release_version in step
keep literal template syntax out of the changelog_entry instruction

August 4, 2026

Run plans from anywhere

graph now serves its plans over MCP, so editors, agents, and other MCP clients can run and author plans without touching the terminal.

Smarter control flow

Plans can pause to ask a person for input — and declare what happens when nobody is there — and can narrow a list down before working through it, which keeps automations from tripping over items they can’t handle.

Sharper diff awareness

Changed-file listings now say what happened to each file, not just that it changed.

A cleaner scripting surface

Command output is structured and consistent across the CLI; scripts that scraped the old text output should switch to --json.

Migration required — a prompt for your coding agent

Existing plans may need updating. Copy this prompt into your coding agent in the repository that carries your plans:

# Migrate graph plans to v0.10.0

You are upgrading the graph plans in this repository — and, if the user asks,
their global library in `~/.config/graph/plans/` — to graph v0.10.0. The
release is fully backward compatible: any plan you leave untouched keeps
working. But one common composition is *latently broken* and must be
migrated wherever it appears, and two workaround patterns can now be
simplified. Be conservative: apply only the migrations below; do not
restructure unrelated steps.

## Prerequisites

- `graph --version` must be ≥ 0.10.0 wherever these plans run.
- If plans run in CI from the container image
  (`ghcr.io/tylerdavis/graph:vX.Y.Z`), the image pin must move to ≥ v0.10.0
  **in the same PR** as any plan change that uses the new features — plans
  load from the repo checkout, but the engine comes from the pinned image,
  so they must move atomically. Check `.github/workflows/` for pins.

## What v0.10.0 adds (facts to work from)

**1. A `filter` control step** — partitions a list by evaluating a gate once
per element:

```yaml
- id: E2
  tool_name: filter
  input:
    over: "{{E1.changes}}"          # must render to an array
    where:                          # per-element; {{item}}/{{index}} in scope
      value: "{{item.status}}"
      op: ne                        # eq|ne|gt|lt|gte|lte|empty|not_empty|contains
      to: deleted
```

- Exactly one of `where` (logical, zero LLM calls) or `infer` (a yes/no
  question judged per element — costs one judge call per item; optional
  `concurrency`, and `model` to pin the verdict model).
- Result: `{items: […], count, dropped: […], dropped_count}` — both halves,
  input order. Empty input or an empty result is a value, not an error.
- `filter` is the one control step allowed **inside** `decide`/`map`/`reduce`
  bodies. There, its own `{{item}}`/`{{index}}` shadow the enclosing body's
  inside the gate — reference the outer element only in `over`.
- A gate referencing a field an element lacks fails the step (plans fail
  hard). Filter before iterating rather than expecting per-item failures.

**2. `builtin__git_changed_files` now returns `changes`** alongside the
unchanged `files`/`count`: one object per file —
`{path, status, old_path, additions, deletions, binary}` — where `status` is
`added|modified|deleted|renamed|copied|type_changed` and `old_path` is set
for renames/copies. Rename detection is now pinned on (`-M`): a rename is
always a single `renamed` entry for its new path, no longer varying with the
machine's `diff.renames` config.

## Migration 1 — REQUIRED: reading changed files at a ref

Find every plan where `git_changed_files` output feeds a `map` over
`builtin__git_file` (or any tool that reads a path at a ref). Grep for
plans containing both `git_changed_files` and `git_file`, and for
`over:` referencing `.files`. This composition crashes on any diff
containing a deletion (the path no longer exists at `head`).

Before:

```yaml
- id: E1
  tool_name: builtin__git_changed_files
  input: { base: "{{input.base}}", head: "{{input.head}}", prefix: "" }
- id: E4
  tool_name: map
  input:
    over: "{{E1.files}}"
    do:
      tool_name: builtin__git_file
      input: { path: "{{item}}", ref: "{{input.head}}" }
```

After (insert a filter; note `{{item}}` becomes `{{item.path}}`):

```yaml
- id: E1
  tool_name: builtin__git_changed_files
  input: { base: "{{input.base}}", head: "{{input.head}}", prefix: "" }
- id: E1b
  tool_name: filter
  input:
    over: "{{E1.changes}}"
    where: { value: "{{item.status}}", op: ne, to: deleted }
- id: E4
  tool_name: map
  input:
    over: "{{E1b.items}}"
    do:
      tool_name: builtin__git_file
      input: { path: "{{item.path}}", ref: "{{input.head}}" }
```

**Critical companion fix:** if a later prompt/template enumerates the file
list and pairs it positionally with the map's results ("numbered to match
the contents below"), rebuild that numbered list from the SAME array the
map iterates (`{{#E1b.items}}{{@index}}. {{path}}{{/E1b.items}}`) — never
from `{{E1.files}}`, which would desynchronize paths from contents. Keep
deletions visible by adding a separate overview section iterating
`{{#E1.changes}}` (path, status, `+{{additions}}/-{{deletions}}`) so the
migration adds context rather than hiding it.

## Migration 2 — RECOMMENDED: retire selection workarounds

- **User exec tools that exist only to filter** a prior step's list (jq/grep
  wrappers, e.g. around `git diff --diff-filter`): replace with a `filter`
  step over the structured field, and delete the tool if nothing else uses
  it.
- **Whole-list LLM selection** (an `infer` step asked "which of these are
  X?" returning a subset): replace with `filter` + `infer` asking the
  question per item. Mind the cost — one judge call per element — and set
  `concurrency`. Keep whole-list inference only for genuinely cross-item
  questions (ranking, dedup).
- Do NOT soften tools that fail loudly on missing data as a substitute —
  loud failure on a truly unexpected path is the designed behavior; `filter`
  exists so plans stop asking for paths that cannot exist.

## Migration 3 — AWARENESS: rename semantics

If any plan gates on `count` or pattern-matches `files` in a repo where
`diff.renames` was disabled, note that renames now surface as one entry
(new path) instead of a delete+add pair. `old_path` on the `renamed`
entry carries the origin.

## Verify

1. `graph plan validate <name>` for every plan you touched — must pass.
2. Where feasible, run the plan against a scratch input in a repo that
   contains a deletion and a rename (use `GRAPH_STORAGE=memory` and a
   temp `.graph/config.toml` to keep real state out of the run).
3. Report per plan: what pattern was found, what changed, and validation
   status. List plans you inspected and deliberately left alone, with the
   reason.

Added

add —json to graph tools list
add —json to graph tools show
serve graph’s plans and authoring commands over MCP
stream progress and honor cancellation
ask steps — put a question to the user from inside a plan
filter steps — partition a list with a per-item gate
per-file change objects on git_changed_files

Changed

return outcomes from the plan commands instead of printing
convert the remaining commands and make —json uniform

Documentation

add a plan authoring skill for the CLI commands
point the authoring loop and quickstart at the plan authoring skill
make the authoring skill draft-first
frame the skill around the whole plan lifecycle
document graph as an MCP server
close out the MCP roadmap and point the skill at the server
explain why the draft arm cannot use and_then

Fixed

write every plan field in snake_case, at every depth
remove revision-by-redraft from both authoring surfaces
don’t load a project the user never pointed at
honour the documented ask retry budget
serve the control steps from the tool catalog
keep MCP writes inside the server’s own config layer

July 30, 2026

Ride out provider outages

Model entries can declare fallbacks, so a failing provider fails over to the next instead of failing your run.

Let a step figure it out

The new agent step runs a bounded tool-calling loop inside a plan for the parts you cannot script ahead of time — and still returns typed results the rest of the plan can reference.

More places to plug in

GitHub release and log tools, a Slack pack for posting messages, and full plan management from the command line.

Added

model fallbacks for provider outage failover (#67)
add the agent control step
add gh_release and git_log to the github pack
add slack pack with slack_post_message
manage plans from the command line

Changed

lift plan authoring rules into graph-core
draft plans one validated step at a time, always

Documentation

rework intro/quickstart, add project-setup skill, tidy release asset names (#65)
escape curly braces in template-language frontmatter (#66)
reorganize the docs — plans-first IA, one owner per fact
coherence pass after the reorg — catalog table parity, models links
restructure the workbench page; split the exit-gates opener
generate workbench screenshots from executed sessions
inline Frame embeds — Mintlify snippets don’t interpolate props into JSX attributes
place workbench screenshots across the reorganized pages
rewrite quickstart manual setup to mirror the fast path
replace the introduction’s plan-run snippet with a workbench hero shot
document the agent control step
document the plan authoring commands
ship an app manifest and a one-click create-app button

Fixed

show never-run steps as skipped after a fired exit gate
add fallbacks field to the shots harness ModelChoice
close the agent step’s validation, path, and boundary gaps
enable the slack pack in the repo-carried config
carry exit codes back to main instead of exiting in place
keep plan list and validate off stdout
stop re-rendering caller-supplied reshape shapes

July 17, 2026

A plan’s root node in the workbench now shows its metadata, inputs, and finish up front, alongside a handful of scrolling and selection fixes.

Added

show plan metadata, input schema, and finish on the root node (#61)

Fixed

wheel over steps/tool list moves selection (#60)
gh_pr_ticket default pattern requires a separator (#62)
wheel scrolls the steps/tool list view (#63)
hide list highlight when selection scrolls out of view (#64)

July 17, 2026

Steadier plan drafting

Drafts are built incrementally — an outline, then one validated step at a time — and invalid drafts can be edited or repaired instead of discarded.

Pick the right model per call

Prompt tools, inference steps, and gates can each name a model, so cheap checks stay cheap and hard calls get the strong model.

Sturdier CI reviews

The PR-review building blocks grew marker-keyed comments, ticket extraction, and file reading at a ref, and tool resolution is now checked before a plan spends a single step.

Added

write the built-in system prompts into the config init starter (#44)
steer check plans to explicit exits and list inference to map (#45)
named models selectable from prompt tools and builtin__infer (#46)
marker-keyed PR comments, ticket extraction, and file/grep at a ref (#47)
catalog-aware tool resolution before any step runs (#49)
incremental draft strategy — outline, then one validated step per inference (#50)
edit input_schema, requires_servers, and silent finish via update_metadata (#51)
mouse support — click to focus, switch tabs, select rows, wheel-scroll (#55)
add data pack with builtin__reshape for shape projection (#58)
optional per-gate model override on exit/decide infer (#59)

Documentation

add graph-github-actions-setup skill for coding agents (#42)

Fixed

render sub-text and borders with the terminal’s dim modifier (#43)
PR reviewer no longer emits absence false positives on truncated diffs (#40)
paste literally, edit invalid drafts, repair bad drafts, fence agent-only tools (#48)
separate outline and drafting phases in workbench trace (#52)
show span start time on the left and duration on the right; surface outline call duration (#53)
order trace chronologically so draft_plan brackets its phases; fix outline duration origin (#54)
carry failing tool error into aborted run result (#56)
default output_schema type + reset workbench iteration budget on progress (#57)

July 15, 2026

A workbench for plans

A dual-pane TUI for drafting and test-running plans: research the project, make precise step-level edits, and watch runs unfold without leaving the terminal.

Simpler storage

Plan and thread state now lives in plain files — nothing to install or run alongside graph.

Projects carry their setup

Config discovery is project-first, so a repository can ship its own graph setup, and step ids can be any descriptive identifier.

Added

replace LadybugDB with file-based storage (#24)
plan workbench — dual-pane TUI for drafting and test-running plans (#25)
workbench debug logging to <data_dir>/workbench.log (#28)
workbench step view shows body sub-steps and the finish stage (#30)
workbench read_file/grep/glob tools for researching the project (#29)
step ids are any unique identifier, not just E-numbers (#31)
workbench tools for precise plan edits: update_metadata, add_step, update_step, delete_step (#33)
[prompts] config overrides for the chat prompt and workbench addendum (#37)
project-first config — config init and default search paths target ./.graph (#38)
draft safety, control-step guidance, turn-failure recovery (#36)

Documentation

cookbook covers a custom bot identity for the CI reviewer (#23)
add @emichy to special thanks (#26)
require worktrees for all coding work in CLAUDE.md (#39)

Fixed

scrolling reaches wrapped content; PgUp/PgDn is the one scroll binding (#27)
draft saves can no longer overwrite a different plan’s file (#32)
section-scoped bare keys are not roots in plan validation (#34)
a broken plan file no longer takes down the whole catalog (#35)

July 11, 2026

Branch execution with decide steps

Plans can now include decide steps that fork execution into then and else branches based on a gate, letting you author plans with conditional logic instead of separate plans per outcome. The gate keyword for a decide step is if.

Iterate over lists with map and reduce

map and reduce steps run a body of steps over each item in a list, so repetitive per-item work no longer needs to be unrolled manually in the plan.

Inline PR review comments

The pr_review tool now anchors its findings as inline diff comments on the pull request, rather than only surfacing them elsewhere.

Added

decide steps fork plan execution into then/else branches (#15)
decide gates read if/then/else — the logical gate keyword is now if (#17)
map and reduce steps iterate a body over a list (#18)
pr_review anchors findings as inline diff comments (#20)

July 10, 2026

Clearer tool listings

graph tools list now groups related tools together and displays them in a tighter, easier-to-scan layout.

Added

grouped listing for graph tools list, tighter layout (#14)

July 10, 2026

graph mcp tools now groups its output by server, and release publishing is atomic — assets can no longer go missing from a published release.

Added

group graph mcp tools output by server (#11)

Documentation

rewrite README, add MIT license (#12)

Fixed

create releases atomically — assets can’t be added after publish (#13)

July 10, 2026

Run graph without building it

Published container images make graph drop-in for CI and containerized environments, and search extensions are vendored into the binary so nothing needs installing alongside it.

Built-ins, organized

Bundled tools now live under one namespace with a dedicated docs page, and new cookbook sections collect worked examples by solution.

Added

publish a container image with each release (#4)
vendor lbug fts/vector extensions into the binary (#9)
builtin__ namespace for bundled tool packs, Built-ins docs page (#10)

Documentation

CI cookbook — the dogfooded plans and workflow, annotated (#7)
cookbook as a section — pages by solution category (#8)

July 10, 2026

Bundled tool packs and CI failure annotations

graph now ships with tool packs included, so plans can call common tools without separate setup. Running plans in GitHub Actions also produces failure annotations, making it easier to spot what went wrong directly in the workflow run.

Added

bundled tool packs and GitHub Actions failure annotations (#2)

Fixed

portable version bump in release.sh; align workspace version with v0.2.0

July 10, 2026

End plans early, on purpose

Plans can now use exit gates to stop execution with an explicit success or error state, instead of running to the end or failing on an unrelated step.

Build plans from other plans

Plans can now call other plans, so you can compose larger workflows out of smaller, reusable pieces rather than duplicating steps across files.

Added

exit gates — end a plan early with success or error state
plan composability — plans call plans

Documentation

bring CLAUDE.md current — composability, exit gates, storage, build story, conventions

July 10, 2026

The first release of graph: author plans — YAML pipelines of tool calls with data flowing between steps — validate them, and run them from the terminal. A built-in agent loop backs ask and chat for conversational work, tools come from your own definitions or any MCP server, and configuration is layered so a repository can carry its own setup.

Added

ladybug spike (validated) + layered config crate
clap command tree, tracing, working config show/init/path
provider trait, Anthropic + OpenAI-compat providers, structured output with repair, role router
rmcp manager — stdio + streamable-http transports, lazy connect, tool discovery with namespacing and overrides, ToolRegistry impl
ReAct loop + ask/chat/tools commands
thread persistence + observed-shape cache (phase 3)
unify thread continuation under —thread
strict typed template engine for the {{Ex.path}} dialect
plan pipeline — planner/validation/execution/solver with bus-driven replanning
YAML plan docs, plans-as-tools, plan_and_execute (phase 4 complete)
JSON input documents for plan run and tools test
nested tool display, pipeline progress, streamed solver
optional solver — plans can render structured output or run silently
backend abstraction — dyn Store everywhere, memory backend
user-defined tools — exec, cypher, and prompt kinds
schema defaults for plan/tool inputs; fmt fixes
codify release process — semver bump, git-cliff changelog, tag-driven binaries
run traces — tools_used in ask envelope, GRAPH_EVENTS=jsonl event stream

Documentation

Mintlify documentation site (25 pages) + CLAUDE.md
point repository URLs at the real remote
fix clone directory in installation
touch content to trigger first build
remove build-trigger scratch line
plans-first framing of core concepts
quickstart — freeze-into-a-plan step
plan-first nav order and README framing; drop unverified heading anchors

Fixed

shut down servers before runtime teardown; silence child stderr
read the shape cache at each planning attempt
steps_executed excludes the input root
replace RUSTFLAGS with per-target build.rs link directives

​Track review findings as living threads

​Changelog docs are generated by graph itself

​Smoother releases

​Added

​Documentation

​Fixed

​Run plans from anywhere

​Smarter control flow

​Sharper diff awareness

​A cleaner scripting surface

​Added

​Changed

​Documentation

​Fixed

​Ride out provider outages

​Let a step figure it out

​More places to plug in

​Added

​Changed

​Documentation

​Fixed

​Added

​Fixed

​Steadier plan drafting

​Pick the right model per call

​Sturdier CI reviews

​Added

​Documentation

​Fixed

​A workbench for plans

​Simpler storage

​Projects carry their setup

​Added

​Documentation

​Fixed

​Branch execution with decide steps

​Iterate over lists with map and reduce

​Inline PR review comments

​Added

​Clearer tool listings

​Added

​Added

​Documentation

​Fixed

​Run graph without building it

​Built-ins, organized

​Added

​Documentation

​Bundled tool packs and CI failure annotations

​Added

​Fixed

​End plans early, on purpose

​Build plans from other plans

​Added

​Documentation

​Added

​Documentation

​Fixed

Track review findings as living threads

Changelog docs are generated by graph itself

Smoother releases

Added

Documentation

Fixed

Run plans from anywhere

Smarter control flow

Sharper diff awareness

A cleaner scripting surface

Added

Changed

Documentation

Fixed

Ride out provider outages

Let a step figure it out

More places to plug in

Added

Changed

Documentation

Fixed

Added

Fixed

Steadier plan drafting

Pick the right model per call

Sturdier CI reviews

Added

Documentation

Fixed

A workbench for plans

Simpler storage

Projects carry their setup

Added

Documentation

Fixed

Branch execution with decide steps

Iterate over lists with map and reduce

Inline PR review comments

Added

Clearer tool listings

Added

Added

Documentation

Fixed

Run graph without building it

Built-ins, organized

Added

Documentation

Bundled tool packs and CI failure annotations

Added

Fixed

End plans early, on purpose

Build plans from other plans

Added

Documentation

Added

Documentation

Fixed