| name | anti-legacy:survey |
| description | Indexes one or more legacy source apps with wicked-estate (the code-graph engine) into per-app SQLite graphs under .anti-legacy/graphs/, then registers a deterministic wicked-estate stats digest as the checksummed `legacy-graph` evidence. wicked-estate natively captures the mainframe estate (COBOL/JCL/CICS/IMS/DB2 — module/function/field, JCL step/dataset, cics_program/cics_map, ims_database/segment, db2_table) AND modern languages (Java, C#, Python, TypeScript, Go, Kotlin, Rust, and others) in one pass, with {confidence, provenance} on every edge. Multiple repos stay as separate per-app DBs and federate via cross-graph (the merge case). No language routing, no batch extractor, no hand-rolled JSON graph. Use when: "scan the codebase", "discover the legacy code", "build the call graph", "index the source apps", "survey the source apps".
|
anti-legacy:survey
Indexes every legacy source directory in config.json with wicked-estate, the
MIT code-graph engine. Each source repo becomes its own structural graph DB under
.anti-legacy/graphs/<app>.db; the survey registers a deterministic stats digest
as the checksummed legacy-graph evidence the rest of the pipeline traces against.
The invariant: every source app indexes to a non-empty graph. wicked-estate
records file/line provenance on every node natively, so traceability back to the
original source is a property of the engine, not something this skill has to assert
per-node. The extraction phase (anti-legacy:extraction) reads each node's source
slice via the helper (wicked-estate source <name>) to understand how the legacy
system implemented each behavior.
Why wicked-estate, not a hand-rolled graph: one engine captures both the mainframe
estate and modern languages, resolves cross-language edges automatically (JCL EXEC PGM → COBOL, CALL → COBOL), and exposes a stable CLI (index/query/blast-radius/
stats/rank/source/cross-graph) plus a writable native requirement field for
the annotations the extraction phase produces. The graph is the evidence.
Deliverable: the code graph + its digest
This skill produces structural graph DBs and a checksummable evidence digest — not a
JSON graph blob. The field contract is the wicked-estate graph itself.
Per-app graph DB — .anti-legacy/graphs/<app>.db, one per source_apps entry:
- Built by
wicked-estate index <path> --db .anti-legacy/graphs/<app>.db.
- Carries
module/function/field (+ estate jcl step/dataset,
cics_program/cics_map, ims_database/segment, db2_table for mainframe;
class/method/struct/interface etc. for modern languages) as nodes, with
file/line provenance, and typed edges (calls/uses/references/accesses/
…) each carrying {confidence, provenance}.
- These DBs are gitignored (rebuilt by re-running survey); they live under
.anti-legacy/graphs/.
legacy-graph.digest.txt — .anti-legacy/legacy-graph.digest.txt, the committed
thin-seam evidence:
- The deterministic
stats_digest of each app's DB (the canonical node/edge-count
block, with volatile lines — STALENESS:, repo: git provenance, db=NN.NMB —
stripped so the digest is byte-stable across re-indexes of the same source).
- Its SHA-256 (computed by
manifest.file_checksum at register time) is the
checksummed legacy-graph evidence the gate/audit contract consumes.
Assertions (enforced by the stats-based done-gate in Step 6, surfaced in Step 4):
- Every app in
config.json indexes to a DB with ≥1 node (an app with zero nodes
means wicked-estate did not recognise the source — flag it; check the path/language).
- Every app's DB has a non-zero behavior-bearing node count (
module/function/
method/class/… — the kinds the extraction phase will annotate). Zero
behavior-bearing nodes means nothing downstream can carry a rule — flag it.
- Assets (DB2 tables, datasets, files) accessed by more than one app are surfaced to
the user as cross-app coupling (a major modernisation risk), discovered via
cross-domain
blast-radius/cross-graph over the estate accesses/uses edges.
Cross-Platform Notes
All graph construction is delegated to the wicked-estate binary via the
run.py wicked_estate helper (scripts/wicked_estate.py), which is pure-Python
subprocess + shutil.which (no shell builtins) and resolves the binary
cross-platform. Any glue here uses python3 with a python fallback. The helper
runs every invocation with cwd = repo root and --db always passed explicitly.
Config
python3 -c "import json; cfg=json.load(open('.anti-legacy/config.json')); [print(a['name'], a.get('language','?'), a['path']) for a in cfg['source_apps']]"
If config.json is missing, halt and ask the user to run anti-legacy:setup first.
Step 1: Check prerequisites
python3 .anti-legacy/run.py manifest status
If manifest is missing or phase is before setup, halt.
Confirm the engine resolves (config wicked_estate_path → WICKED_ESTATE_PATH →
PATH → the wicked-estate fallback). If it does not resolve, the helper raises a clear
error telling the user to set wicked_estate_path or install wicked-estate — surface
that and stop (never silently degrade):
python3 .anti-legacy/run.py wicked_estate resolve_binary
Step 2: Index each source app with wicked-estate
For every source app in config.json (no language routing — wicked-estate handles
the mainframe estate and modern languages in one pass), index the repo into its own
DB. One DB per source repo is what enables cross-graph federation = the merge case.
python3 .anti-legacy/run.py wicked_estate index --fresh \
--app {app1_name} {app1_path} \
--app {app2_name} {app2_path}
This shells wicked-estate index <path> --embeddings --db .anti-legacy/graphs/<app>.db
once per app (deleting any prior db first) and returns the parsed stats (node/edge
counts) for each. The helper creates .anti-legacy/graphs/ if needed.
Always survey with --fresh. Incremental indexing skips unchanged files, so
structure/spans computed by an OLDER engine binary persist stale after an engine
upgrade (e.g. a pre-fix binary's label-only COBOL paragraph spans survive a plain
re-index — verified). --fresh deletes the db first for a full re-parse, so the
survey graph always reflects the CURRENT engine. The graph DBs are gitignored and
rebuilt on demand, so a fresh build is cheap and authoritative.
Embeddings are ON by default (config embeddings: true; pass --no-embeddings
to skip). They are local (no API key) and power semantic correspond / semantic
— the cross-language merge-alignment signal. Without embeddings, cross-repo
correspond degrades to name-only and finds nothing across COBOL↔Java. Note: for
the merge, run correspond with a code-kind filter (--kind Function) — the
unfiltered default is dominated by README/markdown nodes.
There is no mainframe-vs-modern split, no graph_builder.py, no
survey-modern track, and no legacy_graph.json. wicked-estate auto-detects
language by content and records the language per node. Cross-language edges (JCL
EXEC PGM → COBOL, CALL → COBOL, modern imports) resolve automatically.
3a — Multiple repos: keep per-app DBs, federate via cross-graph
Each source app keeps its own DB. Single-repo consumers use the primary
(first) app's DB. Cross-repo queries (shared assets, blast-radius spanning repos)
federate over the per-app DB list with cross_graph:
python3 .anti-legacy/run.py wicked_estate cross_graph {asset_or_symbol} \
--db .anti-legacy/graphs/{app1_name}.db \
--db .anti-legacy/graphs/{app2_name}.db
This is the merge case: two source repos are NOT concatenated into one graph; they
stay separate and join only through the federated query surface.
3b — Language or path unclear
If an app indexes to 0 nodes, the path is likely wrong or the source isn't where
config says. Enumerate the directory to confirm there is indexable source, fix the
config.json path, and re-run Step 3 for that app:
find {app_path} -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10
wicked-estate recognises COBOL, JCL, CICS/BMS, IMS, DB2 DDL, and modern languages by
content; an empty graph almost always means a bad path, not an unsupported language.
3c — Re-project confirmed domain terms onto the fresh graph
A --fresh index deletes and rebuilds each DB, which wipes every domain_* term
annotation a prior vocabulary project wrote (the tags live only in the gitignored DB,
never in a sidecar). So after re-indexing, re-apply the confirmed glossary onto the new
graph so the engine's domain resolution (cluster / by-requirement / read-kv) stays
term-aware:
python3 .anti-legacy/run.py vocabulary project --db .anti-legacy/graphs/<app>.db
This is a clean no-op on the first survey (no terms are confirmed yet →
confirmed_available=0), so it is safe to run every time. On a re-survey after
extraction has confirmed terms, it is mandatory — skip it and the engine silently
degrades to name-only resolution with no error. Read the summary: a GAP: line for an
unbound or all_skipped confirmed term is a coverage signal, not a no-op. See
anti-legacy:vocabulary (Project confirmed terms) for the two-axes model — the committed
glossary is the durable record; these graph tags are a disposable re-derived projection.
Step 3: Summarise and surface key findings
Read each app's graph stats via the helper (no JSON file to parse — the stats come
straight off the DB):
python3 .anti-legacy/run.py wicked_estate stats \
--db .anti-legacy/graphs/{app1_name}.db
Repeat per app (or pass the helper the app list). Summarise the node-kind breakdown,
edge counts, and behavior-bearing totals across all apps.
Flag to the user:
- Any app with zero nodes (path/source problem — fix and re-index; see Step 3b).
- Any app with zero behavior-bearing nodes (
module/function/method/class/
…) — nothing downstream can carry a rule; investigate.
- Any app with a very large node count (large estate — the extraction crawl will
take longer; note it).
- Shared assets — DB2 tables, datasets, or files accessed by multiple apps
(cross-app coupling, a major modernisation risk). Discover these with cross-domain
blast-radius / cross_graph over the estate accesses/uses edges (Step 3a).
- Dead-End / Uncalled Entry Points: programs, classes, or interfaces with
in-degree 0.
- Cross-reference uncalled COBOL programs against JCL to check if they are batch
job-step targets.
- Cross-reference uncalled COBOL programs against CSD/CICS configurations to check
if they are online transaction/screen entry points.
- Cross-reference uncalled COBOL programs against MQ configurations to check if they
consume asynchronous messages.
- For modern languages (Java/C#), check for isolated interfaces (implemented by a
class but never imported/referenced elsewhere).
- For each uncalled entry point identified, decide its modernization disposition
in-band (inline) before proceeding to analyze.
Dead-ends are answered in-band: decide the modernization disposition for each
uncalled entry point inline as part of this step. There is no separate question queue
and no downstream blocking — resolve every dead-end here before the analyze phase.
Run the dead-end detection script to automate the above checks:
python3 .anti-legacy/run.py detect_dead_ends
detect_dead_ends now reads the graph via the wicked-estate helper (in-degree-0
detection through blast_radius/query, no legacy_graph.json), cross-references
against JCL/CSD/BMS/MQ configurations, detects isolated interfaces, and prints the
resulting dead-ends.
The agent resolves each printed dead-end in-band — deciding the modernization
disposition for every uncalled entry point — before proceeding to the analyze phase.
Step 4: Register the digest as evidence and advance phase
Done-gate — assert the graph is real before registering. The gate is now
stats-based (not a per-node file_path check, since wicked-estate carries
provenance natively): every app's DB must have ≥1 node and a non-zero
behavior-bearing count. If the assertion FAILS, do NOT register --status final
and do NOT advance — surface the specific app(s) that indexed empty (or with no
behavior-bearing nodes) and stop. The user fixes the source/path and re-runs Step 3.
The register and advance calls below are CONDITIONAL on this assertion passing.
Write the deterministic stats digest for all app DBs and assert the gate in one step
via the helper (the helper computes stats_digest per DB, strips volatile lines, and
fails non-zero if any app has 0 nodes or 0 behavior-bearing nodes):
python3 .anti-legacy/run.py wicked_estate write_digest \
--out .anti-legacy/legacy-graph.digest.txt \
--db .anti-legacy/graphs/{app1_name}.db \
--db .anti-legacy/graphs/{app2_name}.db
If write_digest exits non-zero, it prints which app DB is empty / has no
behavior-bearing nodes. Fix and re-index — do NOT register or advance.
Only if the digest was written and the gate passed (exit 0), register the digest and
advance. Note: --format text (not json), and no --schema (the
code-graph.schema.json is retired):
python3 .anti-legacy/run.py manifest register legacy-graph \
--path legacy-graph.digest.txt \
--format text \
--produced-by anti-legacy:survey \
--status final
python3 .anti-legacy/run.py manifest advance survey
The registered digest's SHA-256 (computed by manifest.file_checksum) is the
checksummed legacy-graph evidence. After the extraction phase writes requirement
fields, survey/extraction re-registers this digest so it reflects the annotated graph
— making code↔annotation drift checksum-detectable (the §I6 keystone; wired here,
gated in a later workflow).
Output
.anti-legacy/graphs/<app>.db — one wicked-estate structural graph per source app
(gitignored; rebuilt by re-running survey). The estate + modern code graph with
{confidence, provenance} per edge..anti-legacy/legacy-graph.digest.txt — deterministic, checksummable stats digest
(the committed thin-seam evidence).- Manifest: phase =
survey, artifact legacy-graph registered (format=text,
produced-by anti-legacy:survey, status final).
Next step: anti-legacy:analyze to apply structural lenses by querying
wicked-estate (entry points via rank/blast-radius/query, shared-asset coupling
via cross-domain blast-radius, batch-vs-online via JCL/CICS estate node kinds).
