AB-285: COBOL codebase inventory and migration analysis

[devin-ai-integration]

Summary

Documentation only (documentation/migration/, no changes under src/). Source-grounded inventory of the COBOL system for Jira AB-285 (epic AB-276), cross-checked against system-architecture.md and data-dictionary.md. Where the source and the docs disagree the disagreement is recorded as a risk, not silently reconciled.

Doc	Content
README.md	Traceability index (every .cbl, .cpy, JCL, DDL, VSAM, CSD/BMS artifact → where it is covered) + consolidated risk register R-01…R-20
program-inventory-and-call-graph.md	38 program files (P-01…P-38), static CALL / EXEC CICS LINK graph, per-program I/O, SQL, CICS, error behaviour, copybook usage matrix, missing dependencies
data-flow-map.md	Program ↔ store matrix for QSAM / VSAM / DB2 / CICS-BMS, end-to-end flows, TRANHIST → POSHIST field lineage
copybook-entity-mapping.md	20 copybooks → entity / value object / enum / contract / platform glue, with computed record lengths
business-rules-catalog.md	~80 rules tagged CODE / DOC / BOTH / CONFLICT / DEAD with the enforcing paragraph
jcl-job-inventory.md	16 JCL members, DD → DSN bindings vs program ASSIGNs, documented vs actual batch cycle

Every relationship is derived from literal source statements (CALL '…', LINK PROGRAM(…), COPY, ASSIGN TO, EXEC SQL, EXEC CICS, JCL DD, IDCAMS DEFINE, DDL, CSD, BMS); architecture prose that has no implementing code is tagged DOC/missing.

Headline findings (details in README.md risk register)

• Ticket says 37 programs; there are 38 .cbl files — batch/POSUPDT.cbl is a zero-byte placeholder, enumerated as P-04.
• The documented daily cycle TRNVAL00 → POSUPD00 → HISTLD00 → RPTGEN00 does not exist in source or JCL; no code path connects PORTFILE/TRANFILE to POSMSTRE/TRANHIST/DB2 POSHIST.
• PORTTRAN's buy/sell/fee arithmetic (2200-UPDATE-POSITIONS) is never performed and relies on the missing PORTREC copybook. DB2STAT, PORTREC, SQLPOS copybooks are referenced but absent.
• Three conflicting physical definitions of the portfolio master (PORTDEF.jcl 200/18, vsam-definitions.txt 400/12, PORTMSTR.cbl 100/10; PORTFLIO.cpy computes to 148). TRANHIST is ESDS in the data dictionary, KSDS in IDCAMS and code.
• HISTLD00 loads POSHIST from TH-* fields that no copybook defines; there is no skip-to-checkpoint logic despite documented restart.
• Online layer name mismatches: maps INQMAP/INQMNU vs BMS MENMAP/POSMAP/HISMAP/ERRMAP; INQHIST selects TRANS_UNITS… vs DDL QUANTITY…; ERRHNDL is LINKed but not in the CSD; DB2ONLN overwrites its status with the connection count.

Verification

• Scripted cross-check: every file under src/programs, src/copybook, src/jcl, src/database, src/cics, src/maps and every CREATE TABLE/INDEX/VIEW/PROCEDURE name appears in the docs.
• Record lengths recomputed from PIC clauses and compared with LRECL / RECORDSIZE / data dictionary.
• Note: the repo blueprint's make check / make all cannot run — there is no Makefile or tools/preprocess.sh in the checkout; not relevant to this docs-only change but worth fixing in the blueprint.

Link to Devin session: https://app.devin.ai/sessions/62ebf87ae24c48ba91d52d6cfd75bcd8
Open in Devin Desktop: https://app.devin.ai/desktop/session/62ebf87ae24c48ba91d52d6cfd75bcd8?variant=devin

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring