@event4u/agent-config 16.1.0 → 16.3.0

package/dist/agent-src/skills/existing-ui-audit/references/component-taxonomy-detection.md

@@ -0,0 +1,56 @@
+# existing-ui-audit — component-taxonomy detection
+
+> Section-level entry point of the `existing-ui-audit` skill (progressive
+> disclosure). Load this file when § 1b of SKILL.md routes here — it carries
+> the detection rules and the boundary the step must not cross.
+
+## What the detector answers
+
+The question is *"has this project already chosen a way to organize its
+components by granularity, and if so what does it call the tiers?"* — never
+*"which taxonomy should this project use?"*. The recorded value is the
+project's **own** tier directory names, in the project's own order, joined
+with `/`, or `none`. Nothing canonical is ever written: a project with three
+tiers records three, and a project whose tiers are called
+`primitives / patterns / features` records exactly that.
+
+## Three properties, each pinned by a test
+
+- **Declared outranks inferred.** A `## Component taxonomy` section in the
+  consumer project's own `DESIGN.md`, at its root or under `docs/`, listing
+  backticked directory names as list items wins, provided at least two of
+  those directories exist
+  under the component root. The name may be bolded — `- **\`atoms\`** — ...`
+  is read exactly like `` - `atoms` — ... ``. Grounding the declaration against
+  the tree keeps a stale doc from declaring a taxonomy the tree does not have,
+  and a backticked name in prose rather than in a list item is a mention, not a
+  declaration. This is how a project whose tiers appear in no vocabulary the
+  detector knows still gets conformance. The first doc that *qualifies* wins:
+  one with no section, or one naming fewer than two tiers that exist on disk,
+  falls through to the next.
+
+- **A folder that merely sounds like a tier is a collision, not a convention.**
+  `components/{checkout,billing,molecules}` records `none`, and so does the
+  ordinary kind split `components/{layout,pages,forms}` — `layout`, `page`,
+  `block`, `element`, `part` and `cell` are all everyday folder names as well
+  as granularity words. Inference needs at least two tier-shaped buckets **and**
+  more than two thirds of the weighed ones; support folders (`hooks`, `utils`,
+  `types`, `lib`, `styles`, …) are left out of the denominator, so three
+  ordinary siblings cannot hide a taxonomy that is really there. Each floor has
+  its own fixture, because at one hit in three buckets either floor alone would
+  still refuse and neither would be tested.
+
+- **`none` is a real answer, not a failure.** A flat tree, an unreadable tree,
+  a missing component folder, a permission error: all record `none`, and every
+  downstream step then behaves exactly as it did before this detection
+  existed. Detection never throws — degrading to `none` is the safe direction,
+  because `none` is precisely the value that leaves the project's own
+  structures untouched.
+
+## The boundary
+
+Never write a taxonomy the project does not evidence, and never "tidy" an
+existing layout into one. Holding to the project's own structures is the
+standing rule; this step exists to *find* that structure, not to supply one.
+The single place a taxonomy is ever *offered* is the greenfield halt in § 7,
+and a decline there is terminal.

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

@@ -29,7 +29,7 @@ machinery that already exists: `search_stack` in
 [`corpus-grounding`](../corpus-grounding/SKILL.md)
 (`scripts/decision_engine.ts`), whose stack corpus carries `threejs.csv` among
 its stacks, read beside the register in
-[`design-intelligence`](../design-intelligence/references/context-and-registers.md)
+`design-intelligence`
 § Register. No second frontend executor is declared, and none is needed: a
 renderer changes what you ground against, never who writes the UI.
 

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

@@ -42,7 +42,7 @@ execution:
    is the anti-pattern [`icon-consistency`](../../rules/icon-consistency.md)
    § What this gates names by name. Stop at the first rung that answers.
    1. **A brand token or brand guide that names an icon set** — authoritative,
-      stop here ([`brand-source-of-truth`](../../rules/brand-source-of-truth.md)).
+      stop here (`brand-source-of-truth`).
    2. **The set already in use in this project** — detected at the Inspect step
       of the Iconography floor below. One icon system per project; a second
       visual language is the defect, not a preference.

