canary-test-cli 7.1.0 → 8.0.0

package/agents/skills/claude-code/canary-katana/scripts/ledger.mjs

@@ -0,0 +1,183 @@
+// ledger -- the quarantine record for tests that are out of the suite.
+//
+// Every captured deletion is written with its provenance (who, when, what
+// commit, why) so a test that vanishes leaves a trail instead of a silent gap.
+// The ledger is de-duplicated: re-running the capture on the same change adds
+// nothing, and a batch of new entries is sorted for a stable on-disk order.
+//
+// SCHEMA v2 (#771) adds the WHY a row is out, alongside the provenance of how it
+// left: `cause`, `issue`, `expiry`. Two fields deserve their separation --
+// `reason` is DERIVED (the commit subject, "what change did this"), `cause` is
+// ASSERTED (a judgement someone made, "why is it out"). Collapsing them would
+// dress an auto-derived string up as a claim a person stands behind.
+//
+// v2 also makes the ledger no longer purely append-only, for one narrow case
+// documented at `appendEntries`: a row that states a cause SUPERSEDES a causeless
+// row for the same (test, file). See the comment there for why leaving both is
+// worse than replacing one.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SCHEMA_VERSION = 2;
+
+// The fields, in the order they define a row's identity for de-duplication.
+const FIELDS = [
+  'test',
+  'file',
+  'kind',
+  'marker',
+  'commit',
+  'author',
+  'date',
+  'reason',
+  'cause',
+  'issue',
+  'expiry',
+];
+
+/**
+ * Why a test is out of the suite. The two middle values are the ones where the
+ * TEST IS CORRECT and someone else owns the fix, so a producer must require an
+ * `issue` for them -- an untracked "the product is broken" note decays into an
+ * unexplained skip within a release.
+ */
+export const CAUSES = ['flaky', 'product-defect', 'blocked-data', 'obsolete'];
+
+/** Causes for which a row without an `issue` is not a real record. */
+export const CAUSES_REQUIRING_ISSUE = ['product-defect', 'blocked-data'];
+
+/**
+ * @typedef {{test: string, file: string, kind: string, marker: string,
+ *            commit: string, author: string, date: string, reason: string,
+ *            cause: string, issue: string, expiry: string}} LedgerRow
+ */
+
+/** Normalize an entry-like object into a row with the canonical field order. */
+export function LedgerEntry(fields) {
+  const row = {};
+  for (const f of FIELDS) row[f] = fields[f] ?? '';
+  // v1 wrote the tracker link as `ticket` (#781). It is the same fact under a
+  // different name, so it migrates onto `issue` rather than being dropped or
+  // kept alongside -- two fields answering "what is this waiting on" is how a
+  // consumer ends up reading the empty one. `Ticket:` survives as the name of
+  // the COMMIT TRAILER that populates it, which is a mechanism, not a schema.
+  if (!row.issue && typeof fields.ticket === 'string')
+    row.issue = fields.ticket;
+  return row;
+}
+
+// The subset that defines a row's IDENTITY for de-duplication.
+//
+// `issue` and `expiry` are excluded, for the reason #781 excluded `ticket`:
+// identity is what happened -- which test, in which file, muted how, by which
+// commit and why -- and a tracker link is an attribute of that event rather
+// than part of it. Including them would also break the append-only guarantee
+// across this schema change, since rows written before the fields existed key
+// as `''` and the same capture re-run with an issue present would hash
+// differently and append a duplicate of a row already on disk.
+//
+// `cause` IS identity, and deliberately so: `appendEntries` decides supersede
+// on whether a row states one, so a caused and a causeless row for the same
+// test must remain distinguishable here for that decision to have anything to
+// act on.
+const IDENTITY_FIELDS = FIELDS.filter((f) => f !== 'issue' && f !== 'expiry');
+
+const key = (row) => IDENTITY_FIELDS.map((f) => row[f] ?? '').join('\u0000');
+
+/** The (test, file) pair a supersede decision is made on. */
+const pair = (row) => `${row.test ?? ''}\u0000${row.file ?? ''}`;
+
+/**
+ * Load the ledger document, or an empty one when the file is absent.
+ * Throws on unparseable JSON or a non-object top level -- a corrupt ledger is a
+ * hard error the caller must surface, not silently overwrite.
+ *
+ * Every row is normalized through `LedgerEntry`, so a v1 file read here comes
+ * back with the v2 fields present and empty. That is what makes writing
+ * `schema_version: 2` honest: the version claims "these rows have these fields",
+ * and after normalization they do. Stamping the version over un-migrated rows
+ * would make it a promise the file does not keep.
+ * @returns {{schema_version: number, entries: LedgerRow[]}}
+ */
+export function load(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { schema_version: SCHEMA_VERSION, entries: [] };
+  }
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (exc) {
+    throw new Error(`ledger is not valid JSON: ${filePath}: ${exc.message}`);
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error(`ledger top level must be an object: ${filePath}`);
+  }
+  if (!('schema_version' in data)) data.schema_version = SCHEMA_VERSION;
+  if (!('entries' in data)) data.entries = [];
+  if (!Array.isArray(data.entries)) {
+    throw new Error(`ledger entries must be an array: ${filePath}`);
+  }
+  data.entries = data.entries.map((e) => LedgerEntry(e));
+  return data;
+}
+
+/**
+ * Append `entries` to the ledger at `filePath` and persist it. New entries are
+ * sorted by (file, test) and de-duplicated against the batch and disk.
+ *
+ * ONE ROW PER (test, file) MAY STATE A CAUSE, and a caused row wins:
+ *
+ *   - a new row WITH a cause replaces a causeless row for the same pair
+ *   - a new row WITHOUT a cause is dropped when a caused row already exists
+ *
+ * Without this, katana recording `{kind: 'skipped', cause: ''}` and a quarantine
+ * writer recording `{kind: 'skipped', cause: 'product-defect', issue: '#123'}`
+ * differ in `key()` and BOTH persist. A consumer that fails on an unlinked
+ * quarantine (canary-ci-ready does) then fails on the causeless row while the
+ * linked row sits beside it -- the ledger contradicting itself about one test.
+ *
+ * History is not lost to this: rows that differ in cause-bearing state are the
+ * only ones that collapse. Two caused rows, or two causeless rows, keep the
+ * full-field identity and both remain.
+ */
+export function appendEntries(filePath, entries) {
+  const doc = load(filePath);
+  const existing = doc.entries;
+  const seen = new Set(existing.map(key));
+  const causedPairs = new Set(existing.filter((r) => r.cause).map(pair));
+
+  const newRows = entries
+    .map((e) => LedgerEntry(e))
+    .sort(
+      (a, b) => a.file.localeCompare(b.file) || a.test.localeCompare(b.test),
+    );
+
+  for (const row of newRows) {
+    const k = key(row);
+    if (seen.has(k)) continue;
+    const p = pair(row);
+
+    if (row.cause) {
+      // Supersede: drop any causeless row for this pair, then take its place.
+      for (let i = existing.length - 1; i >= 0; i--) {
+        if (!existing[i].cause && pair(existing[i]) === p) {
+          seen.delete(key(existing[i]));
+          existing.splice(i, 1);
+        }
+      }
+      causedPairs.add(p);
+    } else if (causedPairs.has(p)) {
+      // A causeless row must never sit next to a caused one for the same test.
+      continue;
+    }
+
+    seen.add(k);
+    existing.push(row);
+  }
+
+  doc.schema_version = SCHEMA_VERSION;
+  fs.mkdirSync(path.dirname(path.resolve(filePath)), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+  return doc;
+}

package/agents/skills/claude-code/canary-pr-guardian/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: canary-pr-guardian
+description: >
+  PR/pre-commit test-guardian orchestrator: runs the deterministic Tier-0
+  diff-coverage pass, audits affected tests via canary-test-reviewer (Tier 1),
+  and — at the desk with authorTests opt-in — authors missing tests via
+  canary-test-author (Tier 2), staging them and blocking the commit once for
+  human review. Use to guard a change's test quality before it lands.
+---
+
+# Canary: PR Guardian
+
+Guards a change's test quality before it lands. Composes the deterministic
+Tier-0 diff-coverage engine with two native agents — `canary-test-reviewer`
+(read-only audit) and `canary-test-author` (authoring) — under a strict
+write-safety model. This is the **Option A** driver: the engine never calls an
+LLM; **this skill** invokes the agents in-session and enforces
+stage-and-block-once.
+
+**On the tier numbers.** Here they are the values of
+`canary guardian pr-check --tier 0|1|2`, not a repo-wide capability scale — Tier
+1 means "the `--tier 1` pass," which is the agent audit. `Tier-0` is the one
+number with a repo-wide meaning (deterministic, no network, no agent), and
+`Tier-1`/`Tier-2` are guardian-local by
+[ADR 0015](../../../../docs/knowledge/decisions/0015-skill-capability-vocabulary.md).
+Do not carry them into other skills.
+
+## When to Use
+
+- Before opening or updating a PR, to check that new/changed code is tested.
+- As a pre-commit companion when `preCommit.authorTests: true` is set and you
+  want the guardian to author the missing tests for you (at the desk only).
+- NOT in CI for Tier-2 write-back — that is a NON-GOAL. CI runs Tier-0 only (the
+  `CANARY_GUARDIAN_AGENT` env is unset there).
+
+## Safety model (non-negotiable)
+
+- **NEVER commit or push.** This skill only authors and `git add`s. The human
+  reviews the staged tests and re-commits.
+- **Honor every `skipped` reason** from `author-plan` verbatim (opt-in-off /
+  tier / fork / collision / loop-guard). Never override a skip.
+- **Block once.** When `block.block == true`, print the block message and stop —
+  leave the staged tests for the human. The loop-guard sentinel you write in
+  Phase 3 is what stops the guardian re-authoring over its own output on the
+  next run. It is stamped with the current `HEAD` and expires by itself once the
+  human's review commit moves `HEAD` — never delete it yourself.
+- **Authoring is opt-in.** No `preCommit.authorTests: true` ⇒ no writes, ever.
+
+## Phases
+
+### Phase 0 — Deterministic scope
+
+Run the Tier-0 pass and read its findings:
+
+```bash
+canary guardian pr-check --format json
+```
+
+Findings are `untested-new-code` gaps. If there are none, report clean and stop.
+
+**Coverage regressions (#606).** `--coverage` alone answers only "is this
+changed unit covered at all?". To also catch a unit whose coverage _fell_
+against the base branch, pass the base ref's report as well:
+
+```bash
+canary guardian pr-check --coverage lcov.info --base-coverage base-lcov.info --format json
+```
+
+That adds `coverage-regression` findings, graded by how many percentage points
+were lost. Most CI never uploads a base-branch artifact; without
+`--base-coverage` the run degrades **loudly** to "delta unavailable — head-only"
+and `coverage_delta.status` reports `unavailable`. Read that field before
+treating an empty finding list as "no regressions" — a run that compared nothing
+has abstained, not passed.
+
+### Phase 1 — Quality audit (Tier ≥ 1, read-only)
+
+Export the availability signal so the probe reports the ceiling, then audit the
+affected tests with `canary-test-reviewer`:
+
+```bash
+export CANARY_GUARDIAN_AGENT=1   # or 2 when authoring is enabled
+```
+
+If this checkout is a **fork** (an untrusted/read-only context — detect it, e.g.
+`git config --get remote.origin.url` pointing at a fork, or a CI fork PR), arm
+the fork guard so the engine's safety layer never authors on it:
+
+```bash
+export CANARY_GUARDIAN_IS_FORK=1   # any value other than "0"/unset means fork
+```
+
+Leave `CANARY_GUARDIAN_IS_FORK` unset (or `0`) at your own desk on a trusted
+checkout. The guard fails CLOSED: any ambiguous value is treated as a fork and
+authoring is skipped.
+
+Use the `canary-test-reviewer` agent to review the affected tests. This is
+**read-only** — surface weak-test findings; write nothing.
+
+### Phase 2 — Authoring plan (Tier 2 + opt-in)
+
+Ask the engine's safety layer for the plan (intents + block decision):
+
+```bash
+canary guardian author-plan --json
+```
+
+The JSON is `{"intents": [...], "block": {...}}`. Each intent carries `status`
+(`planned` | `authored` | `skipped`), `target_path`, `requirement`, and a
+`skip_reason` when skipped. **Do not author anything the plan skipped** — the
+Engine guards (opt-in, fork, collision, loop-guard) are authoritative.
+
+### Phase 3 — Author, stage, block once
+
+For each intent with `status: "planned"`, use the `canary-test-author` agent
+with the intent's `requirement` as the task and `target_path` as the
+destination. **Never overwrite an existing file at `target_path`.** The engine's
+collision guard runs at plan time, so between planning and writing another
+PR/session may have created the file (a TOCTOU window). If the target already
+exists at write time, skip that intent and report it — do not clobber it. Then
+stage the authored files:
+
+```bash
+git add <target_path>
+```
+
+When `block.block == true`, record the guardian-authored paths in the loop-guard
+sentinel BEFORE blocking, by running the deterministic producer command once per
+authored path:
+
+```bash
+canary guardian mark-authored --path <target_path> [--path <target_path> ...]
+```
+
+This is a real CLI step (not something you `touch` yourself): it writes the
+sentinel inside the real git dir and records exactly the paths you authored,
+stamped with the current `HEAD`. `author-plan` reads it on the next run and
+returns a `loop-guard` skip **while `HEAD` is unchanged**, so the guardian never
+authors on top of its own output — and once the human commits the reviewed
+tests, `HEAD` moves and authoring re-enables itself.
+
+Then print `block.message` (the "N test(s) authored & staged — review and
+re-commit" notice) and **stop**. Do not commit. The human reviews the staged
+tests and re-commits.

package/agents/skills/claude-code/canary-pr-guardian/skill.yaml

@@ -0,0 +1,17 @@
+name: canary-pr-guardian
+version: '1.0.0'
+description:
+  PR/pre-commit test-guardian orchestrator — Tier-0 diff-coverage, Tier-1
+  quality audit via canary-test-reviewer, and at-desk Tier-2 authoring via
+  canary-test-author with stage-and-block-once review.
+stability: static
+triggers:
+  - manual
+platforms:
+  - claude-code
+type: rigid
+tools: []
+tier: 1
+depends_on:
+  - canary-test-reviewer
+  - canary-test-author

package/agents/skills/claude-code/canary-promote-test/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: canary-promote-test
+description: >
+  Move a generated test from `tests/generated/` into the committed test suite —
+  reviews it for correctness, drops the generation header, relocates it to the
+  matching suite directory, and confirms it runs in the project's normal test
+  flow. Use for "promote this test", "commit this generated test", "move this
+  test into the suite", or "keep this test" — always after the generated test
+  has been validated against the SUT, never before. Not for tests needing
+  substantial rewriting (regenerate instead) or throwaway investigation tests
+  (leave in `tests/generated/`).
+---
+
+# Canary: Promote Test
+
+> Move a generated test from `tests/generated/` into the committed test suite.
+> Reviews the test for correctness, drops the generation header, relocates it
+> under the appropriate suite directory, and confirms it runs in the project's
+> normal test flow.
+
+## When to Use
+
+- After `canary-generate-test` produced a file that has been validated against
+  the SUT
+- When a user explicitly asks to "commit", "save", or "keep" a generated test
+- When extending an existing suite with a new case the team has agreed to
+  maintain
+- NOT before the generated test has been executed and reviewed — promotion is
+  the _last_ step, not the first
+- NOT for tests that need substantial rewriting — regenerate with a better
+  prompt instead of hand-patching
+- NOT for tests targeting throwaway investigations (perf spikes, ad-hoc bug
+  triage) — leave those in `tests/generated/`
+
+## Process
+
+### Phase 0: GATE — Get the Structured Verdict First
+
+Run this before reading the test. It is deterministic, takes no API key, and it
+will refuse the drafts that are not worth your review time.
+
+```bash
+canary promote-check tests/generated/api/orders_post.py --json
+```
+
+| Exit | Verdict   | What it means                                                |
+| ---- | --------- | ------------------------------------------------------------ |
+| `0`  | `promote` | No gating defect. Advisory findings may remain — your call.  |
+| `1`  | `block`   | A gating defect. **Do not promote.** Regenerate or fix.      |
+| `3`  | `abstain` | No verdict could be produced. Promotion is **not** approved. |
+
+**Which axes gate, and why only those.** Gating on all eight axes of a quality
+critique would block nearly every promotion, so only deterministic defects do:
+
+| Axis              | Rules                          | Gates | Reason                                                 |
+| ----------------- | ------------------------------ | ----- | ------------------------------------------------------ |
+| `soundness`       | `SOUND-001/002/003`            | yes   | Pins a value no correct implementation must produce    |
+| `assertions`      | `LINT-006`                     | yes   | A test that asserts nothing always passes              |
+| `flakiness`       | `FLAKE-001/002`                | yes   | A hardcoded sleep in a committed suite is a future red |
+| `vacuity`         | `VAC-001/003`, annotated `002` | yes   | Cannot fail, or contradicts a declared `@covers`       |
+| `selectors`       | `LINT-001/002/003`             | no    | Brittle, not wrong — a reviewer's call                 |
+| `maintainability` | `LINT-005`, `FLAKE-003/004`    | no    | Style and softer signals                               |
+
+**`VAC-002` gates only at `annotated` fidelity.** At `import-inferred` it is an
+inference about which symbol the test meant to exercise, and a heuristic must
+not be load-bearing on a promotion gate. If you want the gate to check the real
+target, add the annotation to the generated test:
+
+```ts
+// @covers resolveOverlay
+```
+
+**An `abstain` is not a pass.** Exit 3 means the checker had no subject — an
+unparseable extension, or a file with no test declarations. Promotion falls back
+to the manual review below and is **not** approved by silence. Do not read a
+missing verdict as either stricter or looser than one.
+
+**An LLM judgement never gates.** `harness:test-craft` runs an 8-axis per-test
+critique and remains exactly what step 5 below calls it: an optional deeper
+audit for a human. Everything that blocks in this repo is deterministic, and
+`promote-check` keeps it that way — the verdict has no field an LLM opinion
+could arrive in.
+
+### Phase 1: REVIEW — Confirm the Test Is Worth Keeping
+
+1. **Read the test end-to-end.** Treat it like any other code review — naming,
+   assertions, hardcoded values, missing edge cases. Generated tests are drafts,
+   not finished artifacts.
+2. **Run the test against the real SUT** (not just the env it was generated
+   against). A test that only passes in one environment is a fixture-bound test,
+   not a regression test.
+3. **Check assertion strength.** A test that only asserts "status code 200" is
+   weak; promote it only if that's genuinely the contract. If the SUT returns
+   structured data, the test should assert on shape.
+4. **Confirm no hardcoded secrets or environment-specific URLs.** Replace with
+   fixtures or env-driven config before promoting.
+5. **Optional: run `harness:test-craft` for a deeper quality audit.**
+   `test-craft` runs an 8-axis per-test LLM critique (assertion density,
+   flakiness risk, contract vs implementation, etc.). Use it when the generated
+   test is substantial or when the team wants a second opinion before
+   committing. Not required for simple happy-path tests, and **never a blocker**
+   — see Phase 0.
+6. **Triage the advisory findings** `promote-check` reported. They did not
+   block; deciding whether they matter here is the review's job.
+7. **Decide: promote, regenerate, or discard.** If review reveals more than ~3
+   small fixes, regenerate with a sharper prompt instead.
+
+### Phase 2: RELOCATE — Move into the Suite
+
+1. **Identify the destination directory.** Mirror the suite's structure:
+   - `tests/generated/api/foo.py` → `tests/api/foo.py`
+   - `tests/generated/e2e/checkout.spec.ts` → `tests/e2e/checkout.spec.ts`
+   - `tests/generated/unit/validator.py` → `tests/unit/validator.py`
+2. **Match suite conventions.** Look at neighboring files for:
+   - Import style (relative vs absolute)
+   - Fixture/setup imports (most suites have a `conftest.py` or shared setup)
+   - Naming conventions (`test_<feature>_<case>.py`, `<feature>.spec.ts`)
+3. **Move with `git mv`** so the history is preserved if anyone later runs
+   `git log --follow`.
+4. **Update imports** if the file referenced anything by relative path from
+   `tests/generated/`.
+
+### Phase 3: CLEAN — Drop Generation Artifacts
+
+1. **Remove the timestamped generation header.** The "Generated by Canary on
+   [date]" comment is useful in scratch space — meaningless in a committed test
+   and rots immediately.
+2. **Remove any placeholder TODOs.** The generator sometimes emits
+   `# TODO: adjust selector` or similar — either resolve them or stop the
+   promotion and regenerate.
+3. **Tighten formatting.** Run the project's formatter (`black`, `prettier`,
+   etc.) so the file matches surrounding style.
+4. **Strip dead code.** Imports the generator added "just in case" but the test
+   doesn't use.
+
+### Phase 4: VERIFY — Run in the Project's Normal Flow
+
+1. **Run the suite that owns this test:**
+   - Python: `pytest tests/api/test_orders_post.py`
+   - Playwright: `npx playwright test tests/e2e/checkout.spec.ts`
+   - Match whatever CI runs.
+2. **Run the full suite** to confirm no collateral failure (shared fixtures,
+   port conflicts, ordering issues).
+3. **Confirm CI configuration picks it up.** If the suite has a glob in CI
+   config, verify the new path matches. If not, add it.
+4. **Log the promotion.** Append a one-line entry to `docs/CANARY_STATE.md` so
+   the project ledger tracks which generated tests have been promoted.
+
+## Canary Integration
+
+- **`tests/generated/`** — Source for promotion. Gitignored; nothing here is
+  ever a final artifact.
+- **`tests/<suite>/`** — Destination. Each suite has its own conventions; never
+  invent a new top-level dir during promotion.
+- **`docs/CANARY_STATE.md`** — Append a promotion entry: requirement, generated
+  path, promoted path, date.
+
+## Success Criteria
+
+- The promoted test passes when run via the project's normal test command
+- The full suite passes (no collateral breakage)
+- The file matches the surrounding code style (formatter clean, lint clean)
+- No generation artifacts remain (timestamp header, placeholder TODOs, unused
+  imports)
+- CI picks up the new test on the next push
+
+## Rationalizations to Reject
+
+| Rationalization                                                           | Why It Is Wrong                                                                                                                                                             |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "`promote-check` exited 3, so nothing was wrong"                          | Exit 3 is an abstention — the checker had no subject at all. It is the one outcome that proves nothing, so it can never stand in for approval.                              |
+| "`promote-check` blocked on VAC-002, but the test is fine"                | Only an `annotated` VAC-002 blocks, which means the file's own `@covers` names a symbol the test never touches. Either the annotation is wrong or the test is.              |
+| "I'll wire `harness:test-craft` into the gate for better coverage"        | An 8-axis LLM critique gating a promotion would block nearly everything and would make a judgement load-bearing. Deterministic verdicts gate; critiques inform.             |
+| "The test works, I'll skip the review and just commit it"                 | Generated code looks plausible but commonly has weak assertions or hardcoded values. Review is the whole point — promotion without review just imports debt into the suite. |
+| "I'll fix the 6 issues I found in the review by editing the test"         | Six issues means the prompt was wrong. Regenerate; hand-edits won't transfer to the next similar test.                                                                      |
+| "I'll leave the timestamp header so we know when it was generated"        | Git history already records when the file was committed. The header rots and creates noise.                                                                                 |
+| "It passes against staging, that's good enough"                           | If the test only passes in one environment, it's a fixture-bound smoke check, not a regression test. Either parametrize the env or don't promote it.                        |
+| "I'll commit it without running the full suite — I only changed one test" | New tests can break shared fixtures, conflict on ports, leak state. Always run the full suite once before commit.                                                           |
+
+## Examples
+
+### Example: Clean promotion
+
+**Source:** `tests/generated/api/orders_post_201.py`, validated, single status
+assertion is exactly the contract.
+
+**Action:**
+
+1. `git mv tests/generated/api/orders_post_201.py tests/api/test_orders_post_201.py`
+2. Drop the `# Generated by Canary...` header.
+3. Adjust import to match `tests/api/conftest.py` fixtures.
+4. Run `pytest tests/api/` → passes.
+5. Append to `CANARY_STATE.md`: promoted `orders_post_201.py` →
+   `tests/api/test_orders_post_201.py` on [date].
+
+### Example: Promotion abandoned — regenerate instead
+
+**Source:** `tests/generated/e2e/checkout.spec.ts`. Review finds: hardcoded test
+user creds, no wait for navigation, weak assertion (`expect(true).toBe(true)`),
+TODO comments left in three places.
+
+**Action:** Stop. Regenerate with a sharper prompt that names the real fixture
+user, specifies the wait condition, and asserts the actual checkout success
+state. Do not commit the broken draft.
+
+### Example: Test for throwaway investigation
+
+**Source:** `tests/generated/performance/spike_search_50rps.js`. Used once to
+confirm a single perf hypothesis. No ongoing value.
+
+**Action:** Do not promote. Leave in `tests/generated/`. If the team wants
+ongoing perf monitoring, generate a _new_ test with a sustainable RPS profile
+and promote that.
+
+## Escalation
+
+- **When the review reveals the SUT itself is broken:** Don't promote the test
+  that passes against the broken SUT. File a bug; only promote the test once the
+  SUT is fixed and the assertion has a real contract behind it.
+- **When the suite has no existing convention to match:** This usually means the
+  test belongs in a new sub-suite. Ask the user to confirm the suite structure
+  before inventing one.
+- **When CI doesn't pick up the new path:** Don't merge until CI config matches.
+  A test that exists but isn't run is worse than no test — it implies coverage
+  that doesn't exist.
+- **When the promoted test starts flaking after merge:** Treat as a real
+  regression in the test (or the SUT). Don't quarantine in `tests/generated/` —
+  fix or delete.