Graph Next

---
name: graph-next
description: Execute ONE gated tick of a persistent goal graph created by
  /graph-goal — drift-check done nodes, pick the frontier node, do the work,
  run its acceptance gate, write status back, stop. Bounded, resumable, cheap;
  run under /loop for continuous autonomous progress.
argument-hint: "[goal-slug]"
disable-model-invocation: true
---

# Graph-next: one tick of the loop over the graph

Load `.claude/graph-state/<slug>.json` — `$ARGUMENTS` if given; if the
directory holds exactly one state file, use it; if several, list them and ask
(or, non-interactive, pick the one with the oldest last history entry and say
so). No state file → say so and point at `/graph-goal <goal>`; never invent one.

**Read `../graph/reference/goal-state.md` first** — statuses, gate kinds, and
invariants live there. The contract of this skill: **one node per tick, `done`
only through a passing gate, state written back before you stop.** A tick that
did honest work and failed its gate is a successful tick — the state now knows
something it didn't.

## The tick

**0. Validate + staleness.** Parse the JSON; check statuses are legal, deps
resolve, no cycles. Invalid → report exactly what's wrong, touch nothing, stop.
If `git rev-parse HEAD` fails (no commits yet), make the initial commit now —
the whole drift model is commit-to-commit. Any node `in_progress` is a crashed
previous tick: log it, reset per goal-state.md rule 5.

**1. Drift sweep (pure git, no judgment).** For every `done` node:

```bash
git diff --name-only <last_verified_sha> HEAD -- <watch...>
```

Non-empty → flip to `needs_reverify`, log which files moved. Uncommitted edits
to watched files count too: `git status --porcelain -- <watch...>` non-empty is
the same flip. This is what keeps Monday's "done" honest after Tuesday's
changes — committed or not. Nodes whose `done` is a logged `human-approved`
have no runnable gate; the sweep skips them.

**2. Pick one node.** Priority order, first match wins:
1. `needs_reverify` — cheapest possible tick: rerun the gate. Pass → `done` +
   fresh SHA. Fail → `pending`, attempts reset to 0 (the world changed; this is
   new work, not a failed attempt), log the output tail.
2. Frontier `pending` (all deps `done`) — prefer the one unblocking the most
   downstream nodes; tie-break by file order.
3. Nothing pending and nothing blocked → **goal-complete check**: rerun every
   `done` node's gate top to bottom (skip `human-approved` nodes — no runnable
   gate). All pass → report the goal complete with the full history ledger.
   Any fail → that node goes `needs_reverify` and the loop continues. This
   final sweep is the goal-level receipt.
4. Only `blocked`/`awaiting_human` left → stop and surface them with their
   log reasons. That's the honest answer; don't manufacture work. (A human
   resolves `awaiting_human` → `done` or `pending`, and `blocked` → `pending`,
   by editing the state file — log the decision; see goal-state.md.)

**3. Work it.** Set `in_progress`, write the file (crash marker). Then:
- `wide: false` (default): do the job **inline, in this context** — ordinary
  focused work with the node's `job` as the brief and its objective as the
  boundary. No fan-out, no subagents. This is the cheap loop.
- `wide: true`: run the node through the `graph` skill as a one-shot DAG
  (goal = the node's `job`); its Step-0 cost gate applies as usual.
- Too big for one tick? Split it: replace the node with 2–3 narrower nodes,
  same objective id, each with its own gate, deps preserved (as-needed
  decomposition beats both fixed plans and blind retries). Log the split, write
  the state, and end the tick — the next tick picks up the first piece.

**4. Gate it (the only path to done).** Run the node's acceptance:
- `harness` → run the cmd; `checks` → run all cmds. Exit code(s) decide —
  your opinion of the work does not. Pass → **commit the work first**
  (`git add -A && git commit -m "graph-next: <node-id>"` — the drift sweep is
  commit-to-commit; an uncommitted pass can't be recorded honestly), then
  `done`, `last_verified_sha = git rev-parse HEAD`, attempts reset. If you
  cannot commit, the node stays `pending` and you say why. Fail →
  `attempts += 1`, log the output tail verbatim; at 2 → `blocked` with the
  evidence, else stay `pending` for the next tick.
- `human` → do the work, set `awaiting_human`, put the specific question in
  the log. Never `done`.
- A gate that passed **before** you started the work is a broken gate
  (card-9 Tier-B: a check that cannot fail proves nothing). Fix the gate first
  — make it fail against the pre-work state — then do the work. Log the repair.

**5. Write back + report.** Append the history entry
(`{date, tick, node, action, gate, sha}`; `tick` = previous max + 1), rewrite
the file as valid JSON, and commit the state update (second small commit —
keep `.claude/graph-state/` out of `watch` lists so state commits never read
as drift), then
report in ≤10 lines: node ticked, gate result (with the command), what drifted,
the new frontier, and blocked/awaiting_human counts. Then **stop** — one node
per tick keeps every invocation bounded, resumable, and cheap enough to run
forever. For continuous operation: `/loop /graph-next <slug>`.

## Scope rules (what a tick may never do)

- Never add/edit/remove `frozen_objectives` — humans only.
- New nodes only as splits or discovered prerequisites **under an existing
  objective**, each with a machine-checkable gate. A node that serves no frozen
  objective doesn't get added; propose it via `awaiting_human` instead.
- Never mark `dropped` — propose via `awaiting_human` with the reason.
- Never set `done` from memory of a previous run, another agent's report, or
  "it obviously works" — the gate runs in this tick or the status doesn't move.