@event4u/agent-config 14.11.0 → 14.13.0

package/dist/agent-src/skills/code-refactoring/SKILL.md

@@ -28,8 +28,51 @@ Do NOT use when:
 2. **Understand the scope** — what exactly needs to change and why?
 3. **Find ALL references** — use `codebase-retrieval` and `view` with `search_query_regex` to find every
    caller, implementation, test, and configuration that references the code being changed.
+   **If the change is to a closed set** — an enum, union, literal type, state
+   machine, role or permission set — identifier search is not enough: the
+   consumers that break are the ones that never name the type. Search by shape as
+   well (`switch` / `match` / if-chains over it, lookup tables keyed by it,
+   validators, serializers, schemas, fixtures, translation keys) and classify each
+   as exhaustive, deliberate fallback, or missing case. Procedure:
+   [`downstream-changes-mechanics`](../../../docs/guidelines/agent-infra/downstream-changes-mechanics.md).
 4. **Map the impact** — create a list of all files that will need changes.
-5. **Present the plan** — show the user what will be affected before starting.
+5. **Decide the verdict, if the refactor is a de-duplication** — see the
+   safe-abstraction gate below. An extraction with no recorded verdict is a
+   guess about whether two things are the same thing.
+6. **Present the plan** — show the user what will be affected before starting.
+
+### Safe-abstraction gate — before merging two things into one
+
+This skill performs extractions; it is therefore the place that decides
+whether one should happen. A wrong abstraction costs more than the
+duplication it replaced, because the duplication is visible and the wrong
+abstraction grows caller flags until nobody can remove it. Ask, before
+moving any code:
+
+1. Is this the same knowledge, or two facts that currently look alike?
+2. Would both copies change for the same reason?
+3. Is there one honest domain name that fits **every** call site?
+4. Can the common core stay free of caller-specific flags and modes?
+5. Are public contracts preserved, and do tests prove behavioural equivalence?
+6. **If the two copies diverged tomorrow, would that be a defect or
+   legitimate evolution?**
+
+A "legitimate evolution" answer to the last question is decisive: stop, and
+record the verdict `keep-duplicated`. That closes the refactor **successfully**
+— so does `de-abstract`, splitting a shared unit that has grown modes back
+apart. Neither is a failure to act, and neither needs an apology in the
+output. Textual similarity is not evidence of shared knowledge: copies that
+read identically can encode different assumptions, and merging them changes
+behaviour silently.
+
+The class names and the full verdict list are in
+[`redundancy-taxonomy`](../../../docs/guidelines/redundancy-taxonomy.md).
+
+When the refactor goes the other way and **creates** a new unit, the reuse
+question comes first: does an existing class or component already cover this, and
+what does composing or extending it cost against a new one? Thresholds per
+artifact class:
+[`component-oriented-and-oop-development`](../../../docs/guidelines/component-oriented-and-oop-development.md).
 
 ## Procedure: Refactor code
 
@@ -140,6 +183,7 @@ After the code changes are verified, update all affected documentation:
 1. Find all usages → update all usages → update docs → run the static analyser → run tests.
 
 ### Extract method / class
+0. Run the safe-abstraction gate above — a `keep-duplicated` verdict ends it here.
 1. Create the new method/class → move logic → update caller → update docs → run the static analyser → run tests.
 
 ### Move class to different namespace

package/dist/agent-src/skills/code-review/SKILL.md

@@ -37,11 +37,70 @@ Use this skill when:
 2. **Detect the change-type + depth** — route to the right checklist and pick the review depth (below).
 3. **Architecture** — does the approach make sense? Right layer? Right pattern?
 4. **Correctness** — does it actually work? Edge cases? Error handling?
