Trace contract program
What it is¶
The Trace Contract Program extends the method that produced the subrogation thesis brief to every other tool in the pipeline. The richness of that brief comes from the trace shape, not the renderer. Each tool can produce an equivalent governed section only once its trace carries cited facts with four-status, every rule evaluated and recorded, indeterminates naming fields, money in heads, and deadlines with anchors. The program is the directive that makes each tool's trace meet one contract, brings each through the evaluation kit, and compiles the result into the Claim Intelligence Brief . It starts after Part C acceptance and PD-1 Tier 1, and runs about three and a half weeks single-stream for Auto and Property.
The universal trace shape¶
Part 1 of the directive defines one trace contract for every rules tool. A conforming trace has:
| Section | Content |
|---|---|
| header | Tool, run, and upstream_outputs: which upstream tools' records this run read |
| inputs ledger | Every field read, with value and speaker where stated, or not_stated or not_returned |
| determinations | Each determination with a reason code from a closed enum |
| rules_evaluated | Every gate, defense, exclusion and trigger in the active corpus, the fields it read, its outcome fired or not, and a basis_key |
| indeterminates | Each indeterminate naming the fields it needed and who_can_supply them |
| money heads | Each head stated, computed from stated inputs, pending, excluded or indeterminate |
| deadlines | Each deadline with its anchor; no date, never computed |
| what_would_change | Derived from the indeterminates and the fired rules, not authored |
| contract_gaps | Keys a rule needed with no source path |
Reason codes and statuses are closed enums; a non-enum value raises, and free text is never parsed into one . The four fact statuses, stated, not_stated, not_extractable and not_returned, are the only ones a trace carries . A basis_key is an audit annotation and never adjusts a confidence score.
The contract is generated, not authored. Step 0 of the lineup re-validates subrogation against the generated checker, so the tool that already meets the shape is the first one measured against it.
Per-tool invariants¶
Part 2 is a mapping table: for each tool, how its current trace maps to the contract, and the tool's own monotonicity invariant. The kit applies to every rules-over-facts tool unchanged (generated contract, signed scenario spec with removal axes, per-criterion runner, static coverage of the record graph, invariant fuzzer, corpus mutation, fix protocol), and each tool adds one invariant the fuzzer exercises:
| Tool | Invariant |
|---|---|
| CoverageAnalyzerGKR | Coverage never moves toward covered on fact removal |
| AuthorityGateGKR | Authority never lowers; a missing upstream never makes fast-track likelier |
| CCIEvaluatorGKR | CCI never lowers |
| ReserveEstimatorGKR | Not yet documented |
| JurisdictionResolverGKR, LiabilityAnalyzerGKR, SID Phase B | Not yet documented |
The two tools that call a model, FNOLExtractorGKR and SID Phase A, use the golden-set and presentation-invariance method instead of the kit . Pipeline-level invariants across tools are added from the authority gate step onward.
The six-step cycle¶
Part 3 runs every tool through six steps, with a hold at steps 2 and 6 where the expert rules before work continues:
- Census: what the tool's trace carries today against the contract, with every claim citing its query and returned value.
- Ruling: the expert classifies each gap and rules on it. Hold.
- Contract fix: the trace is brought to the contract under the fix protocol.
- Kit: the evaluation kit runs against the tool, invariant included.
- Brief section: the tool's section is rendered against a target page the expert writes first, sentence by sentence.
- Close-out: standing header, what changed, results, differences as proposed rulings, debts. Hold.
Estimated effort is a day to a day and a half per rules tool. Parts 5 and 6 of the directive cover reporting and the don'ts; the report format is the one in the repository's standing rules, and a close-out that opens with any other set of commands is rejected unread.
The lineup¶
Auto and Property first, each tool for both LOBs before the next:
| Step | Tool | Note |
|---|---|---|
| 0 | Subrogation | Re-validated against the generated checker |
| 1 | carrier_structured normalizer and shared inputs ledger |
Canonical intake schema; replaces standing header item 4 with generate_intake_schema.py --diff once landed |
| 2 | Resolver and obligations | |
| 3 | Coverage | Before liability: the payment gate and authority gate need it, and it carries the most curation |
| 4 | Liability | Moves legally_recoverable from pending to computed |
| 5 | Authority gate | First pipeline invariants |
| 6 | SID Phase B | |
| 7 | CCI | |
| 8 | Reserve | |
| 9 | Compiled Claim Intelligence Brief | Built only from tools that passed their kit |
WC and GL follow. They reuse the contracts, add records, and add CompensabilityAnalyzerGKR as a tenth tool . Status-envelope printing by IntelligenceBriefGKR and ObligationEngineGKR is step 1 work.
Branch and gate¶
All program changes go on the feature branch TraceContractProgram. The testing team keeps testing on main without being impacted. The gate for every change is that subrogation downstream is not broken and is made better: a change that leaves the thesis brief, receipt or conformance worse than the baseline does not merge. Directives to Claude Code stay clean, prescriptive and standards-enforcing, and every commit that changes behaviour re-runs the standing five and reports them .
Why the shape matters¶
Three findings from the arc are the case for one contract. A rules engine with no rules is a well-tested null: three tools were classed shadow-ready on code completeness while their catalogues were empty, and every review passed because every review was of code. A field that names a control claims the control ran, so an empty overlay_rejected list or "no triggers declared anywhere" reported as a clean audit is an unbuilt layer, not compliance. And could-not-evaluate must never render as considered-and-rejected. The contract makes each of these visible in the trace: rules_evaluated shows what was checked, contract_gaps shows what could not be, and indeterminates names who can supply it.
Open items¶
Invariants for the resolver, liability, reserve and SID Phase B are not yet documented. The set of pipeline-level invariants is not yet documented. The program had not started as of the sources; Part C acceptance and PD-1 Tier 1 precede it.