Inspiration

Corporate payment files never died. The people and tools that could read them did.

EDI 820 remittance orders, 823 confirmations and BAI2 bank statements still move between banks and ERP systems every day as fixed-width text. What each byte means is written in a COBOL copybook. A back office that cannot read the copybook retypes the file into a spreadsheet, and nobody can say afterwards which number came from the file and which came from a person.

「820」 is the resurrection: take the file plus its copybook and give the same answer every time, with the evidence attached.

What it does

「820」 runs four separate layers over a payment file.

  1. Parser. Every record is typed at the copybook's byte offsets: trailing overpunch, leading separate sign, COMP-3 packed decimal with no line breaks, implied decimals. A copybook that declares REDEFINES (the same hundred bytes are the payment in one layout and the trailer in another) is read as a region: exactly the layout its discriminator selects, and an unmatched record is reported instead of guessed. Amounts are bigint minor units with an ISO 4217 currency, never floating point.
  2. Reconciler. Control totals per currency, record counts, payment references and value dates against a settlement window, emitted as coded findings with signed deltas.

  3. Explainer. An optional agent layer that narrates a finding, allowed to cite only numbers the first two layers produced. Anything else is refused and replaced with INSUFFICIENT_EVIDENCE. By default it runs a deterministic template and spends no credits.

  4. Human. The exception register. A reason, an expiry date and a compensating control are required before an exception can exist, the register is append only and hash chained, and a waiver never turns a verdict green.

The verdict is deterministic and re-derivable. 820 verify re-runs the deterministic layers from the recorded inputs and compares a SHA-256 fingerprint, read only, so a third party can check the answer without trusting me.

Three surfaces share one core: a CLI with exit codes 0, 2 and 3, a three column web screen that shows the bytes behind a finding, and an MCP server with five tools. The web screen also ships as a static client side build in docs/demo, the same engine compiled for the browser, so a judge can click through eight scenarios with no server at all.

How I built it with Kiro

Kiro CLI 3.5.0 and the .kiro workspace format, used as one loop rather than a list of features.

Spec driven development. .kiro/specs/edi820-importer/ holds 33 requirements in EARS form in seven groups (25 core R1 to R6, plus R8.1 to R8.8 for the register), a design with a delta log for every decision that changed while building, and tasks T0.1 to T9.5, each ending in a command whose output goes into the evidence log. docs/copybook-to-spec.md records what the copybook decides by itself (offsets, widths, sign, scale) and what it cannot decide (is a short record re-synchronised or reported, are totals compared per currency, may the explainer cite nothing), and where each answer was written.

The honest boundary: I did not run the IDE spec flow. The spec was authored in this workspace from the copybooks and the implementation ran here with the spec as the contract. The repository says exactly that rather than implying Kiro generated the code.

Steering. Five steering files, and one of them visibly changed the code. tech.md says money is never floating point; the design draft had typed numeric values as number, which is a float; the implementation uses bigint minor units and the change is recorded as implementation delta 1 in design.md section 10. finance-file-conventions.md holds the domain rules, conventions.md holds the prohibitions (no floats, no silent re-sync, no model in the verdict path), product.md says who the tool is for and what it refuses to decide, and structure.md keeps the layer boundaries the reviewer agent is asked to check.

Custom agent. .kiro/agents/reviewer.json is an adversarial cross review agent: it reads the spec and the deterministic findings and tries to break the claims, and it may not rewrite code. Without a tools array it produced a fluent, confident review with file and line citations and three of its four claims were false, because it had never read a file. With tools: [read, grep, glob, thinking] the same agent found two real defects: a record with a blank reference was skipped entirely so it never appeared as REF_UNMATCHED, and the matched reference count was derived by string matching a human sentence instead of being counted where matching happens. Both are fixed with tests. That is why the product's explainer may only cite numbers the deterministic layers produced: a reviewer's confidence is not evidence.

