ct_2026-04-17
Session 45328ba3-bd9b-41bd-aca1-845c50dce134
Rows
4
Files touched
3
Unique symbols
9
Packs referenced
5
Packs referenced
Compare packs used →Rows (4)
Scenario · Files · Changes · Why- #1Five parallel workers were about to build a catalog in pieces without a shared blueprint for what one entry (a pack) looks like.+9 TypeScript types locking the Pack shape for five parallel workers. Blueprint only, no runtime code.
Why · hook
Pin the shape before the work.
Expand Why + failure modes
Collapse
Why (4-line pedagogy)
- Plain
- Pick one shape for the data before five workers start using it.
- Analogy
- Like everyone agreeing on paper size before the printers start running.
- Principle
- A shared schema is the contract that lets parallel work converge. Without it every worker drifts.
- Hook
- Pin the shape before the work.
Symbols
Failure modes
- Mid
Two parallel workers ship incompatible shapes; integration fails at the wire.
- Trigger
- No shared type pinned before parallel work starts; each worker invents its own.
- Prevention
- Pin the canonical schema before parallel fan-out; add a type-compile gate on merge.
- See also
- pattern-decision-tree
- #2First real CLI install failed: [INVALID] Failed to fetch pack metadata: Pack payload missing slug. The API returned { pack: {...} }; the CLI expected the pack object bare.RegistryClient.get(): parse → (parsed && 'pack' in parsed) ? parsed.pack : parsed. Envelope-aware unwrap.
Why · hook
Mocks lie. Dogfood the handshake.
Expand Why + failure modes
Collapse
Why (4-line pedagogy)
- Plain
- Two workers wrapped the data differently, so nothing flowed through.
- Analogy
- Like mailing a letter — one uses an envelope, the other hands it bare. Receiver only opens envelopes.
- Principle
- Shape is part of the contract. Mocks hide shape drift; only a real handshake reveals it.
- Hook
- Mocks lie. Dogfood the handshake.
Failure modes
- Senior
Unit tests green, first real install fails: 'Pack payload missing slug'.
- Trigger
- API and CLI each mocked the counterparty; contract envelope drifted undetected.
- Prevention
- End-to-end contract test that spans real API + real CLI + real filesystem. No mocks at the boundary.
- See also
- golden-eval-harness
- #3Retry after the envelope fix: metadata OK but [NOT_FOUND] /api/packs/<slug>/raw. Raw MD is a content route under /packs, not an API route.getRawMarkdown(): path /api/packs/*/raw → /packs/*/raw. Content lives under /packs; /api is JSON only.
Why · hook
Group by content type, not caller.
Expand Why + failure modes
Collapse
Why (4-line pedagogy)
- Plain
- The CLI asked for the file at the wrong address. Right house, wrong street.
- Analogy
- Like mailing a letter to '42 Main' when the house is '42 Elm.' Post office returns it even though the building exists.
- Principle
- URLs group by content type, not by caller. /api means data; /packs means content.
- Hook
- Group by content type, not caller.
- #45 concurrent install tests hit random Windows EPERM on fs.rename against a shared AGENTS.md destination.atomicWriteFile(): add EPERM/EACCES/EBUSY retry with backoff; preserve write-before-rename semantics.
Why · hook
If the OS says 'busy,' wait a beat.
Expand Why + failure modes
Collapse
Why (4-line pedagogy)
- Plain
- Five installs ran at once and Windows said 'busy' even though nothing was wrong.
- Analogy
- Five people trying to swap the same bookmark in one book. The book allows one swap at a time; others wait a beat.
- Principle
- Atomicity on rename is OS-dependent. When the OS serializes a shared resource, retry turns the race into a queue.
- Hook
- If the OS says 'busy,' wait a beat.
Cross-references