# Legacy repository adoption prompt

Adopt **A2C** (Architecture-to-Commit) into an **existing** git repository that was not created with A2C from day one.

## Contract

Read and follow as governing artifacts when present (do not invent parallel conventions):

- `.a2c/migration.yaml` — machine-readable migration progress (entry path, tier, completed batches)
- `planning/migration/` — human-readable inventory, anchoring plan, and merge plans you produce
- `AGENTS.md`, `rules/` (especially `02-adr-conventions.md`, `10-adr-significance-scan.md`), Accepted ADRs in `docs/adr/` (after bootstrap)
- `docs/workflow/adoption.md`, bootstrap **ADR-0000** (after scaffold batch)
- [ADR-0018](../../docs/adr/0018-legacy-repository-adoption-workflow.md) — brownfield adoption decision

When method assets are mounted at `tools/ai-rules/`, read rules and templates from there instead of copied root paths.

## Objective

1. **Inventory** the legacy repository without destructive edits (batch 00).
2. **Scaffold** A2C additively — bootstrap skips existing files; never silent overwrite.
3. **Anchor** governing decisions already embodied in legacy code and docs as **Accepted retrospective ADRs** (batch 02).
4. **Merge** remaining governance docs, tooling, and optional canonical intake in bounded batches.
5. Record progress: after each batch, tell the operator to run
   `a2c migrate --complete-batch <batch-id> --path .`
6. Stop after each batch; one logical concern per commit.

## Migration-only `inputs/` (context, not canonical)

The **`inputs/`** folder is a **migration scratch space** for material that explains legacy intent but must **not** be committed to the governed repository.

| Rule | Detail |
|------|--------|
| Purpose | Operator-supplied context: old design notes, wiki exports, interview notes, diagrams, partial ADR drafts, README from a predecessor repo |
| Read-only for AI | Inventory and anchoring batches **read** `inputs/`; write results to `docs/adr/`, `docs/architecture/`, `planning/migration/` |
| Never commit | Do not `git add` paths under `inputs/`; add `inputs/` to `.gitignore` in batch 06 (or earlier if operator requests) |
| vs inputs-intake | [inputs-intake.md](inputs-intake.md) **canonicalizes** drafts into the repo; migration `inputs/` is **evidence only** unless batch 05 explicitly migrates remaining items |
| Operator action | Before batch 02, ask the operator to drop any legacy context into `inputs/` if not already present |

## Anchoring ADRs (batch 02)

**Anchoring ADRs** document architecturally significant decisions **already made** in the legacy codebase — retrospective governance, not new proposals.

They give future AI and human work a precise contract for *why the system looks the way it does*.

### Evidence sources (use all that apply)

1. **Legacy source code** — module boundaries, dependency direction, public APIs, config patterns, data stores
2. **In-repo documentation** — `README.md`, `docs/`, package READMEs, OpenAPI/specs
3. **`inputs/`** — operator migration context (see above)
4. **Git history** — commit messages and tags as **supporting signals only**; never sole evidence

### Anchoring ADR rules

| Rule | Detail |
|------|--------|
| Numbering | Start at **0001** after bootstrap **ADR-0000** (A2C adoption); renumber colliding legacy ADRs per plan |
| Status | **Accepted** — Context must state this is **retrospective documentation** of a pre-A2C decision |
| Honesty | Do **not** invent rationale unsupported by code or supplied context; list gaps in `planning/migration/anchoring-plan.md` for operator follow-up |
| One per commit | `adr(<category>): …` + `docs/adr/INDEX.md` update in the same commit |
| Template | `templates/adr/adr-template.md`; web sources per `prompts/phases/adr-create-update.md` |
| Significance | Apply `rules/10-adr-significance-scan.md` — prefer fewer, precise ADRs over noise |

### batch-migrate-02 deliverables

Execute **`planning/migration/anchoring-plan.md`** (from batch 00) sequentially:

- One **anchoring ADR** per commit until the plan is complete or operator pauses
- Optional **`docs/architecture/overview.md`** when the codebase warrants a single architecture summary (separate commit)

## Adoption tiers

Choose or confirm with the operator (record in `planning/migration/inventory.md`):

