modernize-brief

Synthesize everything in analysis/$system/ into a Modernization Brief: the single document a steering committee approves and engineering executes. Target stack: $target_stack (if blank, the one in analysis/$system/INTENT.md, else recommend one from the assessment).

Read ASSESSMENT.md, topology.json (and the .mmd files beside it; never read TOPOLOGY.html, it is a viewer with the data minified inside) in analysis/$system/ first, and BUSINESS_RULES.md too unless this is a same-technology uplift (the intent or the assessment says so): an uplift keeps the code, so its Behavior Contract is the recorded baseline and extract-rules can wait. If a required file is missing, say so and stop: they come from assess, map and extract-rules, which run first. Four more inputs are conditional:

• RULE_REVIEWS.json / RULE_REVIEWS.md, if they exist (written by /code-modernization:modernize-review): a person's verdicts on individual rules. Never put a rule marked wrong or discuss in the Behavior Contract as settled behavior: list each in section 7 as an open question with the reviewer's note, and block the phase that covers its module on it. A confirmed rule counts as confirmed by a person.
• INTENT.md, if it exists (written by /code-modernization:modernize): what the person wants (goal, target, what must stay true). It is the objective of this plan; never override it with a guess. Its goal decides each phase's build command: a newer version of the same technology means uplift, a rewrite in another technology means transform, a rebuild on a new architecture means reimagine. Without it, the assessment's pattern decides.
• PREFLIGHT.md, if it exists. It holds two things nothing else has: the human's answers to preflight Check 0 (scope, local build and test, bespoke build infrastructure, prior attempts, what is off limits) and the Check 6 scope boundary (whether the source is a slice of a larger codebase, and what outside it depends on code inside it). Both constrain this plan more than anything derivable from the source. Never override a human's answer with a guess.
• DELTA_CATALOG.md, required when the target is a newer version of the same stack. An uplift's phase order is decided by its version deltas, above all by whether the existing tests can even run on the target runtime; phasing without the catalog is planning blind. If it is missing, produce it first (/code-modernization:modernize-uplift $system <source> $target_stack through its delta-catalog step, or the version-delta-analyst agent) and wait for its result: never end your turn while an agent is still running, and never write the brief before the catalog exists. Do not guess at deltas.

Staleness. If an input is newer than an existing MODERNIZATION_BRIEF.md, regenerating is justified. If the brief is newer than every input and the user re-ran this anyway, ask what changed. Note the input timestamps in the brief's header.

The Brief

Write analysis/$system/MODERNIZATION_BRIEF.md with these sections.

1. Objective. One paragraph: from what, to what, why now.

2. Target Architecture. A Mermaid C4 Container diagram of the end state naming every service, data store and integration, then a table mapping each legacy component to its target component(s).

3. Phased Sequence. 3–6 phases, ordered by strangler fig for a cross-stack rewrite (lowest risk and fewest dependencies first) or build-graph leaf-first for an uplift (libraries before the apps that use them). For an uplift, three overrides decide whether the plan works; the uplift command re-applies them at execution, and the two must never disagree:

1. The test harness is a prerequisite, not a leaf. If the catalog shows the test framework or runner does not support the target (NUnit 2 or MSTest v1 on modern .NET, JUnit 4 without the vintage engine, nose on Python 3), migrating it is Phase 1 by itself.
2. A dependency delta every consumer shares forces a coordinated cut (an ORM major version, javax to jakarta): it gets its own cross-cutting phase, not an incremental leaf-first one.
3. A shared node with consumers outside the scope (from the preflight boundary check) needs an explicit decision in the phase that touches it: keep it buildable for old and new consumers (multi-targeting, publishing both), widen the scope to include the consumers, or schedule the break. Never silently migrate it in place.