[PROOF-P1-S3] Write the document contract

[d6veteran]

Stage P1-S3 of the staged plan docs/plan/2026-10-12-any-document-as-a-proof.md: the one contract for a proposal, an analysis, and a note. It adds skills/doc-artifact/SKILL.md and changes nothing outside the stage's three paths.

What the contract fixes

Every kind opens with In one sentence and then Decisions for you, and ends with Open questions and then What I read. Only the sections between are the kind's own.

Kind	What it is for	Its own sections	Size
Proposal	A change that has not been made	Why, What changes, Not doing, What could go wrong, How we will know it worked	under 2,000 words
Analysis	A question, answered from evidence	The question, Findings, What it means	under 2,500 words
Note	Something already known or decided, kept so that it is not lost	The note	under 800 words

• Which kind a request is. The kind the author names. Otherwise the first that fits: a request that ends in a change to make is a proposal, one that ends in an answer is an analysis, and one that only keeps what is known is a note. A plan is none of the three and goes to /ck:plan.
• The top of the file. # <Kind>: <subject>, then Date: <YYYY-MM-DD>. Status: draft, not approved. These are the staged plan's own words, so one line says draft or approved <YYYY-MM-DD> in both.
• Decisions. The first line says which are open, Open: D1, D3. or None open. Then a table, | # | Decision | Choices | Decided |, with the recommended choice first. A decided row stays.
• Findings say how they are known. Each begins its evidence with Seen:, Read:, or Inferred:.
• What I read ends with Not checked:, so every document says where its evidence stops.
• On the proof. No two headings are the same, a file is named in a code span, a link is for a web address, and there is no image and no HTML. I rendered a page that breaks each rule to see what the page does: two headings with one name share one place, a link to a file shows as its raw brackets, an image shows as a stray mark and a link, and HTML shows as text.

Choices made here

The proposal fixes the opening and the ending and leaves the rest to this stage. Each of these is a line or two of the contract, so a comment here is enough to change one before the merge.

1. One list of headings for each kind, not one list for all three. The check file allowed either.
2. The headings are the approved proposal's own, with three changes. The steps and Files are one table, What changes, with a Where column. Why is new: a document that is committed should say what is wrong today without the conversation that led to it. Appendix. is dropped from the last heading.
3. A proposal keeps a table of changes. Its rows are changes and not jobs: no owner and no order of work. Who does which part is a staged plan's to say. This is the line that keeps a proposal from being a second kind of plan.
4. The sizes are 2,000, 2,500, and 800 words, counted before ## What I read so that a long list of sources costs nothing. The approved proposal for this work is 2,018 words by that count, at the edge. The author can ask for more.
5. An approved document has no decision open. So when the author types approved while a row is still open, the command has to record the recommended choice or ask. That is stage P1-S4's to write.
6. Nothing but the date and the status stands above the first heading. I tried a line for the request as typed and took it out: it pushed the one sentence down the page and mostly repeated the title.

Looked at as a page

I wrote one sample document of each kind to the contract, in a scratch folder, rendered each with scripts/render-proof.py, and looked at them at 1280 by 900 and at 375 by 812.

• Pass 1. The worst fault was at phone width. In a proposal's table of changes a file path cannot wrap, so the Where column pushed Done when out of sight.
• Pass 2. Where is now the last column. Change and Done when stay on the screen, and Where is the one that scrolls. The contract says why, so a later edit does not put it back.
• Pass 3. With the request line gone, the one sentence and the first rows of the decisions fit on the first screen under the banner.
• Measured. The list of contents is 240 pixels wide, and a ### entry has 217 of them at 13 pixels: about 33 characters. The contract says 32 or fewer keeps to one line. The longest ## heading it fixes is 26.
• Not looked at. A page published through the Artifact tool, and the dark theme. The pages were served from a scratch folder on this machine.

Checks

• tests/pending/P1-S3.sh moved to tests/checks/P1-S3.sh. Its five checks are as stage P0-S1 wrote them. Only the two lines that start the program changed: it is passed the renderer and a scratch folder, and it imports two more modules.
• Eight checks are added, each for a contract the first five pass and that would still be wrong: the kinds open and end with the same headings word for word; no list names a heading twice; one list for all three kinds or one for each, under a heading that names its kind; the three kinds side by side in one table or list; a size in words for each kind, counted with wc -w; the path docs/<kind>/<date>-<slug>.md; a plan is none of the kinds and /ck:plan is named; and a document under each list's headings goes through the renderer and comes out with each heading once in the page's list of contents, in order, with a place of its own.
• I broke the contract ten ways in a scratch copy. The first five checks passed every one, and each of the eight caught its own. With no contract at all, all thirteen fail and say it is not written.
• bash tests/run.sh: 509 passed, 0 failed, 49 waiting in 4 files. Before the stage: 495 passed, 54 waiting in 5 files. The 14 new passes are this stage's thirteen and the house-style check that reads every contract. Ruff is clean, and the zsh checks ran.
• The check file also runs under Python 3.9.6, the one macOS ships.

Notes for the reviewer and for later stages

• P1-S4. The contract gives the command its path, the three kinds and how to pick one, the status words to write on approval, and the line that counts a document's words. What the command says when it is asked for a brief or a PRD is not decided anywhere. The contract says only that such a document is written to its own contract.
• P1-S5. README.md says "the ten document contracts". There were twelve folders before this stage and there are thirteen now. The README is that stage's file, so I left it.
• P1-S2. Its check that no other skill restates the rules for a comment sent to Claude will read this contract once it lands. The contract holds none of the words it looks for.
• The approved proposal for this work predates the contract and is not changed. It keeps The steps, Files, and Appendix. What I read.
• The frontmatter's description has no colon followed by a space, so a strict YAML reader takes it. brief-artifact and memo-artifact have one and are refused by PyYAML, though Claude Code reads them. I did not touch them.
• The branch is one commit on origin/main at 169363c.

🤖 Generated with Claude Code