@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/blade-ui/SKILL.md

@@ -0,0 +1,135 @@
+---
+model_tier: medium
+name: blade-ui
+description: "Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - laravel
+trust:
+  level: professional
+install:
+  default: false
+  removable: true
+---
+
+# blade-ui
+
+> **Grounded stack guidance:** pull idiomatic Do/Don't + docs URLs from the
+> adopted stack corpus before improvising — `ground.py search --manifest
+> <skills-root>/design-intelligence/data/manifest.json --stack laravel "<topic>"`
+> (the `laravel` stack file is Blade/UI-scoped, not general Laravel). See
+> [`design-intelligence`](../design-intelligence/SKILL.md).
+
+## Positioning — dispatched, not standalone
+
+`blade-ui` is the **apply-step executor** for the Blade 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) |
+| Review + polish loop | [`directives/ui/review.py`](../../templates/scripts/work_engine/directives/ui/review.py) + [`polish.py`](../../templates/scripts/work_engine/directives/ui/polish.py) |
+
+## When to use
+
+Cite this skill when:
+
+- `state.stack.frontend == "blade"` (or the project is clearly Blade-only without Livewire / Flux) and `directives/ui/apply.py` dispatches to this skill
+- Editing or creating Blade views, components, partials, layouts, or forms
+
+Do NOT use when:
+
+- API-only endpoints (use `api-endpoint` skill)
+- Livewire components (use `livewire` skill — it composes Blade views internally)
+- Flux UI components (use `flux` skill)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
+
+## Procedure: Create Blade view or component
+
+### Step 0: Inspect
+
+1. Confirm Blade is used — check `resources/views`, components, layouts.
+2. Inspect existing UI patterns — layouts, partials, component naming, CSS conventions.
+3. Check form handling style — old input, validation errors, session flashes, reusable field partials.
+4. Inspect neighboring templates — match indentation, directives, slot usage, classes.
+5. Determine data flow — what belongs in controller/view model vs. template.
+
+### Step 1: Create the template
+
+1. Use the project's existing layout system.
+2. Keep template presentation-focused — no business logic, no DB queries.
+3. Extract repeated sections into partials or components.
+
+### Step 2: Handle forms (if applicable)
+
+1. Follow project's form style for labels, inputs, validation messages.
+2. Use CSRF protection correctly.
+3. Render validation errors consistently.
+4. Preserve user input with `old()` or project conventions.
+5. Reuse existing field components — don't duplicate.
+
+### Step 3: Validate
+
+1. Check escaping — `{{ }}` by default, `{!! !!}` only when explicitly safe.
+2. Check styling — Tailwind utility classes, not inline styles.
+3. Check accessibility — labels for form fields, semantic HTML.
+
+## Conventions
+
+→ See guideline `php/blade-ui.md` for full conventions.
+
+## Output format
+
+1. Blade view or component file(s) following project conventions
+2. Component class (if applicable) with typed props
+
+### 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
+
+- `@include` shares parent scope — components don't. Know the difference.
+- Always use Tailwind utility classes — not inline styles.
+- Don't put business logic in templates — use view composers or Livewire.
+
+## Do NOT
+
+- Do NOT use `{!! !!}` with user input — XSS risk.
+- Do NOT put business logic in Blade templates — use Livewire or view composers.
+- Do NOT use inline styles — use Tailwind utility classes.
+
+## Auto-trigger keywords
+
+- Blade template
+- Blade component
+- Laravel view
+- partial
+- view logic

package/dist/agent-src/skills/blast-radius-analyzer/SKILL.md