-5. **Quality** — types, naming, readability, DRY, SOLID?
-6. **Security** — input validation, authorization, injection?
-7. **Performance** — N+1 queries, missing indexes, unbounded queries?
-8. **Tests** — are new paths covered? Are existing tests still valid?
-9. **Conventions** — does it follow project standards?
+5. **Quality** — types, naming, readability, SOLID?
+6. **Redundancy** — see below; a verdict, not a "this looks duplicated".
+7. **Propagation** — did a changed concept reach every occurrence? see below.
+8. **Security** — input validation, authorization, injection?
+9. **Performance** — N+1 queries, missing indexes, unbounded queries?
+10. **Tests** — are new paths covered? Are existing tests still valid?
+11. **Conventions** — does it follow project standards?
+
+## The redundancy dimension
+
+`DRY` as a checklist word produced findings nobody could act on: it names a
+principle, not a decision, and it has no answer for the case where two copies
+should stay. Replace it with a verdict.
+
+Classify the finding against
+[`redundancy-taxonomy`](../../../docs/guidelines/redundancy-taxonomy.md) —
+implementation, knowledge, or representation — and record one verdict from that
+document's list. `keep-duplicated` and `de-abstract` are successful outcomes; a
+finding with no recorded verdict stays open. Knowledge, policy, contract and
+delivery-authority duplication outrank clone percentage: two copies of a
+*decision* diverge into a bug, two copies of a loop usually do not.
+
+**Diff-aware, always.** The finding is duplication this change **introduces**,
+or duplication on a surface it touches. Pre-existing duplication is baseline —
+it is named once if the reviewer thinks it matters and it never fails an
+unrelated change. A review that reds a diff against debt it did not create is a
+review nobody will run twice.
+
+For comments, labels, tooltips, placeholders and empty states, run the
+Information Delta Test from the same document rather than judging text volume.
+A reduction that removes an accessibility name is a defect, not a cleanup.
+
+Naming is the same dimension pointed the other way: a diff that introduces a
+second term for a concept the tree already names is the finding, and an existing
+split is baseline. The classes and the `canonicalize-term` / `keep-distinct`
+verdicts are in the same document.
+
+## The propagation dimension
+
+A change is complete when the **concept** changed everywhere, not when the named
+file compiles. Two shapes to check, both of which the file-level review misses:
+
+**A closed set gained or lost a member** (enum, union, literal type, state
+machine, role or permission set, schema `enum`, DB check constraint). List the
+consumers and their status — every `switch` / `match` / if-chain over the type,
+every lookup table keyed by it, every validator, serializer, schema, fixture and
+translation key. A `default` branch that silently absorbs the new member is a
+missing case, not a handled one. Procedure:
+[`downstream-changes-mechanics`](../../../docs/guidelines/agent-infra/downstream-changes-mechanics.md).
+
+**A shared behaviour moved and its siblings did not.** A defect fixed in one
+place is presumed to recur until searched: name the exact wrong construct, grep
+the tree, and report the count — zero is a real answer and worth stating, because
+it distinguishes "this was unique" from "nobody looked".
+
+Diff-aware on the same terms as redundancy: the finding is a concept **this
+change** left half-migrated. Pre-existing incompleteness elsewhere is baseline.
+
+When the diff **creates** a class, component, service or hook rather than
+changing one, the question is whether it needed to exist: what was searched,
+what was found, and why composing or extending the incumbent was rejected. An
+answer, not a ceremony — and the thresholds for when repetition actually earns
+an abstraction are in
+[`component-oriented-and-oop-development`](../../../docs/guidelines/component-oriented-and-oop-development.md).
 
 ## Change-type routing — load only the checklist the diff needs
 
@@ -113,7 +172,7 @@ coverage reads as full coverage.
 the package implements it. That is now true for a recorded reason rather than by
 omission: the pre-registered question — does rotating reviewer order change the finding set
 on a frozen corpus, by more than 15 % — **cannot be answered from the corpus that exists**.
