docs(adr): add the ADR format guide and the write route

[thymikee]

Summary

Part of #3744. First restructure batch: authoring rules only. No ADR record changes.

• Adds docs/adr/FORMAT.md: when to write an ADR (the three-condition test), what it contains (decision, reason, rejected alternatives, consequences/gaps), what it excludes and where each item goes, the living-record rule with the optional dated "Decision history" line, the amend procedure, the restructure ledger rule, and the about-8 KB approximate upper aim.
• Splits the AGENTS.md route: "Read architecture decisions" goes to docs/adr/README.md; "Write or amend an ADR" goes to docs/adr/FORMAT.md.
• Gives docs/adr/FORMAT.md its own 4000-byte budget in the agent-guidance contract test, routes it to the agent-guidance gate in the affected selector and the workflow, and extends the existing routing proof. No overall budget increase, no allowlist, no general ADR size gate.
• Touched files: 6.

Migration ledger

• AGENTS.md read route: kept, intent reworded ("Read architecture decisions").
• AGENTS.md write route: new, to docs/adr/FORMAT.md.
• Authoring rules: new home docs/adr/FORMAT.md.
• No ADR sections deleted or moved.

Validation

Independent review by a different model provider is complete. No findings remain. All required CI checks pass. The branch is CLEAN and mergeable.

• SHA 8e46e04c1e; pnpm check:affected --run --head 8e46e04c1ec1edc07490e90ad572dfed01b06a5d passed, exactCommit=true, checkoutChanged=false.
• Focused: check:agent-guidance, check-affected model tests, gate workflow/routing tests, doc prose/links tests; pnpm format and typecheck clean.
• Docs and gate-routing change only. No runtime or device-facing behavior changes, so device tests do not apply.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.40 MB	5.40 MB	0 B
Package (unpacked)	5.40 MB	5.40 MB	0 B
Package (download)	1.63 MB	1.63 MB	-4 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	42.5 ms	43.5 ms	+1.0 ms
CLI --help	81.0 ms	82.2 ms	+1.2 ms

[thymikee]

The independent review by a different model provider found four text corrections at c8a666877e:

• Keep the dated decision-history line optional, as Restructure ADRs into short decision records #3744 requires. Both current instructions make it mandatory.
• Send PR logs and status change-logs to the umbrella issue. Do not instruct a blanket deletion before their content has an owner.
• Restore automatically and manually in the existing lock rules. The route change must preserve those qualifiers. Meaning-neutral sentence compression can keep the 4,000-byte budget.
• Describe about 8 KB as an upper aim. Do not make it a target that encourages a longer record.

The new format budget, affected selector, workflow paths, and routing proof match the requested ownership. The exact-commit gate passed with an unchanged checkout. I assigned one repair round. Review of that head and CI remain required.

[thymikee]

Repair round at 8e46e04c1e (parent review of c8a666877e), four conditions only:

1. Decision history line stays optional: "you may add" in the record section and in amend step 3. No compulsory wording.
2. Exclusion row: PR logs and status change-logs now route to the umbrella issue, not a blanket delete.
3. AGENTS.md qualifiers restored: "run one at a time automatically", "Do not remove the lock manually". Replaced the saved bytes with the suggested meaning-neutral compressions: "Read only your task's row." and "reclaims provably dead owners". The unknown-owner sentence is unchanged. AGENTS.md is 3992 bytes under the unchanged 4000 budget.
4. Size line reads "Keep ADRs short. Aim below about 8 KB." No exact norm, no ADR-wide gate. FORMAT's own 4000-byte budget is unchanged.

Validation: pnpm check:affected --run --head 8e46e04c1ec1edc07490e90ad572dfed01b06a5d passed, exactCommit=true, checkoutChanged=false. Focused guidance/model/prose/links tests and pnpm format and typecheck clean. docs/adr/FORMAT.md is 3227 bytes.

[thymikee]

The independent review by a different model provider is complete at 8e46e04c1e. No findings remain.

I compared each changed sentence with base 0fb25c474a and the accepted #3744 contract. The four corrections preserve optional history, the history owner, lock qualifiers, and the approximate size aim. No ADR record changes in this batch.

The format file owns a 4,000-byte budget. The affected selector and both workflow triggers reach its existing guidance check. The routing proof covers a format-only edit. FORMAT.md is 3,227 bytes; AGENTS.md is 3,992 bytes. Existing budgets remain unchanged.

Receipt run-9rAu29 passed at this exact commit with checkoutChanged=false. The focused checks passed. No inline threads are open. CI is still running, so the PR is not merge-ready yet.

[thymikee]

Ready at 8e46e04c1e. All required checks pass. The branch is CLEAN and mergeable.

I checked issue comments, reviews, and inline threads. No findings or open threads remain. The independent review by a different model provider is complete. The exact-commit receipt passed with an unchanged checkout.

The check rollup contains 17 passes, one skipped cache job, and a neutral Cubic check. The neutral check does not replace the completed independent review.

The maintainer owns the merge. After merge, I will post the current state on #3744 and start the ADR 0003/0008 pilot.

[thymikee]

I reviewed 8e46e04 and it is ready for human review. The code looks good, and all 19 checks pass with none failing. There are no conflicts.

Not blocking, and you can take or leave these: README.md and FORMAT.md both set shape conventions, and they differ slightly (FORMAT.md makes sections optional and allows a dated Decision history line, while README.md deletes process history), so one file could own them, for example in the ADR 0003/0008 pilot PR. The 8 KB ADR size target at FORMAT.md line 121 has no gate, since the new 4,000-byte budget covers only FORMAT.md itself.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-18 16:11 UTC