@event4u/agent-config 5.10.0 → 6.0.0

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

@@ -0,0 +1,188 @@
+---
+model_tier: high
+name: authz-review
+description: "Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows."
+personas:
+  - security-engineer
+  - backend-architect
+domain: quality
+recommended_for_user_types: [developer, ops]
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# authz-review
+
+
+> **Grounded corpus (Tier-1 consultation):** the threat corpus's
+> `authorization` + `tenancy` rows (IDOR, mass-assignment escalation,
+> unscoped queries, sealed job context — each with negative tests) come
+> from `ground.py ground --manifest
+> <skills-root>/threat-modeling/data/manifest.json "<check under review>"`.
+> Cite corpus rows in findings; surface the evidence gap when no row.
+
+> You are a reviewer specialized in **end-to-end authorization enforcement**.
+> Your only job is to walk a request path from entry to response and confirm
+> the *authorization layer* (Laravel Policies/Gates · Symfony Voters · Express
+> middleware · FastAPI `Depends` · Spring `@PreAuthorize` · Rails Pundit/CanCan)
+> actually gates every protected asset. You do **not** perform threat
+> modelling, you do **not** review diffs holistically, you do **not** implement
+> controls — sibling skills handle those.
+
+## When to use
+
+* A change adds or modifies permission checks, roles, or ownership rules
+* A change exposes a new route, action, or admin-only capability
+* A query fetches tenant-scoped or user-scoped records and you must confirm scope
+* A bug report mentions "user A saw user B's data" or "non-admin accessed admin page"
+* `security-sensitive-stop-rule` fires on an auth/tenant/ownership code path
+
+Do NOT use when:
+
+* The change has no trust boundary crossing — skip entirely
+* You need a pre-implementation risk model — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* A full codebase authorization audit is requested — route to
+  [`security-audit`](../security-audit/SKILL.md)
+* The concern is a diff ready for review — route to
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md)
+* The concern is response/log leakage rather than access gating — route to
+  [`data-exposure-review`](../data-exposure-review/SKILL.md)
+* The concern is implementing a control once identified — route to
+  [`security`](../security/SKILL.md)
+
+## Procedure
+
+### 1. Pick the entrypoints under review
+
+Collect the route(s), action(s), or job(s) in scope for this review. Read the
+task description, open ticket, or user request — do not invent scope. If the
+entrypoint list is unclear, stop and ask.
+
+### 2. Inspect each path end-to-end
+
+For every entrypoint, analyze the authorization chain and record what you find:
+
+| Stage | What to confirm |
+|---|---|
+| Route / binding | HTTP method, URL, controller/handler, middleware chain |
+| Authentication gate | Is login enforced? By which middleware / guard? |
+| Authorization layer | Which policy, gate, voter, or check? Which action/ability? |
+| Data scope | Does the query filter by current user / tenant / owner? |
+| Response filter | Are sensitive fields stripped (resource/serializer/DTO)? |
+| Tests | Is there a negative test (other-tenant / lower-role returns 403/404)? |
+
+Record **what is there**, not what should be there. Use file:line citations.
+
+### 3. Surface the gaps
+
+For every gap, answer:
+
+- Which stage is missing or weak?
+- Which actor can exploit it? (anonymous · authenticated non-owner · wrong tenant · lower role)
+- Concrete impact? (cross-tenant read, privilege escalation, horizontal escalation)
+- Minimum control to add? (policy method, scope, middleware, resource transform)
+- Required negative test assertion?
+
+Do **not** list generic findings ("should use policies") — always anchor to a
+file:line and a specific actor who can reach the gap.
+
+## Validation
+
+Before finalizing the report, confirm:
+
+1. Every entrypoint in scope is walked through **all six stages** of the table
+2. Every 🔴 finding names: stage · actor · impact · missing control · required test
+3. Every 🔴 finding cites at least one file path with line number
+4. You have NOT listed stages that are already correctly enforced as findings
+5. You have NOT confused authentication with authorization in any finding
+6. You have NOT proposed exploit payloads, bypass chains, or offensive steps
+
+## Output format
+
+```
+Skill:   authz-review
+Targets: <routes / actions / jobs, one per line>
+
+Per-entrypoint walk:
+  <METHOD /route> — <controller@action>  (file:line)
+    Auth gate:           <middleware/guard>   ✅/⚠️/❌
+    Authorization:       <policy#ability>     ✅/⚠️/❌   (file:line)
+    Data scope:          <scope/where>        ✅/⚠️/❌   (file:line)
+    Response filter:     <resource/serializer> ✅/⚠️/❌  (file:line)
+    Negative test:       <test path or "—">   ✅/⚠️/❌
+
+Findings (prioritized):
+  🔴  <name> — entrypoint · stage · actor
+      Impact: <concrete damage>
+      Missing control: <what to add, where>
+      Required test: <negative assertion, test file>
+  🟡  ...
+  🟢  ...
+
+Implementation plan:
+  1. <control>, <file/layer>
+  2. ...
+
+Missing tests:
+  1. <assertion>, <test file>
+```
+
+Severity: 🔴 reachable by external or cross-tenant/cross-user actor with
+current privileges / 🟡 reachable only by elevated actor or requires
+partial compromise / 🟢 defense-in-depth hardening, not a live exploit path.
+
+Required fields (ordered):
+
+1. **Skill** and **Targets** — entrypoints in scope
+2. **Per-entrypoint walk** — six-stage table per entrypoint with file:line citations
+3. **Findings** — prioritized, each with entrypoint · stage · actor · impact · missing control · required test
+4. **Implementation plan** — ordered controls mapped to files/layers
+5. **Missing tests** — ordered negative assertions
+
+Runtime confirmation (e.g. *"reproduce the cross-tenant read against staging"*,
+*"query the DB to prove scope leakage"*) is a follow-up for the implementer —
+**this skill does not execute tools, run requests, or touch the database**.
+
+## Gotcha
+
+* **Authentication ≠ authorization.** A logged-in user is not an authorized
+  user. Auth gate green does not make authorization green.
+* **Implicit tenancy via current session** — `Auth::user()->posts` looks safe
+  but breaks the moment an admin impersonation or service-account path bypasses it.
+* **Query scope bypass through relations** — `$user->load('orders.customer')`
+  can leak a sibling tenant if the `customer` relation has no scope.
+* **Resource/serializer leakage** — the policy gated the action; the resource
+  still exposed `internal_notes`. Response filter is a distinct stage.
+* **"Route middleware covers it"** — middleware enforces auth, not per-record
+  authorization. Still need the policy + scope.
+* **Generic advice without file:line** — reject your own finding if you cannot
+  cite the exact location.
+
+## Do NOT
+
+* NEVER return `clean` out of politeness when gaps exist — list them even if the change "probably works"
+* NEVER silently fall back to generic advice when you cannot locate a stage — mark it `❌ not found` with the file you searched
+* NEVER approve a 🔴 finding without a named required negative test
+* NEVER propose exploit payloads, bypass chains, or offensive verification steps — if asked, stop per `never-help-build-offensive-cyber-capability`
+* NEVER treat "only admins reach this" as a control without proof the admin gate is enforced at this stage for this request
+* NEVER rubber-stamp authentication middleware as if it enforced per-record authorization
+
+## References
+
+- **OWASP ASVS v4.0.3** — Chapter V4 Access Control, especially V4.1
+  (General Access Control Design) and V4.2 (Operation-level Access Control).
+  [owasp.org/www-project-application-security-verification-standard/](https://owasp.org/www-project-application-security-verification-standard/)
+- **OWASP Top 10 2021 — A01 Broken Access Control** — canonical failure modes
+  (IDOR, missing function-level checks, forced browsing, metadata tampering).
+  [owasp.org/Top10/A01_2021-Broken_Access_Control/](https://owasp.org/Top10/A01_2021-Broken_Access_Control/)
+- **NIST SP 800-53 AC family** — AC-3 Access Enforcement, AC-6 Least Privilege
+  — rubric for "minimum control" recommendations.
+  [csrc.nist.gov/projects/risk-management/sp800-53-controls](https://csrc.nist.gov/projects/risk-management/sp800-53-controls/release-search#!/800-53)
+- [`threat-modeling`](../threat-modeling/SKILL.md),
+  [`data-exposure-review`](../data-exposure-review/SKILL.md),
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
+  [`security`](../security/SKILL.md),
+  [`security-audit`](../security-audit/SKILL.md) — sibling review / impl skills.

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/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