mex-statechart

MEX statechart

Make behavior easier for a human to understand. Generate only on user intent. If a diagram would obscure the explanation, use a better explanation. A prior agent answer identifies the subject; verify it independently against current code.

1. Identify the bounded subject, reader, and implemented/proposed/agreed-model scope. Read current source and useful tests. Query mex wiki query "<subject>" --limit 5 --json before broad knowledge discovery; inspect matched terms and grounding health, then read live records. Fall back to Router-directed Markdown if unavailable. Use bounded mex timeline --query "subject" --file known/path --limit 10 --json only when history might matter. Verify historical applicability. Fresh Graph may locate evidence; call edges are not state transitions. Never refresh indexes on a read.
2. Retain context only when it changes or explains a state, event, condition, rule, exception, recovery, or abstraction. Record the precise connection and provenance. Keep source/requirement conflicts visible. Omit irrelevant context; do not manufacture a MEX contribution.
3. Read the baseline modeling workflow and runtime instructions. Preserve TLA+ and real TLC checks in normal generation. Reuse agreed rules with provenance; seek agreement only for new inferred rules or material conflicts. Never weaken a rule to get a passing result.
4. Work outside the repository in scratch space. Use the bounded scripts/runtime.mjs workflow entry, not the unbounded original scripts directly. Preserve existing TLA+ reference specifications and their authored configurations unchanged. Both from-spec and agreed-chart directions, settled-state rules, narrower observation points, projected overviews, independent regions, goals, proposed fixes and reference comparisons remain available.
5. Assemble and validate the v1 artifact described in artifact contract. Retain models, configs, mapping, rules, raw temporal traces, omissions, toolchain and regeneration. Use stable identities, not captions. Run check on the artifact to record actual TLC results. For finite traces, map every numbered state/action back to the same graph and retain raw counterexamples. Goals are expected reachability witnesses, never product bugs. Use runtime summary counts, not counts inferred from the drawing. Missing mappings leave alignment unverified. Projection.json is optional: without it, or when check leaves the diagram unverified, accept and disclose that; never write your own TLC output parsers to force a projection. If TLC is unavailable (run status), still assemble the artifact with the check left unavailable and continue to step 7: the picture never depends on Java or TLC.
6. Attempt each modeled implementation bug through real observable code entry points. Separate what execution reproduced, what source inspection supports, and what was not reproduced. Revisit the model when reproduction disagrees. A passing model proves only the configured model and bounds; unavailable/cancelled/resource-limited checking is never success.
7. Run show <artifact> <scratch-dir> once: it prints the deterministic text view and writes the artifact's own diagram.mmd and diagram.png. Deliver by client:
   • Claude Code (terminal and desktop app) does not render Mermaid. Paste the text view in a fenced text block, then always open the printed diagram.png with your file-reading tool, unasked: the desktop app shows it inline. Make that read its own step: first write one short sentence such as "Here is the diagram:", then read the PNG with no other tool call before or after it, because the desktop app collapses grouped tool calls into a small thumbnail. Do not embed the image as Markdown; local image links do not render. In the terminal show also opens the image in the system viewer; tell the user, and give the path. Never present raw Mermaid as the diagram there.
   • Clients with native Mermaid, such as Codex: deliver the artifact's fenced Mermaid first, and the text view for nested or parallel charts. Never hand-draw the diagram as text art; show produces both views. If the image is unavailable, say so and give the .mmd path. Keep domain labels readable; details belong beside the overview. Disclose every material omission. Inspect the image and numbered paths as generation QA. State diagram validity, checker outcome, implementation reproduction, and evidence freshness separately.
8. register the validated artifact into the repository's ignored temporary preview store; this is checkout-only and nothing is shared. Keep its returned route and 24-hour expiry. Offer to open the specific diagram in Hub: for example, "Want me to open this in Hub? I can start it for you." When this repository's live Hub URL is already known, provide a clickable "View this diagram in Hub" link directly to the preview. Otherwise offer to start Hub; do not make the user run a command and find Diagrams themselves. Accepting the offer, or directly asking to open it, authorizes normal Hub startup and browser opening without another confirmation. Follow Opening the preview in Hub to preserve authentication and open the returned preview route. Generation alone does not launch Hub; never invent a localhost URL. Hub Save still requires its own exact review; commit/push remains separate. Regeneration creates a new preview and never updates old evidence baselines.