| Tier | Includes |
|------|----------|
| **docs-only** | ADR contract (including anchoring), `docs/web-source-mapping.md`, architecture docs |
| **workflow-lite** | + rules/prompts mount or copy, pre-commit/gitlint, `planning/` dirs |
| **full** | + stack profile, release scaffolding, inputs canonicalization, hygiene pass |

Default when unclear: **workflow-lite** for software repos; **docs-only** for pure documentation repos.

**Anchoring ADRs apply to all tiers** when the repo contains meaningful legacy code or undocumented decisions.

## Entry paths

| Path | When | Batch 00 focus |
|------|------|----------------|
| **inventory-first** | Legacy repo before A2C; messy or unknown layout | Full repo inventory — **no commits** |
| **bootstrap-first** | `a2c bootstrap` already ran; reconcile skipped paths | Inventory bootstrap gaps, anchoring candidates, conflicts — **no commits** |

Read `entry_path` from `.a2c/migration.yaml`.

## Merge policies (mandatory)

Bootstrap uses skip-if-exists. When a canonical A2C file already exists in the legacy repo:

| File | Policy |
|------|--------|
| `CHANGELOG.md` | Prepend Keep a Changelog header section if missing; **preserve** existing release history |
| `.pre-commit-config.yaml` | **Merge** A2C baseline hooks (a2c-pre-commit-hooks, gitlint on commit-msg, hygiene) with existing repos — do not drop project hooks |
| `.gitlint` | Use A2C policy if missing; if present, merge title/body rules only when operator approves |
| `docs/adr/` | **ADR-0000** reserved for A2C adoption; renumber colliding legacy ADRs; **anchoring ADRs** are new Accepted records from evidence |
| `docs/asr/` | Optional; if legacy has architecture-significant requirements, record them as ASRs (`NNNN-short-title.md`) or note candidates in inventory — see ADR-0019 |
| `README.md` | Merge A2C adoption pointer; do not wipe project content |
| `AGENTS.md` | Merge A2C version block; preserve project-specific sections |

Document every skip/merge decision in `planning/migration/plan.md`.

## Execution batches

Execute **one batch at a time**. After each batch: commit(s), verification, then
`a2c migrate --complete-batch <id> --path .`

| Batch | Scope |
|-------|--------|
| **batch-migrate-00** | Inventory → `inventory.md`, `plan.md`, **`anchoring-plan.md`** — **no commits** |
| **batch-migrate-01** | Scaffold: `a2c bootstrap` (or `init` + selective files) per plan — additive only |
| **batch-migrate-02** | **Anchoring ADRs** from code + docs + `inputs/` per `anchoring-plan.md` — one ADR per commit; note ASR candidates when requirements are explicit |
| **batch-migrate-03** | Governance merge: renumber/merge legacy ADRs, optional ASR files under `docs/asr/`, architecture docs, README, web-source mapping |
| **batch-migrate-04** | Tooling merge: pre-commit, gitlint, CI notes; run `a2c setup-dev` when hooks change |
| **batch-migrate-05** | Optional canonical intake — `@prompts/bootstrap/inputs-intake.md` when `inputs/` still has material to publish |
| **batch-migrate-06** | Hygiene: ensure `inputs/` in `.gitignore`, `git rm -r --cached inputs/` if tracked; deliberate `pre-commit run --all-files` only if operator approves; write **`phase-06-report.md`** |

After each batch: write the phase report, then `a2c migrate --complete-batch <id>`.

### batch-migrate-00 deliverables

Write **`planning/migration/inventory.md`** covering:

- Repository purpose, languages, build/test entrypoints
- Git remotes and default branch
- Existing `docs/`, `docs/adr/`, `docs/asr/` (if any), CI config, pre-commit, changelog
- Implicit architecture-significant requirements in code/docs that may become ASRs
- **`inputs/`** presence and contents (if any)
- Conflicts with A2C canonical layout
- Recommended **tier** and ordered batches 01–06 (skip inapplicable batches)

Write **`planning/migration/plan.md`** with:

