Handoff corpus

Generated from a canonical source

This page is a read-only projection of docs/handoff-corpus/README.md. Edit the canonical file, then run npm --prefix tools/project-knowledge-derive run derive.

The third-party handoff: what a colleague or agency reads to evaluate, take over, or extend this system cold. One page per capability domain, each telling four things — what it's for, how it actually works, where intent and reality diverge, and how to operate & extend it — with every claim cited to an openable source.

This corpus is generated, per the ratified Input-B contract (docs/methodology/handoff-corpus-input-spec.md):

Input-A (the code, read fresh at generation time)
Input-B (_input-b/<domain>.md — intent, rationale, typed deltas, attestations)
        └────────────── generation prompt ──────────────┘
                              ↓
                <domain>.md  (this directory)

How a domain page comes to exist

1. Author the Input-B file from _input-b/_TEMPLATE.md: feature descriptors, load-bearing decisions, the invariant, typed deltas (six-type vocabulary), visual-aid pointers, evidence pointers — and the two attestations, produced by the contract's tracing procedures (trace first; never recollection).
2. Operator ratifies the attestations (status: draft → attested, ratified_by/ratified_on set). Generation is blocked until then.
3. Generate with docs/methodology/prompts/handoff-generation.md — a fresh agent composes Input-A + Input-B into the page, validated against handoff-voice.md.
4. Lint: npx tsx tools/handoff-lint/index.ts (mechanical half — structure, delta types, attestation freshness); voice/citation quality stays a human/agent review.
5. Maintain: re-attest and regenerate when the architecture, its deciding decisions, or the traced live-state change (the as_of_commit frontmatter dates every page).

Reading order for a recipient

Start with the domain you're scoping. The proven exemplars (hand-authored prototypes that set this corpus's bar) live at handoff-specimen-dunning.md and handoff-specimen-payments.md until their generated replacements land here.

Current domains

Domain	Input-B	Page
canonical-charge-rail	_input-b/payments.md — attested	canonical-charge-rail.md
dunning	_input-b/dunning.md — attested	dunning.md
subscribe	_input-b/subscribe.md — attested	subscribe.md
gift-subscriptions	_input-b/gift-subscriptions.md — attested	gift-subscriptions.md
subscriber-self-service	_input-b/subscriber-self-service.md — attested	subscriber-self-service.md
trials-and-intro-offers	_input-b/trials-and-intro-offers.md — attested	trials-and-intro-offers.md
feedback-triage	_input-b/feedback-triage.md — attested	feedback-triage.md
subs-assistant	_input-b/subs-assistant.md — attested	subs-assistant.md
build-a-box	_input-b/build-a-box.md — attested	build-a-box.md
webhooks-and-integrations	_input-b/webhooks-and-integrations.md — attested	webhooks-and-integrations.md
notifications-and-email	_input-b/notifications-and-email.md — attested	notifications-and-email.md
promotions-and-discounts	_input-b/promotions-and-discounts.md — attested	promotions-and-discounts.md
migration-import	_input-b/migration-import.md — attested	migration-import.md
analytics-and-reporting	_input-b/analytics-and-reporting.md — attested	analytics-and-reporting.md
catalog-and-plans	_input-b/catalog-and-plans.md — attested	catalog-and-plans.md
b2b	_input-b/b2b.md — attested	b2b.md
admin-and-cs-tools	_input-b/admin-and-cs-tools.md — attested	admin-and-cs-tools.md