| 1 | // Package plancontract is the structured form of a proposed plan: the record a |
| 2 | // planner submits, the host renders, and every downstream consumer reads. |
| 3 | // |
| 4 | // The plan is data, not prose. A planner that writes markdown forces the host to |
| 5 | // guess at structure — which steps exist, which paths were read rather than |
| 6 | // inferred, whether execution should gate — and every guess is a heuristic that |
| 7 | // fails silently. Here those are fields. |
| 8 | // |
| 9 | // Two rules keep the type honest: |
| 10 | // |
| 11 | // - Identity is host-assigned. ID and Revision are stamped when a plan is |
| 12 | // accepted; a planner submits neither. A revision replaces its predecessor |
| 13 | // under the same ID, so an approval gate can diff instead of reseeding. |
| 14 | // - Evidence is not blurred. VerifiedFiles are paths the planner actually |
| 15 | // read, CandidateFiles are paths it inferred. Free text cannot hold that |
| 16 | // line, so a plan built on guesses cannot present them as facts. |
| 17 | // |
| 18 | // Normalize repairs what is repairable — missing IDs, dangling parents and |
| 19 | // dependencies, nesting past two levels — and Validate rejects what is not, so |
| 20 | // code downstream of an accepted Plan never re-checks its shape. Ordered gives |
| 21 | // Render one deterministic representation of the document's steps. |
| 22 | package plancontract |
| 23 |