package/dist/agent-src/skills/js-library-packaging/SKILL.md

@@ -17,7 +17,7 @@ packs:
 > A React or TypeScript consumer receives this skill through `engineering-base`, which both
 > of those packs require.
 
-The JavaScript twin of [`composer-packages`](../composer-packages/SKILL.md). A component is
+The JavaScript twin of `composer-packages`. A component is
 a file; a **library** is a package with a public surface, and that surface is declared in
 `package.json` rather than inferred. Most of the failures below are silent at author time
 and loud at the consumer's — which is why the surface is read, not assumed.
@@ -167,7 +167,7 @@ declared cost — never here.
 
 ## See also
 
-- [`composer-packages`](../composer-packages/SKILL.md) — the PHP twin; same surface discipline, different manifest.
+- `composer-packages` — the PHP twin; same surface discipline, different manifest.
 - [`standards-from-config`](../standards-from-config/SKILL.md) — the Class-A rule the § Release branch follows.
 - [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md) — the `!` marker a release tool reads.
 - [`ui-component-architect`](../ui-component-architect/SKILL.md) — the component inside the library; this skill is the package around it.

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

@@ -1,6 +1,10 @@
 ---
 model_tier: medium
 name: markitdown
+inputs:
+  - name: source
+    type: string
+    description: "URI of the document to convert — file:, https: or data: (http: is refused). Absent means the skill is being read for its scheme discipline rather than invoked."
 description: "Convert PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown via the markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'."
 status: active
 tier: senior

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

@@ -104,7 +104,7 @@ for `workspace:`-linked packages.
 
 State plainly that the listing came from manifests rather than the runner — an
 inferred target list can miss runner-inferred targets. This is the posture
-[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) already takes for the shadcn
+`react-shadcn-ui` already takes for the shadcn
 CLI; the stop condition is `missing-tool-handling` (never install it silently,
 never fake the output).
 

package/dist/agent-src/skills/playwright-testing/SKILL.md

