Adds a third build method alongside transform (cross-stack rewrite) and
reimagine (greenfield): uplift, for same-stack version bumps (.NET Framework
4.8 -> .NET 8, Spring Boot 2->3, Python 2->3) where the right move is to
PRESERVE the code and fix only the version deltas, not extract intent and
rewrite.
- commands/modernize-uplift.md: delta-catalog-driven, dual-target test harness
(one suite on both runtimes; baseline-on-old is the oracle), leaf-first build
graph ordering, minimal-diff discipline (architecture-critic flags gratuitous
divergence), and a 'this is a rewrite, use transform' escape hatch.
- agents/version-delta-analyst.md: finds the source->target breaking changes
that THIS code hits; drives the ecosystem migration tool (upgrade-assistant /
OpenRewrite / pyupgrade / ng update) and owns the residue; read-only.
- workflows/uplift-deltas.js: parallel finder per delta category, each verified
against the cited code so deltas that don't apply here are dropped.
- Wired into assess (recommended-pattern routing), brief (per-phase command +
leaf-first ordering), preflight (dual-run + tool readiness), status, README.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
COCOMO's constants encode human-team productivity; presenting its
person-months as how long an agentic modernization will take (or cost) is
a claim we should not make. Reframe COCOMO everywhere as a RELATIVE
complexity/scale index for ranking and sequencing systems only:
- assess: capture COCOMO as a complexity index; explicitly ignore scc's
'Estimated Schedule Effort' and cost-in-dollars; ASSESSMENT 'Effort
Estimation' section becomes 'Relative Scale' with a not-a-timeline note;
portfolio heat-map column renamed Complexity (COCOMO index).
- brief: phase plan uses relative T-shirt sizing, not person-months/weeks;
phases render as a dependency flowchart, not a gantt (gantt = calendar).
- portfolio-assess.js: field cocomoPm -> complexityIndex; return label
carries the not-a-duration caveat.
- README: 'A note on COCOMO' explains the index framing and points at
better intrinsic-complexity proxies.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Viewer (assets/topology-viewer.html):
- inline a minified d3 subset (hierarchy/pack, zoom, selection,
interpolateZoom, ease; ISC license) instead of loading from a CDN —
the page is now fully self-contained and works on air-gapped networks
- handle duplicate node ids (unique-suffix; edges bind to the first
occurrence) and store parent references directly, fixing
level-of-detail and selection corruption with messy generated data
- share one reveal rule between drawing, edge culling, and hit-testing
so edges no longer draw into collapsed containers
- pre-bucket edges by kind and keep a per-node adjacency map; the
hover/selection pass no longer scans every edge each frame
- cancel in-flight fly-to animations when a new one starts; clamp
fly-to zoom to the zoom extent; derive max zoom from the smallest
leaf so deep estates stay reachable
- render dead-end candidates (new deadEnds field) with a dashed
outline and a sidebar badge
- clicking a node during a flow walkthrough exits the walkthrough;
search results clear on selection and Escape; surrogate-safe label
truncation; clearer stats line; explicit empty-topology message
Commands:
- new /modernize-status: read-only progress report — artifact inventory
with timestamps, staleness flags, secrets-hygiene checks, next step
- map: deadEnds in the topology schema; datastore names must be logical
identifiers with credentials stripped from URLs/DSNs
- brief: read topology.json + .mmd files (not the interactive HTML);
staleness check against inputs; effort unit aligned to person-months
- transform: secret-safe characterization-test prompt; diff -y fallback
when delta is missing; credential-safe diff selection
- reimagine: target vision is everything after the first argument (was
silently truncated to one word); masking rules in spec/scaffold/
handoff prompts
- brief/transform/reimagine: human-approval gates phrased as explicit
stop-and-wait instead of 'enter plan mode'
- preflight: delta in the tool table; brief added to the verdict list
- README: preflight/status in the workflow; legacy/ deny list also
covers Write; plugin + marketplace descriptions updated
modernize-map previously rendered the call graph and data lineage as
static Mermaid diagrams, which become unreadable once a node has ~10+
edges — exactly the shape of real legacy systems. It now builds an
interactive viewer from a shipped template (assets/topology-viewer.html):
a zoomable circle-pack of domains/modules sized by LOC, rendered to
canvas with level-of-detail reveal, dependency edges with per-kind
toggles, search with fly-to, a per-node detail sidebar, and a flow
walkthrough mode. Small domain-level .mmd exports remain for docs.
- topology.json now has a documented schema (hierarchy + edges + entry
points + observations + flows) consumed by the viewer
- map traces 2-4 business flows anchored to personas (claimant,
operator, auditor), each step in plain business language mapped to
the modules that implement it; the viewer plays them as numbered
paths
- brief gains a Business Walkthroughs section connecting each persona
flow to the phase that replaces it
- new modernize-preflight command: detects the stack, checks analysis
tooling, smoke-compiles a real source file with the legacy toolchain,
inventories missing copybooks/descriptors/binary-only artifacts, and
writes a per-command readiness verdict
- transform now verifies legacy + target toolchains before its plan
gate instead of failing at test time
- README: commands updated, optional-tooling section reframed as 'what
to give Claude'
Fixes found by running the discovery workflow against the AWS CardDemo
mainframe sample (~50 KLOC of COBOL/CICS/JCL/BMS/VSAM):
- modernize-assess: add scc -> cloc -> find/wc fallback chain with the
COCOMO-II formula so Step 1 works when scc isn't installed; same for
portfolio-mode cloc/lizard. Drop the reference to a specific
agent-spawning tool name (just "in parallel"). Sharpen the structural-
map subagent prompt: 5-12 domains, subgraph clustering, ~40-edge cap,
repo-relative paths, dangling-reference check.
- modernize-map: expand the parse-target list with the things a
literal-minded reader would miss on a real mainframe codebase — CICS
CSD DEFINE TRANSACTION/FILE for entry points and online file I/O,
EXEC CICS file ops, SELECT...ASSIGN TO joined with JCL DD,
EXEC SQL table refs (not JCL DD), SEND/RECEIVE MAP, dynamic
data-name XCTL resolution, COBOL fixed-format column slicing. Without
these the dead-code list is wrong (most CICS programs look unreachable).
Also write a machine-readable topology.json alongside the summary.
- modernize-extract-rules: add a Priority (P0/P1/P2) field with a
heuristic, and an optional Suspected-defect field. modernize-brief
reads P0 rules to build the behavior contract, but the Rule Card had
no priority slot — the chain was broken.
- modernize-brief: read the new P0 tags; flag low-confidence P0 rules as
SME blockers.
- modernize-reimagine: drop "for the demo" wording.
- security-auditor agent: add mainframe/COBOL coverage items (RACF,
JCL/PROC creds, BMS field validation, DB2 dynamic SQL, copybook PII)
and mark web-only items as such so it adapts to the target stack.
- README: add Optional Tooling section and a symlink example for the
expected layout.
- modernize-brief: read TOPOLOGY.html (what modernize-map actually
produces) instead of nonexistent TOPOLOGY.md, and tell the user which
command produces each missing input.
- README: rewrite the Commands section to match actual command behavior —
correct output filenames, ordering (brief is the synthesis/approval gate
after discovery, not the first step), agent attributions, and required
args. Add a workspace-layout note and an explicit callout that
modernize-harden edits legacy/, which conflicts with the recommended
deny rule. Reconcile the Overview and Typical Workflow sequences.
- modernize-assess: generalize the production-runtime overlay step so it
no longer assumes a specific MCP server/tool; mark it optional. Fix
app/jcl/ -> legacy/$1/jcl/ for layout consistency.
- modernize-map: make TOPOLOGY.html self-contained (load Mermaid from a
CDN) so it renders in any browser; drop assumptions about an external
artifact renderer. Generalize the telemetry annotation note.
- business-rules-extractor agent: fix command cross-reference to the
actual command name.
- plugin.json: include the brief step in the workflow description.
