@event4u/agent-config 14.12.0 → 14.14.0

package/dist/agent-src/skills/laravel-migration/SKILL.md

@@ -36,7 +36,8 @@ Use this skill when the user asks to create a database migration, add a column,
 - Use `decimal` for money — never `float`.
 - Add indexes for columns used in WHERE clauses and JOINs.
 - Match existing column naming patterns in the same table or domain.
-- Always include a reversible `down()` method.
+- Declare recovery: a reversible `down()`, or a roll-forward plan in the file
+  (see § The recovery contract below). Silence is the violation.
 
 ## Laravel projects
 
@@ -73,7 +74,10 @@ return new class extends Migration {
             $table->foreign('customer_id')
                 ->references('id')
                 ->on('customers')
-                ->onDelete('cascade');
+                // Choose the referential action; never inherit it from a
+                // template. See "Referential action is a decision" below.
+                ->onDelete('cascade'); // cascade: rows here are expendable
+                                       // WITHOUT their customer
 
             $table->index('is_active');
         });
@@ -143,6 +147,54 @@ php artisan migrate --env=testing             # testing
 1. Migration file with up() and down() methods
 2. Model updates if columns or relationships changed
 
+### The recovery contract — one obligation, two branches
+
+Every migration declares **one** of these, and silence is the violation:
+
+1. a `down()` that restores the prior state; **or**
+2. a **roll-forward recovery plan, written in the migration file itself**, for
+   the cases where restoration is genuinely impossible — a completed
+   destructive backfill, a dropped column whose data is gone.
+
+The second branch is not a lighter obligation. A migration taking it records, in
+its own file comments, all three of:
+
+1. **why restoration is impossible**, with the evidence — the data was checked
+   and is unrecoverable, not assumed to be;
+2. **the ordered recovery procedure** — the steps, the inputs each needs, and
+   the criteria that say recovery succeeded;
+3. **the responsible recovery owner**.
+
+Vague intent or missing detail is the violation. The plan lives in the migration
+file and lands in the same diff, because a plan documented "later" somewhere else
+is a plan nobody can review at the moment it matters.
+
+## Referential action is a decision
+
+The template above labels its `onDelete('cascade')` as **one branch**, not a
+default. Copying it unchanged is how a delete of one customer silently removes
+records that had independent value.
+
+| The child row, without its parent, is | Action | What happens |
+|---|---|---|
+| **expendable** — it only means something as part of the parent | `cascade` | deleted with the parent |
+| **self-valued** — it is a record in its own right (an invoice, an audit row, a payment) | `restrict` (or `no action`) | the parent delete FAILS until the child is dealt with |
+| **survivable** — it outlives the parent with the link removed | `set null` | the column is nulled; requires a nullable column |
+
+Two consequences worth stating because they are the ones missed:
+
+- `restrict` is the safe default for anything a finance, audit, or legal reader
+  would expect to still exist. A failed delete is a conversation; a cascaded
+  delete is a recovery.
+- `set null` needs the foreign-key column to be nullable, and it needs the
+  application to handle the orphan state. Choosing it without both is choosing a
+  constraint error later.
+
+Soft deletes do **not** interact with this: `onDelete` fires on a real `DELETE`,
+so a soft-deleting parent never triggers it. If the model soft-deletes, the
+referential action describes what happens on a force-delete or a purge, and that
+is the case to decide against.
+
 ## Gotcha
 
 - Always check if the table/column already exists before creating the migration — the model doesn't always check.
@@ -155,7 +207,9 @@ php artisan migrate --env=testing             # testing
 - Do NOT create migrations without specifying the correct connection when multiple databases exist.
 - Do NOT create tables without checking the project's naming conventions (prefixes, casing).
 - Do NOT use raw SQL in migrations when Schema builder works.
-- Do NOT forget to make migrations reversible (down method).
+- Do NOT leave recovery undeclared — ship a `down()` that restores the prior
+  state, or the three-part roll-forward plan in the migration file. Neither is
+  optional; choosing between them is.
 - Do NOT use `float` for money — use `decimal`.
 - Do NOT forget indexes on foreign keys and frequently filtered columns.
 

package/dist/agent-src/skills/monorepo-workspace/SKILL.md

