Lifecycle Diagram

Lifecycle diagram

Contract

Inputs

The user must supply these inputs; never invent them:

• Entity or process name.
• Every state with its kind (the user's facts about statuses, waits, recoverable failures, and terminals).
• Every legal transition between states.

Optional:

• Ordered phases and lanes.
• Transition guards (waiting conditions), decision conditions, and retry counts.
• Output directory and filenames; defaults are <entity>.lifecycle.json and <entity>.lifecycle.html in the current working directory.

Procedure

1. Bound scope before any write: fix the output directory and the two filenames (defaults above). Every artifact of this run is written there and nowhere else. Done when: the output directory and both filenames are fixed.

2. Collect the lifecycle facts from the user. If a state, transition, guard, or retry count is missing, stop and ask. Never fabricate facts to fill a gap. Done when: all states, transitions, guards, and retry counts are collected from the user.

3. Write the typed lifecycle JSON specification with exactly this shape:

   {
     "specVersion": "1",
     "title": "<entity or process name>",
     "phases": ["<ordered phase>"],
     "lanes": ["<lane>"],
     "states": [
       {
         "id": "<unique id>",
         "kind": "entry|active|waiting|recoverable|success-terminal|failure-terminal",
         "phase": "<one of phases>",
         "lane": "<one of lanes>",
         "summary": "<one line>",
         "outcome": "<success or failure; terminal states only>"
       }
     ],
     "transitions": [
       {
         "from": "<state id>",
         "to": "<state id>",
         "kind": "advance|retry|decision|recovery|abort",
         "when": "<guard or waiting condition>",
         "retries": 3
       }
     ]
   }
   

   phases holds 1-8 ordered entries; lanes holds 0-6 and may be omitted; lane is required on each state only when lanes exists; summary is optional; when is required on decision transitions; retries is allowed only on retry transitions and must be an integer from 1 to 99. Done when: the JSON specification is written with the exact shape and field constraints.

4. Validate the specification fail-closed; any violation blocks delivery:

   • Exactly one state of kind entry.
   • State ids are unique, and every from, to, phase, lane, and outcome value references a declared entry or an allowed literal.
   • Terminal states (success-terminal, failure-terminal) have no outgoing transitions and carry outcome bounded to success or failure, matching their kind; this is the bounded outcome column.
   • Every recoverable state has at least one outgoing recovery transition to an active or waiting state: a real transition back to an active state, never to itself or a terminal.
   • Every state is reachable from the entry state.
   • Nothing from the user's stated facts is absent: every requested legal transition and terminal appears, and nothing extra was invented. Done when: every validation rule passes, or a violation is identified and delivery is blocked.

5. Generate the HTML artifact as one self-contained file: inline CSS and vanilla JS only, zero external references (no CDN scripts, stylesheets, fonts, or images), with the validated specification embedded verbatim. Done when: the HTML is one self-contained file with zero external references and the spec embedded.

6. Render topology, not prose: one node per state and one directed edge per requested transition, laid out as the ordered phase columns; terminals placed in the bounded outcome column; lanes as rows when present; recoverable states show their recovery edge back to the active state; retry edges annotate their retry counts; decision edges show their guards. Cards, lists, or prose describing states never substitute for nodes and edges. Done when: node count equals state count, edge count equals transition count, and every terminal appears in the topology.

7. Make it interactive: hovering a node highlights it and its connected edges; clicking a node reveals its summary and the guards and retry counts of its transitions. HTML-escape every user-supplied string before interpolation and never splice one into script code. Done when: hover and click interactions work and every user-supplied string is HTML-escaped.

8. Optional visual evidence: only if a rendering or inspection capability is actually available, capture up to two image sidecars (for example one rendered screenshot) beside the HTML. Write a sidecar only when actually captured; never fabricate one. Done when: at most two sidecars are written (only when actually captured) or none are written.

9. Run the delivery checks; all must pass:

   • The specification passes the fail-closed rules and the verdict is recorded.
   • The HTML is one file and contains zero external references.
   • Rendered node count equals state count, edge count equals transition count, and every terminal state appears.
   • No user-stated state or transition is missing and none was invented.
   • Sidecars, if any, are within the two-file cap and were actually captured. Done when: every delivery check passes with its verdict recorded.

10. Report the receipt: each written path, the validation verdict, each check result, and the visual-review status - reviewed only when the artifact was actually rendered and inspected, otherwise unreviewed. Done when: the receipt is reported with every path, verdict, check result, and truthful visual-review status.

Failure and recovery

• Missing facts: stop before any write and ask for the missing states or transitions.
• Invalid specification: fix and re-validate, or delete the invalid draft; never render HTML from an invalid specification.
• Impossible constraint: if self-containment or topology completeness cannot be met, keep the specification, report blocked with the exact unsatisfied requirement, and make no done claim.
• Failed delivery check: roll back by deleting exactly the paths written this run, then report the failing check verbatim.
• Never swallow an error and never report the done predicate as satisfied when a check failed.

Output

Return the specification path, the HTML path, any sidecar paths, the validation verdict, the per-check delivery results, and a receipt whose visual-review status is truthfully reviewed or unreviewed.