@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/commands/skills/discover.md

@@ -0,0 +1,77 @@
+---
+model_tier: medium
+name: skills-discover
+pack: meta
+tier: 2
+cluster: skills
+sub: discover
+description: Recommend skills for a role — ranked by four explained classes (most-useful-for-role, related-to-current-task, recently-adopted, popular-in-role). Local-only; every result carries a why.
+skills: [file-editor]
+suggestion:
+  eligible: true
+  trigger_description: "which skills should I use, recommend skills for my role, what fits this work, help me find a skill, /skills:discover sales"
+  trigger_context: "user wants a short, explained skill shortlist instead of scanning the 220-skill catalog"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /skills discover
+
+Surfaces a short, explained skill shortlist for a role. Reuses existing local
+signals only — the skill catalog frontmatter, the role's `skills.yml`
+shortlist, and (when present and not opted out) the local-analytics JSONL.
+Implements the [`skill-discovery`](../../../docs/contracts/skill-discovery.md)
+contract. Local-only, read-only, no network.
+
+## Prerequisites
+
+- Python 3.10 + PyYAML on the host (already a package dependency).
+- A role id — passed as `[role]`, or the active role from
+  `.agent-settings.yml` → `roles.active_role`.
+
+## Steps
+
+### 1. Resolve the role
+
+The user invokes `/skills discover [role]`. The role is the first positional
+argument. If omitted, the recommender falls back to `roles.active_role`. If
+neither resolves, it prints the available roles and stops — do not guess.
+
+### 2. Run the recommender
+
+```bash
+python3 scripts/skill_discovery.py --role <role>
+```
+
+Optional flags: `--format json` (machine-readable), `--limit N` (results per
+class, default 5). The script is pure-local and writes nothing.
+
+### 3. Present the table
+
+Render the recommender's Markdown table to the user:
+`skill · class · why · first command`. Each row's `why` names the *signal*
+(role match, domain adjacency, recent adoption, role popularity) — never a
+bare score. The four classes are:
+
+- `most-useful-for-role` — the role's priority shortlist.
+- `related-to-current-task` — same-domain peers not already shortlisted.
+- `recently-adopted` — used recently in this workspace (analytics) or the
+  shortlist tail when no usage signal exists yet.
+- `popular-in-role` — launched most by this role locally (analytics) or the
+  shortlist when no usage signal exists yet.
+
+### 4. Offer the first command
+
+Each row carries a `first command` — the natural way to start with that skill.
+Suggest the user pick one and run it. Do **not** auto-invoke a skill.
+
+## Rules
+
+- **Local-only, read-only.** No network, no writes, no prompt/response bodies.
+- **Every result has a non-empty `why`** — a contract invariant.
+- **Analytics opt-out honoured.** `AGENT_CONFIG_NO_LOCAL_ANALYTICS` env or
+  `analytics.local: off` → the analytics-backed classes fall back to the role
+  shortlist with an honest `why`; the surface never fabricates a usage signal.
+- **One role per invocation.** Do not chain.

package/dist/agent-src/commands/skills.md

@@ -0,0 +1,57 @@
+---
+model_tier: medium
+name: skills
+pack: meta
+tier: 2
+description: Skill discovery orchestrator — routes to discover. Local, explained skill recommendations over the catalog + role shortlists + optional local analytics.
+cluster: skills
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "which skills should I use, recommend skills for my role, what skills fit this work, I can't find the right skill, /skills:discover"
+  trigger_context: "user is lost in the 220-skill catalog and wants a short, explained shortlist for their role"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /skills
+
+Top-level orchestrator for the `/skills` family — the **skill discovery**
+cluster. Turns existing local signals (the skill catalog, the active role's
+shortlist, and optional local analytics) into a short, *explained*
+recommendation list. Local-only, no network, honours the analytics opt-out.
+
+Anchors: [`skill-discovery`](../docs/contracts/skill-discovery.md) contract —
+input signals, the four recommendation classes, and the non-negotiable
+`why`-per-result requirement.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/skills discover` | `commands/skills/discover.md` | Rank skills for a role by four explained classes (most-useful / related / recently-adopted / popular) |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/skills <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Steps` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, route to `discover` (the only
+   sub-command today) and print its menu.
+
+## Rules
+
+- **Local-only.** The recommender reads local files only — the catalog, the
+  role `skills.yml`, and (if present and not opted out) the local-analytics
+  JSONL. No network, no writes.
+- **Every recommendation carries a `why`.** Never surface an unexplained
+  score — this is a contract invariant.
+- **Honours the analytics opt-out** (`AGENT_CONFIG_NO_LOCAL_ANALYTICS` env or
+  `analytics.local: off`); degrades to catalog + role shortlist gracefully.
+- **Do NOT chain sub-commands.** One `/skills <sub>` per turn.