@@ -57,6 +57,24 @@ In precedence order, and report which one answered:
 Globs are globs: `packages/*` means every direct child carrying a manifest, not
 every directory.
 
+### 2b. Catalogs — the version is declared once, not per member
+
+When the workspace defines a **catalog**, a member's `catalog:` range is a
+REFERENCE, not a declaration. Report the catalog as the version's home:
+
+- A member range starting `catalog:` (bare, or `catalog:<name>`) resolves
+  against the workspace catalog definition. It does not resolve outside the
+  workspace at all — treat it exactly as `workspace:` for publishability.
+- **An upgrade edits the catalog, not the member.** Editing a member that reads
+  `catalog:` is either a no-op or a silent divergence from the catalog, and the
+  catalog exists precisely so the version has one home.
+- **A member carrying a version LITERAL for a dependency the catalog also
+  declares is reported, not gated** — see § Do NOT. Name the member, the
+  dependency, the literal range, the catalog name and the catalog range. Where
+  several catalogs declare the same dependency, list every candidate rather than
+  inventing an applicable one; nothing in the workspace definition says which
+  the literal intended to follow.
+
 ### 3. Task runner — ask the runner, do not read its config
 
 When a runner is present, its own listing is the source of truth, because a
@@ -133,6 +151,14 @@ When the runner was absent, the last line reads
 
 ## Do NOT
 
+- **Do NOT gate on a member version literal.** Whether a catalog repository
+  permits selective literals is that repository's convention, not this suite's
+  to impose. Report it as a structural observation — *"member literal overlaps
+  catalog entry"*, never *"invalid"* — and let the reader decide. An exact
+  mismatch between the literal and the catalog range is reported at higher
+  severity, and still does not gate.
+
+
 - Read `project.json` by hand to enumerate Nx projects — `nx show projects` is
   the source of truth and includes inferred targets.
 - Install `turbo` or `nx` to answer a question. They are the consumer's

package/dist/agent-src/skills/playbook-authoring/SKILL.md

@@ -112,6 +112,33 @@ The derivation therefore unwraps a thin wrapper and records what it points at, a
   confirm, and the file says which id failed. Downgrading is the honest outcome; writing
   the stronger claim and hoping is the failure this skill exists to prevent.
 
+## A confirmed canonical answer is a playbook — including the awkward one
+
+A repository's answer to *"where does new code of this kind go"* is a playbook
+once it has been **confirmed**, graded like any other: `configured` when every
+cited id resolved, `observed` when one did not.
+
+**The awkward case is the one worth writing down.** A public surface version and
+an **implementation generation** are independent axes — a `v1` controller can
+carry the current internal architecture while a `v2` one is half-migrated and
+abandoned. So the canonical answer for a scope is frequently *"the
+older-looking lane"*, and that is exactly the answer nobody records because it
+reads as a mistake. **ADR-248** holds the evidence order that produces it: a live
+decision record, then an executable architecture test, then a shared abstraction
+in maintained code, then current tests and contracts, then several recent
+analogous implementations, then migration docs, then git history, and **names and
+paths last**.
+
+Two bounds, both deliberate:
+
+- **Per scope, never per artifact type.** A repository may legitimately have two
+  right answers in two modules. There is no single global exemplar, and a
+  playbook claiming one is over-reaching its own `scope`.
+- **No second contract.** This is the ADR-244 playbook class unchanged — not a
+  conventions map, not a canonicality registry. A confirmed answer is a
+  playbook; an unconfirmed one is a hypothesis and belongs in the analysis that
+  produced it.
+
 ## Output format
 
 1. One playbook per file in the playbook home, frontmatter first: `task`, `scope`, `grade`,
@@ -156,7 +183,7 @@ The derivation therefore unwraps a thin wrapper and records what it points at, a
 
 ## See also
 
-- [ADR-244](../../../docs/decisions/ADR-244-playbook-is-a-sixth-context-type.md) — the artefact class, its grades, its home, and the two deferred kinds.
+- [ADR-244](../../../docs/decisions/ADR-244-playbook-is-a-sixth-context-type.md) — the artifact class, its grades, its home, and the two deferred kinds.
 - [`standards-from-config`](../standards-from-config/SKILL.md) — the Class-A rule this applies to procedure rather than to style.
 - [`context-document`](../context-document/SKILL.md) — the contexts machinery a playbook reuses as its sixth type.
 - [`command-writing`](../command-writing/SKILL.md) — the numbered-step shape the body follows.

