@event4u/agent-config 5.10.1 → 6.0.0

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

@@ -0,0 +1,271 @@
+---
+model_tier: inherit
+name: feature-planning
+description: "Use when the user says \"plan a feature\", \"brainstorm\", \"explore this idea\", or wants to go from idea to structured plan and roadmap."
+domain: product
+workspaces:
+  - product
+packs:
+  - product-basic
+trust:
+  level: professional
+install:
+  removable: true
+---
+
+# feature-planning
+
+## When to use
+
+Use this skill when:
+- The user has a feature idea they want to explore or plan
+- An existing feature plan needs refinement
+- A feature plan needs to be turned into actionable roadmaps
+
+Do NOT use when:
+- Bug fixes (use `bug-analyzer` skill)
+- Simple, well-understood changes that don't need planning
+
+## Procedure: Plan a feature
+
+1. **Gather requirements** — What problem does this solve? Who benefits? What's the expected outcome?
+2. **Analyze scope** — Which modules, routes, models, services are affected?
+3. **Write the plan** — Create a feature plan document (see template below).
+4. **Verify** — Confirm all affected areas are identified, no missing dependencies.
+
+A **feature plan** captures the "what and why" of a feature:
+- Problem it solves, who benefits, expected outcome
+- Scope, affected modules, technical approach
+- Open questions and decisions
+
+A **roadmap** captures the "how and when" — the step-by-step implementation plan.
+Feature plans and roadmaps are linked but separate concerns.
+
+## File structure
+
+```
+agents/features/                         # Project-wide feature plans
+├── {feature-name}.md
+
+app/Modules/{Module}/agents/features/    # Module-scoped feature plans
+├── {feature-name}.md
+
+.augment/templates/
+└── features.md                          # Feature plan template
+```
+
+Roadmaps generated from features live in `agents/roadmaps/` (or module-level `agents/roadmaps/`).
+
+## Feature lifecycle
+
+### Quick workflow (small features)
+
+```
+Explore → Plan → Refine → Roadmap → Implement
+  ↑                ↑
+  └── iterate ─────┘
+```
+
+| Phase | Command | Output |
+|---|---|---|
+| **Explore** | `/feature-explore` | Brainstorming notes, feasibility check, rough scope |
+| **Plan** | `/feature-plan` | Structured feature doc in `agents/features/` |
+| **Refine** | `/feature-refactor` | Updated feature doc with changes |
+| **Roadmap** | `/feature-roadmap` | Roadmap(s) in `agents/roadmaps/`, linked from feature |
+
+### Full workflow (complex features, 7 phases)
+
+Use the full workflow for features that span multiple files, require architecture decisions,
+or have unclear requirements. Trigger with `/feature:dev`.
+
+```
+Discovery → Exploration → Questions → Architecture → Implementation → Review → Summary
+```
+
+#### Phase 1: Discovery
+- Clarify the feature request — what problem does it solve?
+- Identify constraints, requirements, and affected users.
+- **Understanding Lock (Hard Gate):** Summarize understanding in 5–7 bullets covering:
+  what is being built, why, who it's for, key constraints, explicit non-goals.
+- List all **assumptions** explicitly.
+- **Wait for explicit confirmation before proceeding.** Do NOT design until confirmed.
+
+#### Phase 2: Codebase Exploration
+- Search for similar features in the codebase.
+- Map the architecture and abstractions in the affected area.
+- Identify key files, services, models, routes involved.
+- Present findings with file references.
+
+#### Phase 3: Clarifying Questions
+- Review codebase findings against the feature request.
+- Identify underspecified aspects: edge cases, error handling, integrations, backward compatibility.
+- **Non-functional requirements** — explicitly clarify or propose defaults for:
+  - Performance expectations (response time, throughput)
+  - Scale (users, data volume, concurrent requests)
+  - Security / privacy constraints
+  - Reliability / availability needs
+  - Maintenance and ownership expectations
+- Present all questions in an organized list.
+- **Wait for answers before proceeding.**
+
+#### Phase 4: Architecture Design
+- Design 2-3 implementation approaches with different tradeoffs:
+  - **Minimal changes** — smallest change, maximum reuse.
+  - **Clean architecture** — maintainability, elegant abstractions.
+  - **Pragmatic balance** — speed + quality.
+- Present comparison with pros/cons and a recommendation.
+- **Ask the user which approach to use** (present as numbered options).
+
+#### Phase 5: Implementation
+- **Wait for explicit approval** before starting.
+- Follow chosen architecture from Phase 4.
+- Follow codebase conventions strictly.
+- Track progress via task list or roadmap.
+
+#### Phase 6: Quality Review
+- Review the implementation for:
+  - Simplicity, DRY, elegance.
+  - Bugs and correctness.
+  - Convention adherence.
+- Present findings with severity levels.
+- **Ask what to fix now vs. later.**
+
+#### Phase 7: Summary
+- Summarize what was built, key decisions, files modified.
+- Suggest next steps (tests, documentation, follow-up features).
+- Update roadmap if applicable.
+
+## Decision log
+
+Maintain a running **decision log** throughout the planning process. For each decision:
+- What was decided
+- Alternatives considered
+- Why this option was chosen
+
+Include the decision log in the feature plan file under a `## Decisions` section.
+This ensures future developers (and agents) understand the reasoning, not just the outcome.
+
+## Bite-sized task granularity (structural roadmaps only)
+
+When a feature plan's generated roadmap declares `complexity: structural` in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks ("Add login endpoint", "Update tests") are correct when the work is well-scoped and low-risk.
+
+Structural roadmap tasks must include:
+
+1. **Exact file path** — `app/Modules/Auth/Services/LoginService.php`, never *"the login service"*.
+2. **Complete code** — every method body, import, and signature ready to paste; no `// existing code` ellipses, no `…`.
+3. **Exact command** — the precise CLI invocation, never *"run the migration"*. Examples: `php artisan migrate --path=database/migrations/2026_05_09_create_logins.php` (Laravel), `bin/console doctrine:migrations:migrate --no-interaction` (Symfony), `bin/rails db:migrate VERSION=20260509…` (Rails), `npx prisma migrate deploy` (Prisma), `alembic upgrade +1` (Python / Alembic), `sqlx migrate run` (Rust).
+4. **Expected output** — what success looks like (`Migrated: 2026_05_09_create_logins`) and the exit code.
+5. **No placeholders** — angle-bracket placeholders, `TODO`, `FIXME`, `tbd`, and `???` are blockers; resolve before the task ships.
+
+The complexity flag lives in the roadmap's YAML frontmatter:
+
+```yaml
+---
+complexity: structural   # triggers bite-sized granularity
+# or
+complexity: lightweight  # default — skips bite-sized granularity
+---
+```
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Task Structure + § No Placeholders (v5.1.0); complexity-gating is our addition (Council Round 1, Q4 — mitigates UX pushback for senior engineers on well-scoped work).
+
+## Self-review (3-scan checklist)
+
+Before presenting any plan, run these three scans in order. Each is a fast pass — not a deep review. Failures block presentation; fix and re-scan.
+
+1. **Spec coverage** — every requirement, AC bullet, or constraint from the input has a corresponding section / AC / scope item in the plan. Walk the input top-to-bottom; tick each requirement against the plan; missing items become open questions or new AC.
+2. **Placeholder / TODO scan** — grep the draft for `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX`. Either resolve them now or surface them in the *Open questions* section. No placeholder ships unflagged.
+3. **Type / shape consistency** — proposed data structures, API shapes, file paths, and module names match existing codebase patterns. Cite at least one existing file per new structure as the convention anchor.
+
+This scan is **separate from** adversarial-review (below). Self-review catches mechanical gaps (missing AC, leftover placeholders, mis-shaped types); adversarial-review challenges the plan's reasoning.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
+## Adversarial self-review
+
+After the 3-scan self-review passes, run the **`adversarial-review`** skill before presenting.
+Focus on the "Feature plans / Architecture" attack questions. See that skill for the full process.
+
+## Feature plan format
+
+See `.augment/templates/features.md` for the full structure. Key sections:
+
+- **Problem** — What pain point does this solve?
+- **Proposal** — What's the solution?
+- **Scope** — What's in, what's out?
+- **Affected Areas** — Which modules, models, services, routes?
+- **Technical Approach** — High-level architecture decisions
+- **Non-Functional Requirements** — Performance, scale, security, reliability
+- **Decisions** — Decision log with alternatives and reasoning
+- **Open Questions** — Unresolved decisions
+- **Roadmaps** — Links to generated roadmap files
+
+## Integration with other systems
+
+### Sessions
+
+```markdown
+- **Feature:** `agents/features/my-feature.md`
+```
+
+### Roadmaps
+
+Feature plans link to their roadmaps in the `## Roadmaps` section.
+Roadmaps reference their source feature in the `## Context` section.
+
+### Modules
+
+If a feature is scoped to a single module, the feature plan and roadmaps live in the
+module's `agents/` directory:
+- Feature: `app/Modules/{Module}/agents/features/`
+- Roadmaps: `app/Modules/{Module}/agents/roadmaps/`
+
+
+## Behavior rules
+
+### Research before planning
+
+Before creating a feature plan, always:
+1. **Search the codebase** for related code, existing patterns, and affected areas.
+2. **Read module docs** if the feature touches a specific module.
+3. **Check existing features** in `agents/features/` for overlap or dependencies.
+
+### Be collaborative
+
+- **Ask questions** — don't assume requirements.
+- **Challenge scope** — suggest what can be deferred.
+- **Show tradeoffs** — present options with pros/cons.
+- **Validate feasibility** — check if the codebase supports the approach.
+
+### Keep it navigational
+
+Feature plans are decision documents, not implementation guides.
+Implementation details belong in roadmaps.
+
+## Output format
+
+1. Feature plan document following the template structure
+2. Decision log with rationale for key choices
+3. Implementation roadmap with ordered tasks
+
+## Auto-trigger keywords
+
+- feature planning
+- feature exploration
+- feature roadmap
+- requirements
+
+## Gotcha
+
+- Don't plan features without understanding the business context — ask the user before assuming.
+- The model tends to over-engineer plans — start with the simplest viable solution.
+- A plan without acceptance criteria is incomplete — always define what "done" means.
+- Don't create plans for features that already exist — search the codebase first.
+
+## Do NOT
+
+- Do NOT create feature plans without user input — always collaborate.
+- Do NOT skip codebase research — always check what exists.
+- Do NOT put implementation steps in the feature plan — that's the roadmap's job.
+- Do NOT commit or push without permission.
+- Do NOT duplicate information from `AGENTS.md` or module docs.

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

