amadan

oficina / docs Public

← Discussions

Bootstrap: agent instructions, review rule, shipping cadence, amadan setup, and the design spec closed

On branch agents-md-and-cadence

claude operated by paul@keymail.dev session 70f302d1 · claude-code/2.1.251 · DOCS-T1

Bootstrap branch. Six commits, no application code yet — this establishes how work happens here and lands the design spec. Recreated from carlos/docs discussion #1, which stays as the historical record; amadan has no transfer verb.

  • 7b15270 — AGENTS.md as the canonical agent-instructions file. Paul's two rules: specs and whole branches reviewed by the highest-capability model available, and the shipping cadence (worktree, branch, regular pushed commits, squash-merge only when done, approved, and CI green).
  • 0a07f0a — amadan house rules skill and the prompt ledger at prompts level.
  • 66e9ff6 — design spec r1.
  • b12406c — move to oficina/docs.
  • 14a3c11 — design spec r2, after a Fable review of r1 returned "not ready to become an implementation plan" with seventeen defects.
  • 82961a2 / e473d7c — write the class vocabulary, and record the release gap.

What the review found

Three findings holed the centre, and all three passed every check the spec had defined for itself.

  1. r1 declared "one engine, one truth" and chose ProseMirror — which is contentEditable, so the browser breaks lines. Two layout authorities. The conformance gate compared wazero against a browser running the same module, so it would have stayed green while the product was wrong. Corrected: the engine owns page geometry, the browser owns lines within it, same self-hosted fonts.
  2. "The same compiled artifact both sides" was not available — ywasm is wasm-bindgen and will not instantiate under wazero. One artifact meant a hand-rolled C ABI and losing y-prosemirror, y-indexeddb and y-websocket: offline and presence, traded for a purity being praised in the same paragraph. Corrected to JS yjs in the browser, Rust y-crdt on the server, fixtures as the contract — which is golden vectors, the thing r1 claimed to have transcended.
  3. The word "font" did not appear in r1. §11.1 now settles it, with Carlito and Caladea as metric-compatible stand-ins for Calibri and Cambria so imported Word documents paginate the way Word paginated them.

Also corrected: doc_updates is bounded; hibernation versus held WebSockets; page breaks are decorations rather than nodes, which keeps page geometry out of the CRDT; §9 re-synced against the real five-call Sheets contract (r1 had instances holding the pepper, which Sheets had already ruled against); §8.1's three contradictory sign-in positions collapsed into one; full-text search cut because an FTS5 index would fail our own plaintext gate.

The correction after the correction

r2 reported that ui.ThemeCSS did not exist. It does — main:ui/ui.go:309. It is absent from v0.19.0, and this session was reading a checkout parked on a feature branch at that tag. The Fable review made the same mistake and this session repeated its conclusion without checking the tree.

Underneath: a spec ruling, code on main, and code in the latest release are three different things. main is 17 commits ahead of v0.19.0 (tagged 2026-08-24), and those commits are the themes, shells and twelve locales the design system describes. Markup decision reversed to class="rst-*" accordingly — the attribute grammar exists in no tree and is unstarted.

Two traps recorded: this repo squash-merges, so git branch --merged says nothing about whether work landed; and cite origin/main explicitly, because a local checkout may sit on a feature branch at a tag.

Open

  1. Merge as a bootstrap exception? CI is exit 3 — no .amadan/ci.d/ yet, and a gate that checks nothing to turn the number green teaches everyone to ignore CI.
  2. carlos/docs retirement — Paul's.
  3. Passkey RP ruling (§8.1) — reached this session by relay; recorded as ruled-pending-confirmation, matching how Sheets records it.
  4. The identity-assertion helper — drafted jointly with Sheets, pending Paul's go-ahead to open it on rastrillo's GitHub.

claude operated by paul@keymail.dev session 70f302d1 · claude-code/2.1.251 · DOCS-T1

Merged to main as 878690a, squashed, as the bootstrap exception Paul approved.

To be explicit about what the exception was, since it is the first thing on main and sets a precedent: CI reported exit 3 — no status, because there is no .amadan/ci.d/ and nothing yet to gate. The rule this branch introduces says exit 3 is not green. Writing a gate that checks nothing purely to satisfy that would have made the number green and taught everyone to ignore the number. The real gate lands with the first code branch, where it has go build, go vet, go test and cargo test to run. That is task 2.

main did not exist before this. It was created by the merge rather than committed to directly, so the cadence holds from the first commit rather than from the second.

Both remaining rulings closed today, both confirmed by Paul directly rather than by relay:

  • Passkey RP — one relying party at the home's credential origin; instances verify signed assertions and never enroll passkeys. §8.1 settled.
  • The identity-assertion helper — filed as rastrillo/rastrillo discussion #1, on amadan rather than GitHub, drafted jointly with Sheets and naming both apps as consumers.

Next: the implementation plan, which under the review rule follows a reviewed spec rather than preceding one.

Closing this thread. Remaining work moves to its own branches.