@event4u/agent-config 14.11.0 → 14.13.0

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/project-analysis-core/SKILL.md

@@ -129,6 +129,29 @@ Check:
 6. Known uncertainties
 7. Recommended next specialist skill
 
+## Improvement mode — check for an existing artefact first
+
+Before a full analysis, ask whether this target has already been analysed:
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/scripts/select_analysis_mode.ts "<target>"
+```
+
+`full` → run steps 1-8 as written. `delta` → **read the named artefact first**,
+then analyse only what it does not cover: gaps, sections the tree has moved past,
+patterns that are new since it was written. The output format is unchanged; the
+reading is narrower.
+
+This changes **write economics only**. A concept page is a hypothesis cache,
+never truth — the delta path re-verifies every structural claim it carries
+forward against a live source, exactly as a full run would
+([`source-discovery-gate`](../../rules/source-discovery-gate.md) § v1↔v2
+isolation). A cheaper write is not a licence to trust a cached read, and
+"the page already says so" is not evidence.
+
+An empty page counts as absent: it carries no conclusions to delta against, so
+the router answers `full`.
+
 ## Knowledge capture (`convention_detected` events)
 
 An architecture map or stack finding that recurs (a naming convention,

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
@@ -54,7 +54,14 @@ block above:
 
 ## Compatibility
 
-- **Tested against:** `shadcn@2.1`, Tailwind CSS `3.x`, React `18+`.
+- **Tested against:** `shadcn@4`, Tailwind CSS `4.x`, React `19`, primitives from
+  `@base-ui/react@1`, `components.json` style `base-nova` — every major read out
+  of `tests/fixtures/stack/shadcn-current/package.json`, the verbatim output of
+  `npx shadcn@latest init -d --template vite` on 2026-08-24. No version on this
+  line may be stated from prose; move it only by re-running that scaffold and
+  re-committing the fixture.
+- Tailwind `3.x` and Radix primitives stay supported through the **v3 branch**
+  under § Gotcha — the CLI moved on, existing projects did not.
 - The audit step (`directives/ui/audit.ts`) reads the line above and
   compares it with `state.ui_audit.shadcn_inventory.version`; a major
   mismatch triggers a soft halt before this skill runs.
@@ -63,8 +70,8 @@ block above:
 
 Use when `state.stack.frontend == "react-shadcn"` and `directives/ui/apply.ts`,
 `review.ts`, or `polish.ts` dispatches to this skill, or when a React project
-clearly uses shadcn/ui (presence of `components.json`, `@radix-ui/*`
-dependencies, a `components/ui/` folder of generated primitives).
+clearly uses shadcn/ui (presence of `components.json`, a `@base-ui/react` or
+`@radix-ui/*` dependency, a `components/ui/` folder of generated primitives).
 
 Do NOT use when:
 - Project is Blade + Livewire + Flux (use `flux` / `livewire` / `blade-ui`).
@@ -82,13 +89,23 @@ Do NOT use when:
   writes `state.ui_audit.shadcn_inventory` with the detected version —
   when it diverges by a major, audit emits a soft halt before this
   skill runs.
-- shadcn/ui composes Radix primitives. Accessibility is built in via Radix
-  but only when you use the wrapper components correctly (`asChild`,
+- shadcn/ui composes a primitive vendor — `@base-ui/react` in a CLI-4 scaffold,
+  `@radix-ui/*` in older projects. Accessibility is built in either way, but
+  only when the wrapper components are used correctly (`asChild`,
   `<DialogTrigger>` instead of a bare `<button>`).
-- Tailwind tokens come from `tailwind.config.{js,ts}` (`theme.extend.colors`)
-  and CSS custom properties on `:root` and `.dark` (`--background`,
-  `--foreground`, `--primary`, `--ring`, …). Audit writes them into
-  `state.ui_audit.design_tokens`. Use those tokens; do not hardcode values.
+- **Tailwind tokens: branch on the `css` axis, never guess.** `detect_stack()`
+  emits `axes.css` as `tailwind-v4` or `tailwind-v3`
+  (`work_engine/stack/detect.ts:521-524`); `existing-ui-audit` reads tokens on
+  the same key.
+  - `tailwind-v4` — **no config file exists.** Tokens live in the `@theme` block
+    of the entry CSS named by `components.json` → `tailwind.css`, and that file's
+    `"tailwind": {"config": ""}` — an empty `config` string — IS the v4 marker.
+    Never write `tailwind.config.{js,ts}` in a v4 project.
+  - `tailwind-v3` — tokens come from `tailwind.config.{js,ts}`
+    (`theme.extend.colors`).
+  - Either branch — CSS custom properties on `:root` and `.dark`
+    (`--background`, `--foreground`, `--primary`, `--ring`, …). Audit writes them
+    into `state.ui_audit.design_tokens`. Use those tokens; never hardcode values.
 - Dark mode is class-based (`<html class="dark">`). Every color must come
   from `bg-background`, `text-foreground`, etc. — never raw `bg-white`.
 - Every interactive primitive must declare a focus-visible state via
@@ -243,12 +260,12 @@ this over a registry file.
    `bg-primary text-primary-foreground`, `text-muted-foreground`. No
    `bg-white` / `text-black` / hardcoded `#fff`.
 2. Spacing / radius from theme tokens (`rounded-lg` mapped to `--radius`
-   in `tailwind.config.{js,ts}`). Polish refactors hardcoded values
-   when a token equivalent exists.
+   — in the `@theme` block on `tailwind-v4`, in `tailwind.config.{js,ts}` on
+   `tailwind-v3`). Polish refactors hardcoded values when a token exists.
 3. Dark mode: never branch on a `dark` prop; rely on the `.dark` class
    on the root and semantic tokens.
 4. Every interactive primitive: keyboard trigger present (Enter/Space
-   on buttons, Esc on dialogs — Radix free), visible focus ring,
+   on buttons, Esc on dialogs — free from the primitive vendor), focus ring,
    `aria-label` from `state.ui_design.a11y` when icon-only.
 
 ### Step 3: State coverage

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

@@ -22,8 +22,9 @@ rule. Skip only on explicit *"just do it"* bypass or trivial edits
 ### 0b. Skill-growth gate (new skill only)
 
 The skill count keeps climbing; nothing forces *"should this be a new skill at
-all?"*. Before creating a **new** skill, answer these in the PR body — a new
-skill that cannot answer them is a merge / guideline / no-op in disguise:
+all?"*. Before creating a **new** skill, answer these **in the ledger**,
+`agents/decisions/skill-admissions.jsonl` — a new skill that cannot answer them
+is a merge / guideline / no-op in disguise:
 
 1. **Family** — which capability family does it join? (engineering, product, …)
 2. **Capability** — what does it do that no existing skill does? Name the gap.
@@ -31,6 +32,27 @@ skill that cannot answer them is a merge / guideline / no-op in disguise:
 4. **Why not a guideline** — is this executable workflow (skill) or reference material (guideline)? Guideline-shaped content does not become a skill.
 5. **Visibility tier** — `core` or `lab`? Which pack?
 
+**The answers go in the ledger, not in the PR body.** That used to say PR body,
+and `check_finding_dispositions.ts:11` rejects that exact surface for findings in
+its own words — a comment is *"mutable and unaudited; it is transport, not a
+record"*. The consequence was measurable: **+8 skills landed in one release with
+no visible "no"**, because a refusal kept in a PR body is a refusal nobody can
+grep. One line, appended:
+
+```json
+{"skill":"<name>","decision":"admitted","date":"YYYY-MM-DD","family":"…","capability":"…","why_not_extend":"…","why_not_a_guideline":"…","visibility":"…"}
+```
+
+`check_skill_admissions` is forward-only: it requires a row only for skills added
+since the base ref, so nothing existing needs backfilling. It rejects an answer
+under 12 characters, because a one-word answer is the boilerplate the gate exists
+to catch rather than an answer.
+
+**A refusal is a row too**, and that is the half the PR body lost:
+`{"skill":"…","decision":"rejected","date":"…","instead":"…"}`. A rejected row may
+not name a skill that exists — a record saying a capability was refused while it
+ships is worse than no record.
+
 **Surface overlap before deciding** — run `./scripts-run src/scripts/skill_overlap`
 (or `audit_skill_overlap`) and read the nearest matches; a high-overlap hit is a
 merge signal, not a green light. This gate is the authoring-time companion to the
@@ -236,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`):
@@ -244,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.
@@ -259,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/storybook-workshop/SKILL.md

@@ -131,6 +131,15 @@ that file, which is the one thing a static checker must not start doing.
 
 ## MCP path — opt-in channel, never a dependency
 
+**"Opt-in" is about the agent connecting, not about installing.** A 2026-08-24
+`npx storybook@latest init --yes` scaffold ships `@storybook/addon-mcp` *and*
+`@storybook/addon-a11y` in `devDependencies` by default — recorded verbatim in
+`tests/fixtures/stack/storybook-current/`, which is also the only source any
+Storybook major stated here may come from (`storybook@^10.5.10`). So the addon
+usually already exists; what stays optional is whether an agent reaches a
+running instance. The same scaffold prints *"installed but is not entirely set
+up yet"*, so its presence is not evidence the channel works.
+
 When the project has `@storybook/addon-mcp` **and** a running Storybook,
 [`existing-ui-audit`](../existing-ui-audit/SKILL.md) prefers the live tools —
 `list-all-documentation`, then `get-documentation` for the components that matter — over the

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