package/dist/agent-src/skills/react-shadcn-ui/SKILL.md

@@ -24,7 +24,7 @@ execution:
   handler: shell
   safety_mode: strict
   allowed_tools:
-    - npx
+    - Bash(npx:*)
 ---
 
 # react-shadcn-ui

package/dist/agent-src/skills/skill-writing/references/procedure.md

@@ -258,7 +258,7 @@ rubric:
 ```
 
 `contains` / `file_exists` grade deterministically. `rubric` items grade
-via a fresh sub-agent reading the output against the criterion — keep
+via a fresh subagent reading the output against the criterion — keep
 each criterion to one falsifiable sentence.
 
 **Loop** (orchestrated by `scripts/run_skill_evals.ts`):
@@ -266,14 +266,14 @@ each criterion to one falsifiable sentence.
 1. **Scaffold** — `./scripts-run src/scripts/run_skill_evals scaffold {skill}`
    creates `runs/{timestamp}-{baseline,with-skill}/` and seeds each
    scenario's `meta.json`.
-2. **Baseline run** — spawn one sub-agent per scenario **without** the
+2. **Baseline run** — spawn one subagent per scenario **without** the
    skill loaded. Capture stdout + any artifacts into
    `runs/{timestamp}-baseline/{scenario-id}/`.
-3. **With-skill run** — same scenarios, same sub-agent harness, **with**
+3. **With-skill run** — same scenarios, same subagent harness, **with**
    the skill loaded. Capture into `runs/{timestamp}-with-skill/{scenario-id}/`.
 4. **Grade** — for each scenario, write a `grade.json` file with
    per-assertion pass/fail. Deterministic assertions auto-grade;
-   rubric assertions need a grader sub-agent.
+   rubric assertions need a grader subagent.
 5. **Aggregate** — `./scripts-run src/scripts/run_skill_evals aggregate {skill}
    --run {timestamp}` produces `runs/{timestamp}-benchmark.json` with
    pass-rate, timing, token deltas baseline-vs-with-skill.
@@ -281,7 +281,7 @@ each criterion to one falsifiable sentence.
    --run {timestamp}` prints the diff. Iterate on the skill body
    until `with-skill` outperforms `baseline` on every scenario.
 
-The script ships with sub-agent spawning **stubbed** — the orchestration
+The script ships with subagent spawning **stubbed** — the orchestration
 layer is per-environment (Claude Code, Augment, council). Implement
 the spawn function once for your environment, the rest of the loop
 (aggregate / report / scaffold) works out of the box.

package/dist/agent-src/skills/sql-writing/SKILL.md

@@ -30,7 +30,7 @@ Do NOT use when:
 
 1. **Inspect call site & choose approach** — identify every dynamic value flowing into the query, then pick: query builder when possible. Raw SQL only when query builder can't express the query.
 2. **Parameterize** — Every variable must use `?` binding or named `:param`. Never interpolate PHP variables into SQL strings.