-`agents/evidence/reviews/` holds 123 findings artefacts, and none of them records the file
+`agents/evidence/reviews/` holds 123 findings artifacts, and none of them records the file
 order it was produced under, so the counterfactual is not recoverable; re-running reviewers
 produces fresh judgements in which ordering is confounded with run-to-run variance. Full
 null, with its reopening condition: `agents/evidence/review-rotation-prereg-and-null.md`.

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

@@ -305,6 +305,41 @@ Bad description (vague, no outcome):
 
 > "PR command"
 
+## The `## Examples` section on a user-facing command
+
+Stated once, here — never repeated per command.
+
+A command whose `visibility` is `visible` or `advanced` carries an
+`## Examples` section: **1-3 filled invocations** in a fence, then **exactly
+one Why line**. Filled means a real path, a real ticket key, a real flag — a
+placeholder teaches nothing about what to type.
+
+The Why line uses one of two literals, `**Why it works:**` or a
+`### Why it works` heading, and cites **exactly one** pattern id from
+[`prompt-patterns.yml`](../../config/discovery/prompt-patterns.yml):
+`outcome-not-steps` · `self-check-loop` · `measurable-target` ·
+`give-the-artifact` · `point-at-reference` · `say-the-format`. One id, because
+the Why line's job is the part that transfers to a command the reader has not
+seen, and a line naming three patterns names none of them.
+
+~~~
+## Examples
+
+```
+/work fix the failing login test under tests/feature/auth
+```
+
+**Why it works:** measurable-target — it names the file instead of the symptom.
+~~~
+
+Enforced by `check_command_examples`, forward-only: the 23 in-scope commands as
+of 2026-08-24 are grandfathered in a frozen set inside the gate, and a command
+**added or promoted into `visible`/`advanced`** after that must comply. Two
+things the gate checks that are easy to miss — an invocation must resolve to
+the command's own `name:` (a rename otherwise leaves stale examples behind), and
+a flag used in an example must be documented in the body **outside** the
+section.
+
 ## Encode usage policy in the description
 
 Workflow sequencing, preconditions, ID/output provenance ("copy ids verbatim,

package/dist/agent-src/skills/database/SKILL.md

@@ -113,6 +113,14 @@ SQLite; ORM-agnostic):
 
 ## Gotcha
 
+**MySQL and MariaDB share a query-syntax world. They never share a migration
+one.** Treat them as one engine for writing a `SELECT`, and as two engines for
+everything that changes a schema or reports on a plan: online-DDL semantics,
+lock behavior under `ALTER`, feature availability, and `EXPLAIN` output all
+diverge. Read the engine and its version from the project before making any
+claim in that second group; where the project does not declare one, say the
+engine is unknown rather than assuming.
+
 - Check existing indexes before adding — duplicates waste write performance.
 - Consider multi-tenant implications — queries may need customer DB scoping.
 - `EXPLAIN` output varies between MariaDB and MySQL.

package/dist/agent-src/skills/dependency-upgrade/SKILL.md

@@ -31,6 +31,33 @@ Before upgrading:
 - **Review upgrade guides** — many packages provide migration docs.
 - **Check runtime version requirements** — does the new version need a newer PHP / Node / Python / Go / Rust toolchain?
 
+### 1b. Find where the version is DECLARED, before naming a file to edit
+
+```
+NEVER NAME AN EDIT SITE BEFORE ASKING WHERE THE VERSION IS DECLARED.
+IN A CATALOG WORKSPACE THE MEMBER MANIFEST IS THE WRONG FILE:
+THE VERSION IS ONE ROOT LINE WITH N REFERENTS.
+```
+
+A member `package.json` is the declaration site in an ordinary repository and
+**not** in a workspace using a catalog. There, the member reads `catalog:` and
+the range lives once in the workspace definition — editing the member either
+does nothing or silently diverges from the catalog.
+
+Ask in this order, and stop at the first that answers:
+
+1. **A catalog entry for this dependency** — `pnpm-workspace.yaml` `catalogs:` /
+   `catalog:`, or the equivalent in another manager's workspace definition. If
+   the member's range starts with `catalog:`, this is the edit site. Name the
+   catalog (`default` included) in the guidance, not the member.
+2. **A root-level pin** — `overrides` / `resolutions` / `pnpm.overrides`. A
+   member edit under one of these is overridden at install time.
+3. **The member manifest** — the ordinary case, and only after 1 and 2 are
+   silent.
+
+A repository with no catalog and no root pin behaves exactly as before; this
+step adds a lookup, not a change of default.
+
 ### 2. Plan
 
 Categorize changes needed:

package/dist/agent-src/skills/design-review/SKILL.md

@@ -221,7 +221,7 @@ fields change what a finding *means*:
   all. Under `preserve` a palette or type-family delta is a **defect**; under
   `redesign` it is the point.
 - **`reference_maturity`** decides whether a difference from the reference is a
-  defect. A `wireframe` declares structure, so reproducing its grey boxes is
+  defect. A `wireframe` declares structure, so reproducing its gray boxes is
   over-fidelity, not fidelity.
 
 ```

package/dist/agent-src/skills/doc-coauthoring/SKILL.md

@@ -132,7 +132,7 @@ Verify the doc works for someone without your context.
 * **One question per turn** (Iron Law from `ask-when-uncertain`) — never bundle clarifying + brainstorm + curate prompts in one message.
 * **Never reprint the full doc** during iteration — always use `str-replace-editor`. Reprinting wastes tokens and creates merge drift.
 * **Reader test is not optional** — without it, you ship the version that makes sense to you, not to readers. Skip only on explicit user override.
-* **Sub-agent absence** — `ai-council` may not be configured. Have the manual fresh-Claude fallback ready (Stage 3 step 2).
+* **Subagent absence** — `ai-council` may not be configured. Have the manual fresh-Claude fallback ready (Stage 3 step 2).
 * **Image alt-text** — if the doc embeds images, add alt-text inline; without it, fresh-reader tools can't see them.
 * **Language discipline** — keep the doc body in English (per `language-and-tone`). For verbatim German user phrases or interview quotes, use `DE: … · EN: …` anchor blocks.
 

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -79,7 +79,23 @@ Design starts from project truth, not generic aesthetic memory.
 | `vue` | `resources/js/components/`, `src/components/`, `pages/` |
 | `plain` | `resources/views/`, plus any `*.html` under `public/` |
 
-Capture each component/template as: `{path, name, kind: page|partial|component|layout, exports?: [props]}`.
+Capture each component/template as:
+`{path, name, kind: component|view|style|page, exports?: [props]}`.
+
+The `kind` set is the one `agent-config ui:audit` actually emits — its single
+definition is `AUDIT_KINDS` in `src/cli/commands/uiAudit.ts`, and a test asserts
+this line against that constant rather than restating it. It read
+`page|partial|component|layout` until 2026-08-26; only two of those four values
+existed in the code, so an artefact written by the command was being read here
+against a contract it did not satisfy.
+
+`partial` and `layout` are not in the set. Neither has an operational definition
+that survives contact with a real tree, and adding a branch for a category
+nobody can test is how the previous mismatch happened.
+
+`view` is the **Blade** classification — `*.blade.php` and `resources/views/`.
+It reads zero in a JavaScript tree by construction, which is not the same as
+unused.
 
 ### 2. Identify the design system
 
@@ -100,7 +116,8 @@ Write into `state.ui_audit.design_tokens` (object, never null — empty object i
 
 | Source | What to extract |
 |---|---|
-| `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |
+| **`tailwind-v3`** (`axes.css`) — `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |
+| **`tailwind-v4`** (`axes.css`) — the `@theme` block in the entry CSS; **no config file exists**, and `components.json` `"tailwind": {"config": ""}` is the marker | every `--token: value` declared inside `@theme` / `@theme inline` |
 | `:root { --... }` blocks in `resources/css/`, `app/globals.css`, `src/app/globals.css` | every `--token-name: value` pair |
 | `theme.json` / `tokens.json` (any depth) | flat or nested token tree |
 | `app/css/variables.css`, `assets/scss/_tokens.scss` | SCSS `$var: value` and CSS custom properties |
@@ -109,6 +126,12 @@ Write into `state.ui_audit.design_tokens` (object, never null — empty object i
 
 Group output by category: `colors`, `spacing`, `radius`, `font`, `shadow`, `breakpoint`, `other`.
 
+**Branch on the axis, do not probe for a config file.** `detect_stack()` emits
+`axes.css` as `tailwind-v3` or `tailwind-v4`
+(`work_engine/stack/detect.ts:521-524`); reading it is how this step and
+`react-shadcn-ui` § Gotcha stay on the same key. Absence of
+`tailwind.config.*` is v4's normal state, never a missing file.
+
 **Artifact-sourced tokens stay distinguishable from project tokens.** Every
 group carries a `source` — `project` for the first four rows, `artifact` for the
 last two — because the mapping between them is the thing a port has to keep

package/dist/agent-src/skills/feature-planning/SKILL.md

@@ -121,6 +121,12 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 - Follow chosen architecture from Phase 4.
 - Follow codebase conventions strictly.
 - Track progress via task list or roadmap.
+- **One behavior at a time**: the failing test for that behavior, observed
+  failing, then the minimum code that makes it pass, then the next behavior.
+  Tests are a step of this phase, never a follow-up suggested in Phase 7 —
+  a plan that reaches the summary owing its tests planned test-after.
+  Exceptions are the Do-NOT list in the `test-driven-development` skill,
+  and a skipped cycle is recorded in the decision log rather than passed over.
 
 #### Phase 6: Quality Review
 - Review the implementation for:
@@ -132,7 +138,8 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 
 #### Phase 7: Summary
 - Summarize what was built, key decisions, files modified.
-- Suggest next steps (tests, documentation, follow-up features).
+- Suggest next steps (documentation, follow-up features) — never tests, which
+  Phase 5 already closed per behavior.
 - Update roadmap if applicable.
 
 ## Decision log
@@ -147,7 +154,7 @@ This ensures future developers (and agents) understand the reasoning, not just t
 
 ## Bite-sized task granularity (structural roadmaps only)
 
-When a feature plan's generated roadmap declares `complexity: structural` in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks ("Add login endpoint", "Update tests") are correct when the work is well-scoped and low-risk.
+When a feature plan's generated roadmap declares `complexity: structural` in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks are correct when the work is well-scoped and low-risk — but coarse means *one behavior*, not one layer: ("Reject login with an unknown email — test, then handler", "Reject login with a wrong password — test, then handler"), never an implementation step followed by an "Update tests" step.
 
 Structural roadmap tasks must include:
 

package/dist/agent-src/skills/frontend-render-security/SKILL.md

@@ -52,6 +52,48 @@ NO SECRET, PRIVILEGED KEY, OR SESSION TOKEN LIVES IN CLIENT CODE OR localStorage
 | `target="_blank"` without `rel="noopener"` | Reverse tabnabbing (CWE-1022) | add `rel="noopener noreferrer"` |
 | Missing CSP; missing alt/label/contrast | No XSS second line of defense; a11y failures | strict CSP (no `unsafe-inline`); alt text, labels, AA contrast |
 
+## The server-composed bootstrap payload
+
+A payload assembled **server-side and serialised into the page** for a client
+island is a data-exposure surface: whatever is put in it is readable by anyone
+who can load the page — no API call, no auth check, view-source. Several
+mainstream frameworks ship their own named channel for exactly this, so the
+pattern is a documented mechanism rather than one project's arrangement.
+
+**Inspect the existing payload before judging any field.** Read what the channel
+already carries and check current call sites for what the client actually
+consumes — a field is only defensible against what the page needs, and a review
+that never opened the payload is a guess. The grep below finds it.
+
+**The per-field question, which is what this section is:**
+
+> Would I return this field from a **public, unauthenticated** endpoint?
+> If not, it does not belong in the payload.
+
+Field classes that recur and are almost always wrong there: internal ids that
+enumerate other users' rows · permission and role structures the client only
+needs a boolean of · feature-flag payloads carrying unreleased product names ·
+anything from an admin-scoped query that was convenient to reuse · a whole
+serialised model where the page needs three of its fields.
+
+**Nothing enforces this, and the split is deliberate.**
+
+| Half | What it does | What it cannot do |
+|---|---|---|
+| the grep below | **locates** a payload a field was added to | tell a privileged field from a public one |
+| this checklist entry | carries the **judgement** | run |
+
+The question is not decidable by any check: a grep over the framework-named
+payload channels cannot read intent. So the deterministic half is discovery,
+advisory and non-blocking, and its whole value is putting the question in front
+of a reader who would otherwise never see it. `enforced_by: none` is the honest
+field here — this section refuses nothing.
+
+**What may NOT be encoded.** The particular channel any one repository uses.
+What is encoded is the question and the framework-named channels; a concrete
+in-house payload shape would be one repository's implementation shipped as
+guidance.
+
 ## Backstop greps
 
 Run before committing frontend changes; each should return zero (or every hit is read and justified):
@@ -66,6 +108,8 @@ rg -n "origin:\s*['\"]\*['\"]|Access-Control-Allow-Origin.*\*"
 rg -n "addEventListener\(\s*['\"]message['\"]"   # then confirm each checks event.origin
 # Unhardened external links
 rg -n 'target=["'\'']_blank["'\'']'   # then confirm rel="noopener" present
+# Server-composed bootstrap payload — LOCATES it; the per-field judgement is yours
+rg -n '__NEXT_DATA__|__NUXT__|window\.__INITIAL_STATE__|@json\(|json_encode\([^)]*\)\s*\)?\s*</script>|dehydratedState'
 ```
 
 ## Output format

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

