24. Finishing a sheet is an explicit source transform
- Status: Accepted — decision 7 superseded by ADR 0025; the all-or-nothing roll-back of decision 6 amended (2026-10)
- Date: 2026-10
- Relates to: ADR 0005 and ADR 0006 (compile renders what is written; a correction is an explicit transform), ADR 0011 (the piece-table applier), ADR 0015 (the CLI is the agent interface)
- Scope: a new transform,
finish()/arch finish. No language syntax, no change tocompile(),describe()orlint().
Context
A plan can be sound and still not be a drawing sheet. paper, scale, dims auto, title, schedule rooms and legend are all optional, and a plan without them compiles to a correct picture with no sheet size, no dimension chains, no title block and no tables.
spec.llm.md recommends paper with dims auto all. Models still leave them out. In a run of 72 plans written from the public spec, the mean sheet-completeness score per model ranged from 0.00 to 0.72. A downstream product that post-processes its plans scored 1.00 on the same measure. The gap is not knowledge of the syntax: it is a step nobody runs.
The obvious remedy is to make compile() add what is missing. ADR 0005 and ADR 0006 already refuse that: a default sheet chosen inside the compiler is a decision the source does not state, and every existing plan without paper would render differently.
Decision
1. finish is an explicit transform outside compile(). finish(source, opts?) returns { source, changes[], unresolved[], changed }, the shape repair returns. arch finish follows arch fix's write conventions: it rewrites the input in place by default, prints the unified diff on stderr, and takes --dry-run, --backup and -o.
2. It fills only what is missing, and deletes nothing. Each of the six statements is added only when the plan has none. An authored dim, axes, north or title block is never rewritten. A plan with hand-written dim lines gets no dims auto; that is reported in unresolved. The title block carries only project, taken from the plan's own name: finish does not invent a date or an author.
3. --reissue may replace paper and scale, and nothing else. Without it an authored sheet is kept. If the drawing does not fit that sheet, finish gives up statements in a fixed order (the two tables, then dims auto, then the title) until what is left fits, and reports each one it left out. With --reissue it replaces the sheet instead: it keeps the authored scale when some larger sheet holds it, and chooses both otherwise.
4. The sheet is chosen by the compiler's own fit rule. finish calls fitsOnSheet (src/sheet.ts) with the extents, table rows and title rows that resolve() computes (sheetExtents, planTableRows, titleRows), taking the largest extent over the storeys of a multi-storey plan. It never reads a diagnostic's message. The order is: the finest of 1:50, 1:100, 1:200 and 1:500 that fits some sheet from A4 to A1, on the smallest such sheet, landscape before portrait; A0 only when no scale fits A4 to A1. dims auto is all, or overall when the building's short facade is under 60 mm on paper. When nothing up to A0 at 1:500 holds the drawing, paper and scale are not added and that is reported.
5. The edits are span-based inserts. They go through the Data piece table (src/fix-apply.ts), not through the formatter, so every authored byte and comment survives. A statement is inserted only at a line boundary, in the file's own indentation and line ending.
6. Four laws, each pinned by test (test/finish.test.ts, test/fuzz.test.ts):
| Law | Statement |
|---|---|
| Fixpoint | finish(finish(s).source).source === finish(s).source |
| Never worse | the result has no compile error, no diagnostic code (compile and lint, counted) that the input did not have, and no new furniture conflict (drafting-layer codes and the residential-advisory profiles excepted, see the 2026-10-24 and 2026-10-25 amendments) |
| Fitted | when finish wrote paper or scale, the result raises neither W_SCALE_OVERFLOW nor W_DRAWING_OVERFLOW |
| Untouched | a source that does not compile is returned byte-identical |
A result that breaks the never-worse law is not returned. The whole stage is rolled back and the reason goes in unresolved. A plan that needs nothing comes back byte-identical with changed: false.
Amended 2026-10. The law is unchanged and still absolute (drafting-layer codes excepted, see the 2026-10-24 amendment); the roll-back is no longer all or nothing.
dims auto allon a plan with an opening no chain reaches raises the advisoryW_OPENING_NOT_DIMENSIONED, and the stage then wrote nopaper,scale,title, schedule or legend either. The sheet stage now degrades. When the whole set of statements is refused it tries, in this fixed order,dims auto overallin place ofdims auto all, then nodims auto. If neither passes it builds the set up one statement at a time (paperwithscale, the title,schedule rooms,legend, thendims auto allanddims auto overall) and keeps each one the plan passes the check with. Every statement left out is anunresolvednote with thecodesit would have raised. The search is bounded: at most nine candidates are checked after the input (SHEET_MAX_CHECKS,src/finish.ts). The stage is rolled back whole only when no statement passes on its own. The law is checked under every lint profile.
Amended 2026-10-24 (PR #245). Drafting-layer codes (ADR 0032's
layer: "drafting": todayW_ANNOTATION_OVERLAP,W_TITLE_OVERFLOW,W_DIM_INSIDE,W_DIM_OVERLAP,W_OPENING_NOT_DIMENSIONEDandW_DIM_TEXT_MISMATCH, read fromLINT_CODE_LAYERS) are excluded from the never-worse comparison (NOT_GATED_DRAFTING,src/furnish.ts). A drafting-layer code reports the annotation, not the plan, and the law protects the plan's soundness. So the sheet stage no longer degradesdims auto allfor an opening no chain reaches (the 2026-10 amendment above):W_OPENING_NOT_DIMENSIONEDreports that opening in the finished plan instead.finish's placement is unchanged, and the overprints it always drew are now named. Measured on the eval goldens, the drafting-layer codes offinish's output:W_ANNOTATION_OVERLAPbungalow0 → 2,two-bath-flat0 → 2,sized-bedrooms,three-bed-2bath,two-bed-hallandl-shaped-flat+1 each; no other drafting-layer code gained. Card PS2.40 makesfurnishprefer a candidate that raises no overlap.
Amended 2026-10-25 (PR #248). "Checked under every lint profile" now reads: under the default ruleset and the UNIVERSAL advisory profiles (
accessibility-advisory: physical access, the same in any culture). The three residential-advisory profiles (cn-,uk-,us-residential-advisory,ADVISORY_CODE_PROFILESinsrc/lint/ruleset.ts) are outside the comparison: each reads one jurisdiction's room sizes, they disagree with each other by design (plan-soundness D3), so no single furnished output can satisfy all three, and none of them may govern the default output. Measured on the eval goldens, the profile-only warningsfinish's furnish stage now leaves: with areas read as drawn (the PR's first head, as its review measured it) 14 in 9 plans,uk12,cn2,us0; with net areas (as merged) 28 in 14 plans,uk22,cn6,us0. Every one is aW_ROOM_TOO_SMALLorW_ROOM_TOO_NARROWon a bedroom that the furnished 1500 mmbedmakes a double. The shipped examples gain one (sheet-notes,uk, with net areas; none as drawn). Card PS5.6 letsfinish/furnish --profile <name>hold the law under that one profile.
Amended 2026-11-02 (issue #364). On a plan with
levelblocks the law is also read storey by storey (gainedCodes,src/furnish.ts): a code a storey gained is a gain whatever another storey lost. A single-storey plan has no storey to read, and nothing it gets moved.
Superseded (2026-10). The
furnishstage exists: see ADR 0025. A full run isfurnish, thensheet, and--only furnishruns that stage. The paragraph below is the record of the first version.
7. Stages. finish is built as stages so that --only can select one. This version has one stage, sheet. A furnish stage (placing the furniture a room's use implies) is planned. --only furnish is a usage error that says the stage is not available yet; it is never a silent no-op.
Why it is not a language form
A finish keyword, or a paper auto setting, would put the choice back inside compile(). The source would then say "some sheet" and the drawing would show a particular one, which is the invisible decision ADR 0005 refuses. As a transform, finish writes its choice into the source as ordinary statements. The author reads the diff, and from then on the plan states its own sheet.
It also keeps every existing plan stable. Nothing changes for a source nobody runs finish on, so no byte-identity baseline moves.
Consequences
An agent's loop gains one step, after lint is clean:
arch finish plan.arch.SKILL.mdstates it, and the command is in the manifest, so it is also inarch context, the CLI reference and the generated CLI block ofspec.llm.md.finishadds a sheet to a plan that had none. That switches the plan to paper sizing: every annotation becomes a fixed size on the sheet. This is whatpapermeans, and it is why the step is explicit.The roll-back is all or nothing. A sheet can crowd two hand-written
dimlines intoW_DIM_OVERLAP;finishthen changes nothing and says so. Retrying with fewer statements is not done in this version.Amended 2026-10. It is done now: see the amendment under decision 6. In this case the sheet is left out and reported, and the title and the tables are still written.
A plan with an authored sheet the drawing already overflows is left alone unless
--reissueis passed.
Provenance
The idea of a finishing pass comes from ArchCanvas, a closed product by the same owner, which runs one over generated plans. This is an independent implementation under the MIT licence, written against ArchLang's own internals. No code was copied.