| name | anti-legacy:capture-corpus |
| description | Assemble a GOLDEN CORPUS for the differential-equivalence gate (GATE_3C_DIFFERENTIAL) from whatever is available on the project, and grade how trustworthy it is. Most projects never have pre-captured legacy I/O, so without this the gate is permanently NOT_APPLICABLE. This skill builds the best-available golden — from the test contracts' expected_output (always present after test-strategy), a source-derived reference oracle, or real captured legacy I/O — tags every entry with its provenance + confidence, and emits a provenance report that explains, in plain English, why a verdict built on it should or should not be trusted. The gate then WARNS graded by that confidence ("the data could be incorrect, and here is why") rather than hard-blocking on a golden that may itself be wrong. Only a FAIL against CAPTURED legacy blocks. Use when: "capture corpus", "build a golden corpus", "GATE_3C is NOT_APPLICABLE / vacuous", "I don't have legacy I/O", "differential equivalence has no golden", "assemble parity golden".
|
anti-legacy:capture-corpus
GATE_3C_DIFFERENTIAL proves the target produces the same outputs as the legacy — but only if it
has a golden corpus (legacy inputs + the outputs the legacy produced). The hard truth on a real
project: you usually do not have captured legacy I/O, and you may never get it (the mainframe is
gone, the data is sensitive, the system can't be safely run). Left there, the gate is permanently
NOT_APPLICABLE and proves nothing.
This skill makes the gate useful anyway: it assembles the best-available golden from what the
project actually has, and is honest about how much to trust it. The gate then becomes a
provenance-graded warning — it tells you the parity result and tells you how much that result
is worth, based on where the golden came from. It is not a hard gate unless the golden is
captured legacy: a divergence against an assumed/derived golden is a warning that the data could be
incorrect (the target may be wrong, or the golden may be wrong), not a build-breaker.
The provenance spectrum (strongest → weakest)
| Provenance | Confidence | What it is | Where it comes from |
|---|
captured-legacy | high | a real legacy run / recorded production I/O, with a capture attestation | instrument or replay the legacy system; recorded outputs + a capture manifest |
captured-legacy-unverified | low | a --captured entry that claimed captured-legacy but carried no valid attestation — auto-demoted (ISS-24) | a relabel attempt with no capture manifest |
source-oracle | medium | a reference oracle faithful to the legacy source arithmetic | hand-built from the source (see demo/differential-equivalence/) |
contract-expected | low | the test contracts' scenarios[].expected_output — the assumed behavior authored from the extracted rules | every project has this after anti-legacy:test-strategy |
The gate's trust in a verdict is only as strong as the weakest golden it used. A FAIL against an
attested captured-legacy golden blocks (real divergence → kick back to build); a FAIL
against a source-oracle, contract-expected, or captured-legacy-unverified golden warns (it
might be the golden that's wrong).
Capture attestation — the high tier is machine-enforced, not self-declared (ISS-24)
captured-legacy is the ONLY provenance that can hard-BLOCK the build, so the label alone is not
trusted: it must be proven by a capture attestation. A --captured entry only earns the
captured-legacy stamp when it carries a capture object recording how the I/O was captured —
otherwise it is auto-demoted to captured-legacy-unverified (low) and a warning names it. The
attestation shape (all three keys present + non-empty):
{
"scenario_id": "REQ-1::happy",
"req_id": "REQ-1",
"golden_output": { "GROSS": "1234.56" },
"capture": {
"method": "replay",
"source": "PROD-LPAR1 / BILLING.cbl",
"captured_at": "2026-06-16T14:00:00Z"
}
}
A bare captured-legacy label with no capture block (or a block missing/blanking any key) cannot
reach the blocking tier — both capture_corpus (at stamp time) and differential_equivalence
(at gate time) independently demote it. This is defense-in-depth against a careless or convenient
relabel of an assumed golden.
Cross-Platform Notes
The one command (capture_corpus) is pure standard-library Python through the dispatcher — os,
json, no shell-isms — identical on macOS / Linux / WSL / Windows.
Step 1: Assemble the best-available corpus
python3 .anti-legacy/run.py capture_corpus assemble \
--contracts .anti-legacy/contracts \
--out .anti-legacy/evidence/corpus.json \
--report .anti-legacy/evidence/corpus-provenance.json --json
With nothing but contracts, you get a contract-expected (low-confidence) corpus — the assumed
behavior, NOT the legacy's actual output. That is honest and still useful: it makes the gate run and
warn. Overlay higher-confidence sources as you obtain them (they replace lower ones by scenario_id):
--oracle <source-oracle-corpus.json>
--captured <captured-legacy-corpus.json>
Exit 0 = corpus assembled, 1 = nothing available (no contracts/oracle/captured → the gate will
be NOT_APPLICABLE), 2 = bad inputs.
Step 2: Read the provenance report — believe it, don't oversell it
The report carries golden_confidence (the weakest tier present), the provenance distribution,
and warnings. Surface the warnings to the human. If confidence is low/medium, a subsequent
GATE_3C FAIL is a warning to investigate, not proof the target is broken — the golden itself may
encode an assumption that is wrong. Never present a low-confidence PASS as "parity proven."
Step 3: Raise confidence when you can (optional, recommended for money paths)
- Source oracle (medium). When the legacy can't be run, re-implement the source arithmetic
faithfully and emit its outputs as the golden — the standard migration substitute.
demo/differential-equivalence/billing_oracle.py is a worked example: it encodes BILLING.cbl's
COMPUTE INV-TAX with its real COBOL semantics (no ROUNDED → truncation) so the gate catches a
target that silently rounds.
- Captured legacy (high). If you can run or replay the legacy system, record its inputs +
outputs and feed them via
--captured, each entry carrying a capture attestation
({method, source, captured_at}). This is the only golden that makes GATE_3C a hard gate — and
only when attested: an unattested --captured entry is demoted to captured-legacy-unverified
(low) and warns, so it never forces a false block.
Step 4: Feed the gate
python3 .anti-legacy/run.py differential_equivalence run \
--corpus .anti-legacy/evidence/corpus.json \
--actuals .anti-legacy/evidence/actuals.json \
--contracts .anti-legacy/contracts \
--out .anti-legacy/evidence/differential-equivalence-report.json
The report's gate_posture is PASS / WARN / BLOCK / NOT_APPLICABLE. anti-legacy:gatekeeper
honors it: WARN surfaces loudly but does not block; only BLOCK (a FAIL against captured
legacy) kicks back to build. See anti-legacy:differential-equivalence for the run + record flow.
Done-gate
corpus.json exists (or the report honestly says nothing was assemblable).- A provenance report with
golden_confidence + warnings is produced and surfaced to the human.
- Your status report states (§6): how many scenarios, at what confidence, from which sources, and the
explicit caveat that a low/medium-confidence verdict is advisory — what is NOT proven, and how to
raise it.
Failure cases
- No contracts, no oracle, no captured I/O → empty corpus,
golden_confidence: none; GATE_3C
stays NOT_APPLICABLE. Run anti-legacy:test-strategy first (it produces the contracts whose
expected_output seeds a contract-expected corpus).
- Tempted to relabel a contract-expected corpus as captured-legacy to force a hard gate → it
won't work (ISS-24). A
captured-legacy entry with no capture attestation is auto-demoted to
captured-legacy-unverified (low) at both stamp time and gate time, so the relabel stays a
warning, never a block. The whole point is honest provenance — supply a real capture manifest
({method, source, captured_at}) or accept the low-confidence WARN.