@@ -9,7 +9,7 @@ scope:
 execution:
   type: assisted
   handler: internal
-  allowed_tools: ["github"]
+  allowed_tools: ["Bash(git:*)", "Bash(gh:*)"]
 workspaces:
   - engineering
 packs:

package/dist/agent-src/skills/js-library-packaging/scripts/check_package_surface.ts

@@ -143,20 +143,54 @@ export const checkPackage = (root: string): SurfaceReport => {
     };
     if (exportsField !== undefined) walkConditions(exportsField, 'exports.');
 
-    // (d) — a `workspace:` range only resolves inside the workspace. Published with no
+    // (d) — a range that only resolves INSIDE the workspace. Published with no
     // `private: true` and no publishConfig, the consumer's install fails on a protocol
     // their registry has never heard of.
-    const allDeps = { ...deps, ...asRecord(manifest['devDependencies']), ...peers };
-    const workspaceRanges = Object.entries(allDeps).filter(([, v]) => typeof v === 'string' && v.startsWith('workspace:'));
+    //
+    // `catalog:` was added 2026-08-26 (road-to-internal-estate-fit 4.1) and it is the
+    // same defect, not an adjacent one: pnpm's catalog protocol resolves against the
+    // workspace's catalog definition and means nothing to a registry. It had been
+    // passing as an ordinary registry range, so the finding did not fire where it
+    // should. One predicate, two prefixes — the finding code and its reason carry over
+    // unchanged, which is why this is not a second finding type.
+    const UNPUBLISHABLE_RANGE_PREFIXES = ['workspace:', 'catalog:'] as const;
+    // Each dependency map is scanned SEPARATELY rather than spread into one
+    // object. The previous `{ ...deps, ...devDeps, ...peers }` merge let a later
+    // map SHADOW an earlier one for the same package name: a `workspace:` range
+    // in `dependencies` for a package that also appears in `peerDependencies`
+    // with a registry range was invisible, because the peer value won the spread.
+    // Found 2026-08-26 by a `catalog:` fixture for a name the test manifest also
+    // lists as a peer; fixed with 4.1 rather than noted, because it is the same
+    // predicate and the same few lines.
+    const workspaceRanges: [string, unknown][] = [
+        deps,
+        asRecord(manifest['devDependencies']),
+        peers,
+    ].flatMap((m) =>
+        Object.entries(m).filter(
+            ([, v]) =>
+                typeof v === 'string' &&
+                UNPUBLISHABLE_RANGE_PREFIXES.some((pre) => v.startsWith(pre)),
+        ),
+    );
     if (
         workspaceRanges.length > 0 &&
         manifest['private'] !== true &&
         manifest['publishConfig'] === undefined
     ) {
+        const prefixes = [
+            ...new Set(
+                workspaceRanges.map(
+                    ([, v]) =>
+                        UNPUBLISHABLE_RANGE_PREFIXES.find((pre) => (v as string).startsWith(pre)) ??
+                        '',
+                ),
+            ),
+        ].sort();
         findings.push({
             code: 'workspace-range-publishable',
             severity: 'warn',
-            message: `${String(workspaceRanges.length)} \`workspace:\` range(s) in a package that is neither private nor carrying publishConfig — the protocol does not resolve outside the workspace`,
+            message: `${String(workspaceRanges.length)} workspace-local range(s) (${prefixes.join(', ')}) in a package that is neither private nor carrying publishConfig — the protocol does not resolve outside the workspace`,
         });
     }
 

