Changelog

Update this repository for the breaking changes in graph v0.16.0. Older plan, tool and data files keep working as they are, so don't run any `migrate` command for this. Make only the changes below, and only where they apply.

1. **GitHub and Slack tool names.** These tools moved from graph into the `github` and `slack` packs. Search plans, agents, tools and scripts for the old names and rename every call:
   - `builtin__gh_<name>` becomes `github__tool__gh_<name>`.
   - `builtin__git_<name>` becomes `github__tool__git_<name>`.
   - `builtin__slack_post_message` becomes `slack__tool__slack_post_message`.

   Install each pack you now call with `graph pack add github` or `graph pack add slack`, unless the config already lists it under `[packs.<name>]` (see this release's Config v4 entry).
2. **Overrides of those tools.** A file under a tools directory's `builtin/` subdirectory that overrides one of the tools above now fails to load, because graph no longer ships the tool it names. Move the change into the installed copy at `.graph/packs/<pack>/tools/<name>.yaml`, then delete the override file.
3. **Run events.** A script that reads `GRAPH_EVENTS=jsonl` output and matches `llm_call` events must match `model_call` instead.
4. **Results of nested plan calls.** A `plan__<identifier>` step whose plan ends at a success `exit` now returns that plan's result shape. A failed call now returns one standard error shape. Check any template that reads fields from such a step's result, and run `graph plan validate` on each plan that calls another plan.
5. Run `graph plan validate` on every plan you changed.

**Report back:** each file you changed and why, the packs you installed, and anything you found but left alone.

This repository's graph config needs a change for graph v0.16.0 if any config file lists `github` or `slack` in `[tools].packs`. If none does, report that and change nothing: graph reads older config files as they are.

**What changed:** The `github` and `slack` tools are no longer built into graph. They install as packs, and config version 4 replaces `[tools].packs = [...]` with one `[packs.<name>]` entry per installed pack. graph refuses to load a config whose pack entry isn't installed, and names the pack.

**Steps:**

1. Run `graph config check` to see each config file's version.
2. Run `graph config migrate`, and `graph config migrate --global` if a global config exists. Do not hand-edit the result. Read the notes it prints.
3. For every `[packs.<name>]` entry the migration wrote, run `graph pack add <name>`, adding `--global` for an entry in the global config.
4. Commit `.graph/config.toml`, `.graph/packs/` and `.graph/packs.lock`. If `.gitignore` ignores `.graph/`, let `.graph/packs/` and `.graph/packs.lock` through.
5. Run `graph config check` again and confirm it loads and lists each pack as matching `packs.lock`.
6. If a CI workflow pins `ghcr.io/tylerdavis/graph:vX.Y.Z`, move the pin to `v0.16.0` in the same change. Older images refuse config version 4.

**Report back:** which config files you migrated, the notes `graph config migrate` printed, which packs you installed, and whether any image pin moved.

This release (graph v0.15.0) bumps the config file format from version 2 to version 3, adding OTLP telemetry export support via a new `[telemetry]` section. Any existing `graph` config file is now on an outdated format and must be migrated.

Do the following in this repository:

1. Locate graph config file(s). These are typically named `graph.toml` or similar, and may exist both locally (project config) and globally (user config). Search with something like:
   - `grep -rl "config_version" .` or `grep -rl "\[telemetry\]" .`
   - Also check for a global config (often under a user config directory) if you have access to it.

2. For each config file found, run:
   - `graph config check` to see whether it flags the file as needing migration.
   - `graph config migrate` for the local/project config.
   - `graph config migrate --global` if a global config is in use.

3. After migrating, verify each config file now declares config version 3 (e.g. a `version = 3` or equivalent field the migrate command writes), and confirm no plan or CI workflow is manually pinning an older config version's expectations.

4. If any plan files exist in the repo, re-validate them after the config migration:
   - `graph plan validate <plan-file>` for each plan file (search with `grep -rl "steps:" .` or similar to find plan YAML files).
   - Note: this release does not bump the plan or tool file formats, so plan/tool files themselves should not need `graph plan migrate` or `graph tools migrate` — but re-run `graph plan validate` anyway to confirm the migrated config doesn't break anything.

5. Search CI workflows for any pinned graph image reference, e.g.:
   - `grep -rn "ghcr.io/tylerdavis/graph:v" .github/workflows/`
   If found, update the pin to `ghcr.io/tylerdavis/graph:v0.15.0` in the same change as the config migration, since an older pinned image will refuse to read a config file already rewritten to version 3.

6. Do not hand-write the new `[telemetry]` keys yourself — trust `graph config migrate` to add the correct schema.

Be conservative: only touch config files and the CI image pin described above. Do not modify plan or tool files beyond re-validating them. Report exactly which files you migrated, which CI workflow pins you updated, and which files (if any) you deliberately left unchanged because they were already current or out of scope.

This repository uses `graph` config files that need to be migrated for graph v0.14.0.

**What changed:** The config file format has bumped from version 1 to version 2. The `[models.<role>]` table now replaces the old fixed role slots and the `[models.named]` section — every model is now configured as a role rather than having separate named/fixed-role slots.

**Steps to perform:**

1. Run `graph config check` first to see the current state of your config file(s) and identify what needs updating.
2. Run `graph config migrate` to rewrite your local config to version 2. If you also have a global config, run `graph config migrate --global` as well.
3. Do NOT attempt to hand-edit the `[models.*]` tables yourself — do not invent the exact key shapes. Trust the `graph config migrate` command to apply the correct rewrite (from fixed role slots and `[models.named]` to `[models.<role>]`).
4. After migrating, verify every plan file still validates correctly by running `graph plan validate` against each plan in this repository.
5. Search this repository (and any CI workflow files, e.g. `.github/workflows/*.yml`) for references to a pinned graph container image of the form `ghcr.io/tylerdavis/graph:vX.Y.Z`. If any workflow pins an older version, update the pin to `v0.14.0` in the same change as the config rewrite — an older image will refuse to read the new config version by name.
6. For full details on the schema change, consult this release's CHANGELOG.md entries titled "Graph" and "Config v2" — the "Breaking" line under "Config v2" names the schema change; do not guess beyond what `graph config migrate` applies.

**Report back:** List which config file(s) you migrated, whether a `--global` config was found and migrated, whether any CI workflow image pins were updated, and confirm `graph plan validate` passed for all plans. If you found no config files, workflows, or plans needing changes, say so explicitly and leave everything else untouched.

# Migrate graph config, plans, and tools to v0.13.0

You are upgrading the graph files in this repository — `.graph/config.toml`,
the plans under `.graph/plans/`, the user tools under `.graph/tools/`, and,
if the user asks, the global library in `~/.config/graph/` — to graph
v0.13.0. The release is backward compatible for every well-formed file:
nothing you leave untouched changes meaning. But two things need checking
before the upgrade is trusted, and one file kind can now be stamped with a
version. Be conservative: apply only the migrations below; do not
restructure unrelated steps, tools, or config.

## Prerequisites

- `graph --version` must report ≥ 0.13.0 wherever these files are read.
- If plans run in CI from the container image
  (`ghcr.io/tylerdavis/graph:vX.Y.Z`), the pin must move to ≥ v0.13.0
  **in the same PR** as any file you stamp with a `version` key (Migration 3
  below). A pre-0.13 binary reads the key as an unknown field: it refuses a
  stamped `config.toml` outright and skips a stamped plan from its catalog.
  Files load from the repo checkout but the engine comes from the pinned
  image, so the two must move atomically. Check `.github/workflows/` for
  `image:` pins.

## What v0.13.0 changes (facts to work from)

**1. Every file kind now carries a file version, separate from the binary.**
Config, plan documents, tool documents, and the data directory each have an
integer version that moves only when that file's schema changes. This
release introduces all four at **v1**, which is the schema graph has always
read — the changelog entries `Config v1`, `Plan v1`, `Tool v1`, and
`Store v1` next to `Graph v0.13.0` record the introduction and carry no
schema change. Where the version lives, and what a missing one means:

| File | Version key | Missing means |
| --- | --- | --- |
| `config.toml` (global and project) | top-level `version = 1` | version 1 |
| plan documents | top-level `version: 1` | version 1 |
| tool documents | top-level `version: 1` | version 1 |
| data directory | `<data_dir>/FORMAT`, written on first open | version 1 |

A binary reads every version in its support window and migrates older files
in memory as they load; the file on disk changes only when you run a
`migrate` command. New commands:

```text
graph version                     # binary version + the version each file kind is written at
graph config check                # each config file's version and whether the merged config loads
graph config migrate [--global]   # rewrite config.toml to the current version, comments preserved
graph plan migrate <name|path>    # rewrite one plan file to the current plan version
graph tools migrate <path>        # rewrite one user tool file to the current tool version
```

`graph config check` prints one line per config file:
`<path>	version 1	current (unstamped)` for a file with no `version` key,
`current` once stamped, `migrate` when older than the binary writes, and
`too new` / `too old` outside the window. Files graph itself writes — the
workbench's save, `plan new`, `plan draft`, `plan show` — now always carry
`version: 1`.

**2. Plan steps and tool documents are read strictly.** Before this
release, an unknown key on a *step* (top-level plan keys were already
strict) and any unknown key in a *tool* document were silently dropped.
Now they are load errors that name the key. A plan with one is left out of
the catalog with that diagnostic; a tool file with one fails the whole tool
catalog by path, so every command that builds it stops until the file is
fixed:

- A step accepts exactly `id`, `tool_name`, `input`, and `reasoning`. The
  check runs at every depth — inside `decide`'s `then`/`else` and
  `map`/`reduce`'s `do` bodies too. Error shape:
  `steps[0]: unknown field \`retries\`` or
  `steps[0].input.then[0].input.do: unknown field \`timeout\``. Keys inside
  a step's `input` are the tool's business and are not checked.
- A tool document accepts `name`, `description`, `input_schema`,
  `output_schema`, `read_only`, `kind`, `version`, plus the keys of its
  `kind`: `exec` → `command`, `args`, `env`, `cwd`, `timeout_secs`,
  `output`; `prompt` → `prompt`, `system`, `model`, `caller_output_schema`,
  `caller_model`; `reshape` → `shape`, `caller_shape`. Error shape:
  `unknown field(s) \`tmeout_secs\` for a \`exec\` tool`.

**3. The `[prompts].workbench` override no longer carries the tool rules.**
The rules describing what each `workbench__*` tool does to the draft are
now appended after the override and cannot be replaced by it. The override
is framing and policy only: how the agent should behave in the workbench,
when it may run or save, whether it reads the project. Previously the
override was the agent's *only* description of those tools, so `graph config
init` wrote the full tool list into it and customizations started from
that text.

**4. `graph --version` prints two lines** (`graph 0.13.0` then
`file versions: config 1, plan 1, tool 1, store 1`). `-V` still prints the
binary version alone; `graph version --json` reports `fileVersions` with
`oldest` and `current` per kind.

**5. The data directory gains a `FORMAT` marker** on first open, holding the
store version. A data directory that was previously read-only at open will
now fail to open until the marker can be written once.

## Migration 1 — REQUIRED: find files the strict reader now rejects

Run, from the repository root:

```text
graph plan list --json | jq '.skipped'
graph tools list
```

Every entry under `skipped` whose reason contains `unknown field` is a plan
that loaded before this release and no longer does. If `graph tools list`
fails with `<path>: unknown field(s) ...`, fix that file and run it again —
one bad tool file hides the rest of the catalog. For each hit, open the
file and decide which of two cases it is:

- **A misspelling of a real key** (`tool_name` written as `toolname`,
  `timeout_secs` as `timeout`): fix the spelling. The key was being ignored,
  so the file's behavior changes — a timeout that was never applied now
  is. Say so in your report.
- **A key that was never part of the grammar** (`retries`, `notes`,
  `enabled`, ad-hoc annotations): delete it. If it carried intent worth
  keeping, move it into `reasoning` on a step or `description` on a tool,
  both of which are free text.

Before:

```yaml
steps:
  - id: E1
    tool_name: user__fetch_issues
    input: { project: "{{input.project}}" }
    retries: 3
    note: flaky on Mondays
```

After:

```yaml
steps:
  - id: E1
    tool_name: user__fetch_issues
    input: { project: "{{input.project}}" }
    reasoning: flaky on Mondays; the tool retries internally
```

Do the same sweep over the global library (`~/.config/graph/plans/`,
`~/.config/graph/tools/`) if the user asks for it. Also grep for step keys
the catalog cannot report because the plan is hidden by unconfigured
`requires_servers`: `graph plan validate <name>` opens those from disk.

## Migration 2 — REQUIRED where present: trim the workbench prompt override

Grep `.graph/config.toml` and `~/.config/graph/config.toml` for a
`workbench` key under `[prompts]` whose value mentions `workbench__`:

```text
grep -n 'workbench__' .graph/config.toml ~/.config/graph/config.toml
```

If the override contains tool descriptions (`workbench__show_plan reads any
catalog plan…`, `workbench__load_plan REPLACES the draft…`, and so on), it is
a copy of the old built-in text. Those rules are now appended after the
override by graph itself, so the copy is redundant at best and, as the tools
evolve, a stale contradiction of the real rules at worst.

- If the override is an unmodified copy of the old default, **delete the
  key** and let the built-in framing apply.
- If it was customized, **keep only the framing and policy** — the
  sentences about how the agent should behave, when it may run or save,
  whether it reads the project — and drop every line that describes what a
  `workbench__*` tool does.

Before:

```toml
[prompts]
workbench = """
# Plan workbench
You are running inside the graph plan workbench. Never run or save without asking.
Operate on that draft with the workbench tools:
- workbench__show_plan: read any catalog plan's YAML without touching the draft...
- workbench__load_plan: open a DIFFERENT plan the user explicitly names...
"""
```

After:

```toml
[prompts]
workbench = """
Build the draft plan with the user. Never run or save without asking.
"""
```

## Migration 3 — RECOMMENDED: stamp files with their version

Stamping is optional — an unstamped file is read as v1 — but it is what
future upgrades key on, and a stamped file is refused by name, with the
version it found and the versions the binary reads, instead of failing with
an unknown-field error when a later schema moves. Only do this once the
Prerequisites hold everywhere the files are read (in particular, the CI
image pin).

```text
graph config check
graph config migrate               # ./.graph/config.toml
graph config migrate --global      # ~/.config/graph/config.toml, if the user asked for the global library
graph plan migrate <name>          # once per plan file in .graph/plans/
graph tools migrate <path>         # once per tool file in .graph/tools/
```

What the rewrites do:

- `config migrate` writes `version = 1` as the first key and leaves every
  other line, comment, and table where it was. A file already stamped is
  left untouched.
- `plan migrate` and `tools migrate` rewrite the document through the YAML
  tree, so field order survives. A **leading comment block** (lines before
  the first key) is preserved verbatim; comments elsewhere in the file are
  dropped and the command reports how many. If a plan or tool carries
  comments below its first key that the user wants to keep, either add
  `version: 1` as the first key by hand instead of running `migrate`, or
  move those comments into `reasoning` / `description` first.

Commit the stamped files together with any image-pin change.

## Migration 4 — AWARENESS: scripts that parse `graph --version`

Grep workflows and scripts for `graph --version`. Anything that expects a
single line (`graph --version | awk '{print $2}'`, a version-gate in a
Makefile) should switch to `graph -V` for the bare binary version or
`graph version --json` for the structured form.

## Verify

1. `graph version` reports `0.13.0` or newer, and
   `file versions: config 1, plan 1, tool 1, store 1`.
2. `graph config check` exits 0 and shows every config file as `current`
   (or `current (unstamped)` if you skipped Migration 3).
3. `graph plan list --json | jq '.skipped'` is empty, or contains only
   plans that were deliberately left broken (say which and why).
4. `graph plan validate <name>` for every plan you touched — must pass.
5. `graph tools list` builds the catalog without naming any file.
6. If the workbench override changed, open `graph wb plan` on a scratch plan
   and confirm the agent still edits the draft with the `workbench__*` tools.
7. Report per file: what was found, what changed, and validation status.
   List the files you inspected and deliberately left alone, with the
   reason.

# 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.