package/dist/agent-src/commands/sync-agent-settings.md

@@ -0,0 +1,141 @@
+---
+model_tier: medium
+name: sync-agent-settings
+pack: meta
+tier: 2
+skills: [sync-agent-settings]
+description: Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing
+suggestion:
+  eligible: false
+  rationale: "Settings sync — must be deliberate."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+<!-- cloud_safe: noop -->
+
+# /sync-agent-settings
+
+Reconciles `.agent-settings.yml` with the shipped template
+(`config/agent-settings.template.yml`) and the selected cost-profile
+preset (`config/profiles/{profile}.ini`). Applies the section-aware
+merge rules documented in
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md):
+
+- Template section order wins — keys reorder to match.
+- Existing user scalar values are preserved.
+- Missing keys land with their template / profile default.
+- Template comments replace user comments in the same position.
+- Unknown user keys (not in the template) are preserved under a
+  trailing `_user:` block so custom additions never vanish silently.
+
+Idempotent. Safe to run after every package update.
+
+Use when:
+
+- A new package version added sections (e.g. `chat_history`,
+  `onboarding`) that your local file is missing.
+- A key moved sections (e.g. `pr_comment_bot_icon` from `project` to
+  `personal`) and you want the reshuffle applied.
+- You edited the file by hand and want to normalize formatting.
+
+## When NOT to use
+
+- To change a value (`ide`, `rule_loading_tier`, `max_parallel`) → edit the
+  file directly or ask the agent; the sync only reconciles structure.
+- To create `.agent-project-settings.yml` (team file) → that is a
+  separate concern; this command only touches the developer file.
+- To migrate a legacy flat `.agent-settings` → run
+  `python3 scripts/install.py` first; the installer owns migrations.
+
+## Steps
+
+### 1. Locate script and target
+
+The sync script ships in the installed package. Resolve in order:
+
+1. `./agent-config/scripts/sync_agent_settings.py` — CLI wrapper at the project root.
+2. `vendor/event4u/agent-config/scripts/sync_agent_settings.py` — Composer.
+3. `node_modules/@event4u/agent-config/scripts/sync_agent_settings.py` — npm.
+
+Target is always `<project_root>/.agent-settings.yml`.
+
+### 2. Dry-run — show the user what would change
+
+Run the script with `--dry-run` and capture stdout. Three outcomes:
+
+- **No changes** (exit 0, stdout contains `already in sync`) → tell the
+  user and stop. No prompt needed.
+  ```
+  > ✅ .agent-settings.yml already in sync — nothing to do.
+  ```
+- **Drift detected** → show the unified diff and ask:
+  ```
+  > 📝 /sync-agent-settings would update .agent-settings.yml:
+  >
+  > {diff}
+  >
+  > 1. Apply — write the changes
+  > 2. Skip — leave the file untouched
+  ```
+- **Script error** (exit 2, e.g. template or profile missing) → print
+  the error and stop; do not prompt.
+
+### 3. Act on the choice
+
+- `1` (Apply) → re-run the script **without** `--dry-run`. Confirm:
+  ```
+  > ✅ .agent-settings.yml updated.
+  ```
+  Then re-run with `--check` to confirm idempotency.
+- `2` (Skip) → stop. No changes made.
+
+Free-text replies (`"nö"`, `"leave it"`, unrecognized input) count as
+`2`. Never write on ambiguous input.
+
+### 4. Profile override
+
+The script auto-detects the profile from the target's `rule_loading_tier`
+key and falls back to `minimal`. To sync against a different profile
+(e.g. during a profile change), pass `--profile balanced` or
+`--profile full` — but ask the user first; changing the profile is a
+separate decision from reconciling structure.
+
+## `--check` mode
+
+`sync_agent_settings.py --check` exits **2** if the file is out of
+sync, **0** otherwise — suitable for CI. Emit no diff prompt in
+check-only workflows; report the drift and let the pipeline decide.
+
+## Gotchas
+
+- **Unknown keys end up under `_user:`.** They are not deleted, but the
+  user should review and either upstream them (propose a template key)
+  or remove them. The block carries a comment explaining this.
+- **Bare lowercase identifiers stay unquoted** (`per_turn`, `rotate`,
+  `phpstorm`). Everything else (names, paths, empty strings) stays
+  quoted. That is intentional — idempotency depends on it.
+- **Comments from the template win.** If you added a note above a key,
+  the sync replaces it with the template comment. Put notes in a
+  separate file if you need them to survive syncs.
+- Changes to `config/agent-settings.template.yml` or the profile
+  presets require a package update in the consumer project before
+  this command can apply them.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+there is no `.agent-settings.yml` on disk, no `scripts/sync_agent_settings.py`
+to call, and no template/profile preset reachable. Settings reconciliation
+is a local-agent concern.
+
+## See also
+
+- [`scripts/sync_agent_settings.py`](../../../scripts/sync_agent_settings.py) — the helper
+- [`config/agent-settings.template.yml`](../../../config/agent-settings.template.yml) — canonical template
+- [`config/profiles/`](../../../config/profiles/) — profile presets
+- [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
+- [`scripts/install.py`](../../../scripts/install.py) — first-install path; this command handles the update path
+- [`/sync-gitignore`](sync-gitignore.md) — sibling command for the `.gitignore` block

package/dist/agent-src/commands/sync-gitignore/fix.md

@@ -0,0 +1,149 @@
+---
+model_tier: medium
+name: sync-gitignore-fix
+pack: engineering-base
+tier: 2
+cluster: sync-gitignore
+sub: fix
+skills: [sync-gitignore]
+description: Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) and re-sync the canonical entries
+suggestion:
+  eligible: true
+  trigger_description: "fix .gitignore garbage, clean up legacy agent-config entries, my .gitignore has stale agent entries, /sync-gitignore is not picking up the right paths"
+  trigger_context: "consumer project carries pre-/agents/ runtime patterns (.agent-chat-history, .agent-prices.md) at the root from an older install"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /sync-gitignore:fix
+
+Cleanup sibling of [`/sync-gitignore`](../sync-gitignore.md). Strips
+legacy patterns (pre-`/agents/` runtime artefacts —
+`.agent-chat-history`, `.agent-chat-history.bak`,
+`.agent-chat-history.*.bak`, `.agent-prices.md`, `.council-tmp/` —
+plus the 2.x intermediate `agents/runtime/.agent-prices.md`) from **anywhere**
+in the consumer's `.gitignore` — inside or outside the managed block —
+then re-runs the regular sync so the current canonical entries
+(`/agents/runtime/.agent-chat-history`, `/agents/runtime/.agent-prices.md`,
+`/agents/runtime/council/`) land in the block.
+
+Use when:
+
+- An older installer (pre-May 2026) dropped root-level `.agent-chat-history`
+  / `.agent-prices.md` lines that the current scripts no longer recognise.
+- A 2.x install left `/agents/.agent-prices.md` in the block before the
+  cache moved under `/agents/runtime/`.
+- A hand-edit added one of those legacy paths and it now conflicts with
+  the managed `/agents/...` entry.
+- `/sync-gitignore` reports "already in sync" but git is still ignoring
+  files at the wrong paths.
+
+## When NOT to use
+
+- To remove **user-added** lines from inside the block → that is
+  `--replace` on the base command, and it is destructive. This
+  sub-command only touches the legacy pattern list — nothing else.
+- To delete the entire managed block → do it by hand.
+- To migrate runtime files themselves (move `.agent-chat-history` →
+  `agents/runtime/.agent-chat-history`) → the installer's
+  `migrate_legacy_root_infra` step handles that. This sub-command only
+  fixes `.gitignore`.
+
+## Steps
+
+### 1. Locate script and target
+
+Same resolution order as [`/sync-gitignore`](../sync-gitignore.md):
+
+1. `./agent-config/scripts/sync_gitignore.py`
+2. `vendor/event4u/agent-config/scripts/sync_gitignore.py`
+3. `node_modules/@event4u/agent-config/scripts/sync_gitignore.py`
+
+Target is `<project_root>/.gitignore`. If no `.gitignore` exists,
+stop — there is nothing to fix:
+
+```
+> 📝 No .gitignore found at <project_root>. Nothing to clean up.
+```
+
+### 2. Dry-run with cleanup
+
+Run:
+
+```bash
+python3 <script> --cleanup-legacy --dry-run
+```
+
+Capture stdout (unified diff) and stderr (summary line listing the
+legacy entries that would be removed). Three outcomes:
+
+- **Nothing legacy + block in sync** → tell the user and stop:
+  ```
+  > ✅ .gitignore already clean — no legacy patterns, block in sync.
+  ```
+- **Diff produced** → show it and ask:
+  ```
+  > 🧹 /sync-gitignore:fix would clean up .gitignore:
+  >
+  > {diff}
+  >
+  > Summary: would remove {N} legacy entr{y|ies}: {names}
+  >          would add {M} entr{y|ies} to the managed block
+  >
+  > 1. Apply — write the changes
+  > 2. Skip — leave .gitignore untouched
+  ```
+- **Script error** (exit 2) → print the error and stop; do not prompt.
+
+### 3. Act on the choice
+
+- `1` (Apply) → re-run **without** `--dry-run`:
+  ```bash
+  python3 <script> --cleanup-legacy
+  ```
+  Confirm with the script's own summary lines (removed-legacy count and
+  added-entries count both surface there).
+- `2` (Skip) → stop. No changes made.
+
+Free-text replies (`"nö"`, `"leave it"`, unrecognized input) count as
+`2`. Never write on ambiguous input.
+
+### 4. Suggest the migration check (informational, do NOT auto-run)
+
+If the cleanup removed `.agent-chat-history` or any flavour of
+`.agent-prices.md`, mention that the **file** itself (if still present
+at its old location) may need to move. The installer does this
+automatically via
+[`migrate_legacy_root_infra`](../../../scripts/install.sh) (chat-history,
+root → `agents/`) and
+[`migrate_legacy_prices_file`](../../../scripts/install.sh) (prices,
+root or `agents/` → `agents/runtime/`); the agent does not run them
+from this command. One line of guidance is enough:
+
+```
+> ℹ️  If `.agent-chat-history` still sits at the project root, or `.agent-prices.md` still sits at the project root or under `agents/`, re-run the installer so the runtime can find them again.
+```
+
+## Rules
+
+- **Append-only by default** — `--cleanup-legacy` removes legacy
+  patterns only. User-added non-legacy lines (inside or outside the
+  block) survive untouched.
+- **Never combine with `--replace`** — the destructive full-block
+  rewrite is a separate concern; mixing the two surprises users.
+- **Dry-run first, always** — the user must see the diff before any
+  write.
+- **Do NOT push, commit, or modify other files** — this command writes
+  to `.gitignore` only.
+
+## See also
+
+- [`/sync-gitignore`](../sync-gitignore.md) — append-only sync of the
+  managed block (no legacy cleanup)
+- [`scripts/sync_gitignore.py`](../../../scripts/sync_gitignore.py) —
+  the helper (`--cleanup-legacy` flag)
+- [`scripts/install.sh`](../../../scripts/install.sh) —
+  `migrate_legacy_root_infra` (moves the **files**, complement to this
+  command which fixes the **ignore rules**)

