@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/api-design/SKILL.md

@@ -0,0 +1,120 @@
+---
+model_tier: medium
+name: api-design
+description: "Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design."
+personas:
+  - backend-architect
+domain: engineering
+recommended_for_user_types: [developer, founder]
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# api-design
+
+
+> **Grounded corpus (Tier-1 consultation):** pagination, versioning,
+> error shape (RFC 9457), idempotency, async ops, rate limiting, bulk,
+> naming, expansion, webhooks — `ground.py search --manifest
+> <skills-root>/api-design/data/manifest.json "<concern>"` proposes the
+> grounded pattern (+ hardening + anti-patterns + RFC link) before
+> designing from memory. Corpus: [`data/api-patterns.csv`](data/api-patterns.csv).
+
+## When to use
+
+Use this skill when designing new API endpoints, restructuring existing APIs, or deciding about versioning and deprecation.
+
+Do NOT use when:
+- Implementing an already-designed endpoint (use `api-endpoint` skill)
+- Writing tests for APIs (use `api-testing` skill)
+
+## Procedure: Design an API
+
+1. **Gather context** — read `agents/settings/contexts/api-versioning.md`, `agents/reference/docs/api-resources.md`, `agents/reference/docs/query-filter.md`, `agents/reference/docs/controller.md`, and guideline `php/api-design.md`.
+2. **Identify the resource** — determine the domain entity, its attributes, and relationships. Check existing models and resources for field naming patterns.
+3. **Define endpoints** — list each endpoint with HTTP method, URL path, request body, query parameters, and response structure. Follow existing route file patterns.
+4. **Decide versioning** — determine whether this extends the current version or requires a new version (see decision table below).
+5. **Design error responses** — define 4xx/5xx responses matching the project's existing error format.
+6. **Validate against existing patterns** — compare your design with 2-3 similar existing endpoints. Flag any inconsistencies.
+7. **Run adversarial review** — use `adversarial-review` skill to check for breaking changes, consistency issues, and missing error cases.
+
+## Versioning decisions
+
+### URL-based versioning
+
+Routes versioned via URL prefix: `/api/v1/...`, `/api/v2/...`
+
+```
+routes/api/v1/projects.php  → /api/v1/projects
+routes/api/v2/projects.php  → /api/v2/projects
+```
+
+### Automatic fallback
+
+If a route doesn't exist in the requested version, the system falls back to the next older version. Configured in `config/app.php`:
+
+```php
+'api_versioning' => [
+    'versions' => 'v2,v1',  // newest first
+],
+```
+
+### When to create a new version
+
+| Change type | Action |
+|---|---|
+| Add optional field | Extend current version |
+| Add new endpoint | Add to current version |
+| Remove/rename field | New version |
+| Change field type | New version |
+| Change validation rules | New version |
+
+> If an existing client would break without code changes → **new version required**.
+
+### Deprecation workflow
+
+1. **Mark as deprecated** — add headers: `Deprecation: true`, `Sunset: YYYY-MM-DD`, `Link: <successor>`
+2. **Document** — add to API changelog with sunset date
+3. **Monitor usage** — track clients still using deprecated endpoints
+4. **Remove** — after sunset date, remove route + controller + docs
+
+Minimum 3 months between deprecation and removal.
+
+## Design review
+
+Before presenting an API design, run the **`adversarial-review`** skill.
+Focus on: Breaking changes? Consistency? Error responses?
+
+## Output format
+
+1. Endpoint specification — method, path, request/response structure
+2. Versioning decision with rationale
+3. Error response format following existing project patterns
+
+## Gotcha
+
+- Consistency beats "better" design — check existing patterns first.
+- Always include pagination on list endpoints.
+- Max nesting depth: 2 levels (`/users/{id}/orders/{id}`).
+- Don't version internal APIs only your own frontend consumes.
+- Deprecation without migration path is useless — always provide the replacement.
+- Don't duplicate controllers for new versions — use fallback logic.
+
+## Do NOT
+
+- Do NOT introduce a new response format in an established API — match existing patterns.
+- Do NOT create v2 endpoints without a deprecation plan for v1.
+- Do NOT skip pagination on list endpoints.
+
+## Auto-trigger keywords
+
+- API design
+- REST API
+- endpoint design
+- resource structure
+- response format
+- API versioning
+- deprecation
+- breaking changes