@@ -144,22 +144,46 @@ test('homepage visual regression', async ({ page }) => {
 
 ## Viewport testing
 
+A viewport loop whose only assertion is an image proves that the page rendered,
+not that the breakpoint did anything: the same picture comes back whether the
+media query fired or silently did not. Assert the layout property the breakpoint
+is supposed to change, then keep the capture and name it for the one thing it
+proves.
+
 ```ts
 test.describe('Responsive design', () => {
   for (const viewport of [
-    { width: 1440, height: 900, name: 'desktop' },
-    { width: 768, height: 1024, name: 'tablet' },
-    { width: 375, height: 812, name: 'mobile' },
+    { width: 1440, height: 900, name: 'desktop', columns: '1fr 1fr 1fr' },
+    { width: 768, height: 1024, name: 'tablet', columns: '1fr 1fr' },
+    { width: 375, height: 812, name: 'mobile', columns: '1fr' },
   ]) {
-    test(`renders correctly on ${viewport.name}`, async ({ page }) => {
-      await page.setViewportSize(viewport)
+    test(`lays out correctly on ${viewport.name}`, async ({ page }) => {
+      await page.setViewportSize({ width: viewport.width, height: viewport.height })
       await page.goto('/')
-      await expect(page).toHaveScreenshot(`home-${viewport.name}.png`)
+      // Behaviour: the declared breakpoint actually changed the layout.
+      await expect(page.locator('#grid')).toHaveCSS('grid-template-columns', viewport.columns)
+      // Appearance only: presence + sanity that nothing renders broken.
+      await expect(page).toHaveScreenshot(`appearance-${viewport.name}.png`)
     })
   }
 })
 ```
 
+**Read the probe artifact rather than re-deriving the matrix by hand.**
+`agents/runtime/state/ui-conformance.json` — produced by
+`ui_conformance_probe --target <file> --reference <file>` — carries a
+`viewport_matrix` row per declared width, plus a not-applicable row with its
+reason wherever the host could not cross the breakpoint. A width with no row is
+missing evidence, not a pass, and no dimension reads zero findings because it did
+not run.
+
+**The capture above is appearance-only, and it stays mandatory.** It proves
+presence and sanity — the surface rendered and nothing renders obviously broken —
+and proves nothing about hover, focus, keyboard or a media-preference branch.
+Demoting it from behavioral evidence does not narrow when it runs: it still runs
+at every width in the matrix. Floor and division of labour:
+[`design-review`](../design-review/SKILL.md) § Appearance verification.
+
 ## Debugging
 
 ```bash

package/dist/agent-src/skills/quality-tools/SKILL.md

@@ -27,6 +27,8 @@ Use this skill whenever running or configuring code quality tools:
 
 - **PHP**: PHPStan (static analysis), Rector (automated refactoring), ECS (coding standards)
 - **JS/TS**: Biome (linting + formatting), TypeScript compiler (type checking), Jest/Vitest (tests)
+- **Python**: Ruff (linting + formatting), mypy (type checking), pytest (tests)
+- **Go**: `gofmt`, `go vet`, optionally golangci-lint, `go test`
 
 ## Modes
 
@@ -39,8 +41,16 @@ stack calls for.
 |---|---|---|
 | PHP (`.php` changed) | [`references/php-tools.md`](references/php-tools.md) | Tool detection, PHPStan / ECS / Rector commands and flags, combined pipeline, config files, baseline policy, PHPStan error handling, testing framework, git-aware execution |
 | JS/TS (`.js` / `.ts` / `.tsx` changed) | [`references/js-ts-tools.md`](references/js-ts-tools.md) | Detection, Biome, TypeScript type checking, Jest / Vitest, the JS/TS workflow sequence |
+| Python (`.py` changed, or `pyproject.toml`) | [`references/python-tools.md`](references/python-tools.md) | Detection from `pyproject.toml`, Ruff, mypy, pytest, the workflow sequence, virtualenv and `setup.cfg` gotchas |
+| Go (`.go` changed, or `go.mod`) | [`references/go-tools.md`](references/go-tools.md) | `gofmt`, `go vet`, golangci-lint where present, `go test`, the workflow sequence, vendor and build-tag gotchas |
 
-Both stacks changed → load both mode bodies and run both pipelines.
+More than one stack changed → load each mode body and run each pipeline.
+
+**The resolver decides which row applies, not the file extension alone.**
+`resolve_toolchain` returns the ecosystems it found and the quality commands
+per ecosystem; the rows above name what those commands are. A TypeScript
+repository resolves the ecosystem `js`, never `typescript` — the pack name and
+the ecosystem label are different vocabularies.
 
 ## Execution policy — on demand only, never proactive
 

package/dist/agent-src/skills/quality-tools/references/go-tools.md

@@ -0,0 +1,76 @@
+# quality-tools — Go quality tools
+
+> Mode body of the [`quality-tools`](../SKILL.md) skill. Load this file when
+> the mode table in SKILL.md routes here. The cross-mode material — execution
+> policy, environment, output discipline — stays in SKILL.md and is NOT
+> repeated here.
+
+# Go Quality Tools
+
+## Detection
+
+`resolve_toolchain` (`work_engine/stack/runner.ts`) keys the Go ecosystem on
+`go.mod` and resolves exactly one quality command, `go vet ./...`, plus the
+test command `go test ./...`. It does **not** detect `golangci-lint`, so a
+repository that uses one will show a `quality` list shorter than what its CI
+runs. Read the repository's CI workflow before concluding the resolver's list
+is the whole gate.
+
+| Signal | Tool | What it does |
+|---|---|---|
+| `go.mod` present | **`go vet`** | The toolchain's own correctness checks — printf verbs, struct tags, unreachable code, lost cancel |
+| `go.mod` present | **`gofmt`** | Canonical formatting; not resolved as a command because it is not optional in Go |
+| `.golangci.yml` / `.golangci.yaml` | **golangci-lint** | Meta-linter; the resolver does not detect it |
+
+## The toolchain's own commands
+
+```bash
+gofmt -l .                # list files whose formatting differs — empty is the pass
+gofmt -w .                # rewrite them
+go vet ./...              # the resolver's quality command
+go build ./...            # compiles; the cheapest proof the tree is coherent
+go test ./...             # the resolver's test command
+go test -run '<regexp>' ./pkg/...   # the targeted probe
+go test -race ./...       # the race detector — slow, and the only thing that finds a data race
+```
+
+**`gofmt -l .` with empty output is the pass.** It exits 0 whether or not it
+listed files, so a pipeline that checks only the exit code never fails on
+formatting. Check the output, not the status.
+
+## golangci-lint, where a project has it
+
+```bash
+golangci-lint run         # the whole configured set
+golangci-lint run ./pkg/...   # scoped to a package
+```
+
+It wraps `go vet` among others, so a project with `.golangci.yml` does not
+need `go vet` run separately — and running both doubles the report rather than
+widening it.
+
+## Workflow sequence
+
+1. `gofmt -l .` — read the output, not the exit code.
+2. `go build ./...` — a compile error makes every later step meaningless.
+3. `go vet ./...`, or `golangci-lint run` where the project has it.
+4. `go test -run '<the thing you changed>' ./pkg/...` — targeted.
+5. `go test ./...`, once, at the end; `-race` where concurrency changed.
+
+## Gotchas
+
+- **`./...` from the wrong directory.** The pattern is relative to the working
+  directory, not to the module root. Run it from the directory holding
+  `go.mod`, or name the module path.
+- **A vendored tree.** With `vendor/` present the toolchain defaults to
+  `-mod=vendor`; a dependency added to `go.mod` but not vendored fails to build
+  with an error that names the package, not the mode. `go mod vendor` after any
+  dependency change.
+- **Build tags hide packages.** `go vet ./...` and `go test ./...` skip files
+  excluded by build constraints, so a green run says nothing about a
+  `//go:build integration` file. Name the tag (`-tags integration`) to reach it.
+- **No `go` pack exists in this suite yet.** Go artifacts route through
+  `engineering-base` and this reference; `src/packs/go/pack.yaml` <!-- ref-ignore --> is created by
+  `road-to-stacks-beyond-php` step 2.3, which is blocked on the programme's
+  skill-growth question. Until then this file is the whole of the Go quality
+  surface, by design rather than by omission.

package/dist/agent-src/skills/quality-tools/references/python-tools.md

@@ -0,0 +1,104 @@
+# quality-tools — Python quality tools
+
+> Mode body of the [`quality-tools`](../SKILL.md) skill. Load this file when
+> the mode table in SKILL.md routes here. The cross-mode material — execution
+> policy, environment, output discipline — stays in SKILL.md and is NOT
+> repeated here.
+
+# Python Quality Tools
+
+## Detection
+
+The resolver is the authority, not this table. `resolve_toolchain`
+(`work_engine/stack/runner.ts`) reads `pyproject.toml` and returns the quality
+commands it found; run those. The table says what each one is, so a reader can
+tell a missing tool from an unknown one.
+
+| Indicator in `pyproject.toml` | Tool | What it does |
+|---|---|---|
+| `[tool.ruff]` | **Ruff** | Linting and formatting in one binary; replaces flake8, isort, pyupgrade and (with `ruff format`) black |
+| `[tool.mypy]` | **mypy** | Static type checking |
+| `[tool.pytest.ini_options]` | **pytest** | Test runner — the resolver binds it as the test command, not as a quality command |
+
+A repository with none of the three resolves an empty `quality` list. That
+means **none was resolved**, never that none is needed — the same distinction
+SKILL.md draws for ruby, jvm and dotnet.
+
+## Ruff — linting and formatting
+
+```bash
+ruff check .              # lint, read-only
+ruff check --fix .        # lint and apply the safe fixes
+ruff format .             # format
+ruff format --check .     # format check, read-only — what CI runs
+```
+
+Config lives in `[tool.ruff]` in `pyproject.toml` (or `ruff.toml`). The two
+settings that change what the other commands mean:
+
+- `line-length` — the formatter's wrap column; `ruff check` reports `E501`
+  against the same number.
+- `[tool.ruff.lint] select` / `ignore` — the rule set. An empty `select` is
+  Ruff's default set, not "no rules".
+
+**`--fix` is not a formatter.** `ruff check --fix` rewrites code to satisfy
+lint rules; `ruff format` rewrites layout. A pipeline that runs only the first
+leaves formatting drift that CI's `ruff format --check` then fails on.
+
+## mypy — type checking
+
+```bash
+mypy .                    # check the package
+mypy --strict .           # every optional strictness flag on
+```
+
+Config lives in `[tool.mypy]`. `strict = true` there is the same as `--strict`
+on the command line, so passing the flag to a project that already sets it
+changes nothing — and passing it to one that does not is a different check
+from the one CI runs. Read the config before adding flags.
+
+An error mypy reports on a file the current change did not touch is
+pre-existing debt. Treat it the way SKILL.md's baseline policy treats a
+PHPStan baseline entry: it is not this change's to clear silently.
+
+## pytest — the test runner
+
+Not a quality tool, listed here because the resolver finds it in the same
+file and a reader looking for "the Python commands" expects it.
+
+```bash
+pytest                    # the resolver's bound command
+pytest -q                 # quiet, what `addopts = "-q"` already sets
+pytest -k '<expr>'        # filter by name — the targeted probe
+pytest path/to/test.py    # filter by file
+```
+
+Run the filtered form when verifying one fix. The whole suite is the final
+gate, never the per-iteration probe.
+
+## Workflow sequence
+
+1. `ruff format --check .` — fails fast and costs nothing.
+2. `ruff check .` — lint.
+3. `mypy .` — types.
+4. `pytest -k '<the thing you changed>'` — targeted.
+5. The full suite, once, at the end.
+
+Each step is cheaper and narrower than the next, so running them out of order
+spends the expensive verdict on a failure the cheap one would have named.
+
+## Gotchas
+
+- **A virtualenv the agent did not activate.** `ruff` and `mypy` installed in
+  a project venv are not on `PATH` outside it. `python -m ruff` / `python -m
+  mypy` run the installed copy; a bare `ruff` may run a different version or
+  none.
+- **`requirements.txt` only.** The resolver still binds pytest (at MEDIUM
+  confidence) but finds no quality commands, because it reads them from
+  `pyproject.toml`. An empty `quality` list on such a repository is correct
+  output, not a detection bug.
+- **`setup.cfg` and `tox.ini` carry config too.** Older projects keep flake8
+  and mypy settings there. The resolver does not read them; if a project has
+  no `[tool.*]` block and a populated `setup.cfg`, the tools are configured and
+  the resolver's empty list is a gap in the resolver, worth reporting rather
+  than working around.

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

@@ -31,7 +31,7 @@ Do NOT use when:
 - The diff is low-risk and no ownership map exists — fall back to the
   common role vocabulary below.
 - A full PR description is requested — route to
-  [`/pr:create:description-only`](../../domains/git/pr/create/description-only/command.md) and let
+  `/pr:create:description-only` and let
   it call this skill for the routing block.
 - A threat model is wanted — route to
   [`threat-modeling`](../threat-modeling/SKILL.md).
@@ -210,6 +210,6 @@ Data source: <"ownership-map.yml + historical-bug-patterns.yml"
 
 - [`reviewer-awareness`](../../rules/reviewer-awareness.md) — the rule that routes here: anchor reviewer choice in paths and risk, never seniority
 - [`review-routing-data-format`](../../guidelines/agent-infra/review-routing-data-format.md)
-- [`/pr:create:description-only`](../../domains/git/pr/create/description-only/command.md)
+- `/pr:create:description-only`
 - [`judge-test-coverage`](../judge-test-coverage/SKILL.md) — consumes
   the `required_test` entries from matched patterns.

package/dist/agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -213,7 +213,7 @@ is the wrong question asked well.
 **The escalation threshold applies here too.** A third recurrence of the same
 violation class converts an observation into a deterministic gate — and a review
 finding never silently becomes a hard gate. Both halves, specified in
-[`decision-review` § Removal is a disposition](../decision-review/SKILL.md).
+`decision-review` § Removal is a disposition.
 
 ## Output format
 

package/dist/agent-src/skills/storybook-workshop/SKILL.md

@@ -16,7 +16,7 @@ agent reads to learn what the component accepts, and the harness that catches a
 focus defect while the component is still in isolation. Stack-agnostic — the tool is
 Storybook, the discipline is not.
 
-Lifted out of [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Component workshop, which
+Lifted out of `react-shadcn-ui` § Component workshop, which
 keeps a pointer here rather than a copy.
 
 ## The Iron Law
@@ -135,7 +135,7 @@ Run the project's story test command (the Vitest addon's `storybook test`, or wh
 `package.json` declares — read it, do not assume a name), then read the a11y result.
 
 Write findings into `state.ui_review.a11y` in the shape
-[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Review pass already defines:
+`react-shadcn-ui` § Review pass already defines:
 
 ```
 {violations: [{rule, selector, severity}, …], severity_floor?, accepted_violations?}
@@ -235,7 +235,7 @@ copied verbatim:
 
 ## See also
 
-- [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — the React stack lane, and the `(rule, selector, severity)` shape § Validate writes into.
+- `react-shadcn-ui` — the React stack lane, and the `(rule, selector, severity)` shape § Validate writes into.
 - [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — the inventory the MCP path accelerates.
 - [`js-library-packaging`](../js-library-packaging/SKILL.md) — the package around the workshop.
 - [`accessibility-auditor`](../accessibility-auditor/SKILL.md) — the WCAG depth behind the a11y half.

package/dist/agent-src/skills/tailwind-engineer/SKILL.md

@@ -87,7 +87,7 @@ Structure, controls, grid and breakpoints are never this skill's to adjust;
 those stay 1:1 with the artifact and belong to the rule, not to a
 utility-class decision. **Icons are out of scope here as well, and this skill
 asserts no obligation about them** — the icon system belongs to
-[`icon-consistency`](../../rules/icon-consistency.md). An earlier revision of
+`icon-consistency`. An earlier revision of
 this paragraph claimed icons "stay 1:1 with the artifact" with no citation of
 any kind, while putting them outside its own scope in the same sentence; the
 claim is withdrawn rather than defended, because a clause that reached the tree

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

@@ -39,6 +39,13 @@ CAP PER BEHAVIOR: 5–8 CASES — EACH MUST FAIL FOR A DISTINCT REASON.
 
 ## Does this change owe an executable behavior contract?
 
+This section is the decision *Gherkin*, *BDD*, *Cucumber*, *Behat* and
+*given-when-then* are meant to reach — each pinned as a should-trigger case in
+`evals/triggers.json`, with German exemplars for *Cucumber* and *Behat*. That
+corpus specifies
+the intent; it does not route, and this skill's `description` carries none of
+the terms. A decision, not a guide to writing one.
+
 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

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

@@ -313,6 +313,23 @@ export async function retry<T>(op: () => Promise<T>): Promise<T> {
 Run again → passes. Configurable attempt count, backoff, and jitter all
 wait for their own failing tests.
 
+## The filtered probe, per ecosystem
+
+The discipline above is stack-independent; the **command** is not, and every
+runner invocation elsewhere in this file is a PHP one. Resolve the runner with
+`resolve_toolchain` (`work_engine/stack/runner.ts`) and read its `ecosystems`,
+then filter with that ecosystem's own form — never the whole suite:
+
+| `ecosystems` | Filtered probe |
+|---|---|
+| `php` | `vendor/bin/pest --filter '<name>'` · `php artisan test --filter '<name>'` |
+| `js` | `npx vitest run -t '<name>'` · `npx jest -t '<name>'` |
+| `python` | `pytest -k '<expr>'` · `pytest path/to/test.py::test_name` |
+| `go` | `go test -run '<regexp>' ./pkg/...` |
+
+A TypeScript repository resolves the ecosystem `js`, never `typescript`. The
+whole suite is the final gate and never the per-iteration probe, in every row.
+
 ## Gotchas
 
 * Running the full suite instead of a filtered test hides the RED→GREEN

package/dist/agent-src/skills/test-performance/SKILL.md

@@ -174,4 +174,22 @@ Replace dynamic `getPdo()` probing with explicit config:
 - Do NOT use RefreshDatabase when DatabaseTransactions works — 10x slower.
 - Do NOT run full test suite on every code change — use `--filter`.
 - Do NOT add test-only indexes — fix test design instead.
-- Do NOT disable parallel testing to "fix" flaky tests — fix the root cause.
+- Do NOT disable parallel testing to "fix" flaky tests — fix the root cause.
+
+## Where the time goes, per ecosystem
+
+The diagnosis above is PHPUnit-shaped. The method — measure before optimising,
+find the slowest tests first, separate setup cost from assertion cost —
+transfers; the instrument does not. Resolve the runner with
+`resolve_toolchain` and read its `ecosystems`:
+
+| `ecosystems` | Slowest-test instrument | The usual first cause |
+|---|---|---|
+| `php` | `--profile` / Pest's duration column | database refresh per test |
+| `js` | `vitest --reporter=verbose`, `jest --detectOpenHandles` | module transform and a leaked handle |
+| `python` | `pytest --durations=20` | session-scoped fixtures rebuilt per test |
+| `go` | `go test -v`, `-cpuprofile`, `-race` for the slow-and-flaky pair | a `TestMain` that starts real I/O |
+
+`go test` caches a package's result until its inputs change, so a suite that
+looks fast on the second run may not have run at all — `-count=1` defeats the
+cache when you are measuring.

package/dist/agent-src/skills/ui-component-architect/SKILL.md

@@ -61,7 +61,7 @@ than under-splitting. Meet BOTH conditions before you extract.
 **Read `DESIGN.md` § Owned components first** — it is the project's own inventory of what
 it already owns (component, status, story file, registry item), filled from the story files
 rather than from memory by
-[`design-system-capture`](../design-system-capture/SKILL.md). It is the cheapest possible
+`design-system-capture`. It is the cheapest possible
 prior-art check: one table, and a `deprecated` row tells you not to reach for something that
 still exists in the tree. Absent or empty → fall through to
 [`existing-ui-audit`](../existing-ui-audit/SKILL.md), which reads the codebase itself.
@@ -69,6 +69,29 @@ still exists in the tree. Absent or empty → fall through to
 Then review existing components in the codebase for the same
 responsibility — extend rather than rebuild when a match is found.
 
+**Read `state.ui_audit.component_taxonomy` before you decide where the
+component goes.** The audit (§ 1b of
+[`existing-ui-audit`](../existing-ui-audit/SKILL.md)) records the project's
+**own** granularity tiers, joined with `/`, or `none`:
+
+- **It names tiers** → record the chosen tier on the component's
+  `state.ui_design.components[]` entry as `tier` (the apply step reads that
+  field and nothing else writes it), then place the component inside it and say
+  which:
+  *"conforming to the project's `primitives/patterns/features` taxonomy —
+  `Checkout` goes under `src/components/features/`"*. Match the tier by name;
+  there is no rule here that computes a tier, and there must not be one.
+- **A component fits no tier** → report it as a named conformance gap with the
+  reason, and leave it unplaced. Do not put it somewhere else quietly, and do
+  not invent a tier for it — picking one would need exactly the per-tier rule
+  the measurement below shows is not derivable.
+- **`none`** → behave exactly as you would without this paragraph. A project
+  that organizes its components some other way must not be able to tell that
+  this step exists. Never propose a taxonomy to a project that has one you did
+  not recognise, and never propose one mid-task to a project that has none —
+  the single offer is made once, at the greenfield halt, and a decline there is
+  terminal.
+
 **A new component's workshop is part of its design where the project has one —
 size-conditional, never a generic mandate.** The boundary is
 [`component-oriented-and-oop-development`](../../guidelines/component-oriented-and-oop-development.md)
@@ -81,7 +104,7 @@ checkable before it reaches a page. That skill is stack-agnostic and ships in
 `engineering-base`, so a plain-`react` project receives it exactly as a
 `react-shadcn` one does. The state-coverage matrix the story set is derived
 from is React-specific and lives in
-[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Step 3, deliberately not
+`react-shadcn-ui` § Step 3, deliberately not
 duplicated here; a Blade, Vue or Livewire lane derives its story set from that
 lane's own state list instead.
 

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "16.1.0"
+agent_config_version: "16.3.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/roadmaps.md

@@ -575,6 +575,36 @@ that was never a judgement call.
     full CI pipeline — per `roadmap-ci-steps-policy` a `verify:` must not
     be a full-suite gate.
 
+    **The expectation half — say what the command must produce.** A command
+    alone names no oracle. `` verify: `cat notes.md` `` is a conforming step
+    field that cannot say no, so the box gets flipped on a command that was
+    never able to fail. In practice the great majority of clauses in a
+    roadmap tree state no oracle at all — run the share command below on
+    your own tree rather than trusting a number written here. A clause
+    MAY therefore state what the command must produce, using the arrow
+    `exec:` evidence already carries — not a new symbol:
+
+    - `` verify: `<cmd>` -> 0 `` — the command must exit with that code.
+    - `` verify: `<cmd>` -> /regex/ `` — its output must match.
+
+    Prose after `verify:` stays legal and reads as MANUAL. Forbidding it
+    would invalidate most clauses already in the tree at a stroke, and a
+    grammar that reds every producer gets weakened until it finds nothing.
+    One parser reads the arrow (`src/scripts/_lib/verify_clause.ts`) and
+    nothing parses it a second time. `closure_scan`'s `unfalsifiable-verify`
+    family reports the clauses whose oracle cannot say no, and exits 0
+    unconditionally — it is a listing, never a gate. The share per roadmap
+    is `./scripts-run src/scripts/roadmap_verify_share`.
+
+    **An absence check names its positive control.** A `verify:` asserting
+    that something is *absent* — no match, no occurrence, an empty diff —
+    passes identically when the property holds, when the check itself is
+    broken, when the path moved, and when the corpus is empty. Such a clause
+    MUST name the input on which it does fire: the positive control. A
+    fixture that plants the thing, a prior commit that carried it, or a
+    sabotage the step records. Without one it is a check nobody has seen
+    working, and its green means only that nothing ran.
+
 24. **Ready roadmaps carry a `## Risk Register` (Gate R1).** Every
     ready (non-draft) roadmap ends with a schema-valid Risk Register —
     marker line (`<!-- risk-review: v1 | reviewed: YYYY-MM-DD |

package/dist/agent-src/templates/scripts/work_engine/directives/ui/app_spec.ts

@@ -11,8 +11,9 @@
  *
  * The gate is **scoped to the greenfield-scaffold path only**. It acts only
  * when `state.ui_audit` records `greenfield == True` and
- * `greenfield_decision == "scaffold"`. Every other UI flow sees this slot as a
- * clean `SUCCESS` no-op, so those flows stay byte-identical.
+ * `greenfield_decision` ∈ `{scaffold, granularity_convention}`. Every other
+ * UI flow sees this slot as a clean `SUCCESS` no-op, so those flows stay
+ * byte-identical.
  */
 import {
     type Any,
@@ -21,6 +22,7 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import { GRANULARITY_CONVENTION } from '../../state.js';
 
 /** Declared ambiguity surfaces for this step. */
 export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
@@ -112,14 +114,18 @@ export function run(state: DeliveryState): StepResult {
  * The gate is inert for every other flow: improve-existing, the `bare` /
  * `external_reference` greenfield picks, and the `diff` / `file` envelopes all
  * leave `ui_audit` without the `greenfield == True` +
- * `greenfield_decision == "scaffold"` pair.
+ * `greenfield_decision` ∈ `{scaffold, granularity_convention}` pair.
  */
 function _is_greenfield_scaffold(state: DeliveryState): boolean {
     const audit = state.ui_audit;
     if (!_isDict(audit)) return false;
+    // `granularity_convention` is option 4 — a scaffold that additionally
+    // organises what it creates under a named convention, so it takes the same
+    // grounding pass. Kept in step with the identical guard in `scaffold`.
     return (
         audit['greenfield'] === true &&
-        audit['greenfield_decision'] === 'scaffold'
+        (audit['greenfield_decision'] === 'scaffold' ||
+            audit['greenfield_decision'] === GRANULARITY_CONVENTION)
     );
 }