Add arch plugin (architecture + modernization skills) (#2253)

* Add arch plugin (architecture + modernization skills)

Add the `arch` plugin with two skills:
- `arch:document` — produce a single, cited architecture document for a
  locally-cloned repo, reading files on disk only.
- `arch:modernize` — generate a phased modernization plan, auto-running the
  document workflow first when no architecture doc exists.

Skill sources live in top-level skills/ and are referenced declaratively
from plugins/arch/.github/plugin/plugin.json, per the repo's plugin model.
Regenerated docs/README.plugins.md, docs/README.skills.md and marketplace.json.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Merge arch skills into single doc-and-modernize skill

Collapse the document and modernize skills into one standalone skill
(doc-and-modernize) with Documentation and Modernization modes, keeping
the plugin named arch. Modernization mode now runs the Documentation
workflow inline instead of invoking a separate arch:document skill,
fixing standalone-install cross-skill references. Reframe Documentation
mode as local-first (remote/API lookups are a flagged last resort)
rather than local-only. Regenerate docs and marketplace.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review: list skill by bare ID in arch README

Use 'doc-and-modernize' (repo convention) instead of the namespaced
'arch:doc-and-modernize', noting it surfaces as arch:doc-and-modernize
when installed via the plugin.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review: use non-HTML placeholder in instructions template

Change plain-text <PROJECT NAME> to [PROJECT NAME] in the header and
first paragraph so Markdown renderers don't parse it as an HTML tag and
drop it. The code-span `<N>` on the phase line is unaffected.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review + fix codespell CI failure

- Fix codespell: pre-empts -> preempts in the instructions template
- Consistent terminology: replace 'research step/workflow' with
  'Documentation mode' in SKILL.md, README, and plugin.json description
- Fix run-on: add 'that' before 'Modernization mode must surface'
- Regenerate docs/marketplace for the updated plugin description

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review feedback

- Instruct redacting credentials/tokens from git remote URLs before recording
- CI enforcement: ask user or mark [UNVERIFIED]; remote lookup is flagged last resort

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: samqbush <samqbush@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/plugin/marketplace.json

@@ -87,6 +87,12 @@
       "description": "Play five retro Phaser mini-games in a Copilot canvas while agents work.",
       "version": "1.0.0"
     },
+    {
+      "name": "arch",
+      "source": "plugins/arch",
+      "description": "Architecture and modernization toolkit: produce a cited architecture document for a locally-cloned repo, and generate a phased modernization plan that auto-runs Documentation mode when needed.",
+      "version": "1.0.0"
+    },
     {
       "name": "arize-ax",
       "source": "plugins/arize-ax",

docs/README.plugins.md

@@ -29,6 +29,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t
 | ---- | ----------- | ----- | ---- |
 | [acreadiness-cockpit](../plugins/acreadiness-cockpit/README.md) | Drive Microsoft AgentRC from Copilot chat: assess AI readiness, generate Copilot instructions (flat or nested with applyTo globs for monorepos), and manage policies. Produces a self-contained static HTML dashboard at reports/index.html. | 4 items | agentrc, ai-readiness, copilot-instructions, readiness-report, monorepo, policy, dashboard |
 | [ai-team-orchestration](../plugins/ai-team-orchestration/README.md) | Bootstrap and run a multi-agent AI development team with named roles (Producer, Dev Team, QA). Sprint planning, brainstorm prompts with distinct agent voices, cross-chat context survival, and parallel team workflows. Based on a proven template that shipped a 30-game app in 5 days with zero human-written code. | 4 items | ai-team, multi-agent, sprint-planning, brainstorm, project-management, orchestration, developer-workflow |
+| [arch](../plugins/arch/README.md) | Architecture and modernization toolkit: produce a cited architecture document for a locally-cloned repo, and generate a phased modernization plan that auto-runs Documentation mode when needed. | 1 items | architecture, modernization, documentation, migration, onboarding |
 | [arize-ax](../plugins/arize-ax/README.md) | Arize AX platform skills for LLM observability, evaluation, and optimization. Includes trace export, instrumentation, datasets, experiments, evaluators, AI provider integrations, annotations, prompt optimization, and deep linking to the Arize UI. | 9 items | arize, llm, observability, tracing, evaluation, instrumentation, datasets, experiments, prompt-optimization |
 | [automate-this](../plugins/automate-this/README.md) | Record your screen doing a manual process, drop the video on your Desktop, and let Copilot CLI analyze it frame-by-frame to build working automation scripts. Supports narrated recordings with audio transcription. | 1 items | automation, screen-recording, workflow, video-analysis, process-automation, scripting, productivity, copilot-cli |
 | [awesome-copilot](../plugins/awesome-copilot/README.md) | Meta prompts that help you discover and generate curated GitHub Copilot agents, instructions, prompts, and skills. | 4 items | github-copilot, discovery, meta, prompt-engineering, agents |

docs/README.skills.md

@@ -143,6 +143,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [dependabot](../skills/dependabot/SKILL.md)<br />`gh skills install github/awesome-copilot dependabot` | Comprehensive guide for configuring and managing GitHub Dependabot. Use this skill when users ask about creating or optimizing dependabot.yml files, managing Dependabot pull requests, configuring dependency update strategies, setting up grouped updates, monorepo patterns, multi-ecosystem groups, security update configuration, auto-triage rules, or any GitHub Advanced Security (GHAS) supply chain security topic related to Dependabot. For pre-commit dependency vulnerability scanning in AI coding agents via the GitHub MCP Server, this skill references the Advanced Security plugin (`advanced-security@copilot-plugins`). Use this skill when an agent needs to scan dependencies for known vulnerabilities before committing. | `references/dependabot-yml-reference.md`<br />`references/example-configs.md`<br />`references/pr-commands.md` |
 | [devops-rollout-plan](../skills/devops-rollout-plan/SKILL.md)<br />`gh skills install github/awesome-copilot devops-rollout-plan` | Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes | None |
 | [diagnose](../skills/diagnose/SKILL.md)<br />`gh skills install github/awesome-copilot diagnose` | Perform a systematic diagnostic scan of an AI workflow across 5 quality dimensions — prompt quality, context efficiency, tool health, architecture fitness, and safety — producing a scored report with prioritized remediation actions. | None |
+| [doc-and-modernize](../skills/doc-and-modernize/SKILL.md)<br />`gh skills install github/awesome-copilot doc-and-modernize` | Two related workflows for a locally-cloned codebase, in one skill. Documentation mode produces a single, comprehensive, verifiable architecture document primarily by reading files on disk (local-first) — use it whenever the user wants to understand, map, document, research, or onboard onto a codebase ("research this repo", "write up the architecture", "do an architecture deep dive", "document how this codebase works", "map the system design", "create an onboarding doc"). Modernization mode generates a phased plan to modernize, migrate, upgrade, or rewrite a legacy system ("modernize this", "plan the migration", "how would we rewrite this", "how do we get off this legacy stack"); if no architecture document exists yet it first runs Documentation mode, then continues straight through to the plan. It assumes the legacy stack may be dead, runs a time-boxed feasibility spike, and picks the highest achievable rung on a safety ladder instead of demanding a fully-green legacy CI gate up front. | `references/copilot-instructions.template.md`<br />`references/migration-hazards.md` |
 | [documentation-writer](../skills/documentation-writer/SKILL.md)<br />`gh skills install github/awesome-copilot documentation-writer` | Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework. | None |
 | [dotnet-best-practices](../skills/dotnet-best-practices/SKILL.md)<br />`gh skills install github/awesome-copilot dotnet-best-practices` | Ensure .NET/C# code meets best practices for the solution/project. | None |
 | [dotnet-design-pattern-review](../skills/dotnet-design-pattern-review/SKILL.md)<br />`gh skills install github/awesome-copilot dotnet-design-pattern-review` | Review the C#/.NET code for design pattern implementation and suggest improvements. | None |

plugins/arch/.github/plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "arch",
+  "description": "Architecture and modernization toolkit: produce a cited architecture document for a locally-cloned repo, and generate a phased modernization plan that auto-runs Documentation mode when needed.",
+  "version": "1.0.0",
+  "keywords": [
+    "architecture",
+    "modernization",
+    "documentation",
+    "migration",
+    "onboarding"
+  ],
+  "author": {
+    "name": "Awesome Copilot Community"
+  },
+  "repository": "https://github.com/github/awesome-copilot",
+  "license": "MIT",
+  "skills": [
+    "./skills/doc-and-modernize/"
+  ]
+}

plugins/arch/README.md

@@ -0,0 +1,25 @@
+# Arch Plugin
+
+Architecture and modernization toolkit for locally-cloned repositories. It produces a single, cited architecture document from the code on disk, and generates a phased modernization plan that automatically runs Documentation mode first when no architecture document exists yet.
+
+## Installation
+
+```bash
+copilot plugin install arch@awesome-copilot
+```
+
+## What's Included
+
+### Skills
+
+- **`doc-and-modernize`** — Two complementary workflows for a locally-cloned repository, in one skill (installed via this plugin it surfaces as `arch:doc-and-modernize`):
+  - **Documentation mode** — Produce one comprehensive, verifiable architecture document for a repository you already have checked out locally. Works local-first (prefers the local checkout, treating remote/API lookups as a flagged last resort), cites every claim to a file + line, flags unverified facts, resolves contradictions, and deep-dives the most complex subsystems. Ideal for onboarding docs and system-design maps.
+  - **Modernization mode** — Generate a phased modernization plan for a legacy codebase. If a current architecture document exists it builds on it; otherwise it first runs the Documentation mode workflow to produce one, then continues to the plan. Produces per-feature migration docs, tech-stack recommendations with ADRs, and an adaptive, safety-laddered phased implementation plan.
+
+## Source
+
+This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot).
+
+## License
+
+MIT

