background design decisions

Design decisions

Five choices are recorded in code or docs. Where a date is written down, it is given. Where only the decision survives, it is marked as appears to.

Prompt-quality single source of truth (2026-06-04)

The header of lib/prompt-quality/contract.ts records the decision directly: "See DECISIONS.md (2026-06-04): SSOT prompt-quality contract established; Transform + template migration deferred to P2." The module canonicalizes the existing SuperPromptSchema rather than inventing a new shape, so adoption carried no public type change. A vocabulary table maps the three prompt skeletons (Optimizer, Transform, template renderer) onto the canonical fields; it is documented but not enforced here. Converting Transform and the templates to this contract is deferred to P2.

Capsule-root layout instead of a src/ tree

src/README.md states that the legacy project has no src/ tree. Its code lives in the capsule-root desktop/, lib/, data/, prisma/, scripts/, types/, and __tests__/ directories to preserve the existing module aliases and the Electron build layout. The directory appears to have been kept only to hold that note.

Pinned pnpm (pnpm@11.21.0)

package.json pins packageManager and carries a //packageManager comment explaining why: a deterministic resolver is needed for "clone and run", which an arbitrary local pnpm version does not deliver. The pin appears to match the Monorepo root toolchain at extraction time; the comment says the capsule may move ahead of root once independent.

Window sizing in character cells, versioned

desktop/main.ts sizes the window in transcript columns and rows, never fixed pixels. The renderer measures the real character cell and reports it over window:fit-grid; the main process converts it with gridToContentSize. A persisted sentra-desktop-window-state.json carries a WINDOW_STATE_VERSION, currently 7, and a saved size from an older layout is discarded. The comments record each bump: v4 discarded the pixel-era 1280x860, v5 and v6 tracked grid-target changes, and v7 discarded the 13px-face fit when the face shrank to 11px.

Coding Brief is fill-by-default (v3.0)

docs/CODING_BRIEF_STANDARD.md is v3.0, last updated 2026-09-23. Earlier versions told the Optimizer to ask rather than invent, which produced briefs full of [TODO: ...] holes. v3.0 narrows the never-invent rule to existing code (paths, functions, commands, test names) and requires every other element to carry a concrete proposal, listed under ASSUMPTIONS. The runtime validator lives in lib/prompt-quality/contract.ts.