[vernonstinebaker]

NullBoiler was the only main null-stack repo with neither an AGENTS.md nor a CONTRIBUTING.md (CLAUDE.md carries the module map, which stays authoritative there).

• AGENTS.md: engineering protocol — division of labor across the null stack, the architecture facts from recent orchestration work (BUG: strategy expansion discarded — raw body stored instead of expanded workflow (P0) #36 stored-workflow persistence, BUG: A2A dispatch uses tasks/send (v0.2) — incompatible with nullclaw A2A v0.3.0 message/send #42/fix(dispatch): align A2A protocol with v0.3.0 message/send #48/BUG: tracker dispatch mode fails before any worker HTTP — claims task, sets up workspace, never contacts tagged workers, retries exhaust silently #53 A2A URL + wire conventions, BUG: {{steps.X.output}} renders as empty string silently — worker receives blank prompt #40 strict rendering, BUG: /tracker/* endpoints block for the duration of tick() network I/O #41/fix(tracker): serve /tracker/* from tick-independent snapshot #50 snapshot serving), the known-gaps list (BUG: synchronous worker dispatch has no timeout — hung worker hangs the step forever #43/BUG: run with no eligible worker waits silently forever (no fail-fast on permanent dead-end) #44/MQTT and Redis Streams dispatch are non-functional stubs (vendored no-op hiredis/mosquitto) #32) so nobody builds on them, test/format requirements, and the no-silent-failures rule.
• CONTRIBUTING.md: contribution flow — commit gates, CI matrix expectations, regression-test mandate, docs obligations for API changes.

Docs-only; no code changes.

[DonPrus]

Checked the architecture notes against current main, the linked fixes/issues, the reusable CI configuration, and the existing CLAUDE.md. Referencing the existing module map avoids maintaining a duplicate map. The A2A URL convention, expanded-workflow persistence and published tracker snapshot match the merged code. I also checked the vendored hiredis/mosquitto sources and listener loops: the warning that those transports are stubs is justified despite their implemented-looking wrappers. Both new files merge cleanly.

One documentation clarification would be useful: on_failure.transition_to is not currently applied. Tracker.driveFailed reads on_failure.retry and eventually calls failRun; it never reads the failure transition. #52 was closed without merging. It would be great to describe the trigger naming as the intended contract while explicitly listing the unimplemented failure-transition path among the known gaps. on_success.transition_to is implemented. This avoids telling future contributors that both paths already work.

This is a pre-existing implementation gap rather than a regression from these docs; approving with that non-blocking clarification.

[vernonstinebaker]

Addressed in 18c7814, both parts of your clarification:

• Trigger bullet no longer claims both paths work. It now states on_success.transition_to is applied as the FSM trigger name (tracker.zig:1367, via resolveSuccessTrigger), and that the same naming is the intended contract for on_failure.transition_to, which is parsed but not yet applied (fix(tracker): apply the workflow's on_failure transition when a dispatch fails #52).
• Known gaps now lists it explicitly: on_failure.transition_to is parsed but never read — driveFailed reads on_failure.retry and falls through to client.failRun (fix(tracker): apply the workflow's on_failure transition when a dispatch fails #52, closed without merge).

Verified against source before writing: transition_to appears in only 3 files, and in tracker.zig only at 1367-1368 (the success path); from_json.zig/workflow_loader.zig handle parsing only. No merged PR closes #52.

Docs-only, +76/-0 across two new files. CI running; approval retained.

[DonPrus]

Rechecked 18c7814 against tracker.zig and workflow_loader.zig. The guide now correctly distinguishes the implemented success trigger from the parsed-but-unapplied failure transition and lists the latter as a known gap. The earlier documentation nit is resolved; approval stands.