-3. **Use MariaDB syntax** — Not PostgreSQL or MSSQL. Check `php/sql.md` for MariaDB-specific patterns.
+3. **Read the engine, then choose the syntax** — check, in order: the project's DB config (`config/database.php` default connection, `DB_CONNECTION`), a `docker-compose.yml` service image, a migration using engine-specific syntax. MySQL and MariaDB share the query-syntax world this skill writes in; PostgreSQL and MSSQL do not. **If none of those declare an engine, say so and ask — do not assume one.** A query written for the wrong engine passes review and fails in production.
 4. **Verify** — Run EXPLAIN on complex queries. Check that no PHP interpolation (`"$var"`, `'{$var}'`) appears in SQL.
 
 ```
@@ -66,6 +66,12 @@ DB::select("SELECT * FROM users WHERE email = '{$email}'");
 
 ## Gotcha
 
+**MySQL and MariaDB share a query-syntax world. They never share a migration
+one.** Same principle as `database`: one engine for writing a `SELECT`, two for
+online-DDL semantics, lock behavior under `ALTER`, feature availability and
+`EXPLAIN` output. Never carry a claim from the second group across the two
+without naming the engine and version it was measured on.
+
 - MariaDB and MySQL have subtle syntax differences.
 - The model writes `$variable` in SQL strings instead of `?` placeholders.
 - `GROUP BY` with `ONLY_FULL_GROUP_BY` requires all non-aggregated columns.

package/dist/agent-src/skills/standards-from-config/SKILL.md

@@ -50,20 +50,43 @@ found", do not fabricate one).
    - Python: `pyproject.toml` / `ruff.toml` (`[tool.ruff]`, `[tool.black]`),
      `setup.cfg`.
    - Ruby: `.rubocop.yml`. Go: `gofmt`/`golangci.yml`.
-2. **Derive as pointer + digest, never a flattened claim.** Each standard is one
+2. **Follow the chain before you digest, and pick the config NEAREST the edit.**
+   Read literally — one file, one parse — this procedure returns a null on a
+   repository whose root config is a single `extends`. A fourteen-line linter
+   config whose only load-bearing line points into a package in the same
+   workspace is not a project without standards; it is a project whose standards
+   are one hop away, and "no enforced standard found" there is a false negative
+   that reads exactly like a true one. `extends` is specified in TypeScript,
+   ESLint, Biome and Stylelint; `includes` plays the same role in PHPStan and
+   Rector; `workspace:` is documented in npm, yarn, pnpm and bun.
+   - **Precedence is nearest-first, and it is not a preference.** The config in
+     the edited path's own directory governs, then its parent, up to the
+     repository root. A per-package `tsconfig.json`, `.eslintrc`, `.env` or
+     deployment manifest is the one that package's build reads; a root file it
+     does not extend has no effect on it. Reading the root config for an edit
+     inside a package that carries its own is a **wrong** answer, not a coarse
+     one. Report the outranked root candidate too, so the precedence is visible.
+   - **An unresolvable hop is a named gap with a PARTIAL digest, never an
+     absence.** Say which hop failed and why. A partial digest naming its gap is
+     usable; a null that reads as "no standards" is a lie.
+   - **A hop that leaves the repository is labelled `external` and excluded from
+     the digest.** Presenting a third-party preset as the project's own standard
+     is worse than reporting nothing — the reader cannot tell which rules the
+     project chose. Report it with its path; do not merge it.
+3. **Derive as pointer + digest, never a flattened claim.** Each standard is one
    line: the **value**, the **config file it came from**, and the **scope** it
    applies to. Write `ruff.toml → line-length = 88 (scope: src/**/*.py)`, NOT
    "the project uses line length 88". The pointer makes the claim re-checkable
    and the next agent can open the config to confirm.
-3. **Preserve scope; surface conflicts, never flatten them.** If two configs (or
+4. **Preserve scope; surface conflicts, never flatten them.** If two configs (or
    an inline / per-directory override) give two values, emit **two pointers with
    two values + their scopes** — never one ambiguous merged claim. A visible
    conflict is correct; a hidden flattened guess is the failure mode.
-4. **Stamp staleness.** Record each source's `config_mtime` (or content hash).
+5. **Stamp staleness.** Record each source's `config_mtime` (or content hash).
    The digest is stale when the config file's mtime/hash changes → re-derive. No
    human gate is needed (Class A is deterministic) — the digest is **regenerated
    from the config, never hand-edited**.
-5. **Persist** as a Class-A context card under `agents/settings/contexts/` (see
+6. **Persist** as a Class-A context card under `agents/settings/contexts/` (see
    Output format). Class A is high-trust *because* config-derived — it is read
    for heuristics only and never bypasses a fresh structural read (the v1↔v2
    isolation contract in `evidence-discipline`).

package/dist/agent-src/skills/supply-chain-intake/SKILL.md

@@ -51,18 +51,25 @@ PIN IT, LOCK IT, CVE-SCAN IT. NEVER PIPE A REMOTE SCRIPT STRAIGHT TO A SHELL.
    ```
    Non-existent, brand-new (published days ago), or near-zero-download → **stop**, treat as hallucination/slopsquat.
 2. **Typo-adjacency** — is the name within 1–2 chars of a far-more-popular package (`python-dateutil` vs `dateutil`, `lodahs` vs `lodash`)? If so, you probably want the popular one — confirm before installing.