package/dist/agent-src/skills/judge-artifact-completeness/rubrics/ticket-quality-score.json

@@ -18,8 +18,8 @@
       "name": "Acceptance criteria",
       "cross_cutting": false,
       "weight": 3,
-      "criterion": "Acceptance criteria are written as verifiable Given-When-Then or numbered checklist items, not as task descriptions. Each criterion is independently testable. An implementer can write a test before touching code.",
-      "gap_signal": "AC section missing; or AC items are task descriptions ('implement the API') rather than verifiable outcomes ('returns 200 with a body matching the schema')."
+      "criterion": "Acceptance criteria are independently testable outcomes, not task descriptions — an implementer can write a test before touching code. Whether they are owed in Given-When-Then form is decided by the observable-behavior test in `src/skills/test-case-discovery/SKILL.md` § Does this change owe an executable behavior contract?, not asserted here: most tickets owe verifiable checklist items, and only a change with an audience outside the code owes a behavior contract. Where one is owed, that section's anti-script rule applies — a criterion naming a selector, a timeout or a keystroke scores as a gap, however well-formed its Given-When-Then.",
+      "gap_signal": "AC section missing; or AC items are task descriptions ('implement the API') rather than verifiable outcomes ('returns 200 with a body matching the schema'); or a Given-When-Then criterion scripts the interface ('When I click #submit') instead of stating the rule."
     },
     {
       "id": "dor_readiness",

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

@@ -33,6 +33,41 @@ Use this skill for all Laravel-specific code generation and editing tasks, espec
 
 This skill extends the base `php-coder` skill and applies Laravel conventions on top of the project's general PHP rules.
 
+## 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.
+`illuminate/*` PACKAGES WITH NO SKELETON MARKER IS A THIRD STATE, AND THIS SKILL
+DOES NOT APPLY TO IT.
+```
+
+Laravel 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 |
+|---|---|
+| `artisan` | the console entry point the skeleton writes |
+| `config/app.php` | the skeleton's bootstrap config |
+| `bootstrap/app.php` | the application bootstrap |
+
+`illuminate/*` 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.
+
 ## Procedure: Write Laravel code
 
 → **First apply the `php-coder` skill** — it handles project docs, module docs, patterns, and quality tools.

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.