chore: publish from main

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.