@@ -0,0 +1,126 @@
+---
+model_tier: medium
+name: flux
+description: "Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - laravel
+trust:
+  level: professional
+install:
+  default: false
+  removable: true
+---
+
+# flux
+
+> **Grounded stack guidance:** Tailwind-layer Do/Don't + docs URLs via
+> `ground.py search --manifest <skills-root>/design-intelligence/data/manifest.json
+> --stack html-tailwind "<topic>"`. See
+> [`design-intelligence`](../design-intelligence/SKILL.md).
+
+## Positioning — dispatched, not standalone
+
+`flux` is the **primitive-library executor** for projects on the
+Livewire + Flux stack. It is invoked by
+[`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
+once the design brief is locked, and revisited by `review.py` /
+`polish.py` during the design-review loop. It does **not** own the
+flow, does **not** drive the audit, and does **not** lock the design.
+
+| Concern | Owner |
+|---|---|
+| Audit + token inventory (mandatory pre-step) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) |
+| Design brief (layout / states / microcopy) | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Universal design heuristics | [`fe-design`](../fe-design/SKILL.md) |
+| Component logic / state / actions | [`livewire`](../livewire/SKILL.md) |
+| Static Blade partials | [`blade-ui`](../blade-ui/SKILL.md) |
+
+## When to use
+
+Cite this skill when:
+
+- The project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
+- Building forms, modals, dropdowns, toasts, or other standard UI elements that Flux already provides
+
+Do NOT use when:
+
+- Raw Blade templates without Flux (use `blade-ui` skill)
+- Livewire component logic / state (use `livewire` skill)
+- React + shadcn (use `react-shadcn-ui` skill)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
+
+## Procedure: Create a Flux view
+
+### Step 0: Inspect
+
+1. Confirm Flux is installed — check `composer.json` for `livewire/flux`.
+2. Check existing views — match Flux component usage patterns.
+3. Check Flux docs — https://fluxui.dev/docs for latest API.
+
+### Step 1: Build the view
+
+1. Use `<flux:*>` components instead of raw HTML.
+2. Use `variant` prop for styling (not custom Tailwind for standard styles).
+3. Use `wire:model` for Livewire binding.
+4. Use `label` prop on form fields (accessibility).
+
+### Step 2: Validate
+
+1. No raw HTML form elements where Flux equivalents exist.
+2. No manual error rendering (Flux has built-in validation display).
+3. No conflicting Tailwind classes overriding Flux styles.
+
+## Conventions
+
+→ See guideline `php/flux.md` for component reference, variants, forms, icons.
+
+## Output format
+
+1. Blade view using Flux components with correct props and slots
+2. Livewire component class if interactive behavior is needed
+
+### Review pass — a11y findings + preview envelope
+
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
+  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
+  pre-existing entries on replay. Omit the envelope on apply passes; the
+  engine's `_apply_a11y_gate` only fires when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
+
+## Gotcha
+
+- The model tends to use old Flux API syntax — always check latest docs.
+- Flux has built-in validation display — don't add manual error rendering alongside it.
+- Don't mix Flux with raw HTML form elements in the same form.
+
+## Do NOT
+
+- Do NOT use raw `<input>`, `<select>`, `<button>` when Flux equivalents exist.
+- Do NOT override Flux styles with conflicting Tailwind — use variants or slots.
+- Do NOT skip the `label` prop on form fields — accessibility.
+
+## Auto-trigger keywords
+
+- Flux UI
+- Livewire components
+- Flux component
+- Laravel Flux

package/dist/agent-src/skills/jira-integration/SKILL.md

@@ -0,0 +1,187 @@
+---
+model_tier: medium
+name: jira-integration
+description: "Use when the user says \"check Jira\", \"create ticket\", \"update issue\", or needs JQL queries, ticket transitions, or branch-to-ticket linking."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Jira Skill
+
+## When to use
+
+Use this skill when:
+- Reading a Jira ticket for context (bug reports, feature requests)
+- Creating new Jira issues from discovered bugs or planned work
+- Transitioning ticket status (e.g., "In Progress" → "In Review")
+- Writing JQL queries to find related issues
+- Linking branches or PRs to Jira tickets
+
+
+Do NOT use when:
+- GitHub Issues (use `github-api` tool directly)
+- Linear or other issue trackers
+
+## Procedure: Work with Jira
+
+1. **Identify action** — Search, read, create, update, or transition a ticket?
+2. **Use the correct endpoint** — See API table below.
+3. **Execute** — Make the API call with required fields.
+4. **Verify** — Confirm the response contains expected data or the ticket was updated.
+
+| Tool | Purpose |
+|---|---|
+| `jira-integration` (GET `/search/jql`) | Search issues with JQL |
+| `jira-integration` (GET `/issue/{key}`) | Read a specific ticket |
+| `jira-integration` (POST `/issue`) | Create a new ticket |
+| `jira-integration` (PUT `/issue/{key}`) | Update a ticket |
+| `jira-integration` (GET `/issue/{key}/transitions`) | Get available status transitions |
+| `jira-integration` (POST `/issue/{key}/transitions`) | Transition ticket status |
+| `jira-integration` (POST `/issue/{key}/comment`) | Add a comment |
+| `jira-integration` (GET `/project`) | List projects |
+| `jira-integration` (GET `/field`) | List available fields (check before writing JQL) |
+
+## Branch-to-ticket detection
+
+Extract ticket IDs from branch names automatically:
+
+```
+feat/DEV-1234/user-notifications  →  DEV-1234
+fix/DEV-5678/null-pointer         →  DEV-5678
+hotfix/DEV-999/critical-fix       →  DEV-999
+```
+
+Pattern: `[A-Z]+-[0-9]+` anywhere in the branch name.
+
+Use `git branch --show-current` to detect, then fetch the ticket:
+
+```
+jira GET /issue/DEV-1234
+```
+
+## JQL patterns
+
+### Common queries
+
+```jql
+# My open tickets
+assignee = currentUser() AND status != Done ORDER BY priority DESC
+
+# Tickets in current sprint
+project = DEV AND sprint in openSprints() AND assignee = currentUser()
+
+# Recently updated bugs
+project = DEV AND type = Bug AND updated >= -7d ORDER BY updated DESC
+
+# Tickets by component
+project = DEV AND component = "Import" AND status != Done
+```
+
+### Tips
+
+- Always check available fields first: `GET /field`
+- Use `currentUser()` for the authenticated user
+- Use `sprint in openSprints()` for current sprint
+- JQL is case-insensitive for field names but case-sensitive for values
+
+## Creating tickets
+
+### Required fields
+
+Always check issue types first: `GET /issue/createmeta/{project}/issuetypes`
+
+Minimum fields for creation:
+- `project` — project key (e.g., `DEV`)
+- `issuetype` — issue type (Bug, Task, Story, etc.)
+- `summary` — short title
+
+### Description format (ADF)
+
+Jira uses Atlassian Document Format for descriptions:
+
+```json
+{
+  "version": 1,
+  "type": "doc",
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Description text here." }
+      ]
+    }
+  ]
+}
+```
+
+### Attribution
+
+Always add attribution when creating issues or comments:
+
+```
+Co-authored by Augment Code
+```
+
+With link to `https://www.augmentcode.com/?utm_source=atlassian&utm_medium=jira_issue&utm_campaign=jira`
+
+## Status transitions
+
+Before transitioning, always get available transitions first:
+
+```
+GET /issue/DEV-1234/transitions
+```
+
+Then transition with the correct ID:
+
+```json
+POST /issue/DEV-1234/transitions
+{ "transition": { "id": "31" } }
+```
+
+**Important:** Never transition without explicit user permission (see `rules/no-commit.md` — same principle applies to ticket status changes).
+
+## Linking to PRs
+
+When creating PRs, include the Jira ticket in:
+- **Branch name:** `feat/DEV-1234/description`
+- **PR title:** `feat(DEV-1234): description`
+- **PR description:** Link to the ticket
+
+## Related
+
+- **Skill:** `bug-analyzer` — uses Jira as input source for bug investigation
+- **Skill:** `feature-planning` — uses Jira for feature context
+- **Command:** `/bug-investigate` — auto-detects Jira tickets from branch
+- **Command:** `/feature-plan` — auto-detects Jira tickets from branch
+- **Rule:** `no-commit.md` — never change ticket status without permission
+
+
+## Output format
+
+1. Jira ticket data presented in structured format
+2. Ticket key, summary, status, and relevant fields
+
+## Gotcha
+
+- Jira field names are case-sensitive in JQL — `status` works, `Status` doesn't.
+- Don't create duplicate tickets — always search first with JQL before creating.
+- The model tends to forget that Jira description uses ADF (Atlassian Document Format), not Markdown.
+- `accountId` is required for assignee — display name alone doesn't work in the API.
+
+## Do NOT
+
+- Do NOT change ticket status without explicit user permission.
+- Do NOT create tickets without checking for duplicates.
+
+## Auto-trigger keywords
+
+- Jira
+- ticket
+- issue
+- JQL
+- workflow transition
+- sprint

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

