migrate

Brownfield Migration

Adopt govctl incrementally in an existing codebase per [[ADR-0032]], recovering governance from real evidence without inventing history or changing behavior. This differs from the govctl migrate command, which upgrades outdated artifact formats in an already governed project.

Discovery

If gov/config.toml is missing, use init when the request authorizes scaffolding; otherwise ask first. If it exists, find what earlier runs already migrated with govctl status, govctl search <topic>, and the rfc, adr, and work list commands. Use govctl <resource> --help for current syntax.

Read the smallest useful evidence: docs and changelogs, manifests, schemas, API contracts, deployment config, code comments that expose durable constraints, VCS history that shows why a choice was made, and issue trackers only for active work. Extend an existing artifact that already owns a subject instead of duplicating it.

Hard Stops

• Discovery is read-only. Create artifacts or annotate source only after the user selects the scope.
• Ask the user before any lifecycle or destructive artifact operation (accept, reject, finalize, advance, bump, deprecate, supersede, delete) unless the request already authorizes it. Source annotation also needs approval; one approval may cover a stated batch.
• Edit governed files only through govctl commands, using root govctl clause for Clauses.
• Never present inferred rationale, alternatives, requirements, implementation or test status, or active work as fact.
• Do not make an RFC normative or advance it just because related code exists.
• Do not create Work Items that track the migration itself.
• Change product code only through approved, behavior-neutral annotations.
• Stop when evidence conflicts, a backfill would misrepresent history, or a transition lacks approval or evidence.

Choosing Candidates

Prefer decisions that are hard to reverse, cross-cutting, or repeatedly questioned; skip tool-enforced style, incidental dependencies, and behavior inferred only from code.

For each candidate record the evidence location, what it supports, what is inferred, whether rationale and alternatives are recoverable, and the proposed type and priority. Say plainly when evidence is missing: a historical ADR may omit unrecoverable alternatives but never invents one, and RFC Clauses still pass the rfc-writer contract test. Present this as a compact report and let the user select, defer, or reject each group before any change.

Backfill Loop

Work in small batches so partial migration stays useful:

1. Recheck governed state and the selected evidence.
2. Draft with adr-writer, rfc-writer, or wi-writer.
3. Review with adr-reviewer or rfc-reviewer.
4. Show uncertainties and proposed lifecycle outcomes to the user.
5. Perform only approved transitions.
6. Run govctl check and render affected projections.
7. Optionally record the batch with commit.

• ADRs: reconstruct context and alternatives where evidence allows and separate observed consequences from predictions. Accept an adopted choice as historical only after user confirmation; route an unresolved one to discuss.
• RFCs: keep traceability to the source. Each phase needs approval and evidence: existing implementation for impl, complete implementation for test, and complete implementation and tests for stable. Otherwise stop at the last defensible phase.
• Work Items: include scope, governing references, categorized testable criteria, and risk-matched guards.
• Source references: follow the repository's comment conventions, use resolvable [[...]] links, and never claim more conformance than the evidence supports.

Resuming And Failures

On resume, rediscover existing artifacts and references, match candidates by subject and evidence rather than title, skip completed work, keep user changes instead of overwriting them, and report the prior partial state.

When a check, render, or review fails, keep the batch unpublished, fix the content, and rerun the failing check. Never advance lifecycle state to make validation pass; escalate when no authoritative recovery path exists.

Done When

• each selected candidate is created, deferred, or rejected explicitly;
• artifacts separate recovered fact from inference, and every lifecycle state has evidence and approval;
• annotations resolve and no duplicates or product changes were introduced;
• govctl check passes and projections are current; and
• the report lists artifacts, states, annotated paths, uncertain history, remaining scope, and validation results.

Normal workflows (discuss, spec, gov, quick) can start after the first coherent baseline; exhaustive backfill is not required.