The Kit Boundary

"Shared plumbing has exactly one owner. Edit it there, deploy it by sync — and a copy you edit locally fails the tests on purpose."

One Owner for the Shared Layer

Forge, Vesta, and Waystone share a real layer of app-agnostic plumbing — the cwkPippa client, the publish client, the veil, ULID, the settings slice, the capture outbox and ask-thread contracts, shared UI atoms, calendar date math. That layer has a single owner: cwkSiblingKit. Forge carries it as vendored shims (kit_*.py on the backend, frontend/src/kit/ on the client), but the source of truth is the kit. This exists because the trio was seeded from the same shape on the same day and the shared code instantly appeared in triplicate, with same-day drift and one real cross-app bug. The kit is the fix: dedup with an owner.

Vendored, With a Drift Check

Distribution is not a package install; it is vendored copies plus a drift check. A sync script's --check mode runs inside each consumer's test suite, so a vendored file that has been hand-edited fails that repo's tests. The rule this enforces is blunt: edit kit files in the kit, deploy them by sync — never edit the vendored copy in place. The failing test is the guardrail that keeps three apps from quietly diverging on the code they are supposed to share, which is exactly the disease the kit was created to cure.

Edit kit files in the kit only; a locally edited vendored copy fails the drift check. The kit is the single owner of shared plumbing; consumers carry synced copies. The test that fails on a local edit is not friction to route around — it is the mechanism that keeps the family from re-forking the code it just de-duplicated.

The Kit Never Absorbs Domain Shape

There is a hard line on what the kit may own. It takes the app-agnostic plumbing and nothing else — journeys stay in Waystone, journals in Vesta, and the entire health domain stays in Forge. The kit must never grow a health field, a symptom type, or an analysis rule. This is the same rule as "an engine is defined by what it owns," applied to the shared layer: the plumbing is common precisely because it is not about anyone's domain. The instant domain shape leaks into the kit, the boundary that makes sharing safe is gone.

Code

What the kit owns vs what Forge owns·text

cwkSiblingKit (one owner, vendored to consumers + drift check):
  - cwkPippa client layer (brain vocabulary, streamed turns)
  - publish client + canonical publication record
  - veil, ULID, settings slice
  - capture outbox + ask-thread contracts
  - shared UI atoms, calendar date math

cwkForge (owns its domain, NEVER pushed into the kit):
  - the seven readings, the interpretation rubric
  - aggregates / narration / analysis, observe-never-diagnose
  - the digest contract, health-density calendar query

# edit kit files in the kit; deploy by sync.
# a hand-edited vendored copy -> the drift check fails the suite.

Exercise

While working in Forge you spot a real bug in a kit file — say the capture outbox. Where do you fix it so all three sibling apps get the fix, and what specifically goes wrong if you 'just fix it here' in Forge's vendored copy instead?

Hint

Fix it in cwkSiblingKit and re-sync. Editing the vendored copy fails Forge's own drift check, and even if you bypassed that, the other two apps never receive the fix and the shared code has now forked — the exact drift the kit exists to prevent.

One Owner for the Shared Layer

Vendored, With a Drift Check

The Kit Never Absorbs Domain Shape

Code

External links

Exercise

Progress

Comments 0