@event4u/agent-config 16.2.0 → 16.3.0

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.
@@ -104,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.2.0"
+agent_config_version: "16.3.0"
 
 # --- Project identity ---
 project:

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

@@ -133,12 +133,11 @@ export function run(state: DeliveryState): StepResult {
             return _halt_coverage(state, provided, report.gaps);
         }
         notes.push(...report.fallbacks);
-        // 3.1 — reported in shadow: the outcome value is unchanged for one
-        // release, so a caller branching on it is found by the line rather
-        // than by the breakage.
-        const handed_back = _handed_back_line(report);
-        if (handed_back !== null) {
-            notes.push(handed_back);
+        // 3.2 — the shadow is now the outcome. 3.1 shipped the line one
+        // release ahead (16.2.0 carries it) so a caller branching on
+        // `SUCCESS` was found by the words before it is found by the value.
+        if (carried_nothing(report)) {
+            return _halt_carried_nothing(state, report, notes);
         }
     }
 
@@ -390,6 +389,49 @@ function _halt_coverage(
     });
 }
 
+/**
+ * BLOCKED halt — the port accounted for everything and carried none of it.
+ *
+ * The gap list is empty here by construction: a complete report and a complete
+ * surrender look identical to `coverage_gaps`, which is why this is its own
+ * halt rather than a gap. `questions` is non-empty because the dispatcher
+ * rejects a `BLOCKED` result that surfaces nothing to answer — handing the
+ * work back has to come with a way forward, not just a refusal.
+ */
+function _halt_carried_nothing(
+    state: DeliveryState,
+    report: CoverageReport,
+    fallbacks: ReadonlyArray<string>,
+): StepResult {
+    const directive = _resolve_directive(state);
+    const lines: string[] = [
+        agent_directive(directive),
+        '> Apply rejected: the coverage report accounts for every declared ' +
+            'item and the port carried none of them over.',
+        `> All ${report.declared.length} declared item(s) are in \`flagged\`:`,
+    ];
+    for (const item of report.handed_back) {
+        lines.push(`> - \`${item}\``);
+    }
+    lines.push(
+        '> A complete report and a complete hand-back are the same empty gap ' +
+            'list, so this is checked separately — flagging one handler the ' +
+            'port could not carry is the ledger working; flagging all of them ' +
+            'is the port not having run.',
+        '> 1. Continue — implement the items above and re-write ' +
+            '`ui_apply.coverage` with each one in `honoured` or `translated`, ' +
+            'leaving in `flagged` only what genuinely could not be carried',
+        '> 2. Flag deliberately — say here which of the items above are out of ' +
+            'scope for this port and why, and the operator decides',
+        '> 3. Abort — drop this UI request',
+    );
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message: [...fallbacks, `UI apply rejected: ${_handed_back_line(report)}`].join('\n'),
+    });
+}
+
 /** Return the agent-written `ui_apply` envelope, or `null`. */
 function _apply_envelope(state: DeliveryState): Record<string, Any> | null {
     const data = _pyTruthy(state.ticket) ? state.ticket : {};