Build Contract Activation

Orient yourself first

npm run crm -- app inspect --json

Read valid, then problems[], then limitations[], in that order. Every problem is fixed or reported before anything is built on top of it, and every limitation is a hard boundary on what you may claim. Then read packages[], capabilities[], resources[], actions[], policies[] and providers[]: that list is what exists. A capability absent from the report does not exist, whatever a record name, a label or a document suggests.

If the repository documents this skill names are absent, you are in a project built from this framework rather than in the framework itself. The inspection report is then the source of truth and those documents are optional background — do not guess at their contents, and do not assume a path exists because this skill names it.

Background, where they exist: ARCHITECTURE.md, DECISIONS.md (ADR-018 and its addenda), docs/CONTRACT_ACTIVATION.md and docs/PACKAGE_AUTHORING.md. They are the deeper source for the rules below, not a prerequisite for them — the rules stand on their own.

Build it as a domain package, not in core

1. A new domain lives in packages/<domain>/ and is registered through the checked-in packages/domains/generated/index.js — the same path a third-party package uses. The kernel must never import it, and removing that one static import must leave every other milestone working. Prove it: boot the same project without the package and assert the kernel is unchanged.
2. The declaration is plain data built with definePackage from the public surface packages/core/index.js: { packageContract: 1, name, version, label, resources[], requires[], capabilities[], actions[], policies[{kind, definition}], metadata() }. metadata() returns function-free JSON for /api/schema; never a handler, a credential or a path. Import nothing else under packages/core — docs/PACKAGE_AUTHORING.md and crm package validate are the contract.
3. If the domain needs something the runtime does not have, that is a generic runtime capability with no domain word in it, recorded as an ADR-018 addendum — never a domain concept smuggled into packages/core. M12 needed exactly three: the domain registry seam, a strict boolean input type and an injectable application clock.
4. Domain records are ordinary manifests (writable: "managed" throughout → capabilities get/list) applied by the project, not written by hand.

Classify on two axes, never from recurrence

1. Recurrence is not a classification, and one axis is not enough. Ask two questions per component: is it a recurring right (commercialActivation), and does it owe anything beyond the money (obligations)? Annual support answers yes to both — a single exclusive label has to drop one, and dropping the first removes real recurring money from the subscription. A recurring API charge may owe nothing; a one-time migration owes delivery work.
2. Classification is a versioned, fingerprinted policy (ADR-015): defineOrderActivationPolicy({name, version, config, classifyComponent}). Deterministic, synchronous, total — no clock, no network, no database, no randomness. Thresholds and mappings go in config so the fingerprint covers them; a closure-held table is invisible to it.
3. Decide from explicit identity in the Order snapshot — component key, SKU, offer — never from label text and never from the live catalog. The context is deep-frozen on purpose.
4. Either axis may be ambiguous, and an ambiguous axis blocks activation until a human resolves that axis with its own reason. obligations: [] is a decision that nothing further is owed; 'ambiguous' is the absence of one. Do not add a default that guesses.
5. Every component becomes exactly one Contract Line whatever the answers are, and no obligation type is ever created twice for one component.
6. Publish a new version to change a decision; never edit a registered one (the next boot refuses it). Historical activations must still explain themselves.
7. Enforce coherence regardless of policy or override: a subscription line must recur (409 CLASSIFICATION_INCOHERENT).

Separate planning from committing

1. plan-activation is read-only: no domain record, no business audit, no event. Any actor may prepare it — that is how an agent contributes without committing the business.
2. activate-contract requires actor.type === 'user' (an agent is 403 HUMAN_APPROVAL_REQUIRED). It is a human-actor boundary, not Finance/Legal role enforcement — real roles need the Production Spine.
3. Recompute the plan inside the activation transaction from the Order. Never trust a plan, an amount, a product, a tier or a hash supplied by the client.
4. A human override decides one dimension of one component ({orderComponentId, dimension, value, reason}): bounded non-blank reason, never the ambiguity it is meant to resolve, never a component of another order, never the same component and dimension twice, no control characters (SQLite ends a text value at the first NUL byte). Store the policy's answer and the human's on each axis.

Copy the signed source, prove it first