@@ -0,0 +1,95 @@
+---
+model_tier: medium
+name: lint-skills
+description: "Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata."
+domain: process
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 120
+  allowed_tools: []
+  command:
+    - python3
+    - src/scripts/skill_linter.py
+    - "--all"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# lint-skills
+
+## When to use
+
+Use this skill when:
+
+- Validating the shape of every skill and rule in `.agent-src.uncondensed/`
+- Verifying execution metadata (`execution.type`, `handler`, `command`) is well-formed
+- Checking locally before opening a PR that CI's skill-lint job will pass
+- Investigating a reported linter failure on a specific skill or rule
+
+Do NOT use when:
+
+- Linting only one file — call `python3 src/scripts/skill_linter.py <path>` directly
+- Checking cross-references between files — use `check-refs` instead
+- Checking condensation freshness — use `bash scripts/condense.sh --check` instead
+
+## Procedure
+
+### 1. Inspect the environment
+
+Confirm `python3` is available and the working directory is the agent-config
+repository root — the linter expects to find `.agent-src.uncondensed/skills/`
+and related directories relative to `cwd`.
+
+### 2. Dispatch via the runtime layer
+
+Invoke the skill through the runtime dispatcher so the `execution:` block in
+this skill's frontmatter governs the call:
+
+```bash
+python3 scripts/runtime_dispatcher.py run --skill lint-skills
+```
+
+The dispatcher resolves the request, the shell handler runs
+`python3 src/scripts/skill_linter.py --all`, captures stdout/stderr, and returns
+a typed `ExecutionResult`.
+
+### 3. Verify the result
+
+Check the returned `ExecutionResult`:
+
+- `status: success` and `exit_code: 0` → all skills and rules are clean
+- `exit_code: 1` → warnings only — review `stdout` for the listed warnings
+- `exit_code: 2` → errors present — fix the flagged files before continuing
+- `status: timeout` → the linter exceeded `timeout_seconds` — investigate
+- `status: error` → the interpreter could not launch — check that `python3`
+  is on `PATH` and the repository root is the current working directory
+
+## Output format
+
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of skills and rules the linter inspected, if known
+3. List of files with errors (first 10), each with code and message
+4. Next action: fix errors, re-run, or surface the raw `stdout` for review
+
+## Gotchas
+
+- The command uses `--all`, which walks the full tree — expect several seconds
+  of runtime on a warm repo; bump `timeout_seconds` if the repo has grown
+- Running outside the agent-config repo root will make the linter report zero
+  skills, which looks like a pass but is actually a no-op
+- Warnings (`exit_code: 1`) do not fail CI by default; do not dismiss them as
+  "green" when the task is to get to zero warnings
+
+## Do NOT
+
+- Do NOT invoke `src/scripts/skill_linter.py` directly when the intent is to test
+  the runtime path — use the dispatcher so the handler and result object are
+  exercised
+- Do NOT raise `timeout_seconds` to hide a genuinely slow linter pass —
+  investigate the slowdown first
+- Do NOT add shell redirection or pipes to `command` — the handler runs
+  `subprocess.run` with `shell=False`; only argv form is supported