-3. **Version safety** — the model's version pin may predate a CVE fix (training-cutoff reintroduction). Take the current patched release, then scan:
+3. **Version source — look it up BEFORE you write a version, and report which outcome you got.** This is a precondition of step 4, not a note on it. Two outcomes, with opposite handling, and only the first is forbidden:
+   - **Invention** — writing a version string that **no source in the repository produced**. Always forbidden. A version that appeared from nowhere is unverifiable by anyone downstream, including you an hour later.
+   - **Lookup failure** — having searched the **declared version sources** and found none. Those sources are per ecosystem: a catalogue or a `workspace:` protocol entry, an existing manifest in the tree (`package.json`, `composer.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`), and the lockfile. This is **not** a violation. Resolving it from the registry or from the user is the correct move; report it as *unresolved-then-resolved* with the source named.
+
+   **Silence is the failure, never the fallback.** Producing a version with no source and no report is the thing the rule forbids; reporting an unresolved lookup is the thing it asks for.
+
+   A manifest that already expresses a version through a protocol — `workspace:*`, a catalogue reference — is **left as it is**. Rewriting it to a literal discards the mechanism the repository chose and pins a value the workspace was resolving for you. `workspace:` is documented in npm, yarn, pnpm and bun; catalogued versions are a documented feature of pnpm and bun.
+4. **Version safety** — the model's version pin may predate a CVE fix (training-cutoff reintroduction). Take the current patched release, then scan:
    ```bash
    npm audit           # block on high/critical
    pip-audit
    osv-scanner -r .
    ```
-4. **Pin + lock** — install exact + commit the lockfile; reject floating ranges (`^`, `latest`, no lockfile) on production deps.
+5. **Pin + lock** — install exact + commit the lockfile; reject floating ranges (`^`, `latest`, no lockfile) on production deps.
    ```bash
    npm install --save-exact <pkg> && git add package-lock.json
    ```
-5. **License** — confirm the license is compatible with the project's declared license before it lands.
-6. **No pipe-to-shell** — never `curl … | bash` an install; download → inspect → execute over pinned HTTPS, or surface it to the user for confirmation.
+6. **License** — confirm the license is compatible with the project's declared license before it lands.
+7. **No pipe-to-shell** — never `curl … | bash` an install; download → inspect → execute over pinned HTTPS, or surface it to the user for confirmation.
 
 ## MCP-server intake — the dependency gate plus two extra checks
 

package/dist/agent-src/skills/symfony-workflow/SKILL.md

@@ -180,3 +180,38 @@ Then add these **Symfony-specific** checks:
 - Messenger `failure_transport` is opt-in; without it, failures vanish.
 - Compiled container changes need `cache:clear` in `prod` before debugging "config not applied".
 - Symfony 7.x removed deprecated APIs — verify `composer.lock` before assuming 6.x patterns work.