package/dist/agent-src/commands/sync-gitignore.md

@@ -0,0 +1,140 @@
+---
+model_tier: medium
+name: sync-gitignore
+pack: engineering-base
+tier: 2
+cluster: sync-gitignore
+skills: [sync-gitignore]
+description: Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing
+suggestion:
+  eligible: false
+  rationale: "Settings sync — must be deliberate."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /sync-gitignore
+
+Top-level entry point for the `/sync-gitignore` family. Bare `/sync-gitignore`
+runs the interactive append-only sync described below. The `:fix`
+sub-command additionally scrubs legacy patterns (pre-`/agents/` layout)
+from anywhere in the consumer's `.gitignore` before re-syncing.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/sync-gitignore` (bare) | this file (`## Default flow`) | Interactive — append-only sync of the managed block, dry-run preview, confirm before write |
+| `/sync-gitignore:fix` | `commands/sync-gitignore/fix.md` | Cleanup — strip legacy root-level patterns (pre-`/agents/` layout) wherever they appear, then sync |
+
+## Dispatch
+
+1. Parse the user's argument: `/sync-gitignore[:<sub>] [args]`.
+2. Bare `/sync-gitignore` → run the `## Default flow` below verbatim.
+3. `/sync-gitignore:fix` → load `commands/sync-gitignore/fix.md` and follow
+   its `## Steps` section verbatim.
+4. Unknown sub-command → print the table above and ask which one.
+
+## Default flow
+
+Ensures the consumer project's `.gitignore` contains every entry the
+package expects to be ignored (symlinked `.augment/` subdirectories,
+`/agent-config` CLI wrapper, `.agent-settings*`, `agents/runtime/.agent-chat-history*`).
+Canonical list lives in `config/gitignore-block.txt`; the same file
+drives the installer, so the two cannot drift.
+
+Use when:
+
+- A fresh package version added new managed entries and the installer
+  has not been re-run yet.
+- The project's `.gitignore` never got the block (older install, manual
+  setup, or installer ran with `--skip-gitignore`).
+- You want to audit what the block **should** look like without writing.
+
+### When NOT to use
+
+- To disable logging or change what is logged → that is
+  `chat_history.enabled` in `.agent-settings.yml`, not `.gitignore`.
+- To delete the block entirely → do it by hand; the package will not
+  re-remove its own entries.
+- To change what the block contains → edit
+  `config/gitignore-block.txt` in the package repo and re-release.
+- To clean up legacy garbage from older installs → use
+  [`/sync-gitignore:fix`](sync-gitignore/fix.md) instead.
+
+### 1. Locate script and target
+
+The sync script ships in the installed package. Resolve in order:
+
+1. `./agent-config/scripts/sync_gitignore.py` — if the CLI wrapper
+   directory exists at the project root.
+2. `vendor/event4u/agent-config/scripts/sync_gitignore.py` — Composer.
+3. `node_modules/@event4u/agent-config/scripts/sync_gitignore.py` — npm.
+
+Target is always `<project_root>/.gitignore`. If no `.gitignore` exists,
+stop and tell the user — the package does not create one unilaterally:
+
+```
+> 📝 No .gitignore found at <project_root>. Create one first (e.g. `touch .gitignore`), then re-run /sync-gitignore.
+```
+
+### 2. Dry-run — show the user what would change
+
+Run the script with `--dry-run` and capture stdout. Three outcomes:
+
+- **No changes** (exit 0, stdout says "already in sync") → tell the
+  user and stop. No prompt needed.
+  ```
+  > ✅ .gitignore already in sync — nothing to do.
+  ```
+- **Additions only** (default append-only mode) → show the unified
+  diff and ask:
+  ```
+  > 📝 /sync-gitignore would add {N} entr{y|ies} to .gitignore:
+  >
+  > {diff}
+  >
+  > 1. Apply — write the changes
+  > 2. Skip — leave .gitignore untouched
+  ```
+- **Script error** (exit 2, e.g. template missing) → print the error
+  and stop; do not prompt.
+
+### 3. Act on the choice
+
+- `1` (Apply) → re-run the script **without** `--dry-run`. Confirm:
+  ```
+  > ✅ .gitignore updated ({N} entries added).
+  ```
+- `2` (Skip) → stop. No changes made.
+
+Free-text replies (`"nö"`, `"leave it"`, unrecognized input) count as
+`2`. Never write on ambiguous input.
+
+### 4. Offer `--replace` only when asked
+
+Do **not** suggest `--replace` by default. It rewrites the block in
+full and drops user-added lines inside the block — destructive.
+Mention it only if the user explicitly asks to clean up or reset the
+block, and confirm once more before running it. For removing legacy
+root-level patterns (not user-added lines), prefer
+[`/sync-gitignore:fix`](sync-gitignore/fix.md).
+
+## Rules
+
+- The script honors the explicit `# event4u/agent-config — END` marker.
+  Legacy blocks without it get the marker added automatically on the
+  first sync — that is expected, not a bug.
+- User-added lines **inside** the block survive append-only syncs.
+  They do not survive `--replace`.
+- Changes to `config/gitignore-block.txt` require a package update in
+  the consumer project before this command can apply them.
+- **Do NOT chain sub-commands.** One `/sync-gitignore <sub>` per turn.
+
+## See also
+
+- [`scripts/sync_gitignore.py`](../../../scripts/sync_gitignore.py) — the helper
+- [`config/gitignore-block.txt`](../../../config/gitignore-block.txt) — canonical block body
+- [`scripts/install.sh`](../../../scripts/install.sh) — installer integration (same source of truth, `--skip-gitignore` to opt out)