skills/doc-and-modernize/SKILL.md

@@ -0,0 +1,850 @@
+---
+name: doc-and-modernize
+description: >-
+  Two related workflows for a locally-cloned codebase, in one skill.
+  Documentation mode produces a single, comprehensive, verifiable architecture
+  document primarily by reading files on disk (local-first) — use it whenever the user wants to
+  understand, map, document, research, or onboard onto a codebase ("research
+  this repo", "write up the architecture", "do an architecture deep dive",
+  "document how this codebase works", "map the system design", "create an
+  onboarding doc"). Modernization mode generates a
+  phased plan to modernize, migrate, upgrade, or rewrite a legacy system
+  ("modernize this", "plan the migration", "how would we rewrite this", "how do
+  we get off this legacy stack"); if no architecture document exists yet it
+  first runs Documentation mode, then continues straight through to the plan. It
+  assumes the legacy stack may be dead, runs a time-boxed feasibility spike, and
+  picks the highest achievable rung on a safety ladder instead of demanding a
+  fully-green legacy CI gate up front.
+---
+
+# Documentation & Modernization
+
+Two complementary workflows for a repository the user already has checked out
+locally, bundled as one skill:
+
+- **Documentation mode** — produce one definitive, cited architecture document
+  from the code on disk. Ideal for onboarding, system-design maps, or as the
+  evidence base for a modernization effort.
+- **Modernization mode** — turn that architecture into a phased, safety-laddered
+  plan to upgrade, migrate, or rewrite a legacy system.
+
+## Mode selection
+
+- If the user wants to **understand, document, map, research, or onboard onto** a
+  codebase, run **Documentation mode**.
+- If the user wants to **modernize, migrate, upgrade, or rewrite** a system, run
+  **Modernization mode**. Modernization mode is self-sufficient: if no
+  architecture document exists yet, it runs the **Documentation mode** workflow
+  first (in the same pass), then continues straight through to the plan.
+
+When in doubt, produce the architecture document first — it is the audited
+evidence base both modes rely on.
+
+## Documentation mode
+
+Generate one definitive, cited architecture document for a repository the user
+already has checked out locally. The goal is a writeup someone could hand to a
+new engineer as their onboarding reference — broad enough to cover the whole
+system, deep enough on the hard parts to be useful, and trustworthy because
+every claim traces back to a file on disk.
+
+### Why local-first
+
+Reading from the local checkout (not the GitHub API or the web) is the deliberate
+**default**. It is faster, free, avoids rate limits, and — most importantly — it
+describes *the exact code in front of you* rather than whatever `main` happens
+to look like remotely. The one tradeoff is that remote-only facts (star counts,
+full CI run history, sibling repos) aren't visible. That's fine: state those as
+out-of-scope or mark them `[UNVERIFIED]` rather than guessing.
+
+Local-first is not local-*never*-remote: a web/API lookup is a deliberate
+**last-resort fallback**, reserved for a fact that genuinely cannot be determined
+from disk and that materially matters to the document. When you do reach for it,
+flag the result clearly (e.g. `[UNVERIFIED]` / sourced-remotely) so the reader
+knows it didn't come from the checkout, and never let it become the easy path
+that displaces reading the code on disk.
+
+### Workflow
+
+1. **Establish identity first.** Run `git remote -v`, `git branch --show-current`,
+   and `git log -1` so the document is anchored to a specific remote, branch, and
+   commit. A reader must be able to tell which snapshot this describes. Remote
+   URLs can contain embedded credentials (e.g. `https://<token>@github.com/...`)
+   — **redact any credentials/tokens** from the URL before recording it in the
+   document.
+2. **Detect, don't assume.** Read the real manifests (`go.mod`, `package.json`,
+   `Cargo.toml`, `pyproject.toml`, `pom.xml`, etc.), the `Makefile`/task runner,
+   CI config, and any repo-specific agent or contributor docs (`AGENTS.md`,
+   `CONTRIBUTING`, `README`, `docs/`). These are the source of truth for the tech
+   stack and commands — prefer them over your prior knowledge of the framework.
+3. **Map breadth, then drill into depth.** First build the whole-repo map (the
+   three lenses below), then pick the 2-3 hardest subsystems and go deep on them.
+4. **Verify as you go.** Open the files you cite. If you reference a line number,
+   you should have actually read that line. Unsupported claims are worse than
+   omissions here — the whole value of this document is that it can be trusted.
+
+### Output structure
+
+Produce a **single Markdown file** with the sections below, in this order. Adapt
+the headings to the actual project (a CLI tool has no "frontend" lens — fold that
+slot into whatever matters for that repo), but keep the three-lens shape and the
+verification discipline.
+
+#### Part 1 — Whole-repo technical deep-dive
+- What the repository is (one paragraph, cited to README).
+- Tech-stack detection table: layer | technology | evidence (file+line).
+- Entry points (backend, frontend, CLI — whatever applies).
+- **Commands & Verification Inventory** — a table of the canonical project
+  commands (`command | purpose | evidence`), verified against the task runner /
+  manifests / CI config, not guessed. Cover build, run/serve, test (and how to
+  run a single test), lint, format, and — where they exist — typecheck,
+  end-to-end/smoke, contract, and any other gate commands, plus the CI
+  workflow(s) that run them and on what trigger. **Also record whether CI is
+  *enforced*** — i.e. whether any workflow is a **required status check /
+  branch-protection rule** that actually blocks merges, versus one that merely
+  runs — since that distinction is a manual, human-configured setting that
+  Modernization mode must surface, not assume. Enforcement usually cannot be
+  determined from the local checkout alone: ask the user, or mark it
+  `[UNVERIFIED]` unless confirmed from an authoritative source (any remote
+  lookup is a flagged last resort, per the local-first rule above). This
+  inventory is the source of
+  truth that downstream planning (Modernization mode) cites so its exit
+  criteria are runnable, not aspirational. Detect these per-ecosystem (npm/yarn/
+  pnpm, `make`, `just`, `cargo`, `go`, `poetry`/`tox`/`nox`, `gradle`/`maven`,
+  etc.) — do not assume a stack. Mark any command you could not verify
+  `[UNVERIFIED]`.
+- Directory layout for each major area, with a one-line purpose per directory.
+- **Deployment & Runtime Surface** — a table of every place the language/runtime
+  and backing-service versions are pinned *for running* the system (not just
+  building it): container base images (`Dockerfile`/`Containerfile`,
+  `docker-compose*` build contexts), CI runner images / `setup-*` versions,
+  `engines`/`.nvmrc`/`.tool-versions`/`runtime.txt`, serverless/lambda runtimes,
+  and stateful data-store image tags (DB/cache/broker/search). Cite each with
+  file+line. This surface is what a later platform/runtime bump must move in
+  lockstep — flag any drift between build-runtime and run-runtime here so it's
+  visible before a modernization plan is written.
+- **EOL / dead-dependency scan** — call out frameworks, runtimes, base images,
+  and libraries that are end-of-life, unmaintained, or removed in a likely target
+  major (e.g. a framework whose next major renames namespaces or drops a
+  component family). Mark each `[INFERRED]`/`[UNVERIFIED]` as appropriate. This is
+  the raw material Modernization mode's feasibility spike and hazard red-team
+  build on.
+- Data/storage layers, APIs, plugins/extensions, background jobs, CI/CD, testing.
+
+#### Part 2 — Context & ecosystem
+- Local checkout identity table (remote, branch, HEAD commit, version, license).
+- Repo-specific agent/contributor docs present, and what rules they encode.
+- Developer gotchas (test watch-mode defaults, slow builds, codegen-must-commit,
+  pre-commit hooks) — each cited.
+- How this project relates to its broader ecosystem or sibling services, *as
+  visible from disk* (build tags, optional linked repos, separately-deployable
+  components). Don't import remote ecosystem trivia.
+
+#### Part 3 — Architectural blueprint
+- Tech-stack summary (can reference the Part 1 table).
+- C4-style diagrams as Mermaid: Level 1 system context, Level 2 containers,
+  Level 3 a representative request/component lifecycle.
+- Layering and dependency rules (what may depend on what, and what enforces it).
+- Cross-cutting concerns table: auth, config, logging, metrics/tracing, secrets,
+  error handling, feature flags — each with its location and evidence.
+- Inferred Architectural Decision Records (reconstructed from code + docs).
+- Governance & enforcement mechanisms (CI gates, codegen verification,
+  CODEOWNERS, review gates, compatibility rules).
+- "How to add a feature" guide plus common pitfalls.
+
+#### Subsystem deep-dives
+Identify the 2-3 most complex or architecturally significant subsystems — the
+parts a new engineer would most struggle with, such as an evaluation/scheduling
+engine, a plugin loader pipeline, a state machine, or a rendering/migration
+framework. For each, add a dedicated subsection covering its internal structure,
+lifecycle or state machine, key types, and data flow, with local file+line
+citations and a small Mermaid diagram where it clarifies the flow. This is what
+separates a useful onboarding doc from a directory listing — spend real effort
+here.
+
+#### Confidence assessment
+A table of the major claim areas rated **High / Inferred / Unverified**, so a
+reader knows exactly which parts to trust outright and which to double-check.
+
+#### Footnotes — local file citations
+A list of the key local files the document relies on, each with a one-line note
+on what it establishes.
+
+### Conventions that make the document trustworthy
+
+These are the habits that distinguish this skill's output from a generic
+overview. They matter because the document's entire value is that a reader can
+rely on it without re-deriving everything.
+
+- **Cite every non-obvious claim** to a local path, with a line number where it
+  pins something specific (`pkg/server/server.go#L39-L41`). Relative paths from
+  the repo root keep links clickable.
+- **Mark uncertainty honestly.** Use `[INFERRED]` for something you reasoned to
+  but didn't see stated, and `[UNVERIFIED]` for something you're repeating but
+  didn't confirm (e.g. a build-timing claim from a doc you didn't re-measure).
+  Honest gaps are more useful than false confidence.
+- **Resolve contradictions, don't restate them.** If two sources disagree (say a
+  version literal in code vs. the manifest), go read the code, decide the real
+  answer, and label it `[Resolved contradiction]` with the explanation. Leaving
+  a reader to puzzle over a conflict is a failure mode.
+- **Note compatibility and deploy-cadence rules** the repo enforces — separate
+  FE/BE PRs, bidirectional storage compatibility, additive-only protobuf changes
+  — because these are the rules a newcomer most easily breaks.
+- **Prefer precise counts over vague ones.** "73 service packages", "89 workflow
+  files" (from a directory listing) reads as verified; "many services" reads as a
+  guess.
+
+### Scope control
+
+Keep the document grounded in the checkout. It's easy to drift outward into the
+project's wider ecosystem (related products, README marketing, satellite repos)
+— resist that unless it's visible on disk, and clearly label anything that comes
+from outside the local tree. The reader asked for *this codebase*, documented
+faithfully.
+
+## Modernization mode
+
+Generate a complete, actionable modernization plan for a legacy codebase. This
+skill focuses on the forward-looking work — what to modernize, why, in what
+order, and how — but it is **self-sufficient**: it ensures an architecture
+document exists first, producing one via Documentation mode when needed.
+
+**Assume dead-by-default.** People reach for modernization precisely because the
+old stack is hard or impossible to upgrade — EOL runtimes, uncompilable native
+modules, retired package mirrors, abandoned frameworks. So this skill does **not**
+assume you can resurrect the legacy toolchain and stand up a fully-green CI gate
+before touching anything. That "freeze-then-lift" approach is the *lucky* case,
+not the default. Instead the skill runs a **time-boxed feasibility spike**, then
+picks a migration strategy and a **safety strategy** matched to how alive the
+system actually is. On a truly dead app, building a green legacy gate *is itself
+a modernization project* — a circular trap this skill is designed to avoid.
+
+Three ideas drive the whole plan and are introduced below: the **Testability
+Milestone** (when — per component — the system can actually build, run, and pass
+a test again), the **safety ladder** (the highest rung of regression safety
+you can actually reach, with a downgrade treated as a blessed outcome, not a
+failure), and the **CI Milestone** (which phase first stands up CI — and the
+reminder that *enforcing* CI as a required check is a manual human step, not
+something the agent can do).
+
+### Prerequisites
+
+This skill needs an understanding of the system's architecture before it can
+plan. Resolve that as follows:
+
+1. If an architecture document already exists — produced by **Documentation mode**
+   above, or a README / ARCHITECTURE.md the user points to, or enough
+   prior conversation context — use it and skip to the workflow below.
+2. **If none exists, run the Documentation mode workflow above first** to
+   generate a cited architecture document, then continue **straight through**
+   to Phase 1 below in the same pass. Do not stop to ask the user to run it
+   separately, and do not pause for review between the two documents.
+
+The result is two artifacts: the architecture document (the audited evidence
+base) and this modernization plan (the forward-looking action set).
+
+**Before planning, confirm a Commands & Verification Inventory exists.** Exit
+criteria are only worth anything if they are *runnable*, so the plan must be able
+to cite the project's canonical build / run / test / lint / typecheck / e2e /
+contract commands and CI gate(s). Documentation mode produces this
+inventory in Part 1; if you're working from a README or prior context that lacks
+it, detect and record those commands yourself (per-ecosystem — npm/yarn/pnpm,
+`make`, `just`, `cargo`, `go`, `poetry`/`tox`/`nox`, `gradle`/`mvn`, etc.) before
+writing exit criteria. Never invent a command you haven't verified against the
+task runner / manifests / CI config.
+
+### Workflow
+
+#### Phase 1: Assess Current State (from existing docs)
+
+Read the architecture document and extract:
+
+1. **Tech stack inventory** — languages, frameworks, runtimes, dependencies with
+   versions where visible
+2. **Feature/domain map** — the major functional areas of the system
+3. **Pain points already identified** — tech debt, concerns, deprecated deps,
+   architectural violations noted in the existing docs
+4. **Deployment and infrastructure** — how it runs today
+
+Do NOT re-read every source file. Trust the architecture doc. Only open specific
+files if a modernization question requires verifying a detail (e.g., "is this
+dependency actually used or just declared?").
+
+#### Phase 2: Feasibility Spike, Strategy Fork & Safety Ladder
+
+This is the pivot of the whole plan. **Do it before recommending a target
+architecture or writing any phases.** Its job is to answer, quickly and honestly:
+*how alive is this system, what migration shape fits, and how much regression
+safety can we actually achieve?*
+
+##### 2a. Run a time-boxed feasibility spike
+
+Put a **hard time box** on it (e.g. one day). The spike's question is **NOT "can
+we make CI green?"** — it is **"can we get this to run even *once* to capture its
+behavior?"** Probe, per component / deployable unit:
+
+- Does it **install** its dependencies today (ideally **from a committed
+  lockfile without hand-patching**)?
+- Do **native/build steps** succeed on a **currently supported** toolchain?
+- Does it **boot / start**?
+- Can the **test runner execute at all**, and does **≥1 meaningful test pass**?
+
+Record what you actually observed — including partial success (common in
+monorepos: one service installs and tests green while another can't compile). Do
+**not** sink two sprints resurrecting a corpse to discover it's unresurrectable.
+When the time box expires, decide with the evidence you have.
+
+##### 2b. Locate the Testability Milestone (per component)
+
+**"Testable" is not a precondition you can satisfy on a dead app — for a dead app
+it is an *output* of modernization, not an input.** So every plan must name, up
+front, its **Testability Milestone**: the specific phase at which the system
+(or a given component) first satisfies **all four** conditions at once:
+
+1. Runs on a **supported** (non-EOL) runtime.
+2. Dependencies install **from a lockfile without hand-patching**.
+3. Native / build steps **succeed on the current toolchain**.
+4. The **test runner executes and ≥1 meaningful test passes in CI**.
+
+Assess this **per component** — as the reference Nylas run showed, a near-modern
+cloud service can cross the line immediately while a legacy Electron client
+doesn't cross it until several phases later. **This milestone is the single most
+important marker in the plan.** State where it lands for each component, out loud.
+
+##### 2c. Label every phase pre- or post-testability
+
+The Testability Milestone splits the effort into two regimes with **different
+safety rules**:
+
+- **Pre-testability ("dark") regime:** the component can't be trusted to run.
+  Safety comes from **non-test** sources (see the safety ladder below).
+  **Requiring a CI test gate here is a category error** — you're demanding green
+  tests from something that isn't alive yet.
+- **Post-testability ("lit") regime:** it builds and runs on a live, supported
+  stack. *Now* real CI, characterization, and e2e are achievable and worth the
+  investment. The classic green-gate belongs **here**.
+
+**Rule: never require an automated test gate on a component before that component
+crosses its own testability line.**
+
+##### 2d. Choose the migration strategy — the A/B fork
+
+The spike decides which of two shapes fits (this is a per-component call in a
+monorepo):
+
+- **(A) Freeze-then-lift.** Net the old app *as-is*, then upgrade under the net.
+  Requires the old app to be **resurrectable at acceptable cost** — i.e. it
+  *almost* runs. This is the traditional "characterization tests before you
+  change anything" path. **Opt-in, not the default.**
+- **(B) Beachhead-then-expand (walking skeleton).** Don't net the corpse. Drive
+  the **thinnest possible end-to-end slice onto the modern stack** until it
+  builds, boots, and tests; then strangle the rest in, writing tests **on the new
+  stack** as you go. **This is the default for dead apps.** In strategy B, the
+  first phase is *"reach the Testability Milestone with the smallest slice,"* not
+  *"freeze the whole legacy toolchain."*
+
+If a component **can't be built or run at all**, characterization tests on the
+*old* stack are impossible by definition — invert the approach: **stop trying to
+net the corpse and build the net on the *target* stack incrementally**, using the
+old code/output as the reference oracle.
+
+##### 2e. Pick the highest achievable rung on the safety ladder
+
+Regression safety is a ladder, not a binary. Choose the **highest rung you can
+actually reach** per component; **a downgrade to a lower rung is a blessed,
+first-class outcome — not a failure — provided the residual risk is named.**
+
+- **L4 — Full automated gate:** green lint + unit + characterization + e2e in CI.
+- **L3 — Partial gate:** some suites green + lockfile + CI on the achievable
+  subset; the rest **quarantined** with a named list.
+- **L2 — Characterization / golden-master only:** can't run in CI, but capture
+  I/O snapshots / behavioral diffs (manual is acceptable).
+- **L1 — Reversibility-based:** no runnable tests; safety comes from small
+  reversible steps, strangler / parallel-run, a smoke checklist, and review.
+- **L0 — No net possible:** treat as a spec-driven rewrite (old code = the spec)
+  or archive.
+
+**Safety is not only tests.** There are at least five sources, and on dead apps
+2–4 often outweigh 1:
+
+1. **Tests** (characterization / unit / e2e) — strongest, often unachievable on
+   dead apps.
+2. **Reversibility** — tiny commits, branch-per-change, trivial rollback.
+3. **Isolation** — feature flags, strangler-fig, run old + new in parallel and
+   **diff outputs**.
+4. **The running old system as an oracle** — record/replay real I/O to
+   characterize behavior without a test harness.
+5. **Human review + domain knowledge.**
+
+**Anchor safety at the behavioral *seams*, not the unit.** The durable,
+stack-agnostic contracts of any app are its externally observable behaviors:
+HTTP endpoints, DB schema/queries, file/wire formats, CLI output, protocols. Pin
+*those* as golden-master / approval snapshots — **they survive the rewrite; unit
+tests on dead legacy code get deleted the moment you replace the module.** Get an
+**oracle**, ranked by what's available:
+
+- **Best — it runs *somewhere*** (prod, a VM, an old container, even read-only),
+  **and you're allowed to use it**: record real I/O and replay it against the new
+  code. One successful capture beats a permanent green legacy CI. *(Do not assume
+  this rung is always available — a faithful third-party reimplementation or a
+  resurrected legacy binary may be off-limits by policy, licensing, or an
+  explicit decision to build "with only what we have." If so, skip to the
+  self-frozen rung.)*
+- **Fallback — it doesn't run at all:** the old **source is the spec**;
+  supplement with prod logs, DB dumps, docs, tickets, and accept that
+  characterization tests get written **against the new implementation** to lock
+  it once verified correct.
+- **Self-frozen golden master — no external reference exists or is permitted:**
+  when nothing trustworthy runs *and* you may not borrow an external oracle, the
+  **modernized component records its *own* golden master the moment it first runs**
+  (at its Testability Milestone), and every later phase diffs against that frozen
+  snapshot. This is a real, usable rung — but **name its residual risk out loud**:
+  it guarantees the *self-consistency of later refactors*, **not** the correctness
+  of the first boot (the snapshot is only as correct as the run that produced it).
+  Pair it with human review / spec cross-checks to bless that first run.
+
+##### 2f. Feed an economic/oracle triage into the choice
+
+Weigh **regression cost** when picking a rung: Is the app **in production**? Does
+it have **real users**? Is the **old system still runnable** as a reference? An
+abandoned app with zero users has near-zero regression cost — an expensive gate
+there is **over-engineering**. A production system with users justifies a higher
+rung and a real oracle.
+
+##### 2g. Locate the CI Milestone (name the phase that stands up CI)
+
+Just as the Testability Milestone names *when a component can first run and be
+tested*, the **CI Milestone** names *when continuous integration is first stood
+up* — and it must be **stated out loud in the roadmap, not buried in a phase
+body.** A common failure of modernization plans is leaving the reader unable to
+tell which phase introduces CI; name it explicitly.
+
+**Rule: CI is stood up in the *first lit phase* — at or immediately after the
+component crosses its Testability Milestone — never before.** CI cannot be green
+on a component that cannot yet build/run, so wiring a CI *gate* during the dark
+regime is the same category error as demanding a test gate there. (Trivial
+scaffolding — a lint-only or build-only workflow — may appear earlier, but the
+authoritative test gate lands at the CI Milestone.)
+
+**CI is two distinct steps, and the second is human-only** — call both out:
+1. **Author the CI workflow file** (e.g. `.github/workflows/*.yml`, `.gitlab-ci.yml`,
+   Azure Pipelines) that runs the gate. **An agent can do this.**
+2. **Make that workflow an *enforced* gate** — a **required status check /
+   branch-protection rule / merge-request approval rule**. This is a manual
+   platform-UI / admin step (GitHub → Settings → Branches; GitLab protected
+   branches + MR settings; etc.) that **an agent cannot perform.** Until a human
+   configures it, CI *runs* on PRs but does **not** *block* merges.
+
+Because step 2 is outside the agent's reach, **every plan that stands up CI must
+emit it as an explicit user action item** (in the phase's exit criteria and in
+§9 Open questions / decisions needed from stakeholders), so the reader knows the
+gate is not self-enforcing until they turn it on.
+
+**Output of Phase 2:** for each component — the spike result, the chosen strategy
+(A or B), the located Testability Milestone, the pre/post label, and the target
+safety-ladder rung with any residual risk named — **plus the plan-wide CI
+Milestone** (which phase stands up CI) and the reminder that enforcing it is a
+manual human step. Everything downstream depends on these.
+
+#### Phase 2.5: Red-team every phase against the hazard catalog (mandatory)
+
+The strategic scaffolding above (testability, safety ladder, CI milestone) is
+necessary but **not sufficient**. Modernization plans also fail on *tactical,
+ecosystem-predictable* hazards — an incomplete quarantine set, a forgotten
+namespace codemod, a runtime bump that leaves the base images behind, a stateful
+data-store major treated as an image bump, an edge rewrite that drops the
+anonymous route class. These are so recurring that they have their own catalog:
+**`references/migration-hazards.md`** (H1–H8).
+
+**Rule: before any phase is implemented, red-team its plan against every hazard
+in `references/migration-hazards.md`.** For each hazard, ask "does this phase
+trigger it?", run the hazard's detection probe against the real repo, and fold
+its plan action into the phase's tasks/exit criteria **before** writing code. A
+hazard caught in planning is a task; caught in review it's rework; caught in prod
+it's an incident. Record hazards you checked and **cleared**, not just the ones
+that fired — a silent skip is indistinguishable from a miss.
+
+This is the institutionalized form of an independent-critic pass. Do it yourself
+by walking the catalog, and — where an independent second opinion is available
+(e.g. a rubber-duck / critique agent) — use it: on the reference PiggyMetrics run
+such a pass caught a **blocking plan gap in every single phase**, and each gap
+was an instance of an H1–H8 class. Bake the outcome into each phase's
+"Decisions made" and exit criteria so the executing agent inherits the cleared
+checklist rather than re-discovering the hazard.
+
+#### Phase 3: Recommend Target Architecture
+
+**Decision framework — always evaluate in this order:**
+
+For each component/dependency, work through these levels from least-disruptive to
+most-disruptive. Stop at the first level that solves the problem:
+
+1. **Upgrade in place** — Can you bump the major version and fix breakages?
+   (e.g., Node 14→22, Python 2→3, React 16→19, Rails 5→7). This is the default
+   answer. Only reject it if the upgrade path is officially unsupported, the
+   breaking changes are so extensive they exceed rewrite cost, or the framework
+   itself is abandoned/EOL.
+
+2. **Swap the dependency** — If the specific library is dead but the pattern is
+   fine, can you swap to a maintained alternative with the same interface shape?
+   (e.g., Moment.js → date-fns, Request → got/fetch, CoffeeScript → TypeScript
+   with decaffeinate). Prefer drop-in or mechanical migration tools when they
+   exist.
+
+3. **Wrap/adapt (Strangler Fig)** — If the component's interface is sound but
+   internals are unmaintainable, can you put a clean interface in front and
+   incrementally replace internals behind it? This works when coupling is
+   manageable and the system can run with old and new coexisting.
+
+4. **Rewrite** — Only when: the framework is abandoned with no upgrade path, the
+   architecture fundamentally cannot support required new capabilities (e.g.,
+   synchronous-only design that must become real-time), or honest estimation shows
+   upgrade cost exceeds rewrite cost. Require explicit justification for every
+   rewrite recommendation — "it's old" is not sufficient.
+
+5. **Remove** — Dead code, features with zero usage, deprecated capabilities
+   superseded by other systems. Verify usage claims before recommending removal.
+
+**Bias toward conservatism.** The cheapest migration is the one you don't do.
+Every level of disruption adds risk, timeline, and cost. A working system on an
+older framework is better than a half-finished rewrite on a new one.
+
+**Mechanical-migration riders (apply whenever a recommendation is an upgrade,
+swap, or removal).** These are the parts of a target-architecture decision that
+first-draft plans routinely drop; each maps to a hazard class in
+`references/migration-hazards.md`:
+
+- **Transitive-quarantine completeness (H1).** When removing/cutting over a whole
+  dependency family, grep the dead artifact across **all** manifests and list the
+  *full* set of dependents that must move or be quarantined — not the subset you
+  first thought of. State the post-cutover build target explicitly.
+- **Framework-major codemods (H2).** A **major** bump carries mechanical breaking
+  changes independent of your logic — namespace renames, removed deprecated APIs,
+  a changed **test engine**, changed config keys. Enumerate each as its own task
+  and prefer the ecosystem's automated **recipe/codemod tool** (OpenRewrite,
+  jscodeshift/react-codemod, `2to3`/`pyupgrade`, etc.) over hand-editing on large
+  trees. Don't forget the test-framework migration — it is the most-forgotten one.
+- **Runtime↔deployment lockstep (H3).** If a recommendation bumps the
+  language/runtime **major**, every place the runtime is pinned for *running* the
+  app — base images, `docker-compose` build contexts, CI runner images,
+  `engines`/`.nvmrc`/`.tool-versions`, serverless runtimes — must move in the
+  **same phase**. Build-runtime and run-runtime must never drift across a phase
+  boundary, or the app builds green and then fails to run.
+
+Produce a **Target Architecture** section that includes:
+
+- **Recommended tech stack** with rationale for each choice (framework, language,
+  runtime, database, infrastructure)
+- **Architectural pattern** recommendation (monolith → modular monolith →
+  services, event-driven, serverless, etc.) with justification
+- **What stays vs. what goes** — explicitly categorize each major component using
+  the decision framework above:
+  - ✅ Keep as-is (still modern/adequate)
+  - ⬆️ Upgrade in place (bump version, fix breakages)
+  - 🔀 Swap dependency (replace dead library with maintained equivalent)
+  - 🔄 Wrap/adapt (add an interface layer, incrementally replace internals)
+  - 🔁 Rewrite (fundamentally incompatible — justification required)
+  - 🗑️ Remove (dead code, deprecated features, superseded)
+
+For each recommendation, write an inline ADR:
+
+```markdown
+#### ADR: [Decision Title]
+- **Context:** [Why this decision is needed]
+- **Decision:** [What we chose and which decision framework level it falls under]
+- **Alternatives considered:** [What else was evaluated and why it lost]
+- **Consequences:** [Tradeoffs accepted]
+```
+
+#### Phase 4: Per-Feature Migration Analysis
+
+For each major feature/domain identified in the architecture doc, produce a
+section covering:
+
+1. **Current implementation** — one paragraph summary with file references
+2. **Migration strategy** — the A/B choice from Phase 2 for this component
+   (Freeze-then-lift vs. Beachhead/walking-skeleton), plus the tactic: Strangler
+   Fig, Big Bang rewrite, Lift & Shift, Incremental Refactor, or Leave In Place
+3. **Testability status** — where this component's **Testability Milestone**
+   lands, and its **safety-ladder rung** (L0–L4) with residual risk named
+4. **Dependencies and coupling** — what else breaks or must move with it
+5. **Effort estimate** — T-shirt size (XS/S/M/L/XL) with justification
+6. **Risk assessment** — what can go wrong, data migration concerns, user impact
+7. **Acceptance criteria** — how you know the migration succeeded (expressed
+   against the chosen oracle/seam contracts, not against a not-yet-alive test
+   suite)
+
+#### Phase 5: Phased Implementation Plan
+
+Produce an ordered, phased plan. Each phase should be independently deployable
+(no half-migrated states that can't run in production).
+
+**Phase gating is regime-aware (applies to every phase).** State this rule at the
+top of the phased plan and honor it in every phase's exit criteria. A phase is
+**not complete** until its Verification & Exit Criteria pass. Those criteria must
+be (a) **objectively verifiable**; (b) **actually executed and recorded** before
+the next phase starts; and (c) **gated** — do not advance to phase N+1 until
+phase N's criteria are demonstrably met. **But which criteria are valid depends
+on the component's regime (Phase 2c):**
+
+- **Post-testability ("lit") phases:** exit criteria are runnable commands / green
+  CI — **green CI on the phase's branch/PR is the authoritative signal.**
+- **Pre-testability ("dark") phases:** the component isn't alive yet, so a green
+  CI test gate is a **category error**. Exit criteria come from the achievable
+  safety-ladder rung instead — captured seam/oracle snapshots, reversibility
+  scaffolding proven present, a passed smoke checklist, recorded review. Do **not**
+  block a dark-regime phase on a test suite that can't run yet.
+
+Report to the user any phase whose pass/fail is unknown rather than assuming it
+passed.
+
+**The first phase establishes maximum *achievable* safety — not a fixed "green
+legacy gate."** Do not hard-code "resurrect everything and make CI green." Shape
+the first phase from the Phase 2 outputs, per component:
+
+- **Strategy A (Freeze-then-lift), component is resurrectable:** the first phase
+  *is* the classic Safety Net & Baseline — purely additive, no behavior change:
+  - **Characterization / golden / contract tests** at the **seams** that pin
+    current observable behavior (protocol traces, API snapshots, output goldens).
+  - **CI + lint + formatter** wired up and green (an authoritative gate for later
+    lit-regime phases).
+  - **Pinned dependencies / committed lockfile** and a recorded known-good
+    baseline (versions, toolchain, how it builds and runs today).
+  - **"Net proven to fail."** Deliberately mutate the code (e.g., change one
+    protocol code or return value), confirm the new tests go **red**, then
+    revert. A safety net that never fails is proof of nothing — prove it has
+    teeth.
+- **Strategy B (Beachhead/walking-skeleton), component is dead:** the first phase
+  is **"reach the Testability Milestone with the smallest slice"** — drive the
+  thinnest end-to-end path onto the modern stack until it builds, boots, and runs
+  ≥1 real test green, capturing seam/oracle contracts from the old system to
+  validate against. **Do not try to net the corpse.** Its exit criterion is the
+  achievable safety-ladder rung with residual risk named — a **blessed downgrade
+  is not a failure.**
+
+Only after the first phase's criteria are met (at whatever rung) do the
+subsequent infrastructure and feature phases begin.
+
+Structure each phase as:
+
+```markdown
+### Phase N: [Name] (T-shirt size: M)
+
+**Goal:** [One sentence]
+**Regime:** [pre-testability ("dark") | post-testability ("lit")] — per component
+**Safety rung:** [L0–L4, with residual risk named if below L4]
+**Prerequisites:** [Which phases must complete first]
+**Duration estimate:** [Relative, not calendar — e.g., "2-4 sprints"]
+
+#### Tasks
+| ID | Task | Component | Blocked by |
+|----|------|-----------|------------|
+| N.1 | ... | ... | — |
+| N.2 | ... | ... | N.1 |
+
+#### Risks & Mitigations
+- **Risk:** ... → **Mitigation:** ...
+
+#### Decisions made
+- [Every sub-decision this phase depends on, resolved and documented here so the
+  phase can be implemented without further user input. State "dropped" vs
+  "deferred" explicitly for anything cut.]
+
+#### Verification & Exit Criteria (Definition of Done)
+- [ ] [Regime-appropriate criterion. For LIT phases: a runnable command / green
+      CI check, citing the actual command from the Commands & Verification
+      Inventory. For DARK phases: the achievable safety-ladder rung's evidence —
+      captured seam/oracle snapshots, reversibility proven, smoke checklist
+      passed — NOT a green test suite the component can't yet run.]
+- [ ] [Include a parity/characterization check against the chosen oracle whenever
+      the change is meant to preserve behavior.]
+- [ ] [If purely additive, assert it: "no behavior/dependency/logic changed."]
+- [ ] [If exiting below L4, state the residual risk and which later phase closes
+      it (e.g., "client test gate deferred to the client-migration phase").]
+```
+
+**Ordering principles:**
+- **Locate the Testability Milestone first**, per component — schedule the
+  smallest slice that reaches it early rather than deferring "testable" to the end
+  while demanding a gate at the start.
+- **Never require a component's automated test gate before it crosses its own
+  testability line.**
+- **Name the CI Milestone in the roadmap.** State explicitly which phase stands
+  up CI (the first *lit* phase, at/after the Testability Milestone) so the reader
+  never has to guess when CI arrives — and flag that *enforcing* it (required
+  status check / branch protection) is a manual human step, not an agent task.
+- **First-phase safety before behavior change** — establish the highest
+  achievable rung (not necessarily a full green gate) before modifying behavior.
+- Infrastructure and cross-cutting concerns next (auth, config, logging, CI/CD)
+- Highest-risk or highest-value features next (prove the pattern early)
+- Low-risk, low-coupling features last (easy wins to parallelize)
+- Data migrations get their own phase with rollback plans
+
+#### Phase 6: Execution Governance
+
+Modernization plans fail in execution, not on paper. Bake in the governance that
+keeps each phase honest and reversible (generic across any ecosystem):
+
+- **Branch per phase.** Never commit phase work to the default branch. Open one
+  PR per phase; let CI on the PR be the authoritative green signal before merge
+  **for lit-regime phases**. For dark-regime phases, the PR still carries the
+  rung's evidence (captured contracts, smoke results, reversibility scaffolding).
+- **Merge to trunk before the next phase; never stack (H7).** Each phase branch
+  is cut **from trunk**, and its PR is **merged to trunk before the next phase
+  starts**. Never base a phase branch or its PR on a *sibling* phase branch — that
+  is how PRs get merged into each other, the trunk silently stalls several phases
+  behind, and later phases are forced into the exact bind where the no-stacking
+  rule has to be broken. Before starting a phase, verify the previous phase is
+  merged to trunk and `git log origin/<trunk>..HEAD` is empty at branch creation.
+  **If controlled stacking is genuinely unavoidable, it is allowed only with a
+  required reconciliation PR** that lands the stack onto trunk **and an explicit
+  residual-risk note** — never as a silent default.
+- **Confirm the trunk name; retire legacy defaults.** Pin the repo's real trunk
+  (e.g. `main`) and, if a second default-ish branch exists (`master`), mark it
+  "history only — do not target" so phase work never lands on the wrong branch.
+- **The gate matches the regime.** Lit phases advance on green CI; dark phases
+  advance on the achievable safety-ladder rung with residual risk named — not on
+  a "looks done" judgement, and not on a test suite that can't run yet.
+- **Stand up CI at the CI Milestone, and hand off enforcement to a human.**
+  Name the phase that introduces CI (the first lit phase). Distinguish the two
+  steps: authoring the workflow file is agent-doable; making it an **enforced
+  required status check / branch-protection (or MR-approval) rule is a manual
+  platform-UI step the agent cannot perform.** Until a human configures it, CI
+  *runs* but does not *block* merges — so record "enable branch protection /
+  required checks" as an explicit user action item (in the CI phase's exit
+  criteria and in §9 stakeholder decisions), never as a completed agent task.
+- **Interface-preserving & independently deployable.** Each phase leaves the
+  system runnable, so rollback = redeploy the previous version. Prefer
+  interface-preserving rewrites (wrap internals behind a stable interface) and
+  prove equivalence with the seam/oracle contracts (golden/characterization
+  tests where they exist).
+- **Living plan.** Update `MODERNIZATION_PLAN.md` status markers as each phase's
+  exit criteria are met — ✅ complete / ⏭️ descoped / 🗑️ dropped — record the
+  decisions made during implementation, and **update the safety-ladder rung /
+  residual-risk register** as components cross their testability lines.
+- **Keep the executable docs alive too (H8).** The living-plan discipline is not
+  only the plan file. Any phase that changes **topology** — module/reactor
+  membership, removed services, renamed branches, changed commands, new/removed
+  endpoints — must update `.github/copilot-instructions.md`, the `README`, and any
+  module/topology list **in the same PR**. Treat those doc updates as part of the
+  phase's Definition of Done, not a follow-up — a stale "quarantined module" list
+  or a hard-coded old-branch link actively misleads the next agent/human.
+- **Red-team each phase before implementing it (Phase 2.5).** Walk the phase plan
+  against `references/migration-hazards.md` (H1–H8) and fold the fixes into tasks
+  and exit criteria before writing code. Record the cleared checklist in the
+  phase's "Decisions made".
+- **Emit editable instructions.** Produce a `.github/copilot-instructions.md`
+  (create the `.github/` directory if needed) from the template at
+  `references/copilot-instructions.template.md` — a commands table plus the
+  regime-aware phase-gate and branch/PR rules — so the executing agent/human has
+  the canonical commands and gates in the location GitHub Copilot auto-loads. The
+  user edits it to their own gates. If a `.github/copilot-instructions.md` already
+  exists, do not overwrite it — merge the commands/gating/branch sections in, or
+  write the generated file alongside as
+  `.github/copilot-instructions.modernization.md` and tell the user to merge.
+
+#### Phase 7: Migration Safety Net
+
+Document the operational guardrails needed:
+
+- **Feature flags** — what gets flagged and how old/new coexist
+- **Data migration strategy** — schema changes, backfills, dual-write periods.
+  For a **stateful data-store major upgrade** with persisted volumes (H5), an
+  engine image/tag bump is **not** a migration: pick and document one path —
+  a sequential/feature-compatibility-version upgrade with steps + rollback, **or**
+  an explicit **destructive reset** (drop volumes, re-seed) when the data is
+  ephemeral/demo — stated as a deliberate decision, with the prior-major image
+  retained for rollback. (e.g. Mongo 3→7 over an existing `/data/db` volume needs
+  `down -v` + re-seed for a demo, or a staged FCV upgrade for real data.)
+- **Rollback plan** — per phase, how to revert if something fails
+- **Transitional-insecure-state register (H6)** — every deliberately-weak state
+  introduced to keep the system runnable mid-migration (permit-all shims, CSRF
+  disabled, an open endpoint, a placeholder secret) listed with: why it's needed,
+  the phase that **closes** it, the residual risk, and a by-design-until-phase-N
+  note for reviewers. Scope each weakening as tightly as possible (e.g. a
+  permit-all chain should still explicitly disable form-login/HTTP-Basic).
+  Pre-declaring these converts recurring scanner/reviewer churn into a tracked
+  decision.
+- **Oracle & seam contracts** — which running instance / recorded I/O / golden
+  snapshots (or a **self-frozen golden master**, when no external reference is
+  available or permitted) serve as the behavioral reference, and how new work is
+  diffed against them
+- **Testing strategy** — what new test coverage is needed (built on the *target*
+  stack as components cross their testability line), and what stays quarantined
+- **Observability** — metrics/alerts that prove the new system matches the old
+
+### Output Structure
+
+Produce a primary Markdown file named `MODERNIZATION_PLAN.md` with:
+
+1. Executive summary (one paragraph: what, why, rough scope)
+2. Current state assessment (from architecture doc)
+3. **Feasibility spike result & strategy** — per component: spike findings, the
+   A/B migration strategy, the located **Testability Milestone**, the target
+   **safety-ladder rung**, and a **residual-risk register** for anything below L4;
+   plus the plan-wide **CI Milestone** (which phase stands up CI) with a note that
+   *enforcing* it is a manual human step
+4. Target architecture with ADRs
+5. Per-feature migration analysis (with testability status + safety rung)
+6. Phased implementation plan — first phase establishes the highest *achievable*
+   safety rung (not a fixed green legacy gate); every phase is labeled
+   pre/post-testability and carries regime-appropriate, gated exit criteria; the
+   **CI Milestone phase is named explicitly** and lists "enable branch protection
+   / required status checks" as a manual user action
+7. Execution governance (branch-per-phase, regime-aware gate, living-plan status)
+8. Migration safety net (oracle & seam contracts, flags, rollback, observability)
+9. Open questions / decisions needed from stakeholders — including any manual
+   platform-configuration handoffs the agent cannot perform (e.g. enabling
+   required status checks / branch protection to make CI an enforced gate)
+
+Also emit a companion **`.github/copilot-instructions.md`** (the path GitHub
+Copilot auto-loads; create `.github/` if absent) from
+`references/copilot-instructions.template.md`, populated with the project's
+canonical commands and phase-gating / branch rules, for whoever executes the
+plan to edit and adopt. Never overwrite an existing
+`.github/copilot-instructions.md` — merge into it or write a sibling
+`.github/copilot-instructions.modernization.md` and flag it for the user.
+
+### Conventions
+
+- **Cite the architecture doc** when referencing current state rather than
+  restating everything. Keep this document forward-looking.
+- **Be opinionated.** Make concrete recommendations, not "you could do A or B."
+  State what you'd pick and why. The user can override.
+- **Scope realistically.** A modernization plan that tries to change everything at
+  once is fiction. Identify what's phase 1 vs. "future consideration."
+- **Resolve every in-phase decision during planning.** A phase plan must carry
+  all the sub-decisions its implementation depends on, already decided and
+  documented (the "Decisions made" block), so the phase can be executed without
+  going back to the user. State **"dropped" vs "deferred"** explicitly for
+  anything cut — they are not the same. Reserve `[DECISION NEEDED]` for genuine
+  *stakeholder/business* choices (budget, team size, product direction, timeline
+  pressure) that block a phase; drive those to resolution with the user during
+  planning rather than leaving them open in an implementable phase.
+- **Don't gold-plate.** If a component works fine on the old stack and has no
+  maintenance burden, "leave it alone" is a valid recommendation.
+- **Assume dead-by-default; make safety adaptive.** Don't demand a fully-green
+  legacy CI gate up front. Run the feasibility spike, pick the highest achievable
+  safety-ladder rung, and treat a **downgrade as a blessed outcome** with residual
+  risk named — never a failure.
+- **Locate testability in time.** Every plan must name its **Testability
+  Milestone** per component and never require a component's automated test gate
+  before that component crosses its own testability line.
+- **Name the CI Milestone, hand enforcement to a human.** State which phase
+  stands up CI (the first lit phase), and make explicit that turning CI into an
+  *enforced* required check / branch-protection rule is a manual platform step
+  the agent cannot do — surface it as a user action item, not a done task.
+- **Net the seams, not the corpse.** Anchor safety at externally observable
+  contracts (protocols, schemas, wire/file formats, endpoints) with a ranked
+  oracle (running instance → recorded I/O → code-as-spec → **self-frozen golden
+  master** when no external reference exists or is permitted). Don't sink sprints
+  resurrecting a dead toolchain just to run a test that gets deleted at rewrite.
+- **Keep it generic.** Express commands and gates in terms of *the project's*
+  package manager / test runner / CI — never assume a specific stack.
+- **Red-team every phase before implementing (H1–H8).** Walk each phase plan
+  against `references/migration-hazards.md` and fold the fixes into tasks/exit
+  criteria first — a hazard caught in planning is a task; in review, rework; in
+  prod, an incident. These tactical hazards (incomplete quarantine, framework
+  codemods, runtime/base-image lockstep, route-class enumeration, data-store
+  upgrade paths, transitional-insecure-state noise, stacked-PR/trunk drift,
+  living-doc drift) are what strategic scaffolding alone keeps missing.

skills/doc-and-modernize/references/copilot-instructions.template.md

@@ -0,0 +1,137 @@
+# Copilot Instructions — [PROJECT NAME]
+
+> **Generated by the doc-and-modernize skill (Modernization mode) as an editable starting point.**
+> Save this at **`.github/copilot-instructions.md`** (the path GitHub Copilot
+> auto-loads). It encodes the *canonical commands* and the *phase-gating rules*
+> an agent (or human) must follow while executing `MODERNIZATION_PLAN.md`. Tune
+> the gates, commands, and branch rules to your project — the placeholders below
+> are intentionally generic. Delete this note once customized.
+
+[PROJECT NAME] is being **modernized**. The safety strategy is **adaptive**: the
+legacy stack may be partly or wholly dead, so we do **not** assume a fully-green
+legacy CI gate exists up front. Each component is on the **highest achievable rung
+of the safety ladder** (L0–L4), has a named **Testability Milestone** (the phase
+where it first builds, runs, and passes ≥1 test on a supported toolchain), and is
+labeled **pre-testability ("dark")** or **post-testability ("lit")**. CI is stood
+up at a named **CI Milestone** (the first lit phase); enforcing it as a required
+check is a manual human step. See `MODERNIZATION_PLAN.md` for the phase roadmap,
+per-component testability/rung, the CI Milestone, and the residual-risk register;
+`ARCHITECTURE.md` for the audited current state. Work one phase at a time; do not
+advance until the current phase's exit criteria are demonstrably met.
+
+## Commands
+
+> Fill from the architecture doc's **Commands & Verification Inventory**. Use
+> your ecosystem's real runner (npm/yarn/pnpm, `make`, `just`, `cargo`, `go`,
+> `poetry`/`tox`/`nox`, `gradle`/`mvn`, …). Delete rows that don't apply.
+
+| Action | Command |
+|--------|---------|
+| Install / restore deps | `<install command>` |
+| Build | `<build command>` |
+| Run / serve locally | `<run command>` |
+| Unit tests (all) | `<test command>` |
+| Single test file | `<single-file test command>` |
+| Single test by name | `<single-test-by-name command>` |
+| Lint | `<lint command>` |
+| Format / check | `<format command>` / `<format-check command>` |
+| Typecheck (if applicable) | `<typecheck command>` |
+| End-to-end / smoke (if applicable) | `<e2e command>` |
+| Contract / characterization tests | `<contract test command>` |
+
+CI (`<path to CI workflow>`) runs `<ordered gate list, e.g. lint → typecheck →
+test → e2e>` on `<runtime/version>` for every push and PR. CI was stood up in
+**phase `<N>`** (the first *lit* phase). **Enforcement is a separate manual
+step:** until a human turns this workflow into a **required status check /
+branch-protection rule** (`<platform: e.g. GitHub → Settings → Branches; GitLab
+protected branches>`), CI *runs* on PRs but does **not** *block* merges.
+
+> **Keep this table current.** If a phase introduces a new long-term command,
+> update this table (and confirm it with the user during planning) — don't leave
+> the canonical command list stale.
+
+## Phase gating (regime-aware; applies to every phase)
+
+A phase is **not complete** until its **Verification & Exit Criteria** in
+`MODERNIZATION_PLAN.md` pass. Those criteria must be:
+
+1. **Objectively verifiable** — runnable commands / captured evidence, not a
+   subjective judgement.
+2. **Actually executed and recorded** — run them and note the result in the plan
+   before starting the next phase.
+3. **Gated** — do **not** advance to phase N+1 until phase N's criteria are
+   demonstrably met.
+
+**Which criteria are valid depends on the component's regime:**
+
+- **Post-testability ("lit") phases:** exit on runnable commands / **green CI on
+  the phase's branch/PR — the authoritative signal.** Shared baseline: `<lint
+  command>` and `<test command>` must pass; if the change touched the client /
+  transport / protocol / any public interface, the relevant end-to-end and
+  contract/characterization tests must also stay green.
+- **Pre-testability ("dark") phases:** the component isn't alive yet, so a green
+  CI test gate is a **category error**. Exit on the phase's achievable
+  **safety-ladder rung** instead — captured seam/oracle snapshots, reversibility
+  scaffolding proven present, a passed smoke checklist, recorded review. **Do not
+  block a dark phase on a test suite that can't run yet.** A blessed **downgrade**
+  to a lower rung (with residual risk named) is a valid exit, not a failure.
+
+**Never require a component's automated test gate before it crosses its own
+Testability Milestone.** Report to the user any phase whose pass/fail is unknown
+rather than assuming it passed.
+
+## Decisions
+
+- When a phase is planned, **all sub-decisions must be resolved and documented**
+  in the plan so implementation needs no further user input.
+- State **"dropped" vs "deferred"** explicitly for anything cut — don't leave it
+  ambiguous.
+- Update `MODERNIZATION_PLAN.md` status markers (✅ complete / ⏭️ descoped /
+  🗑️ dropped) as each phase's exit criteria are met, and **update the
+  safety-ladder rung / residual-risk register** as components cross their
+  Testability Milestone.
+
+## Branching & PRs
+
+Each phase is developed on its **own branch** — never commit phase work directly
+to the default branch (`<default branch>`). Create a new branch at the start of a
+phase (e.g. `phase-N-<short-name>`). Once the phase's exit criteria are met and
+recorded, push the branch and open a PR to the default branch. For
+**post-testability ("lit")** phases, let CI on the PR be the authoritative green
+signal before merging. For **pre-testability ("dark")** phases, the PR instead
+carries the achievable safety-ladder rung's evidence (captured contracts, smoke
+results, reversibility scaffolding) with residual risk named.
+
+**Merge to trunk before the next phase; never stack.** Cut each phase branch
+**from the trunk (`<default branch>`)**, and **merge its PR to trunk before
+starting the next phase.** Never base a phase branch or its PR on a *sibling*
+`phase-N` branch — stacked phase PRs get merged into each other, the trunk
+silently stalls several phases behind, and later phases are forced into a bind.
+Before starting a phase, verify the previous phase is merged and
+`git log origin/<default branch>..HEAD` is empty at branch creation. **Controlled
+stacking is allowed only if genuinely unavoidable — and only with a reconciliation
+PR that lands the stack onto trunk plus an explicit residual-risk note.**
+
+> **Confirm the trunk name; retire legacy defaults.** Pin the real trunk
+> (`<default branch>`). If a second default-ish branch exists (e.g. a legacy
+> `master` alongside `main`), mark it "history only — do not target" so phase
+> work never lands on the wrong branch.
+
+**Keep the executable docs alive with the code.** Any phase that changes
+**topology** — module/reactor membership, removed services, renamed branches,
+changed commands, new/removed endpoints — must update **this file**, the
+`README`, and any module/topology list **in the same PR**. A stale module list or
+a hard-coded old-branch link actively misleads the next agent/human.
+
+**Register transitional-insecure states.** If a phase intentionally introduces a
+temporary weak state to stay runnable (permit-all shim, CSRF disabled, an open
+endpoint, a placeholder secret), record it with the phase that **closes** it and
+a by-design-until-phase-N note, and scope it as tightly as possible — this
+preempts recurring scanner/reviewer churn.
+
+> **CI enforcement is a manual, human-only step.** An agent can author and run
+> the CI workflow, but making it a **required status check / branch-protection
+> rule** so it actually *blocks* merges is a platform-UI/admin action
+> (`<GitHub → Settings → Branches; GitLab protected branches; etc.>`) the agent
+> cannot perform. Until you configure it, treat "green CI is authoritative" as a
+> convention you enforce by hand. Do this once, at/after the CI Milestone phase.

skills/doc-and-modernize/references/migration-hazards.md

@@ -0,0 +1,286 @@
+# Migration Hazard Catalog
+
+A generic, **stack-agnostic** catalog of migration hazards that are *predictable
+per ecosystem* but are routinely missed in a first-draft modernization plan.
+Every phase plan should be **red-teamed against this list before it is
+implemented** (see Modernization mode's pre-implementation red-team step).
+
+Each hazard is written as: **Trigger** (when it applies) → **Risk** (what breaks)
+→ **Detection probe** (a concrete check you can run now) → **Plan action** (what
+to add to the phase) → **Examples** (per-ecosystem, illustrative only).
+
+> These are *hazard classes*, not a fixed checklist for one stack. The examples
+> (Java/Spring/Mongo/Docker etc.) are illustrations drawn from real runs — map
+> each class onto whatever ecosystem you're actually migrating. If a hazard
+> doesn't apply, say so explicitly rather than silently skipping it.
+
+---
+
+## How to use this catalog
+
+Before implementing **any** phase:
+
+1. Walk every hazard below and ask "does this phase trigger it?"
+2. For each triggered hazard, run the **detection probe** against the real repo.
+3. Fold the **plan action** into the phase's tasks and exit criteria *before*
+   writing code — a hazard caught in planning is a task; caught in review it's
+   rework; caught in prod it's an incident.
+4. Record hazards you checked and cleared, not just the ones that fired — a
+   silent skip is indistinguishable from a miss.
+
+Empirically (the PiggyMetrics run, phases 0–6) an independent critic caught a
+**blocking plan gap in every single phase**, and each gap was an instance of one
+of the classes below. Running this catalog *is* that critic, institutionalized.
+
+---
+
+## H1 — Incomplete quarantine / removal set
+
+**Trigger:** You are removing, quarantining, or cutting over an entire dependency
+family (a dead framework, a removed runtime API, an EOL library set) and only
+some modules are being touched.
+
+**Risk:** A module you *didn't* list still transitively depends on the removed
+artifact, so the default build/test target fails after the cutover — often in a
+module the plan never mentioned.
+
+**Detection probe:** Grep the dead artifact/coordinate across **all** manifests,
+not just the ones you're editing (`pom.xml`/`build.gradle`, `package.json`,
+`*.csproj`, `requirements*.txt`/`pyproject.toml`, `go.mod`, etc.). Every hit is a
+module that must move or be quarantined in the same phase.
+
+**Plan action:** Enumerate the **full transitive set** of dead-artifact
+dependents up front and list every one in the phase's reactor/quarantine
+decision. State the post-cutover build target explicitly (which modules are in,
+which are quarantined).
+
+**Examples:**
+- *JVM:* Spring Cloud 2023 removes Netflix Hystrix/Turbine; `monitoring` and
+  `turbine-stream-service` still pulled `netflix-hystrix-dashboard` /
+  `netflix-turbine-stream` and broke `mvn verify` even though the plan only
+  quarantined `gateway` + `auth-service`.
+- *JS:* dropping `request` — grep for every `require('request')` / `from
+  'request'`, not just the one service you remembered.
+- *Python:* removing a C-extension lib — check every `import` site + extras.
+
+---
+
+## H2 — Framework-major mechanical codemods (namespace / API / test-engine)
+
+**Trigger:** A **major** version bump of a framework, language, or platform
+(not a patch/minor). Major bumps carry *mechanical* breaking changes independent
+of your own logic.
+
+**Risk:** The plan treats "bump the version" as one task and misses the
+whole-tree mechanical migrations the bump forces — namespace renames, removed
+deprecated APIs, changed test runner/engine, changed config keys — so the build
+won't even compile.
+
+**Detection probe:** Read the target version's **migration/upgrade guide** and
+identify the known breaking-change recipes. Grep the tree for the old namespace /
+API surface to size the change. Check whether an **ecosystem codemod/recipe tool**
+exists.
+
+**Plan action:** Enumerate each mechanical migration as its **own explicit task**,
+and prefer the ecosystem's automated recipe tool over hand-editing where it's
+reliable. Decide tool-vs-manual deliberately (small trees may be safer by hand;
+large trees need the tool). Include test-framework migration in the list — it is
+routinely forgotten.
+
+**Examples:**
+- *Spring Boot 2→3:* `javax.* → jakarta.*` namespace migration **and** JUnit 4→5
+  (add `junit-vintage-engine` to keep JUnit 4 tests running, migrate
+  `OutputCapture`-style Jupiter-only cases). Tool: **OpenRewrite**.
+- *JS:* CommonJS→ESM, or React class→hooks. Tools: **jscodeshift**, `react-codemod`.
+- *Python:* `2to3`/`pyupgrade`; `async` API renames.
+- *.NET:* `Newtonsoft`→`System.Text.Json`, `HttpClient` patterns.
+
+---
+
+## H3 — Runtime bump not in lockstep with deployment artifacts
+
+**Trigger:** You bump the **language/runtime major** (JDK, Node, Python, Ruby,
+Go) used to *build* the app.
+
+**Risk:** The build now emits artifacts for the new runtime, but the
+**deployment/runtime surface** still pins the old one — base images, CI runner
+version, buildpacks, `engines` fields, lambda runtimes — so the app builds green
+and then fails to *run* (bytecode/ABI/syntax mismatch), often only in a
+smoke/e2e step, or silently in prod.
+
+**Detection probe:** Inventory every place the runtime version is pinned:
+`Dockerfile`/`Containerfile` base images, `docker-compose*` build contexts, CI
+workflow `setup-*`/runner images, `.tool-versions`/`.nvmrc`/`runtime.txt`,
+`engines` in `package.json`, serverless runtime keys. Cross-check each against
+the new target.
+
+**Plan action:** Add an explicit task to move **every** deployment/runtime pin in
+the same phase as the build bump. Never let build-runtime and run-runtime drift
+across a phase boundary. Verify the smoke path actually builds/runs the new
+artifacts (and doesn't build quarantined modules).
+
+**Examples:**
+- *JVM:* source-built services emit JDK 21 bytecode but every `Dockerfile` still
+  `FROM java:8-jre` → containers won't start; dev-compose still *built* the
+  quarantined `auth-service`.
+- *Node:* CI bumped to Node 22 but Docker image still `node:14-alpine`.
+- *Python:* venv on 3.12 but the container base is `python:3.7`.
+
+---
+
+## H4 — Traffic-flow / route-class enumeration gap (edge & auth rewrites)
+
+**Trigger:** Rewriting an edge/gateway, an auth/identity layer, or any
+request-routing/security boundary.
+
+**Risk:** The plan pins the obvious authenticated happy path and silently drops
+one or more *other* traffic classes — anonymous flows (signup, password reset,
+public assets, health/metrics scrape), service-to-service calls, webhooks — so
+those break at cutover.
+
+**Detection probe:** Enumerate **every route class** the boundary must serve:
+(1) anonymous/public, (2) end-user authenticated, (3) service-to-service
+(machine tokens/scopes), (4) infra/observability (health, readiness, metrics
+scrape), (5) webhooks/callbacks. For each, confirm the new config has an explicit
+rule.
+
+**Plan action:** Make the route-class enumeration an explicit artifact of the
+phase (a table of route class → new rule → scope). Call out that
+scanners/security expect infra endpoints (e.g. metrics scrape) to remain
+reachable. Decide token/scope granularity for s2s calls (narrow scope, not a
+generic "server" grant).
+
+**Examples:**
+- *BFF/OAuth2:* SCG BFF + TokenRelay covered login but missed the **anonymous
+  registration POST + signup assets**, and `/uaa/users` was `permitAll` instead
+  of requiring a narrow `user.write` service scope.
+- *Metrics:* resource-server security must keep `/actuator/prometheus` open or
+  scraping silently breaks.
+
+---
+
+## H5 — Stateful data-store major upgrade treated as an image/version bump
+
+**Trigger:** Bumping the **major version** of a stateful backing service
+(database, cache, broker, search index) that has **persisted data/volumes**.
+
+**Risk:** Engine majors frequently can't start on prior-major on-disk data
+without a sequential/FCV upgrade path. A naive image bump either fails to start,
+appears flaky depending on local volume state, or corrupts data.
+
+**Detection probe:** Check whether the store has persisted volumes/data
+directories, and read the engine's supported upgrade path (sequential majors?
+feature-compatibility-version steps? dump/restore only?). Determine whether the
+data is production/durable or ephemeral/demo.
+
+**Plan action:** Choose and document **one** path: (a) sequential/FCV migration
+with steps + rollback, or (b) an **explicit destructive reset** (drop volumes,
+re-seed) when the data is ephemeral/demo — stated as a decision, not an accident.
+Put this in the migration safety net with a rollback plan.
+
+**Examples:**
+- *MongoDB 3→7:* direct image bump over an existing anonymous `/data/db` volume
+  is unsafe; for a demo, the blessed path was `docker compose down -v` +
+  re-seed via native `initdb.d`, with the old `mongo:3` image retained for
+  rollback.
+- *Postgres major:* needs `pg_upgrade` or dump/restore, not just a tag change.
+
+---
+
+## H6 — Transitional-insecure state trips scanners & reviewers repeatedly
+
+**Trigger:** A phase intentionally introduces a temporary, deliberately-weak
+state to keep the system runnable mid-migration — permit-all security shims,
+CSRF disabled, an open endpoint, a hard-coded secret placeholder, a disabled
+check.
+
+**Risk:** Every code scanner (CodeQL, Dependabot, SAST) and every automated
+reviewer flags it **each review**, generating recurring noise and re-litigation,
+and — worse — a shim that was meant to be temporary silently ships because
+nobody tracked its closing phase.
+
+**Detection probe:** For each transitional weakening, ask: which scanner will
+flag this, and which later phase closes it? Is the weakening *minimally* scoped
+(e.g. permit-all chains should still explicitly disable form-login/HTTP-Basic so
+the surface is exactly what's intended)?
+
+**Plan action:** Maintain a **transitional-insecure-state register**: each shim
+with (a) why it's needed, (b) the phase that closes it, (c) the residual risk,
+(d) a note to reviewers that it's by-design-until-phase-N. Scope each weakening
+as tightly as possible. Pre-declaring it converts review churn into a resolved,
+tracked decision.
+
+**Examples:**
+- Phase-5 permit-all `SecurityConfig` shims flagged CodeQL "CSRF disabled" on
+  every service, every review; the fix was to explicitly disable form-login/basic
+  and annotate "stateless permit-all shim, closed in Phase N."
+
+---
+
+## H7 — Stacked-PR trap & trunk split-brain (phased governance)
+
+**Trigger:** A multi-phase migration where each phase depends on the previous,
+developed branch-per-phase.
+
+**Risk:** If phase N+1 is branched off phase N's branch (instead of trunk) and
+phase N is never merged to trunk, PRs get merged **into each other**, the trunk
+silently stalls several phases behind, and later phases are forced to stack —
+producing the exact bind where the "no stacked PRs" rule has to be overridden.
+A parallel failure: a repo with **two default-ish branches** (`master` +
+`main`) where phase work targets the wrong one.
+
+**Detection probe:** Before starting a phase, verify the previous phase's PR is
+**merged to trunk** and the new branch is cut **from trunk** (`git log
+origin/<trunk>..HEAD` should be empty at branch creation). Confirm the repo's
+real trunk name and that no legacy default branch is being targeted.
+
+**Plan action:** Mandate **merge each phase PR to trunk before starting the next
+phase**. Never base a phase branch/PR on a sibling phase branch. If genuinely
+blocked and controlled stacking is unavoidable, require a **reconciliation PR**
+that lands the stack onto trunk and an explicit **residual-risk note**. Pin the
+trunk name and mark any legacy default branch "history only — do not target."
+
+**Examples:**
+- PiggyMetrics phases 3 & 4 were merged into each other; `main` stuck at Phase 2;
+  `master`/`main` split-brain — reconciled only by a dedicated PR #6, after
+  Phase 5 had to break the no-stacking rule.
+
+---
+
+## H8 — Living-doc drift (topology changes outrun the docs)
+
+**Trigger:** A phase changes system **topology** — module/reactor membership,
+removed services, renamed branches, changed commands, new/removed endpoints.
+
+**Risk:** Only the plan's status markers get updated; the **executable/onboarding
+docs** (`.github/copilot-instructions.md`, `README`, module lists, command
+tables) go stale and start actively misleading the next agent/human — e.g. a
+"quarantined module" list that no longer matches the reactor.
+
+**Detection probe:** After any topology change, diff the change against every doc
+that *describes* topology: agent-instructions file, README, architecture doc's
+module/command tables, compose/service inventories.
+
+**Plan action:** Extend the **living-plan discipline** beyond the plan file:
+any phase that changes topology must update `copilot-instructions.md`, the
+README, and any module/topology list **in the same PR**. Treat these docs as
+part of the phase's Definition of Done, not a follow-up.
+
+**Examples:**
+- `copilot-instructions.md` quarantine text stayed stale after `gateway` moved
+  into the reactor and `monitoring`/`turbine` were removed; README hard-coded a
+  `master` branch link that 404'd after the trunk became `main`; actuator
+  exposure omitted `refresh`, breaking the `@RefreshScope` workflow.
+
+---
+
+## Quick pre-flight checklist (per phase)
+
+- [ ] **H1** Grepped the dead artifact across *all* manifests; full quarantine set listed?
+- [ ] **H2** Enumerated the major-bump codemods (namespace, removed APIs, test engine); recipe tool chosen?
+- [ ] **H3** Every runtime pin (base images, CI runners, engines) moved in lockstep with the build bump?
+- [ ] **H4** Every route class enumerated (anon, authed, s2s, scrape, webhook) with an explicit rule?
+- [ ] **H5** Stateful-store major has a migration path *or* an explicit destructive-reset decision + rollback?
+- [ ] **H6** Every transitional-insecure state registered with its closing phase + scoped tightly?
+- [ ] **H7** Previous phase merged to trunk; new branch cut from trunk; trunk name confirmed?
+- [ ] **H8** Topology change reflected in copilot-instructions.md + README + module lists in the same PR?