[gilesknap]

In a long goal, state.md drifted even though it was edited every turn. Now had stray blank lines and no (nothing running). Done grew one line per agent return and ended up out of order. Decided collected events. Next and Queue still named merged items. updated= was typed by hand and was wrong. Nothing in the plugin checked the file's content. This PR adds that check and moves the most error-prone edits into goal.sh. Plugin version 0.3.0 -> 0.4.0.

Stacked on #114 (hook session ownership and the narrower Stop check): this branch is based on #114's branch and should merge after it.

Closes #108
Closes #110
Closes #111
Closes #112

Changes

• scripts/state-lint.sh <state> [<log>] [<sidecar>] (orchestrate: add a state.md lint run by the Stop and SessionStart hooks #108). Prints lint: <code>: <text> and always exits 0. Codes: now-blank, now-empty, now-finished, pending-but-done, decided-events, decided-unattributed, done-order, size, done-long, head-long, marker-stale, section-stale.
  • done-order compares the YYYY-MM-DD HH:MMZ stamps, date and time, so a goal can run over several days. Unstamped entries are placed by their label's time in log.md.
  • section-stale skips empty or placeholder-only sections, and after it reports a section it counts again from zero.
  • section-stale keeps section hashes in the goal's .lint sidecar, so the orchestrator is still the only writer of state.md.
  • Thresholds can be overridden with STATE_LINT_* environment variables.
• Hooks (orchestrate: add a state.md lint run by the Stop and SessionStart hooks #108).
  • Stop runs the lint after a turn that was substantive or wrote the state file. It passes the findings on only when the set differs from the last set it reported, kept in .lint-last. Counts and times are masked for that comparison; #N is kept. Any nudge goes out in the same message. The stop_hook_active guard is unchanged.
  • SessionStart prints the findings after the lost-agent lines, headed "fix what is wrong; a finding you judged wrong may stay", which matches the skill. They are added to goal_context in lib.sh (from orchestrate: scope the hooks to the owning session; narrow the Stop check #114), so the Stop turn that claims a goal with goal.sh start|resume shows them too.
  • As with orchestrate: scope the hooks to the owning session; narrow the Stop check #114, the hooks act only in the session that owns the goal. orchestrate: scope the hooks to the owning session; narrow the Stop check #114's ownership logic and its substantive and touched predicates are unchanged; this PR only adds the lint call and the nudge's wording.
• Size is measured in bytes (orchestrate: skill wording makes state.md grow one row per event and insert out of order #110). size flags a file over 10 KB; the pre-trim file was 98 lines but 14.7 KB. head-long flags a head over the injection cap (40 lines / 4000 bytes). The "under 150 lines" rule is gone.
• goal.sh touch (orchestrate: the model types the state.md updated= marker and gets it wrong #111). Sets updated=, and so do now and land. The skill and the Stop nudge no longer ask the model to type a time.
• goal.sh now '<entry>' and goal.sh land <label> ['<done line>'] (orchestrate: optional goal.sh helpers for the Now/Done moves (now, land) #112).
  • now adds a Now entry in place of (nothing running).
  • land drops the entry whose text contains -> <label> -> and restores (nothing running) when Now empties. Given a done line, it appends - YYYY-MM-DD HH:MMZ <text> after the last Done entry. land - '<text>' is for an item no agent ran. land also drops an entry that starts with the label, so now 'foreground: <item>' pairs with land foreground. Both keep the file's mode and fold newlines in their arguments into spaces.
  • Both rewrite Now with no blank lines and print the new Now.
  • Added because launches and returns are the most frequent state edits, and the free-form Edits caused the blank lines, the lost placeholder and the out-of-order Done. Each helper is one awk pass in goal.sh, which is already the orchestrator's own tool, so the single-writer rule holds.
• Docs: docs/how-to/use-orchestrate-mode.md gains a "The state file" section covering the format, goal.sh touch/now/land and the lint.
• SKILL.md and the template (orchestrate: skill wording makes state.md grow one row per event and insert out of order #110).
  • Now is edited only through now/land.
  • Done is the last section: one stamped line per finished item, not one per agent return. Agent returns and review rounds stay in the log.
  • Decided holds rulings only, each ending (<who>, <date>).
  • After every return or ruling, re-read the file down to ## Decided and fix what it contradicts.
  • When an item finishes, collapse its lines into its Done line.
  • The template's Done example carries the <YYYY-MM-DD HH:MMZ> prefix, and Decided's example ends (<who>, <YYYY-MM-DD>).

The lint, the skill and the helpers use one format: Now holds one line per entry or - (nothing running); Done is last, - YYYY-MM-DD HH:MMZ <text>; Decided entries end with (<who>, YYYY-MM-DD).

Testing

• bash tests/orchestrate_plugin.sh: 284 passed / 0 failed, on top of orchestrate: scope the hooks to the owning session; narrow the Stop check #114's 224. New tests:
  • A synthetic drifted fixture (tests/fixtures/orchestrate/) yields each code.
  • The goal.sh start template yields no findings.
  • goal.sh touch sets updated= to the current minute.
  • now/land work with an empty Now and a non-empty Now, an absent label, -, and repeated calls. The resulting file passes the lint.
  • Stop reports a finding set once, stays silent when it is unchanged or only a count changed, speaks again on a new finding, stays silent under stop_hook_active, and does not run after a read-only turn.
  • SessionStart shows the findings, and shows nothing for a clean file. The Stop turn that claims the goal shows them too.
• The lint was run by hand on the real pre-trim state file from the goal that prompted the issues. It reported now-blank (6), now-empty, pending-but-done (Seed a new .claude.json with {} instead of an empty file #104, gh-auth: support a second, organisation-scoped GitHub token #47, Persist local /etc/claude-sandbox.conf edits across rebuilds and updates #6), decided-events (3), decided-unattributed (3), done-order (11), size (14771 bytes) and done-long (42). On the same file after the manual trim it reported nothing.

Merge order: stacked on #114; merge it first.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AJKFfYT7qdSfhkZGj6syCo