@event4u/agent-config 14.5.0 → 14.7.0

package/dist/agent-src/skills/ai-council/references/output-and-synthesis.md

@@ -0,0 +1,125 @@
+# ai-council — output path and synthesis
+
+> Mode body of the [`ai-council`](../SKILL.md) skill (router-head retrofit,
+> 2026-08-20). Content moved VERBATIM from SKILL.md — load this file when the
+> mode table in SKILL.md routes here.
+
+## Output path convention
+
+Council artefacts (questions, responses, sessions) are **dev-time
+scratch** — gitignored in both the package repo and consumer repos
+and auto-pruned after `ai_council.session_retention_days` (default
+7). They inform a decision; they are not the durable contract. The
+durable contract lives in the roadmap / ADR / skill body that cites
+the council's convergence inline.
+
+**Linking to a specific council file is forbidden by
+[`no-roadmap-references`](../../../rules/no-roadmap-references.md)
+(council clause)** — gitignored, not in the cloned repo, gone after
+the retention window. Inline the convergence with date + members
+instead.
+
+Three directories, three modes:
+
+| Mode | Path | Format |
+|---|---|---|
+| **Topic-anchored question** (paired with a roadmap or ADR) | `agents/runtime/council/questions/<topic-slug>.md` | Markdown |
+| **Topic-anchored response** (paired with the question above) | `agents/runtime/council/responses/<topic-slug>.json` | JSON from `council:run --output` |
+| **Ad-hoc session** (no durable artefact yet) | `agents/runtime/council/sessions/<UTC-timestamp>.json` | JSON from `council:run --output` |
+
+`<topic-slug>` is kebab-case and **must match** the corresponding
+roadmap / ADR slug if one exists (e.g. `path-fixes` mirrors the
+matching `road-to-<topic-slug>` roadmap under `agents/roadmaps/`).
+
+### Forbidden
+
+- Files at `agents/` root (e.g. `agents/runtime/council/question-foo.md`).
+- Dot-prefix scratch (e.g. `agents/.council-question-foo.md`).
+- Any other directory below `agents/` (e.g. `agents/scratch/`,
+  `agents/evidence/notes/`). Operator scratch belongs under
+  `agents/runtime/tmp/` (gitignored).
+- Cross-references from any artefact to specific council files —
+  see [`no-roadmap-references`](../../../rules/no-roadmap-references.md)
+  (council clause). Inline the convergence summary instead, with
+  date and member list for traceability (`Council (claude-sonnet-4-5
+  + gpt-4o, YYYY-MM-DD) reviewed N candidate strategies; converged
+  on …`).
+
+### Exempt
+
+- `agents/evidence/audits/` — historical audit bundles. The canonical
+  council dirs are gitignored; audit bundles are tracked,
+  cohesive narratives that may include council artefacts as
+  part of their evidence trail (e.g. `audits/2026-05-14-north-star/`
+  bundling its triggering question, raw responses, and synthesis
+  alongside the audit's findings). The layout linter
+  (`scripts/check_council_layout.ts`) skips this directory.
+
+`scripts/check_council_layout.ts` is the mechanical check for the
+output path convention — wire it into the package's CI pipeline so
+violations break the build.
+
+## Synthesis templates (lens-aware)
+
+The **Convergence / Divergence** slot in `council:render` output is
+populated with a lens-specific synthesis prompt. The host agent reads
+this prompt and writes the summary in the shape it dictates. The five
+templates live in `scripts/ai_council/prompts.ts::_SYNTHESIS_TABLE`
+and are exposed via `synthesis_template(mode)`.
+
+**R4 Q4 split** — decision lenses get a structured Karpathy-style
+template; creative lenses keep an open-ended prose body. **Every lens
+now closes with two required verdict-discipline sections** — **Kill
+criteria** (observable falsifiers with a threshold or event, checkable
+without re-convening the council) and **Concrete next step** (exactly
+one artefact-producing action) — added so no synthesis ships an
+unfalsifiable verdict (road-to-opt-council-deliberation Phase 0):
+
+| Lens | Class | Synthesis sections |
+|---|---|---|
+| `default` | decision | Agreement · Clashes · Blind spots · Recommendation · **Kill criteria · Concrete next step** |
+| `pr` | decision | Consensus · Conflicts · Must-fix before merge · Recommendation · **Kill criteria · Concrete next step** |
+| `analysis` | decision | Top-10 by consensus · Supporting · Outliers · **Kill criteria · Concrete next step** |
+| `design` | creative | open prose body + **Kill criteria · Concrete next step** |
+| `optimize` | creative | open prose body + **Kill criteria · Concrete next step** |
+
+Input modes (`prompt` / `roadmap` / `diff` / `files`) inherit the
+`default` decision template — they are bundling shapes, not lenses.
+
+**Source citations:**
+* Template shape — Round 2 council verdict
+  (`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-1.md`,
+  Opus's lens-adaptive synthesis proposal).
+* Decision/creative split — Round 4 Q4 verdict
+  (`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-3-responses.json`).
+  R4 reframed `optimize` as creative because perf trade-offs resist
+  pre-templated shape — Performance-wins / Trade-offs /
+  Implementation-order is too rigid for the variety of optimize-lens
+  artefacts. R4 reframed `design` for the same reason — design
+  critiques are inherently narrative.
+
+### `--prose-synthesis` escape hatch (R4 Q4)
+
+Both `council:run` and `council:render` accept symmetric escape-hatch
+flags on top of the lens table:
+
+* `--prose-synthesis` — force creative-lens passthrough (bare slot)
+  regardless of lens. Use when the user on `default`/`pr`/`analysis`
+  prefers a narrative recommendation over the structured template.
+* `--no-prose-synthesis` — force the `default` structured template
+  even on a creative lens. Use when a `design` or `optimize` artefact
+  has a one-shot need for Karpathy-style structure.
+
+The flag is mutually exclusive — picking one disables the other on
+the same invocation. When `council:run` records either flag in the
+output JSON, `council:render` honours it unless the renderer is
+called with an explicit flag of its own.
+
+### Renderer lens resolution
+
+`council:render <responses.json>` resolves the active lens in this
+order: explicit `--prompt-mode` flag > `prompt_mode` field in the
+payload > `mode` field in the payload > `None` (default decision
+template). The `--prose-synthesis` / `--no-prose-synthesis` flag
+overrides the table regardless of how the lens resolved.
+

package/dist/agent-src/skills/ai-council/references/procedure.md

@@ -0,0 +1,143 @@
+# ai-council — procedure and critical evaluation
+
+> Mode body of the [`ai-council`](../SKILL.md) skill (router-head retrofit,
+> 2026-08-20). Content moved VERBATIM from SKILL.md — load this file when the
+> mode table in SKILL.md routes here.
+
+### Neutrality — context-handoff
+
+External reviewers do better critique when they know **what the
+project is**, not just what the artefact looks like. The council
+ships a neutral **handoff preamble** (modelled on `/agent-handoff`)
+in front of every member's system prompt, assembled by
+`prompts.handoff_preamble(project, original_ask)`:
+
+| Carried | Forbidden |
+|---|---|
+| Project name (from `composer.json` / `package.json` / repo dir) | Host-agent identity (Augment, Claude Code, Cursor, Cline, Windsurf, Copilot agent) — stripped line-by-line before send |
+| Stack one-liner inferred from manifest files | Host-agent reasoning, prior turns, internal analysis |
+| One paragraph of repo purpose from `README.md` (max 400 chars) | Host-agent framing language ("I think this looks weak", "the user probably wants…") |
+| The user's **original ask** verbatim (the free-form sentence that triggered `/council`) | Anything the host agent generated about the artefact |
+
+`detect_project_context()` in `scripts/ai_council/project_context.ts`
+reads only the manifest files + root README; missing fields collapse
+to `None` and the preamble silently omits the line. With both
+`project=None` and `original_ask=""`, the preamble degrades to the
+bare `NEUTRALITY_PREAMBLE` (v1 shape — back-compat for callers that
+have not migrated yet).
+
+## Procedure
+
+1. **Resolve target.** Identify the artefact mode (`prompt`, `roadmap`,
+   `diff`, `files`) and locate the source. Refuse to proceed if the
+   target is ambiguous.
+2. **Bundle + redact.** Call `scripts/ai_council/bundler.ts` to produce
+   a redacted artefact bundle. If `BundleTooLarge` fires, surface the
+   size and ask the user to narrow scope — do NOT truncate silently.
+3. **Clear the spend bound.** The council is standing-authorized — there is
+   no per-invocation approval. What still binds is a *bound*, resolved in
+   this order:
+   - **No billable member** (every member is `mode: cli` under
+     subscription auth — `billable=False`) → nothing is spent. Render the
+     estimate table as information and fan out. No gate.
+   - **Billable members with a configured ceiling** (`cost_budget.max_total_usd`
+     non-zero, or `daily_limit_usd` non-zero) → the ceiling **is** the
+     authorization the user already gave. Render the estimate and fan out.
+     `on_overrun` still fires per member on breach (below) — that is where
+     the user regains the decision.
+   - **Billable members with no ceiling at all** (`max_total_usd: 0` AND
+     `daily_limit_usd: 0`) → unbounded paid spend, so surface the estimate
+     and require an explicit `1`. Nothing bounds the call, so the user must.
+
+   Autonomy settings do not *create* a bound and do not lift the last case.
+   Consumers who want the old per-run gate back set a small
+   `cost_budget.max_total_usd`: every call then breaches and `on_overrun`
+   asks, per member.
+4. **Fan out.** Dispatch the bundle to each enabled council member via
+   `scripts/ai_council/orchestrator.ts`. Each member receives the
+   neutrality preamble from `prompts.ts` plus the artefact — nothing
+   from the host agent's prior reasoning.
+5. **Render results.** Stack each member's response under its own
+   provider-attributed heading. Never merge or paraphrase responses
+   into the host agent's voice.
+6. **Summarise.** Write a `Convergence / Divergence` block listing
+   agreements, disagreements, and unique insights — provider-attributed.
+7. **Critically evaluate** every finding before it leaves the host
+   (see *Critical evaluation* below). The host is the convener **and**
+   the skeptic — never a reviewer of the artefact itself, but always a
+   reviewer of the **council's output**.
+8. **Translate validated findings to options.** Convert each finding
+   the host accepts (or accepts with modification) into a concrete
+   numbered option for the user. Tag every option with the host's
+   verdict so the user sees the agent's reasoned position, not the
+   council's raw output. The user decides; the council advises; the
+   host filters.
+
+## Critical evaluation — convener-skeptic stance
+
+```
+COUNCIL CONVERGENCE IS NOT CORRECTNESS.
+DO NOT BLINDLY ACCEPT FINDINGS. DO NOT BLINDLY REJECT THEM.
+EVERY FINDING GETS A REASONED VERDICT BEFORE IT REACHES THE USER.
+```
+
+### Mechanism claims need a probe, not a second opinion
+
+```
+A MECHANISM CLAIM IN A COUNCIL ARTEFACT IS MARKED `unverified:` UNTIL A PROBE COVERS IT.
+A VERDICT RESTING ON AN UNVERIFIED MECHANISM CLAIM DOES NOT BIND.
+SEVERAL MODELS AGREEING MULTIPLIES PLAUSIBILITY. IT DOES NOT PRODUCE EVIDENCE.
+```
+
+A **mechanism claim** asserts how the machine behaves: "this toggle removes the
+cost", "that gate scans X", "the host reads the router". The council deliberates
+over **arguments**, never against the running system — it cannot execute a command,
+so it has no way to falsify one. Marking such a claim `unverified:` in the artefact
+keeps the reader from mistaking a well-argued mechanism for a measured one, and the
+non-binding clause means the fix for a wrong claim is a probe, not a re-vote.
+
+**Case zero (2026-07-29).** An accepted ADR claimed a compile-time toggle gave
+"zero-cost dormancy" because the rule was dropped from `dist/router.json`. Two
+council members praised the reasoning; neither could check it. A one-line `grep`
+later showed the toggle was read by the router compiler and by **nothing in the
+projector**, so the rule's body kept shipping as a file — and the host reads the
+file. The claim was half wrong, the verdict that rested on it was void, and what
+caught it was a probe, not a third opinion.
+
+The council is **uninformed about the codebase, ADRs, locked
+contracts, prior decisions, and project history** — it sees only the
+artefact + neutrality preamble. That is the source of its diversity
+**and** its blind spots. Convergence between members can mean shared
+generic best-practice priors, not project-specific correctness.
+
+The host applies a critical lens to **every finding** (convergence
+**and** divergence) before surfacing it as a numbered option:
+
+| Check | Question | Tool |
+|---|---|---|
+| **Codebase fit** | Does the finding match the actual code, files, signatures, conventions? | `view` / `codebase-retrieval` / `grep` |
+| **Locked-decision conflict** | Does it contradict an ADR, kernel rule, contract under `docs/contracts/`, or `docs/decisions/`? | `view` |
+| **Already addressed** | Is it a generic best-practice already covered by an existing rule, skill, or test? | `view` / `grep` |
+| **Cost / benefit** | Is the change worth the diff size, churn, and review cost vs. the marginal benefit? | reasoning |
+| **Hallucination** | Does the finding cite a file, function, or behavior that does not exist? | `view` |
+
+Each finding receives one of three verdicts:
+
+- **`accept`** — codebase fits, no locked-decision conflict, benefit clears cost. Surface as a normal numbered option.
+- **`accept-with-modification`** — core insight valid, but the proposed shape needs adjusting (wrong file, contradicts ADR detail, scope creep). Surface with the **modified** patch and a one-line note.
+- **`reject`** — finding is wrong (hallucinated reference, contradicts a locked decision, already addressed, generic noise). Surface as a **Rejected by host** entry with a one-line reason. Still visible — the user can override.
+
+The verdict is the host's **own** reasoning, not the council's.
+Pretending convergence equals correctness, or paraphrasing council
+output as host analysis, both breach the [`direct-answers`](../../../rules/direct-answers.md)
+no-invented-facts rule. When the host cannot reach a confident
+verdict on a finding (mixed evidence, ambiguous scope), it surfaces
+the finding as `needs-input` with the open question — the user
+decides, the host does not guess.
+
+### What this is NOT
+
+- **Not a re-review by the host.** The host did not write the artefact independently and cannot critique it independently — that boundary still holds.
+- **Not a vote against the council.** Rejecting a finding requires evidence (file, line, contract reference), not preference.
+- **Not silent filtering.** Every finding reaches the user with its verdict and reason. The user can pick a `reject` option and override the host.
+

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

@@ -280,6 +280,24 @@ in the rule; the lock catalog, fire steps, and failure modes live here.
    contract — every re-evaluated lock gets a fresh, correctly-scoped
    disposition, not a re-statement of the old one.
 
+   When the lock is an **ADR**, the disposition carries the five-field reopen
+   record from [`adr-layout § Reopen record`](../../../docs/contracts/adr-layout.md):
+   the original rationale **addressed** (not cited), what changed with tree
+   evidence, dependants and external commitments touched, the rollback path,
+   and a blast radius — `narrow | wide | irreversible` — with the evidence for
+   that call. Two clauses bind the same record: **precedent creates no
+   authority** (that a similar ADR was reopened is never grounds for this one),
+   and **one seat must argue the strongest case for keeping the decision**.
+   Both answer precedent laundering through correlated self-review, which is
+   the failure two independent council seats named for this mechanism on
+   2026-08-19: the proposer frames the evidence, correlated seats ratify, and
+   the amendment becomes authoritative input for the next review.
+
+   Proportionally: a narrow, reversible, bounded transition takes the light
+   path (record + council); `wide` or `irreversible` adds owner notification.
+   Identical ceremony for a typo-level amendment would cost more than asking
+   the owner and the mechanism would die of its own weight.
+
 ### When NOT to fire
 
 - The blocked change has no real benefit — the gate is not a lever to

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

@@ -23,6 +23,20 @@ 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)
 
+## Modes
+
+This skill is a router head. The cross-mode material — execution policy,
+language detection, environment, output, gotchas — lives below. The per-tool
+procedure bodies live in `references/`; load exactly the mode the detected
+stack calls for.
+
+| Detected stack | Mode body | Covers |
+|---|---|---|
+| 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 |
+
+Both stacks changed → load both mode bodies and run both pipelines.
+
 ## Execution policy — on demand only, never proactive
 
 ```
@@ -59,6 +73,26 @@ git diff --name-only origin/main..HEAD | grep -E '\.(js|ts|tsx)$'  # → JS/TS t
 
 If both PHP and JS/TS files changed → run **both** pipelines.
 
+## Procedure
+
+1. Confirm a run is justified — see Execution policy above. No trigger, no run.
+2. Detect the stack from the changed files — see Language detection above.
+2b. **Inspect the project's own quality config before running anything.** Read
+   the config files the detected stack actually ships (`phpstan.neon`,
+   `ecs.php`, `rector.php`, `biome.json`, `tsconfig.json`, the `scripts` block
+   of `package.json`) and the task/make wrapper if one exists. Never assume a
+   default ruleset, a default baseline, or a default command — the mode body
+   names where to look per stack. Running a tool against assumed config
+   produces findings the project never asked for.
+3. Load the matching mode body from the table in Modes and follow its
+   procedure. PHP → [`references/php-tools.md`](references/php-tools.md)
+   § Procedure: Run quality checks. JS/TS →
+   [`references/js-ts-tools.md`](references/js-ts-tools.md)
+   § JS/TS Quality Workflow.
+4. Both stacks changed → run both mode procedures; neither result excuses the
+   other.
+5. Report per Output format below.
+
 ## Related rules and guidelines
 
 - `verify-before-complete` rule — no pass claims without fresh output; suppressed runs are surfaced as "delegated to remote CI", never claimed
@@ -71,332 +105,6 @@ If both PHP and JS/TS files changed → run **both** pipelines.
 
 ---
 
-# PHP Quality Tools
-
-## Tool Detection
-
-Check `composer.json` to determine which tools are available and how to run them.
-Use the **first matching** command style:
-
-| `composer.json` contains | Command style | Example |
-|---|---|---|
-| A project-specific quality wrapper (exposes `quality:*` commands) | `php artisan quality:*` or `composer quality:*` | `php artisan quality:phpstan` |
-| `phpstan/phpstan` or `larastan/larastan` | `vendor/bin/phpstan` | `vendor/bin/phpstan analyse` |
-| `rector/rector` | `vendor/bin/rector` | `vendor/bin/rector process` |
-| `symplify/easy-coding-standard` | `vendor/bin/ecs` | `vendor/bin/ecs check --fix` |
-
-**Priority:** If a project ships a `quality:*` wrapper (Artisan or Composer script), always prefer it —
-wrappers typically add git-aware execution, caching, automatic baseline regeneration, and memory
-management on top of the native tools.
-
-If none of the above is installed → skip quality checks, inform the user.
-
-All commands run **inside the Docker container** if Docker is used (`docker compose exec` or `make console`).
-
-## Commands
-
-### PHPStan — Static Analysis
-
-```bash
-# Native:
-vendor/bin/phpstan analyse                          # Analyse all configured paths
-vendor/bin/phpstan analyse --memory-limit=512M      # With memory limit
-vendor/bin/phpstan analyse --error-format=github    # CI-friendly format
-
-# With a project-specific quality wrapper:
-php artisan quality:phpstan          # Laravel
-composer quality:phpstan             # Composer
-```
-
-**Native flags:**
-
-| Flag | Description |
-|---|---|
-| `--memory-limit=SIZE` | Set memory limit (e.g. `512M`, `1G`) |
-| `--debug` | Activate debug mode |
-| `--error-format=FORMAT` | Output format: `table` (default), `github`, `gitlab` |
-| `--pro` | Toggle PHPStan Pro |
-
-**Wrapper-only flags** (typical of a `quality:*` wrapper — verify in the project):
-
-| Flag | Description |
-|---|---|
-| `--baseline` | Generate/update phpstan baseline file |
-| `--ignore-git` | Skip Git check, analyse all files |
-| `--xdebug` | Activate Xdebug mode |
-
-### ECS — Easy Coding Standard
-
-```bash
-# Native:
-vendor/bin/ecs check                  # Dry-run
-vendor/bin/ecs check --fix            # Auto-fix
-
-# With a project-specific quality wrapper:
-php artisan quality:ecs --fix         # Laravel
-composer quality:ecs -- --fix         # Composer
-```
-
-**Native flags:**
-
-| Flag | Description |
-|---|---|
-| `--fix` | Fix errors automatically |
-| `--clear-cache` | Clear the ECS cache |
-
-**Wrapper-only flags** (typical of a `quality:*` wrapper — verify in the project):
-
-| Flag | Description |
-|---|---|
-| `--ignore-git` | Skip Git check, check all files |
-| `--paths-to-scan[=PATHS]` | Custom paths, e.g. `--paths-to-scan='["./core"]'` |
-| `--source-branch[=BRANCH]` | Source branch (default: HEAD) |
-| `--target-branch[=BRANCH]` | Target branch to compare against |
-
-### Rector — Automated Refactoring
-
-```bash
-# Native:
-vendor/bin/rector process              # Auto-fix
-vendor/bin/rector process --dry-run    # Preview changes
-
-# With a project-specific quality wrapper:
-php artisan quality:rector --fix       # Laravel
-composer quality:rector -- --fix       # Composer
-```
-
-**Native flags:**
-
-| Flag | Description |
-|---|---|
-| `--dry-run` | Preview changes without applying |
-| `--clear-cache` | Clear the Rector cache |
-
-**Wrapper-only flags** (typical of a `quality:*` wrapper — verify in the project):
-
-| Flag | Description |
-|---|---|
-| `--ignore-git` | Skip Git check, check all files |
-| `--paths-to-scan[=PATHS]` | Custom paths |
-| `--source-branch[=BRANCH]` | Source branch (default: HEAD) |
-| `--target-branch[=BRANCH]` | Target branch to compare against |
-
-### Combined Commands
-
-There is no native single command for running all three tools. Run them in sequence:
-
-```bash
-# Full pipeline (native):
-vendor/bin/rector process && vendor/bin/ecs check --fix && vendor/bin/phpstan analyse
-
-# With a project-specific quality wrapper (if it ships these combined commands):
-php artisan quality:refactor --fix     # Rector + ECS
-php artisan quality:finalize           # Rector + ECS + PHPStan (full pipeline)
-```
-
-## Procedure: Run quality checks
-
-1. Run PHPStan — fix all errors
-2. Run Rector + ECS with auto-fix — fix style + refactoring
-3. Run PHPStan again — verify step 2 didn't introduce new issues
-
-If step 3 finds errors → fix and repeat from step 2.
-
-Detect commands from project (see Tool Detection above).
-
-## Configuration
-
-Config files are typically in the **project root**. Do NOT modify without explicit user permission.
-
-Detect config location:
-- Check project root first: `phpstan.neon`, `ecs.php`, `rector.php`
-- Some projects use `phpstan.neon.dist` instead of `phpstan.neon`
-
-### Standard config files
-
-| File | Tool | Purpose |
-|---|---|---|
-| `phpstan.neon` | PHPStan | Level, paths, extensions, `ignoreErrors`, disallowed calls |
-| `phpstan-baseline.neon` | PHPStan | Baseline for existing errors (auto-managed, do NOT edit) |
-| `ecs.php` | ECS | Code style: rule sets, configured rules, skip list |
-| `rector.php` | Rector | Refactoring: rule sets, PHP version sets, skip list |
-
-### Understanding the project's config
-
-Read the actual config files to understand what rules are active:
-
-- **phpstan.neon**: Check `level`, `paths`, `ignoreErrors`, `includes` (baselines, extensions)
-- **ecs.php**: Check which rule sets are active (PSR-12, PHP-CS-Fixer sets), skip list
-- **rector.php**: Check PHP version sets, active rule sets, skip list
-
-Common patterns across projects:
-- PHPStan at high levels (8-9) with `disallowedFunctionCalls` banning `var_dump()`, `dd()`
-- ECS with PSR-12 base, trailing commas, Yoda style
-- Rector with PHP version migration sets and naming conventions
-
-## Baseline policy
-
-- **NEVER** edit `phpstan-baseline.neon` by hand.
-- **NEVER** add errors, update counts, or regenerate manually.
-- If the project ships a quality wrapper (exposing `quality:*` commands), it may regenerate the baseline automatically.
-
-## PHPStan error handling
-
-Priority order for dealing with PHPStan errors:
-
-1. **Fix the code** — always the first choice. Fix the actual type issue.
-2. **Add type hints / PHPDoc** — if the code is correct but PHPStan can't infer the type.
-3. **Inline ignore (last resort)** — only for confirmed false positives:
-   ```php
-   // @phpstan-ignore-next-line — false positive: reason here
-   ```
-
-### When `phpstan.neon` changes ARE allowed
-
-Adding `ignoreErrors` entries to `phpstan.neon` is allowed when:
-
-- The error is a **structural limitation** of the toolchain (e.g., Pest tests bind `$this` at runtime, PHPStan can't resolve `artisan()`,
-  `get()`, etc. on `PHPUnit\Framework\TestCase`)
-- The pattern applies **broadly** to a category of files (e.g., all test files), not just one specific line
-- The fix would require abandoning the project's conventions (e.g., rewriting Pest tests as PHPUnit classes)
-
-**If unsure whether a `phpstan.neon` change is appropriate → ask the user before making the change.**
-
-### NEVER do these
-
-- Add entries to baseline files (`phpstan-baseline.neon`)
-- Add `ignoreErrors` for individual files or specific code issues that should be fixed
-- Use `@phpstan-ignore-next-line` without a reason comment
-
-See also: `php-coding` rule → PHPStan section.
-
-## Testing framework
-
-- **Always write tests in Pest**, not PHPUnit class syntax — unless the user explicitly asks for PHPUnit.
-- Pest tests in `tests/Unit/` automatically use `UnitTestCase` as the base class (configured in `tests/Pest.php`).
-- PHPStan cannot fully resolve Pest's runtime bindings — this is handled via `ignoreErrors` patterns in `phpstan.neon`.
-
-## Git-aware execution
-
-By default, all tools only check files changed since the last commit.
-
-| Flag                         | Effect                                        |
-|------------------------------|-----------------------------------------------|
-| (default)                    | Only changed files (fast, for iterative work) |
-| `--ignore-git`               | All files (cache still applies)               |
-| `--clear-cache`              | Changed files, but ignore cache               |
-| `--ignore-git --clear-cache` | Complete fresh run of all files               |
-
----
-
-# JS/TS Quality Tools
-
-## Detection
-
-Check `package.json` for available tools:
-
-| Indicator                             | Tool                                                          |
-|---------------------------------------|---------------------------------------------------------------|
-| `@biomejs/biome` in devDependencies   | **Biome** — linting + formatting                              |
-| `typescript` in devDependencies       | **TypeScript** — type checking                                |
-| `jest` or `vitest` in devDependencies | **Test runner**                                               |
-| `eslint` in devDependencies           | **ESLint** — legacy linting (check if Biome replaces it)      |
-| `prettier` in devDependencies         | **Prettier** — legacy formatting (check if Biome replaces it) |
-
-## Biome — Linting + Formatting
-
-Biome replaces ESLint + Prettier in one tool.
-
-### Config
-
-- Config file: `biome.json` or `biome.jsonc`
-- Includes formatter settings (indent style, line width, trailing commas)
-- Includes linter rules (recommended + custom overrides)
-- Includes import sorting (via `assist.actions.source.organizeImports`)
-
-### Commands
-
-```bash
-# Check (dry-run) — shows errors without fixing
-npx biome check .
-
-# Fix — auto-fix all fixable issues (formatting + linting + imports)
-npx biome check --write .
-
-# Format only
-npx biome format --write .
-
-# Lint only
-npx biome lint .
-```
-
-### Via npm scripts (preferred)
-
-Check `package.json` scripts — projects typically define:
-
-```bash
-npm run biome          # Check (dry-run)
-npm run biome:fix      # Auto-fix
-```
-
-Always prefer npm scripts over raw `npx` commands when they exist.
-
-## TypeScript — Type Checking
-
-### Commands
-
-```bash
-# Type check without emitting files
-npx tsc --noEmit
-
-# Via npm script (preferred)
-npm run tscheck
-```
-
-### Config
-
-- Config file: `tsconfig.json` (may have `tsconfig.app.json`, `tsconfig.node.json` for different targets)
-- `strict: true` should be enabled in all projects
-- Check `compilerOptions.paths` for import aliases
-
-## Jest / Vitest — Testing
-
-### Commands
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test file
-npx jest path/to/test.spec.ts
-
-# Run with coverage
-npx jest --coverage
-
-# Watch mode
-npx jest --watch
-```
-
-## JS/TS Quality Workflow
-
-After JS/TS code changes, run this sequence:
-
-```
-1. npx biome check --write .     → Auto-fix formatting + linting
-2. npx tsc --noEmit              → Verify type safety
-3. npm test                      → Run test suite
-```
-
-Or via npm scripts:
-
-```
-1. npm run biome:fix             → Auto-fix
-2. npm run tscheck               → Type check
-3. npm test                      → Tests
-```
-
-If step 2 finds type errors → fix them in code, then re-run step 1 (Biome may reformat).
-
 ## Execution environment
 
 ### PHP tools