Back to tracesTraceagent-workspace-templateApr 17, 2026

ct_2026-04-17

Session 45328ba3-bd9b-41bd-aca1-845c50dce134

Rows

Files touched

Unique symbols

Packs referenced

Tags

#m1-m6 #pillar-2-design #dogfood #interface-drift #eval-gate #publish-prep #docs-consolidation

Packs referenced

Compare packs used →

rag-hybrid-bm25-vector golden-eval-harness pattern-decision-tree shadcn-data-table linear-command-palette

Download raw .md

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.
src/lib/pack-schema.ts
+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
AddedPack PackContract PackLayers TransferMatrixEntry Telemetry SecurityReview PackComparison ChangelogEntry PackSource
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.
cli/src/registry.ts
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.
cli/src/registry.ts
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.
cli/src/install.ts
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

Packs

rag-hybrid-bm25-vector golden-eval-harness pattern-decision-tree shadcn-data-table linear-command-palette

Tags

#m1-m6 #pillar-2-design #dogfood #interface-drift #eval-gate #publish-prep #docs-consolidation

Back to tracesTraceagent-workspace-templateApr 17, 2026

ct_2026-04-17

Session 45328ba3-bd9b-41bd-aca1-845c50dce134

Rows

Files touched

Unique symbols

Packs referenced

Tags

#m1-m6 #pillar-2-design #dogfood #interface-drift #eval-gate #publish-prep #docs-consolidation

Packs referenced

Compare packs used →

rag-hybrid-bm25-vector golden-eval-harness pattern-decision-tree shadcn-data-table linear-command-palette

Download raw .md

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.
src/lib/pack-schema.ts
+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
AddedPack PackContract PackLayers TransferMatrixEntry Telemetry SecurityReview PackComparison ChangelogEntry PackSource
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.
cli/src/registry.ts
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.
cli/src/registry.ts
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.
cli/src/install.ts
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

Packs

rag-hybrid-bm25-vector golden-eval-harness pattern-decision-tree shadcn-data-table linear-command-palette

Tags

#m1-m6 #pillar-2-design #dogfood #interface-drift #eval-gate #publish-prep #docs-consolidation