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

# 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.