@@ -0,0 +1,193 @@
+---
+model_tier: high
+name: blast-radius-analyzer
+description: "Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency."
+personas:
+  - backend-architect
+domain: discovery
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# blast-radius-analyzer
+
+> You are an analyst specialized in **change-impact analysis**.
+> Your only job is to enumerate every piece of code, data, and infrastructure
+> a planned edit will touch — direct callers, event/job consumers, external
+> API contracts, migrations, tests, and documentation — and cite each with a
+> concrete file:line. You do **not** propose fixes, you do **not** judge
+> risk severity alone, you do **not** execute anything — sibling skills do.
+
+## When to use
+
+* Before editing a method, class, or DB column used by more than one caller
+* Before changing an event payload, queue job shape, or scheduled command
+* Before renaming, deleting, or changing the signature of any public API
+* Before altering a migration, seeder, or shared factory/fixture
+* When the implementer says *"just a quick rename"* of something non-local
+
+Do NOT use when:
+
+* The target is a truly local symbol (private method called in one file) —
+  skip, it has no blast radius
+* You need to trace how one data element flows — route to
+  [`data-flow-mapper`](../data-flow-mapper/SKILL.md)
+* You need abuse-case modelling — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* You need a diff-level review — route to
+  [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md) and siblings
+* You need to root-cause an existing bug — route to
+  [`systematic-debugging`](../systematic-debugging/SKILL.md)
+
+## Procedure
+
+### 1. Pin the change under analysis
+
+Name the exact symbol, column, or contract under change — e.g. *"rename
+`Order::grandTotal()` to `Order::totalCents()`"* or *"drop column
+`users.legacy_ref`"*. If the change is unclear, stop and ask. Do not map
+an imagined refactor.
+
+### 2. Identify direct dependencies
+
+Run grep/search for the exact symbol, column, or event name. Enumerate:
+
+| Dependency class | What to collect |
+|---|---|
+| Call sites | Every invocation: `file:line` + containing function/class |
+| Overrides | Subclasses, trait users, interface implementations |
+| Tests | Tests that exercise the symbol directly |
+| Factories / seeders | Code that constructs or populates the target |
+| DB references | Foreign keys, indexes, views, triggers on the column |
+| Config / docs | YAML, JSON, Markdown that name the symbol |
+
+### 3. Inspect indirect dependencies
+
+For each direct dependency, identify second-order fan-out:
+
+- Events emitted by the changed code → listeners and queued jobs
+- Jobs dispatched → workers, failed-job handlers, schedulers
+- API responses → OpenAPI spec, resource classes, external clients
+- DB schema → migrations that assume the column exists, seeders, reports
+
+Stop at second order unless a caller is itself heavily fanned-out (call it
+out explicitly — don't silently chase cascades).
+
+### 4. Score reach and surface risks
+
+For every dependency, mark:
+
+- **Reach:** `local` (≤3 sites) · `module` (one module/bounded context) ·
+  `cross-module` (multiple bounded contexts) · `external` (public API, queue
+  consumer, other service, persisted data)
+- **Risk type:** signature break · behavior change · data migration ·
+  contract change · flaky test surface · none
+- **Owner hint:** module path, codeowner, or team if discoverable
+
+### 5. Consult engineering memory
+
+Via [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
+`retrieve(types=["ownership"],
+keys=<changed paths + changed symbol>, limit=5)`. Surface:
+
+- **Architecture decisions** that constrain the planned change — check the
+  ADR index [`docs/decisions/INDEX.md`](../../../docs/decisions/INDEX.md) and
+  cite the ADR number + the decision verbatim so the report is self-auditing.
+- **Ownership** matches — add these as `owner hint` candidates when
+  the direct grep had no result.
+
+Memory entries are supplementary, never authoritative: a grep miss is
+still a grep miss. Do not infer dependencies from memory alone.
+
+## Validation
+
+Before finalizing the report, confirm:
+
+1. Every listed dependency has a file:line citation — no bare filenames
+2. Call-site count is exact — the output says `7 call sites`, not `several`
+3. Second-order fan-out is bounded — any runaway chain is flagged, not expanded
+4. Every `external` reach has at least one named owner hint or an explicit
+   "owner unknown — ask"
+5. You have NOT invented dependencies that grep did not find
+6. You have NOT merged direct and indirect dependencies — they are listed separately
+
+## Output format
+
+```
+Skill:   blast-radius-analyzer
+Change:  <one-line description of the planned edit>
+
+Direct dependencies (N total):
+  - Call sites (N):
+      <file:line>  <containing function/class>  reach: <local|module|cross-module|external>
+      ...
+  - Overrides (N):
+      <file:line>  <subclass/trait/impl>
+  - Tests (N):   <file:line list>
+  - Factories / seeders (N):   <file:line list>
+  - DB refs (N):   <file:line or schema object>
+  - Config / docs (N):   <file:line list>
+
+Indirect dependencies (2nd order, bounded):
+  - Events → listeners:   <event name> → <listener file:line>
+  - Jobs → workers:       <job name>   → <worker file:line>
+  - API → clients:        <endpoint>   → <resource/spec file:line>
+
+Reach summary:
+  local: N · module: N · cross-module: N · external: N
+
+Risk surfaces:
+  - Signature break:   <list>
+  - Behavior change:   <list>
+  - Data migration:    <list>
+  - Contract change:   <list>
+
+Open questions:
+  - <anything grep could not resolve or owners unknown>
+```
+
+Required fields (ordered):
+
+1. **Skill** and **Change** — one-line edit summary
+2. **Direct dependencies** — grouped by class, each with file:line citations and exact counts
+3. **Indirect dependencies** — 2nd-order only, bounded
+4. **Reach summary** — counts per reach level
+5. **Risk surfaces** — dependencies grouped by risk type
+6. **Open questions** — unresolved items with grep evidence
+
+Runtime confirmation (e.g. *"actually run the test suite to see what breaks"*,
+*"diff the OpenAPI spec"*) is a follow-up for the implementer — **this skill
+does not execute code, run tests, or touch the network**.
+
+## Gotcha
+
+* **Reflection / string-based dispatch** — `call_user_func`, event names as
+  strings, Laravel `resolve($classString)`. Grep the string too, not just the symbol.
+* **Dynamic column access** — `$model->{$field}` or query builder `->get([...])`
+  with variable arrays. A column rename can leak through these.
+* **Trait / mixin fan-out** — overriding a method pulled in via trait affects
+  every class using the trait. Enumerate trait users.
+* **Migration ordering** — the column exists in migration X; migration Y later
+  renames it. Both must change together.
+* **Stopping at first order** — renaming an event without updating the queued
+  job class-name serializer silently drops jobs. Always check event/job fan-out.
+* **Counting fuzzily** — `"about 10 callers"` is not a blast radius. Count exact.
+
+## Do NOT
+
+* NEVER return `safe` out of politeness when external reach exists — mark it clearly
+* NEVER silently fall back to "module-level impact" when grep shows cross-module callers
+* NEVER claim a dependency without a file:line citation from grep output
+* NEVER chase dependencies past 2nd order without explicit scope approval — flag and stop
+
+## References
+
+- **Martin Fowler — "Refactoring: Improving the Design of Existing Code"** (2018)
+  — chapters on *Moving Features Between Objects* and *Organizing Data*
+  define safe rename/move sequences that map onto the reach levels used here.
+  [martinfowler.com/books/refactoring.html](https://martinfowler.com/books/refactoring.html)
+- [`data-flow-mapper`](../data-flow-mapper/SKILL.md),
+  [`threat-modeling`](../threat-modeling/SKILL.md),
+  [`systematic-debugging`](../systematic-debugging/SKILL.md) — sibling analysis skills.

package/dist/agent-src/skills/character-consistency/SKILL.md

@@ -0,0 +1,192 @@
+---
+model_tier: inherit
+name: character-consistency
+description: "Use when a character must stay visually identical across AI video scenes — locks identity tokens (silhouette, palette, wardrobe, prop) in JSON. Triggers 'character lock', 'same character'."
+personas:
+  - hollywood-director
+domain: product
+workspaces:
+  - small-business
+packs:
+  - ai-video
+lifecycle: experimental
+trust:
+  level: experimental
+install:
+  default: false
+  removable: true
+---
+
+# character-consistency
+
+> Lock a character's visual identity into
+> `agents/reference/ai-video/<project>/characters/<id>.json` so every scene
+> reuses the **exact same tokens** verbatim. Downstream skills
+> ([`video-director`](../video-director/SKILL.md),
+> [`pixar-storyteller`](../pixar-storyteller/SKILL.md),
+> [`motion-choreographer`](../motion-choreographer/SKILL.md)) read
+> this file and never paraphrase. Verified by visual regression
+> (pixel similarity ≥ 95%, Phase 6 Step 3).
+
+## When to use
+
+- A multi-scene run names the same character on screen more than
+  once — Character Lock is mandatory before the second scene drafts.
+- A character drift bug landed (face / outfit / prop changed between
+  scenes) — re-lock and rerun the affected scenes.
+- A series, episode, or recurring ad uses the same on-screen identity.
+
+Do NOT use when:
+
+- One-shot scene with no recurring character — overhead is wasted.
+- The "character" is an environment or set (a place, not an
+  entity) — use a `style.json` lock pattern in the project's notes
+  instead. Recurring creatures, vehicles, and hero objects DO get a
+  real lock — pick the matching `subject_class` below.
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Check `agents/reference/ai-video/<project>/characters/` — if a lock already
+   exists for this id, **read it, do not redraft**. Edits require an
+   explicit revision note (Phase 6 visual regression must rerun).
+2. Confirm the character will appear in ≥ 2 scenes; one-shot → skip.
+
+### Step 1: Draft identity tokens
+
+Emit a JSON file at
+`agents/reference/ai-video/<project>/characters/<character-id>.json` with the
+following fields. Every field is mandatory; missing field → fail
+the lock.
+
+```json
+{
+  "id": "kebab-case-id",
+  "name": "Display Name",
+  "subject_class": "humanoid | creature | vehicle | abstract | object",
+  "silhouette": "one-line read of the body shape from 30m",
+  "palette": ["#hex1", "#hex2", "#hex3"],
+  "wardrobe": "garment list, materials, era",
+  "signature_prop": "the one object that travels with them",
+  "posture_default": "how they stand when not acting",
+  "eye_behavior": "blink rhythm, glance habit",
+  "face": "age band, skin tone, hair (length / color / texture), distinguishing marks",
+  "voice_note": "timbre + cadence for native-audio adapters; null if N/A",
+  "reference_frame": "scenes/<id>/frames/<n>.png or null",
+  "version": 1
+}
+```
+
+#### Subject-class token matrix
+
+Field NAMES are fixed (downstream consumers extract them verbatim);
+their SEMANTICS shift per `subject_class`. Missing `subject_class` →
+`humanoid` (back-compat with existing locks). The blueprint layer
+stays subject-agnostic on purpose — it only consumes the rendered
+SUBJECT string; class semantics live here, in the one file the
+drafting agent reads.
+
+| Field | humanoid | creature | vehicle | abstract | object |
+|---|---|---|---|---|---|
+| `silhouette` | body shape from 30m | body shape + locomotion read | hull/body outline | dominant form | outline + scale cue |
+| `wardrobe` | garments, materials, era | integument: fur / scales / skin texture + markings | body panels, livery, decals, wear | motif / texture field | surface finish, material, wear |
+| `signature_prop` | the object that travels with them | anatomical signature (horn, tail tuft, scar) | hood ornament / aerial / charm | recurring sub-form | defining attachment or mark |
+| `posture_default` | how they stand | gait + resting stance | stance / ride attitude | motion signature | resting pose / orientation |
+| `eye_behavior` | blink rhythm, glance habit | eye/ear behavior | lighting signature (headlights, dash glow) | pulse / emission rhythm | highlight + reflection behavior |
+| `face` | age band, skin, hair, marks | head anatomy (muzzle, eyes, dentition) | front fascia (grille, lights) | focal form | defining front / face side |
+| `voice_note` | timbre + cadence | vocalization | engine / motion sound | sound signature | interaction sound |
+
+Universal slots (`id`, `name`, `palette`, `reference_frame`,
+`version`) keep one meaning across all classes.
+
+Worked example — `creature`:
+
+```json
+{
+  "id": "moor-wyrm",
+  "name": "Moor Wyrm",
+  "subject_class": "creature",
+  "silhouette": "low six-limbed serpentine bulk, head held below shoulder line",
+  "palette": ["#2e4a3f", "#c9b458", "#1a1a1a"],
+  "wardrobe": "moss-green plated scales, gold-flecked underbelly, mud-matted ridge fur",
+  "signature_prop": "broken left tusk capped with a brass ring",
+  "posture_default": "coiled low, weight on forelimbs, tail tip always moving",
+  "eye_behavior": "slow horizontal nictitating blink; ears flatten before lunges",
+  "face": "blunt muzzle, four-nostril ridge, amber eyes with horizontal pupils",
+  "voice_note": "sub-bass rumble with clicking overtones; null if scenes are scored only",
+  "reference_frame": null,
+  "version": 1
+}
+```
+
+### Step 2: Reference frame
+
+1. After the first scene renders, copy the highest-quality frame
+   showing the character full-face and full-body to
+   `agents/reference/ai-video/<project>/characters/<id>.ref.png`.
+2. Update `reference_frame` in the JSON to point at it.
+3. Phase 6 visual regression compares every subsequent scene's
+   character frame against this reference (ImageMagick `compare`
+   ≥ 95% similarity).
+
+### Step 3: Validate
+
+1. JSON parses (`jq . characters/<id>.json` exits 0).
+2. All mandatory fields present and non-empty.
+3. `subject_class` (when present) is one of `humanoid | creature |
+   vehicle | abstract | object`; each field reads per the matrix row
+   for that class — a creature lock with a garment list in `wardrobe`
+   is a drafting error, not a style choice.
+4. Palette has ≥ 2 and ≤ 5 hex values.
+5. Downstream skills cite this file by path, never paraphrase its
+   contents.
+
+## Output format
+
+1. **`agents/reference/ai-video/<project>/characters/<id>.json`** — locked
+   identity tokens, schema above.
+2. **`agents/reference/ai-video/<project>/characters/<id>.ref.png`** —
+   reference frame (added after first render).
+3. **`agents/reference/ai-video/<project>/characters/CHANGELOG.md`** — one
+   line per revision: `v<n> · YYYY-MM-DD · reason · scenes-to-rerun`.
+
+## Gotcha
+
+- A non-humanoid lock without `subject_class` reads as humanoid
+  downstream — the lock is structurally weaker and nobody can tell.
+  Always set the class for non-humanoid subjects.
+- The model wants to "improve" identity tokens on each scene —
+  this is the silent drift failure. Tokens are immutable until a
+  revision note bumps `version`.
+- Palette without a count fails downstream — adapters need a small
+  closed set (2–5 hex).
+- `voice_note: null` is explicit; missing the key entirely breaks
+  the schema validator.
+- Reference frame is captured *after* the first successful render,
+  not before — bootstrap scenes have no reference and only the
+  JSON locks them.
+- A revision (`version` bumped) requires Phase 6 visual regression
+  to rerun against every prior scene that used the old version.
+
+## Do NOT
+
+- Do NOT paraphrase identity tokens when drafting scene prompts —
+  copy verbatim or break the lock.
+- Do NOT edit a locked JSON in place without bumping `version` and
+  adding a CHANGELOG line.
+- Do NOT skip the reference frame after the first render — visual
+  regression has nothing to compare against.
+- Do NOT lock a character that appears in only one scene.
+
+## Policies
+
+When a character lock would identify or render a real person, consult before emitting the JSON:
+
+- [`agents/settings/policies/media/likeness.md`](../../../agents/settings/policies/media/likeness.md) — real-person identity tokens require a cited likeness release.
+- [`agents/settings/policies/media/public-figures.md`](../../../agents/settings/policies/media/public-figures.md) — recognised public figures carry the harder gate (publicity rights + transformative-intent).
+- [`agents/settings/policies/media/voice-cloning.md`](../../../agents/settings/policies/media/voice-cloning.md) — when `voice_note` references a real person's voice.
+- [`agents/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — outputs carrying a real-person lock require the non-removable AI-generation disclosure downstream.
+
+Refuse-and-surface the file path; do not silently sanitise the prompt.
+

package/dist/agent-src/skills/check-refs/SKILL.md

@@ -0,0 +1,96 @@
+---
+model_tier: medium
+name: check-refs
+description: "Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions."
+domain: process
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 60
+  allowed_tools: []
+  command:
+    - python3
+    - src/scripts/check_references.py
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# check-refs
+
+## When to use
+
+Use this skill when:
+
+- A skill, rule, command, guideline, or context has been renamed or deleted
+- Linking a newly added artifact from elsewhere in `.agent-src.uncondensed/`
+- Preparing a PR that touches cross-references between agent artifacts
+- CI's `check-refs` job failed and the broken reference needs to be located
+
+Do NOT use when:
+
+- Only the body of a single file changed and no names or paths were touched
+- Checking frontmatter shape or required sections — use `lint-skills` instead
+- Verifying condensed vs uncondensed pairs — use `bash scripts/condense.sh --check` instead
+
+## Procedure
+
+### 1. Inspect the scope of recent changes
+
+Identify whether any artifact was renamed, moved, or removed since the last
+clean run. Cross-reference checks are relevant only when names or paths shift;
+pure body edits cannot break references.
+
+### 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 check-refs
+```
+
+The dispatcher resolves the request, the shell handler runs
+`python3 src/scripts/check_references.py`, captures stdout/stderr, and returns a
+typed `ExecutionResult`.
+
+### 3. Verify the result
+
+Check the returned `ExecutionResult`:
+
+- `exit_code: 0` → all cross-references resolve
+- `exit_code: 1` → at least one broken reference — read `stdout` for file,
+  line, and the offending ref, then fix the source or update the target
+- `status: timeout` → the checker exceeded `timeout_seconds` — investigate
+- `status: error` → interpreter or script missing — confirm `python3` and
+  `src/scripts/check_references.py` are available at the repository root
+
+## Output format
+
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of broken references found, if any
+3. First 10 broken references with `file:line → missing-target`
+4. Next action: fix references, re-run the skill, or surface `stdout` for
+   review
+
+## Gotchas
+
+- The checker is read-only — it never rewrites references, so a clean run
+  after a fix must be produced by re-invoking the skill, not by assumption
+- Running outside the agent-config repo root makes the checker inspect zero
+  files and report a false pass
+- Relative links inside comments or fenced code blocks may still be parsed as
+  references depending on the checker's current rules; do not suppress a
+  broken ref without confirming it is a genuine false positive
+
+## Do NOT
+
+- Do NOT invoke `src/scripts/check_references.py` directly when the intent is to
+  verify the runtime path — always go through the dispatcher so the
+  `ExecutionResult` is produced and inspectable
+- Do NOT raise `timeout_seconds` to mask a slowdown — investigate which part
+  of the tree grew large enough to push past 60 seconds
+- Do NOT add piping or redirection to `command` — the handler uses
+  `shell=False` and will refuse anything outside pure argv form