package/dist/agent-src/commands/tests/create.md

@@ -0,0 +1,91 @@
+---
+model_tier: medium
+name: tests-create
+pack: engineering-base
+tier: 2
+cluster: tests
+sub: create
+skills: [pest-testing, quality-tools]
+description: Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
+suggestion:
+  eligible: true
+  trigger_description: "write tests for these changes, add tests for this branch"
+  trigger_context: "code changes on the branch without matching test changes"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /tests create
+## Instructions
+
+### 1. Detect the test framework
+
+Resolve the framework via the
+[`toolchain-resolver`](../../contexts/execution/toolchain-resolver.md) — write
+tests in the framework the project actually uses, never a hard-coded one:
+
+- **PHP** → Pest (`pestphp/pest`) or PHPUnit.
+- **JS/TS** → Vitest or Jest. **Python** → pytest. **Go** → `testing`.
+  **Rust** → `#[test]`.
+
+Then read the existing tests under the project's test directory to match
+the style and conventions already in use (assertion shape, naming, fixtures).
+
+### 2. Identify what changed
+
+- Run `git diff origin/main..HEAD --name-only` or `git diff origin/master..HEAD --name-only` (depending on project) to get all changed
+  files.
+- Focus on **source files with business logic** in the detected
+  language — skip config, generated files, migrations, views, assets.
+- Read each changed file and understand what was added or modified.
+
+### 3. Understand the code before writing tests
+
+- Use `codebase-retrieval` to understand the classes, their dependencies, and how they're used.
+- Read existing tests for the same or related classes to match patterns.
+- Understand what the method is supposed to do, not just what it does.
+
+### 4. Write meaningful tests
+
+**DO write tests that:**
+
+- Test the **actual business logic** and expected behavior.
+- Cover **edge cases**: null values, empty strings, boundary values, invalid input.
+- Test **error handling**: what happens when things go wrong?
+- Test **different code paths**: if/else branches, early returns, fallback behavior.
+- Verify **return values and side effects** that matter.
+- Use descriptive test names that explain the scenario (e.g. `it returns fallback status when input is empty`).
+
+**Do NOT write tests that:**
+
+- Assert trivial things like parameter count, method existence, or class name.
+- Just repeat the implementation as assertions (testing that `1+1` returns `2` when the code literally does `1+1`).
+- Test framework internals or getter/setter boilerplate.
+- Test private methods directly — test through the public API.
+- Have no real assertion value (e.g. "it does not throw" without meaningful setup).
+
+### 5. Test structure
+
+- One test file per class/service being tested.
+- Place tests in the matching directory structure under `tests/` (mirror the source structure).
+- Group related tests with `describe` blocks (Pest) or separate test methods (PHPUnit).
+- Use data providers for testing multiple input/output combinations.
+- Mock external dependencies (database, HTTP, file system) — don't test infrastructure.
+
+### 6. Verify
+
+- Run the tests locally in the PHP container to make sure they pass.
+- If a test fails, fix it — don't just delete it.
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Quality over quantity** — 5 meaningful tests beat 20 trivial ones.
+- If a class is hard to test (too many dependencies, global state), flag it and suggest a refactoring approach instead of writing brittle
+  tests.
+
+## See also
+
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#tester) — Tester mode output contract (Behaviour under test / Edge cases / Negative paths / Reproduction / Coverage gaps)