+
+## When NOT to use — components without the framework
+
+```
+A DEPENDENCY PROVES A LIBRARY IS AVAILABLE. ONLY THE ENTRY POINT AND THE
+ROUTER PROVE WHICH APPLICATION SHAPE IS RUNNING.
+`symfony/*` PACKAGES WITH NO SKELETON MARKER IS A THIRD STATE, AND THIS SKILL
+DOES NOT APPLY TO IT.
+```
+
+Symfony ships its ORM, container, collections and HTTP layer as
+independently installable packages, usable with no framework present — a
+published distribution model, not one consumer's arrangement. An application
+built that way has a **custom entry point and a custom router**. Routing it here
+offers a CLI that does not exist, a request-validation primitive that is not
+wired, and a routes file that was never there: every suggestion confidently
+wrong, and the reason visible only from the entry point.
+
+**The probe set, and its cost.** A fixed set of filesystem existence checks plus
+one manifest read — no directory walk, no content scan, and never re-derived per
+session. Any ONE marker present means the framework is real:
+
+| Probe | Meaning |
+|---|---|
+| `bin/console` | the console entry point the skeleton writes |
+| `config/bundles.php` | the bundle registry |
+| `config/services.yaml` | the DI service config |
+
+`symfony/*` in `composer.json` with **none** of those markers is
+*components-without-the-framework*. Say so and route away from this skill rather
+than answering as though the framework were there.
+
+Implemented deterministically in `src/install/detect_php_shape.ts`
+(`detectPhpShape`), whose `PROBE_PATHS` is this table and whose verdict names
+what a wrong route would have offered.

package/dist/agent-src/skills/test-case-discovery/SKILL.md

@@ -37,6 +37,91 @@ FLOOR PER BEHAVIOR: 1 HAPPY + 1 BOUNDARY + 1 ERROR (+1 ABUSE ON SECURITY PATHS).
 CAP PER BEHAVIOR: 5–8 CASES — EACH MUST FAIL FOR A DISTINCT REASON.
 ```
 
+## Does this change owe an executable behavior contract?
+
+Cases and contracts are not the same artifact. A **case** is something you assert
+in the project's unit runner. An **executable behavior contract** — a
+specification written in the language of whoever asked for the change, and run
+by a tool that reads it — is a heavier thing, and most changes do not owe one.
+Ask for one everywhere and it degrades into a second, slower unit suite; ask for
+one nowhere and behavior nobody can read stays unstated.
+
+### The observable-behavior test
+
+> **Does this change alter behavior someone outside the code can observe, and
+> would that person describe it in their own words?**
+
+Both halves have to hold: observable behavior with no outside audience is
+still only a case. *Observable* rules out anything a caller cannot see. *In their own
+words* rules out behavior that is real but has no audience outside the codebase —
+if the only person who can state the rule is the person reading the
+implementation, a case in the unit runner states it better and cheaper.
+
+**Yes → a contract is owed.** A refund is issued when an order is cancelled
+within 14 days; a member on a lapsed plan is denied the export; a rejected
+upload tells the uploader which rule it broke.
+
+**No → cases, not a contract.** At least these:
+
+- **A refactor with no behavior change.** Nothing outside the code can observe
+  it, by definition. If something can, it was not a refactor.
+- **An internal invariant with no external vocabulary.** Cache key derivation,
+  retry backoff, connection-pool sizing, a query plan. Real behavior, no
+  audience — the failure is stated as a case, not as a sentence somebody outside
+  the code would say.
+- **A pure boundary or error path with no business reading.** Rejecting a
+  malformed UTF-8 sequence is a case; *"we do not accept expired coupons"* is a
+  contract.
+- **A change whose only observer is another part of this system.** A consumer
+  written by the same team is a caller, not an audience. Contract tests between
+  services are a different tool and a different question.
+
+When the answer is yes, the ordering is unchanged: the contract fails before the
+implementation exists and passes after — see
+[`test-driven-development`](../test-driven-development/SKILL.md). A contract
+first seen green has the same unknown sensitivity as any other test never seen
+red.
+
+### The anti-script rule
+
+```
+A CONTRACT STEP NAMING A SELECTOR, A TIMEOUT, OR A KEYSTROKE IS A DEFECT
+IN THE CONTRACT — NOT AN IMPLEMENTATION DETAIL THAT HAPPENS TO BE THERE.
+WRITE WHAT IS TRUE, NEVER WHAT IS CLICKED.
+```
+
+A contract that scripts the interface is pinned to the interface: it goes red on
+every redesign that changes nothing anyone cares about, and stays green through
+the redesign that breaks the rule. It also stops being readable by the person
+whose words it was supposed to be in — which was the only reason to pay for it.
+
+**Wrong** — this is a click script wearing Given-When-Then:
+
+```gherkin
+Given I open "/cart?id=42"
+When I click #apply-coupon
+And I type "SUMMER" into input[name=code]
+And I wait 2 seconds
+Then .cart-total should contain "€45.00"
+```
+
+Every line is about the page. Change the button id and it fails; move the
+discount rule and it passes.
+
+**Right** — same behavior, stated as the rule it is:
+
+```gherkin
+Given a cart of €50
+When the customer applies a valid 10% coupon
+Then the order total is €45
+```
+
+The rule survives the redesign, and the person who asked for it can read it.
+
+**The test for a step:** could it still be true if the product were a CLI, an
+API, and a web page? If not, it belongs in the implementation the contract calls
+into, not in the contract.
+
 ## Procedure — the five-step funnel
 
 ### 1. Behavior inventory (30 seconds)

package/dist/agent-src/skills/test-driven-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: test-driven-development
-description: "Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'."
+description: "Implementing a feature, fixing a bug, refactoring — failing test first, then the code. For a WRONG test, `testing-anti-patterns` wins."
 domain: quality
 workspaces:
   - engineering
@@ -72,16 +72,28 @@ failed proves nothing about the code under test.
 ### Iron Law — delete-and-restart over keep-as-reference
 
 ```
-WHEN UNTESTED CODE EXISTS AND A TEST IS NEEDED — DELETE THE CODE,
+UNTESTED CODE THIS TASK JUST WROTE, AND A TEST IS NEEDED — DELETE THE CODE,
 WRITE THE TEST, REIMPLEMENT. NEVER KEEP IT "AS REFERENCE".
+THIS LAW COVERS YOUR OWN UNTESTED OUTPUT. IT IS NOT A LICENCE TO DELETE
+PRE-EXISTING CODE, AND NEVER OVERRIDES A REUSE VERDICT.
 ```
 
 Reading the existing implementation while writing its test is
-test-after-the-fact with extra steps. The 12-row anti-rationalization
-table that follows expands the most common ways this Iron Law gets
-talked-around. Externalized to
-[`testing-anti-patterns/process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md)
-to keep this skill under the 400-line sunset trigger.
+test-after-the-fact with extra steps. Which code that applies to has three
+answers, and only the first is a deletion:
+
+| The code is | Do |
+|---|---|
+| **untested, written by this task** | delete it, write the test, reimplement — the Iron Law above |
+| **pre-existing and tested** | keep it. Its tests are the record of its behaviour; deleting it to re-derive the same thing discards evidence and contradicts the reuse verdict |
+| **pre-existing and untested** | do NOT delete. Write a **characterization test** pinning the behaviour it has today — including the behaviour you think is wrong — then change it under that test |
+
+The middle row is the one this law used to get wrong: unqualified, it read as
+a standing instruction to delete tested legacy that a reuse verdict would
+keep. Case detail, the characterization-test procedure, and the 12-row
+anti-rationalization table are in
+[`testing-anti-patterns/process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md),
+which keeps this skill under the 400-line sunset trigger.
 
 ## Mode contracts — Goal / Activities / Forbidden / Output
 
@@ -91,10 +103,21 @@ checks it from the diff** — an unverifiable prohibition does not ship.
 | Mode | Goal | Activities | Forbidden (diff check) | Output contract |
 |---|---|---|---|---|
 | **Design** | One-sentence behavior + enumerated cases | Steps 1–2 | **No production code** (diff touches no `src/**` production path) · no test bodies yet | Case list (happy/boundary/error) |
-| **Test-Red** | A failing test that fails RIGHT | Steps 3–4 | **No production edits** (diff = `tests/**` only) · test must fail at an **assertion, not an import/setup error** (failure output cites the assertion line) | Failing test + its observed failure reason |
+| **Test-Red** | A failing test that fails RIGHT | Steps 3–4 | **No production edits** (diff = `tests/**` only) · the failure must be **about the behaviour under test**. Valid: a failing **assertion** · a **missing target** — class-not-found, or a compile/type error naming the unimplemented symbol · a **contract failure** (wrong shape, wrong status, unmet interface). Invalid: a broken **fixture** · a **syntax error** in the test · a missing **unrelated dependency** · a **runner or environment** fault | Failing test + its observed failure, named as one of the three valid classes |
 | **Implement** | Minimum code to green | Steps 5–6 | **No test edits** (no `tests/**` paths in Implement-phase diffs — changing the assertion to fit the code is the canonical violation; genuinely-wrong test → STOP and ask, never silently edit) · no scope beyond the one case | Green run output |
 | **Debug** | Fix a defect found later | (re-enter at 3) | **No bugfix before a reproducing regression test exists** (the fix commit contains a `tests/**` addition that fails without the fix) | Regression test + fix, verified red→green |
 
+#### What makes a RED valid — relevance, not the line number it fails on
+
+The discriminator is **whether the failure is about the behaviour under test**,
+never where in the run it surfaces. A class that does not exist yet can only
+fail at load, so demanding an assertion would force a production stub before
+the first test — the exact thing this skill forbids. The four invalid classes
+are failures of the harness: they would fail identically with the behaviour
+fully implemented, so they measure nothing about it. Unsure → re-read the
+failure output and name which of the seven it is; an unclassified red is not a
+RED.
+
 ### Mode inference on resume
 
 Step 0 of any resume: if `agents/runtime/state/HANDOFF.md` exists, resume
@@ -107,7 +130,8 @@ assume Design:
 | No test for the target behavior | Design |
 | Test exists, currently failing at an assertion | Implement |
 | Test exists + passing, defect reported | Debug |
-| Test failing at import/collection error | Test-Red (fix the test, not the code) |
+| Test failing at load because the target does not exist yet | Implement (that is a valid RED) |
+| Test failing on a harness fault — fixture, syntax, unrelated dependency, runner | Test-Red (fix the test, not the code) |
 
 At every mode transition, one consent-checkpoint sentence (per
 `ask-when-uncertain` / `autonomous-execution` — no new mechanism): name the

package/dist/agent-src/skills/testing-anti-patterns/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: testing-anti-patterns
-description: "Use BEFORE writing/changing tests, adding mocks, or test-only methods on production classes — vs mocking-the-mock, production pollution, partial mocks, and overfit/tautological assertions"
+description: "BEFORE writing/changing tests, mocks, or test-only methods on production classes — mocking-the-mock, production pollution, overfit assertions; for order, `test-driven-development` wins."
 domain: quality
 workspaces:
   - engineering

package/dist/agent-src/skills/testing-anti-patterns/process-anti-patterns.md

@@ -17,11 +17,48 @@ is still mocking the mock.
 ```
 WHEN YOU FIND YOURSELF KEEPING UNTESTED CODE "AS REFERENCE" WHILE WRITING
 A TEST FOR IT — DELETE THE CODE. WRITE THE TEST. THEN REIMPLEMENT.
+THE CODE IN QUESTION IS THE UNTESTED CODE THIS TASK JUST WROTE.
+IT IS NOT PRE-EXISTING CODE, AND THE LAW NEVER OVERRIDES A REUSE VERDICT.
 ```
 
 The cheap path is one extra round-trip. The expensive path is a test that
 silently encodes the bug it was supposed to catch.
 
+### The three cases — only one of them is a deletion
+
+Unqualified, this law reads as a standing instruction to delete any untested
+code in reach. That reading is wrong in two of the three cases, and the wrong
+one is expensive: it discards working behavior a reuse verdict would keep.
+
+| The code is | Do | Why |
+|---|---|---|
+| **untested, written by this task** | delete it, write the test, reimplement | Nothing is lost — you can rewrite what you wrote minutes ago, and the test is then written against the behavior you wanted rather than the code you happened to produce |
+| **pre-existing and tested** | keep it | Its tests ARE the record of its behavior. Deleting it to re-derive the same thing throws away evidence you cannot cheaply rebuild, and directly contradicts a reuse / extend verdict |
+| **pre-existing and untested** | write a characterization test first | Deleting it destroys the only remaining record of what it does. The test comes first, but it pins TODAY's behavior — not the behavior you wish it had |
+
+### The characterization-test procedure
+
+For the third case, in order:
+
+1. **Observe, do not judge.** Run the code on real inputs and record what it
+   actually returns — including outputs you believe are wrong. Bug-compatible
+   is the point: the test's job is to detect *change*, not to assert *correctness*.
+2. **Pin the observed values.** Assert them exactly. A characterization test
+   whose expected value is derived from the same code it tests is a tautology.
+3. **Name it as one.** Prefix or tag the test (`characterizes_…`, a
+   `@characterization` marker) so a later reader does not mistake a pinned bug
+   for a desired behavior.
+4. **Now change the behavior.** With the pin in place, the intended change is
+   an ordinary red-green cycle: the characterization test that must now change
+   is the blast radius, made visible.
+5. **Update or delete the pin deliberately.** When the new behavior is
+   correct, the pinned assertion is edited *because the behavior changed* —
+   stated in the diff, never quietly.
+
+**What this is NOT.** Not permission to skip TDD on new behavior — the pin
+covers what exists, the new behavior still starts from a failing test. Not a
+coverage exercise: pin the behavior the change will touch, not the whole file.
+
 ## 12-row anti-rationalization table
 
 The urge to skip TDD is strongest on tasks where TDD matters most. Name