1. The signed immutable Order is the only commercial source. Verify before writing: order accepted, envelope completed and belonging to the same quote version, artifact belonging to that envelope, the three agreeing on the document hash, and the snapshot complete. Each refusal gets a stable code.
2. Copy every amount, tier schedule and grouped total; reading the live catalog here is a defect. Copy the customer from the Order's own party snapshot so a rename cannot move the contract.
3. Dates are calendar dates (YYYY-MM-DD), validated by round-trip so 2026-02-30 is refused rather than normalized. State inclusivity, bound the term, refuse a notice period without auto-renewal, and record auto-renew and notice days as recorded only — there is no scheduler, so nothing fires on them.
4. Do not present a post-signature input as a signed term. If the signed document does not carry it, store its provenance next to it (termsSource) and require a human reason. When the order DOES carry a signed term snapshot (order-term), copy it verbatim as signed-order-terms, refuse manual term inputs (SIGNED_TERMS_AUTHORITATIVE) and collect no reason — the signature is the reason. Check what the document package actually contains before writing "the signed term" anywhere, and never collapse the two provenances.
5. Nothing is active before it starts. Decide state against an injected business date: a future term is scheduled and stays scheduled (no scheduler exists), and an ended term is refused rather than recorded as active.

One transaction, DB-enforced identity

1. Activation run, contract, version, lines, subscription, subscription lines and obligations commit together or not at all. Test it with fault injection at every write, and prove the retry produces exactly one complete activation.
2. Identity is a DB-unique source key, not a check-then-write: contract:order:<orderId>, contract-version:<contractId>:1, subscription:contract:<contractId>, contract-line:<versionId>:<componentId>. Prove it with two concurrent activations in one app and across two connections.
3. Never modify the source Order: set only its managed link.
4. "Already activated" is the first answer on a retry — before any classification work — so the refusal does not depend on whether the caller repeated the overrides.

Admin

Plan control, both axes of every classification with their reasons, each undecided axis highlighted with its own override editor that demands a reason, calendar term inputs carrying the term's provenance, one activation control that disables on submit, the human-actor caveat stated. After activation: evidence only — no control to progress, complete, bill, renew or cancel anything. The section renders only when /api/schema publishes the domain.

Renewal and amendment execution (M16b, ADR-035)

A renewal or amendment does not edit the agreement. It produces a successor agreement — its own signed Order, its own document hash, its own term and its own Subscription — written by the same activation writer, plus one immutable contract-succession row naming what it replaces. Issue no UPDATE against any historical contract, version, line, subscription or obligation row.

1. Signed evidence or nothing. Build a successor only from an Order carrying the ADR-033 term snapshot (order-term, covered by the signed documentHash). An Order whose signed document carried no term is refused 409 SUCCESSOR_TERMS_NOT_SIGNED. Never promote post-signature operational dates into a signed renewal term, and never collapse the three provenances (signed / post-signature operational / absent-unknown) into one badge.
2. Plan and execute are different things. The plan writes nothing — no record, no audit entry, no domain event. Execution is human-only and recomputes every fact inside its own transaction, so a recorded ready is an observation with a timestamp and never an authorisation.
3. One execution per source, enforced by the database. contract-succession.sourceContractId, .successorContractId, .successorOrderId and .executionRef are each UNIQUE. No in-process lock.
4. Derive the classification; never accept one. Match lines on offerLogicalKey|componentKey and derive renewal | expansion | contraction | mixed | commercial_change from the delta. Claim a narrow label only when the evidence supports exactly one reading — a price movement with no quantity movement is commercial_change, because nothing about it expanded.
5. Record continuity; block only incoherence. contiguous | gap | overlap | unknown against the source's inclusive end date. Overlap is a mid-term amendment and a gap is a lapse; only a successor term starting before the source term started is refused.
6. The round has an exit. planned → awaiting_signed_order | ready → executed, plus abandoned from any non-terminal state; both terminals never regress and nothing in the table reads a clock.

Do not implement here

Billing, invoicing, payment, usage rating, proration, ramps, minimum commitments, tax, FX, revenue recognition, MRR/ARR/TCV, seat changes on a live subscription, automatic or scheduled renewal, renewal-notice delivery, customer notification, cancellation, delivery execution, partner assignment, time/expense/margin, change requests, customer acceptance, service contracts, entitlements, SLA, support cases, a scheduler, a durable outbox, authentication.

Finish with npm run verify and the starter (node examples/starters/b2b-lead-qualification/install.mjs).