package/dist/agent-src/skills/api-design/data/api-patterns.csv

@@ -0,0 +1,13 @@
+Concern,Keywords,Applies To,Recommended Pattern,Hardening,Anti-Patterns,Docs URL
+Pagination,collection list large dataset paging,REST any scale,"Cursor-based pagination for unbounded/ordered feeds; offset only for small, stable admin tables",Cursor token opaque + signed; include next/prev links (RFC 8288); cap page size server-side,Offset pagination on hot tables (deep-offset scans); exposing raw DB ids as cursors,https://www.rfc-editor.org/rfc/rfc8288
+Versioning,breaking change version v1 v2 deprecate,public REST API,URI major version (/v1/) for public APIs; additive changes within a version; sunset with Deprecation + Sunset headers,Announce ≥6 months; dual-run window; changelog per version,Header-only versioning for public consumers (invisible in logs/docs); breaking within a version,https://www.rfc-editor.org/rfc/rfc8594
+Error shape,error response problem detail validation message,any HTTP API,"RFC 9457 application/problem+json: type, title, status, detail, instance + per-field errors array",Stable machine-readable type URIs; correlation id; never leak stack traces,Bare string bodies; 200-with-error-flag envelopes; localized-only messages,https://www.rfc-editor.org/rfc/rfc9457
+Idempotency,retry duplicate POST payment create network timeout,mutating endpoints,Idempotency-Key header on POST money/resource creation; store key→result with TTL; replay returns first result,Scope keys per principal; 409 on key reuse with different payload,Relying on client dedupe; making POST 'safe' by chance,https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
+Filtering & sorting,filter query search sort fields sparse,collection endpoints,Explicit allowlisted filter/sort params; document operators; reject unknown params with 400 problem+json,Index-backed filters only; combine with cursor pagination,Free-form q= passed to the DB; sort on unindexed columns,https://www.rfc-editor.org/rfc/rfc9110
+Partial update,update patch put field subset,resource endpoints,PATCH with JSON Merge Patch (RFC 7396) for flat resources; full PUT for replace semantics; ETag + If-Match for lost-update protection,412 on stale ETag; document null-vs-absent semantics,PUT that silently merges; PATCH without concurrency control,https://www.rfc-editor.org/rfc/rfc7396
+Async operations,long running job export import 202 status polling,operations >2s,"202 Accepted + operation resource (/operations/{id}) with status, progress, result link; optional webhook on completion",Operation resource is GET-pollable + cacheable; include Retry-After,Holding the connection open; 200 with 'check back later' prose,https://www.rfc-editor.org/rfc/rfc9110#status.202
+Rate limiting,throttle quota 429 rate limit headers,public/partner APIs,429 + RateLimit headers (limit/remaining/reset); per-principal buckets; document burst vs sustained,Distinguish per-IP (anon) vs per-key (auth); Retry-After on 429,Silent throttling; global single bucket; HTML error bodies,https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
+Bulk operations,bulk batch many items import,write-heavy integrations,Dedicated /batch endpoint with per-item status array (multi-status semantics); cap batch size; idempotency key per batch,"Partial success is explicit per item, never all-or-nothing-by-accident",Looping client calls as the documented path; unbounded batch size,https://www.rfc-editor.org/rfc/rfc9110
+Resource naming,naming url path nouns plural kebab,any REST API,"Plural nouns, kebab-case paths, no verbs in URIs (verbs live in HTTP methods or POST /resource/{id}/actions for true RPC)",Stable ids in paths; relationship via sub-resources one level deep,Deep nesting >2 levels; mixed singular/plural; camelCase paths,https://www.rfc-editor.org/rfc/rfc9110
+Field selection & expansion,sparse fieldsets include expand embed n+1,read-heavy APIs,Explicit ?fields= allowlist and ?include= for relationships with a documented max depth,Defaults stay lean; expansion costs documented; guard with per-include query budget,Auto-embedding everything; client-driven unbounded expansion,https://jsonapi.org/format/#fetching-sparse-fieldsets
+Webhook delivery,webhook callback event delivery retry signature,outbound events,"Signed payloads (HMAC + timestamp), exponential backoff retries with dead-letter, event id for consumer idempotency",Document signature scheme + rotation; include event type registry,Fire-and-forget delivery; unsigned payloads; retrying forever,https://www.rfc-editor.org/rfc/rfc2104

