doc-behavior-state-machines

Packet · {{ repo }} · behavior/state-machines.md

1. Objective

Produce {{ docs_root }}/behavior/state-machines.md: one H2 per state machine in {{ repo }}, each containing exactly one Mermaid stateDiagram-v2 block that reflects the states and transitions declared in source, followed by a path:LOC citation to the definition site.

2. Scope

• Create: {{ docs_root }}/behavior/state-machines.md
• Do not touch: {{ docs_root }}/behavior/processes.md, any other file under {{ docs_root }}/, any source file in the repo, .context.md, .prefetch.md, or any .packets/*.md other than this one.
• Conditional file — this packet is only seeded when sql(WHERE kind='StateMachine') returns ≥ 2 rows. The state-machine count is carried in {{ context_path }} § State machines; the orchestrator verified the count before spawning.

3. Input specification

Source	Read how	Cache state
Shared context	Read {{ context_path }}	always first
Prefetch ledger	Read {{ prefetch_path }}	always first
State-machine inventory	{{ context_path }} § State machines (count + names + paths)	cached
State-machine nodes (detail)	mcp__codehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='StateMachine'"})	mid-run, only if .context.md slice is truncated
States + transitions per machine	mcp__codehub__context({symbol: <machine-name>})	mid-run
Verbatim state/transition text	Read <file_path>:<start_line>	mid-run

4. Process

1. Read {{ context_path }} and Read {{ prefetch_path }}. Confirm .context.md § State machines lists ≥ 2 machines. If the slice is truncated, call the sql fallback in Section 3.
2. For each state machine: call mcp__codehub__context({symbol: <machine-name>}) to pull states, entry state, transitions, and terminal states.
3. For each machine: Read the definition file at start_line..start_line+60 to verify state names and transition labels before drawing. Do not invent transitions.
4. Draft state-machines.md with H1 = {{ repo }} · State machines. One H2 per machine, in alphabetical order by machine name. Under each H2: exactly one fenced Mermaid stateDiagram-v2 block, then a single-line Defined at: <backtick path:LOC> citation.
5. Transitions use the source-level event name as the Mermaid edge label (e.g., start(), complete()). Do not paraphrase event names.
6. Write {{ docs_root }}/behavior/state-machines.md.