Hooks. .kiro/hooks/parser-guardrails.json declares three hooks, and all three fire in live sessions with out/hook-log.txt committed so a reader can check rather than trust: PostFileSave runs the unit and property suites when a parser or copybook file is saved; the stop hook resolves the newest report holding a verdict and re-derives it with the real CLI entry, so fingerprint drift surfaces in the session; the task hook appends one row to EVIDENCE.md and logs its own firing. Each of them was broken first and was fixed by probing, not by reading: the stop hook's command pointed at a module with no entry point, the trigger name was AgentStop which never fires, and the task hook's trigger was PostTaskExecution instead of PostTaskExec. The probes are in docs/kiro-session-evidence.md.

MCP. src/mcp/ is a JSON-RPC 2.0 server over stdio with five tools: parse_file, reconcile, explain_findings, verify and exceptions. It is implemented against the protocol directly because the SDK could not be installed here, and a unit test runs a real stdio session, including a malformed line that must not kill the server. It is attached to the reviewer agent through .kiro/settings/mcp.json; in the review session the agent called reconcile, exceptions and verify and got back FAIL with 4 findings and the fingerprint 7af64454..., and the same call replayed outside an agent prints the same values. The agent and the CLI are not two implementations.

Property based testing. Seven property suites, 31 property tests, 311 tests in total with fast-check and Vitest. Round trip byte fidelity including CRLF and a COMP-3 stream with no newlines; 500 generated copybooks compiling to contiguous field starts; REDEFINES layouts covering the same byte range with a discriminator that selects one; amount encodings that re-encode to the same bytes. The amount property found a real bug (the encoder sized values by integer digits only, so implied decimals were dropped), and the overpunch table was wrong in the first draft because it was built from 'A' + 0.

Kiro powers. Not used. Nothing here depends on a bundled power, and I would rather say that than describe a power I read about.

Challenges

Trust is the product. The first version of the tool was easy. The hard part was removing every place where it could quietly be right for the wrong reason: a short record silently re-synchronised, a blank reference dropped, a matched count derived from prose, a BAI2 trailer counted in three different branches. Four of the six defects listed in EVIDENCE.md are of that kind.

The copybook is not a spec. It gives byte offsets and nothing about what must be true. Writing 25 core requirements that a copybook cannot express is where most of the design work went.

A confident reviewer is not a reviewer. The agent's failure without read tools was more instructive than its success, because the product makes the same distinction between a model that narrates and a layer that proves.

Accomplishments

  • 311 tests, 31 of them properties over generated inputs, with a regression file for every failure the build found in itself, including a truncated record that used to reach PASS with zero findings (now INCOMPLETE, exit 2).
  • Three byte layouts, one REDEFINES region with two active layouts, and three formats (820, 823, BAI2) through one reconciler.
  • A verdict anyone can re-derive: verify prints both fingerprints and the first differing field path, and does not touch the report.
  • An agent layer that cannot invent a number and costs zero credits by default.
  • A human layer that cannot be edited back into agreement: append only, hash chained, and a waiver carries an owner, a reason, a compensating control and an expiry.
  • One engine in three places: CLI, local screen and a static browser build whose fingerprints are asserted equal to the CLI's for all eight sample scenarios.

What I learned

Writing the prohibitions down as rules, not preferences, made the biggest difference. "Never silently re-synchronise" is exactly the kind of thing a generator will happily violate because it makes the demo pass. A written requirement and a property test exist to disagree with the code, which is not the same as asking a model to be careful.

What's next

  • A host side witness: two independent runs of the same file on different machines, compared by fingerprint.
  • Streaming parse for files larger than memory, and OCCURS DEPENDING ON, which changes every offset after it and needs a decided rule rather than a parser tweak.
  • A reconciliation mode for 823 confirmations against 820 remittances, which is the same engine with a different reference direction.

The parsing and reconciliation core is already decoupled from the runtime (CLI, stdio MCP server, and local browser tab), and human waivers already use a SHA-256 hash-chained append-only ledger. For enterprise deployment, the next step is integrating with on-prem DLP policies and adding multi-signature approval workflows on top of that ledger to prevent single-approver fraud.

All sample data is synthetic, from a fictional company. No customer, bank or employer data is used. Apache-2.0.

Built With

Share this project:

Updates

Submission history