package/dist/agent-src/skills/api-design/data/manifest.json

@@ -0,0 +1,34 @@
+{
+  "manifest_version": 1,
+  "domain": "api-design",
+  "tier": "lookup-only",
+  "retriever": "bm25",
+  "default_domain": "patterns",
+  "domains": {
+    "patterns": {
+      "file": "api-patterns.csv",
+      "search_cols": [
+        "Concern",
+        "Keywords",
+        "Applies To",
+        "Recommended Pattern"
+      ],
+      "output_cols": [
+        "Concern",
+        "Applies To",
+        "Recommended Pattern",
+        "Hardening",
+        "Anti-Patterns",
+        "Docs URL"
+      ],
+      "max_results": 3
+    }
+  },
+  "owner": "package-maintainer",
+  "refresh_cadence": "quarterly",
+  "upstream": {
+    "repo": "derived: RFC 9110/9457/7396/8288 + httpapi WG drafts",
+    "sha": "RFC set as of 2026-06",
+    "last_checked": "2026-06-07"
+  }
+}

package/dist/agent-src/skills/api-endpoint/SKILL.md

@@ -0,0 +1,100 @@
+---
+model_tier: medium
+name: api-endpoint
+description: "Use when creating an API endpoint or HTTP route handler — detects the project stack and routes to the matching carve-out (laravel-api-endpoint, nextjs-patterns, symfony-workflow)."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# api-endpoint
+
+
+> **Grounded corpus:** endpoint-shape decisions (pagination, error shape,
+> idempotency, rate limits) ground via the
+> [`api-design`](../api-design/SKILL.md) corpus — `ground.py search
+> --manifest <skills-root>/api-design/data/manifest.json "<concern>"`.
+
+## When to use
+
+Use this skill when the user asks to create a new API endpoint, REST route, or HTTP handler.
+
+Do NOT use when:
+- Modifying existing endpoints — use the code-refactoring skill.
+- API design decisions (versioning, deprecation, contract shape) — use [`api-design`](../api-design/SKILL.md).
+
+## Stack routing
+
+Detect the stack, then hand off to the matching carve-out skill for the framework-specific procedure (file layout, validation primitive, response-shaping convention).
+
+| Detected stack | Carve-out skill |
+|---|---|
+| Laravel (`artisan` + `composer.json` with `laravel/framework`) | [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md) |
+| Symfony (`bin/console` + `composer.json` with `symfony/framework-bundle`) | [`symfony-workflow`](../symfony-workflow/SKILL.md) |
+| Next.js (`next` in `package.json`) | [`nextjs-patterns`](../nextjs-patterns/SKILL.md) |
+| Express / Fastify / NestJS / plain Node | follow project conventions in `agents/` + `package.json scripts` |
+| FastAPI / Django / Flask | follow project conventions in `agents/` + `pyproject.toml` |
+| Go (`net/http`, `gin`, `echo`, `fiber`) | follow project conventions in `agents/` + `go.mod` |
+| Rust (`axum`, `actix-web`, `rocket`) | follow project conventions in `agents/` + `Cargo.toml` |
+
+If the project doc folder (`agents/`) has an endpoint-creation guide, that is the source of truth — read it before generating code.
+
+## Procedure: Create an API endpoint (stack-neutral)
+
+1. **Read project docs** — Check `./agents/` and `AGENTS.md` for endpoint conventions, routing layout, response shape.
+2. **Detect stack** and route to the carve-out per the table above.
+3. **Plan the endpoint** — method, path, request shape, response shape, auth requirement, idempotency.
+4. **Create the route registration** in the project's routing surface (route file, decorator-annotated handler, file-based router).
+5. **Create the request handler / controller** — thin; delegate business logic to a service / use-case.
+6. **Validate input at the boundary** via the framework's validation primitive (FormRequest, Zod, class-validator, Pydantic, struct-tag validators, etc.) — never inline ad-hoc `if` checks.
+7. **Authorize the action** via the framework's authz primitive (Policy, voter, guard, middleware, route dependency).
+8. **Shape the response** through a transformer / serializer / DTO — never return raw ORM entities.
+9. **Document** the endpoint (OpenAPI annotations / generated spec / project doc).
+10. **Verify** — run the project type-checker + targeted tests + smoke probe (`curl` / Bruno / Postman / integration test).
+
+## Conventions (apply on every stack)
+
+- **One handler, one responsibility** — prefer single-purpose handlers over multi-action controllers when the framework supports it.
+- **No business logic in the handler** — delegate to a service / use-case layer.
+- **Validate at the boundary** — never trust raw request data inside the handler.
+- **Authorize every state-changing action** — no unprotected mutating endpoints.
+- **Shape responses through a transformer** — DTO, serializer, API resource, response model — never expose raw ORM entities.
+- **Version the API surface** explicitly (`/v1/`, header, content-type) — don't rely on implicit versioning.
+
+## Stack-specific procedures
+
+For Laravel projects (the most fully-fleshed-out carve-out in this package), see [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md) — covers single-action controllers, `FormRequest`, `Resource`, `Policy`, `CollectionFormRequest`, OpenAPI attributes, and the versioned route layout.
+
+For other stacks, read the matching carve-out from the table above and combine with the project's `agents/` docs.
+
+## Output format
+
+1. Generated files — route registration, handler, request validator, response shaper, authorization rule.
+2. Test file with happy path and validation-error cases (using the project's test framework).
+3. Summary of created files and their locations.
+
+## Gotcha
+
+- Don't forget to register the route — creating the handler without the route is a common miss.
+- Always check if a similar endpoint already exists — duplicates cause confusion.
+- Validation rules must match the documented contract (OpenAPI / schema / typed client) — keep them in sync.
+- Response shapes are part of the public contract — adding a field is additive; renaming or removing is breaking.
+
+## Do NOT
+
+- Do NOT put business logic in the handler — delegate to services / use-cases.
+- Do NOT skip request validation — every handler validates at the boundary via the framework's primitive.
+- Do NOT return raw ORM entities — always go through a transformer / serializer / response model.
+- Do NOT create unprotected state-changing endpoints — authorize every mutation.
+- Do NOT improvise framework idioms — read the carve-out (`laravel-api-endpoint`, `nextjs-patterns`, etc.) for the stack-correct shape.
+
+## Auto-trigger keywords
+
+- create endpoint
+- new API route
+- route handler
+- controller creation
+- REST endpoint
+- add endpoint

package/dist/agent-src/skills/async-python-patterns/SKILL.md

@@ -0,0 +1,158 @@
+---
+model_tier: medium
+name: async-python-patterns
+description: "Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized."
+domain: engineering
+status: active
+refresh_trigger: "Python ships a new structured-concurrency primitive (post-TaskGroup), OR ≥30% of cited upstream cookbook examples become deprecated, OR the cited libraries (aiohttp, httpx, anyio, trio) cut a major version with breaking async surface changes."
+sunset_criterion: "When `https://docs.python.org/3/library/asyncio.html` ships an in-tree decision framework AND consumer projects no longer cite this skill in PR reviews for two consecutive review cycles."
+workspaces:
+  - engineering
+packs:
+  - python
+lifecycle: experimental
+trust:
+  level: professional
+install:
+  default: false
+  removable: true
+---
+
+# async-python-patterns
+
+Decision framework for picking the right Python asyncio primitive. **The pattern cookbook lives upstream** (links in § Provenance) — this skill is the predicate, not the recipe library. Sunset-policy compliant: the 600+ lines of language-specific cookbook stay in authoritative Python docs.
+
+## When to use
+
+- Designing a new async I/O-bound service (FastAPI, aiohttp, async DB client).
+- Reviewing a diff that introduces `asyncio.gather`, `asyncio.create_task`, `TaskGroup`, `as_completed`, or `wait_for`.
+- Mixing sync and async code (calling sync libs from async context, or vice versa).
+- Diagnosing event-loop blocking, never-awaited warnings, or cancellation leaks.
+
+Do NOT use when:
+
+- The work is CPU-bound — async will not help; route to multiprocessing or threadpool.
+- The runtime is not Python — read the host runtime's concurrency guide.
+- The fix is a single missing `await` — read the upstream tutorial directly.
+
+## Decision framework
+
+### Step 1 — Verify async is the right tool
+
+```
+Workload is:
+  I/O-bound, many concurrent waits  → async fits (network, disk, IPC).
+  CPU-bound (parsing, math, crypto) → async is wrong; use ProcessPoolExecutor.
+  Mixed                              → async shell + run_in_executor for CPU bursts.
+  Single sequential call             → don't introduce async; sync is simpler.
+```
+
+### Step 2 — Pick the concurrency primitive
+
+```
+Run N independent coroutines, ALL must complete:
+  Same trust level, exceptions cancel siblings  → asyncio.TaskGroup (3.11+; preferred).
+  Pre-3.11 OR exceptions must NOT cancel peers  → asyncio.gather(*, return_exceptions=...).
+
+Run N coroutines, react to results as they finish:
+  → asyncio.as_completed (yields completed futures in finish order).
+
+Run N coroutines, race to first success / failure:
+  → asyncio.wait(..., return_when=FIRST_COMPLETED) + cancel pending.
+
+Schedule fire-and-forget background work:
+  → asyncio.create_task + keep a strong reference (else GC eats it).
+  Forgetting the reference is the #1 silent-failure source.
+
+Bound the wait time:
+  → asyncio.wait_for(coro, timeout=...)  → raises TimeoutError on expiry.
+  → asyncio.timeout(...) context manager (3.11+; preferred when many awaits share a deadline).
+
+Bound concurrency (rate-limit, connection pool):
+  → asyncio.Semaphore(n); acquire around the awaitable.
+```
+
+### Step 3 — Bridge sync ↔ async correctly
+
+```
+Async code calls sync, blocking, function:
+  Short pure-CPU              → fine, accept the block (microseconds).
+  Long, blocking, or I/O-sync → await loop.run_in_executor(None, fn, *args).
+  Library has async sibling   → switch the library (httpx vs requests, aiosqlite vs sqlite3).
+
+Sync code calls async function:
+  Top-level entrypoint        → asyncio.run(coro()).
+  Inside running loop         → never asyncio.run; create_task + await it.
+  Test suite                  → pytest-asyncio fixture; never raw run() in tests.
+```
+
+### Step 4 — Cancellation discipline
+
+Every long-running coroutine MUST be cancellation-safe:
+
+- Catch `asyncio.CancelledError`, perform cleanup, **re-raise**. Swallowing it silently breaks the propagation chain.
+- Use `try / finally` (or `async with`) around resource acquisition so cancellation cannot leak file handles, DB connections, locks.
+- Detached `create_task` without a strong reference is undefined behavior; either store the task or use a TaskGroup.
+
+### Step 5 — Don't block the event loop
+
+A single blocking call (sync I/O, time.sleep, CPU-heavy parse, large JSON load) freezes every coroutine. Audit every leaf function under `async def`:
+
+- Sleep → `await asyncio.sleep`, never `time.sleep`.
+- HTTP → `httpx.AsyncClient` / `aiohttp`, never `requests`.
+- DB → `asyncpg` / `aiosqlite` / `motor`, never the sync driver.
+- File → `aiofiles` for hot-paths, or `run_in_executor` for one-shots.
+
+## Procedure: Apply to a new async feature
+
+1. Run Step 1; reject if work is CPU-bound.
+2. Sketch the call graph; tag each `await` site with its primitive (Step 2).
+3. Mark every sync↔async boundary; pick the bridge per Step 3.
+4. For each long-running coroutine, write the cancel-safety contract (Step 4).
+5. Grep the leaf calls for blocking sins (Step 5); replace or push to executor.
+6. Hand the sketch to a reviewer **before** coding; cite this skill.
+
+## Output format
+
+1. Call-graph table: coroutine · concurrency primitive · timeout · cancel-safety note.
+2. Sync↔async boundary list: site · bridge · justification.
+3. Blocking-call audit: leaf function · status (async / executor / accepted-block + reason).
+4. Cancel-safety contract for each background task.
+
+## Gotcha
+
+- "It works in my REPL" — `asyncio.run` inside an already-running loop (Jupyter, FastAPI startup) raises `RuntimeError`. Use `await` directly or `nest_asyncio` (last resort).
+- `asyncio.gather` swallows the second exception silently; use `return_exceptions=True` and inspect, or use `TaskGroup` (cancels all on first error, surfaces the group).
+- `create_task` results that nobody awaits look fine until the program exits and Python prints `Task was destroyed but it is pending!`. Always `await` or use a TaskGroup.
+- `wait_for` on a non-cancellation-safe coroutine leaks resources; the timeout cancels the task but cleanup never runs.
+- Libraries that "support async" via thread pools (e.g. `requests-async`) often re-block the loop under load; verify with the cited upstream library docs, not the README.
+
+## Do NOT
+
+- Do NOT call `asyncio.run` from a running loop.
+- Do NOT swallow `CancelledError` without re-raising.
+- Do NOT call sync blocking I/O from async paths without `run_in_executor`.
+- Do NOT spawn `create_task` without storing the reference (or using TaskGroup).
+- Do NOT inline the asyncio cookbook into this skill — externalize per Sunset Policy.
+
+## Auto-trigger keywords
+
+- asyncio
+- async / await
+- gather / TaskGroup / wait_for
+- event loop blocking
+- cancellation
+- sync to async bridge
+
+## Provenance
+
+- Adopted from: an external reference (MIT, © 2025 an external reference) — **Sunset Policy applied**: 694-line cookbook source reduced to a ~140-line decision framework; pattern catalogues externalized to upstream docs below.
+- Externalized cookbook:
+  - asyncio core: https://docs.python.org/3/library/asyncio.html · https://docs.python.org/3/library/asyncio-task.html
+  - TaskGroup (3.11+): https://docs.python.org/3/library/asyncio-task.html#task-groups
+  - Structured concurrency: https://anyio.readthedocs.io · https://trio.readthedocs.io
+  - Async HTTP: https://www.python-httpx.org/async/ · https://docs.aiohttp.org/en/stable/
+  - Async DB: https://magicstack.github.io/asyncpg/ · https://aiosqlite.omnilib.dev/
+- Cross-linked: [`error-handling-patterns`](../error-handling-patterns/SKILL.md), [`mcp-builder`](../mcp-builder/SKILL.md), [`api-design`](../api-design/SKILL.md), [`performance`](../performance/SKILL.md).
+- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `async-python-patterns`).
+- Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.

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.