- Per-file merge strategy (skip / merge / create)
- ADR numbering plan (0000 adoption, legacy renumbering, anchoring range)
- Bootstrap command line (`copy` vs `--with-ai-rules submodule|clone`, optional `--profile`)
- Risks and operator decisions needed before batch 01

Write **`planning/migration/anchoring-plan.md`** with:

- **Candidate anchoring ADRs** — proposed `NNNN-short-title`, significance, evidence pointers (file paths, modules, `inputs/` docs)
- **Priority order** for batch 02 (most foundational decisions first)
- **Gaps** — decisions that cannot be anchored without operator input; prompt operator to add `inputs/` context
- Explicit note when a repo is too small for anchoring (skip batch 02 with operator approval)

Write **`planning/migration/anchoring-readiness.md`** with:

- **Verdict:** `Strong` | `Partial` | `Weak` (first line must be parseable: `**Verdict:** Partial` or `Verdict: Partial`)
- **Coverage matrix** — architectural area → evidence → candidate ADR → status (ready / code-only / blocked)
- **Counts** — ready, code-only, blocked
- **Gaps** — what is missing; concrete `inputs/` suggestions
- **Ways forward** — options A / B / C for the operator
- **Last assessed** — ISO date + trigger (batch 00, reassess, new inputs)
- **Operator notes** — overrides and scope decisions (free text)

The CLI reads the verdict to warn on every `a2c migrate` invocation. **Never block** — inform and let the operator confirm.

### batch-migrate-00r (reassess, iterative)

When the operator runs `a2c migrate --reassess` after adding `inputs/` or changing the repo:

- Re-read code, docs, and `inputs/`
- **Update only** `anchoring-readiness.md` and add a short delta note to `phase-00-report.md`
- **No commits** to `docs/adr/` in this mini-batch
- Operator runs `a2c migrate` again to review the updated verdict

Repeat reassess → migrate as many times as needed.

### Phase completion reports

At the **end of every batch** (including 00, before `--complete-batch`), write **`planning/migration/phase-NN-report.md`** where `NN` matches the batch number (`00` … `06`):

| Section | Content |
|---------|---------|
| **Done** | Factual summary of work completed |
| **Learned** | Analysis and surprises |
| **Quality** | Self-assessment of this phase (anchoring readiness for batch 00) |
| **Risks** | What may go wrong if the next phase proceeds |
| **Recommendation** | Proposed way forward |
| **Operator decision** | What the human chose (record from chat when known) |

These files give a visible trail of migration progress. Jump between phases by opening the matching report.

### Human confirmation (`a2c migrate`)

Tools **never block** adoption. The CLI is deliberately cautious:

- Every `a2c migrate` (except `--status`) summarizes state, readiness warnings, and asks **“Are you sure?”** on a TTY
- `--complete-batch` always confirms before recording progress
- `--reassess` and `--reset` confirm before acting
- `--reset` requires typing `reset`; non-interactive reset needs `--reset-confirm reset`
- Non-interactive runs: **warnings only** on stderr — no prompts

If readiness is **Partial** or **Weak**, the CLI warns again when the next batch is anchoring (02) or when completing a batch that leads there. The operator may always proceed.

## Verification (each batch after commits)

- `a2c doctor --path .`
- `a2c validate --path .` (when A2C markers exist)
- `a2c web-sources check --path .` (when docs changed)
- `git status` — **`inputs/` must not appear** as staged after batch 06

## Out of scope

- Application feature implementation unrelated to adoption
- Rewriting Accepted legacy ADRs in place (supersede with new ADRs instead)
- Committing `inputs/` migration context to the governed repository
- Bulk web-source conversion of Accepted ADRs (soft adoption — ADR-0011)
- Superbuild workspaces — use `eai-supmig`, not this prompt

## Current batch

> Start with `batch-migrate-00` unless `.a2c/migration.yaml` lists completed batches — then continue with the next incomplete batch.

## Stop condition

After **batch-migrate-06**:

1. Confirm `.a2c/migration.yaml` phase is `complete`
2. List anchoring ADRs created and canonical files updated
3. Confirm `inputs/` is gitignored and not tracked
4. Suggest follow-up epics or commit-plan items
5. **Stop** — do not start product implementation unless asked