claude-code-pilot 3.2.0 → 3.3.0

package/src/skills/prisma-patterns/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: prisma-patterns
+description: Prisma ORM patterns for TypeScript backends — schema design, query optimization, transactions, pagination, and critical traps like updateMany returning count not records, $transaction timeouts, migrate dev resetting the DB, @updatedAt skipped on bulk writes, and serverless connection exhaustion.
+origin: ECC
+---
+
+# Prisma Patterns
+
+Production patterns and non-obvious traps for Prisma ORM in TypeScript backends.
+Tested against Prisma 5.x and 6.x. Some behaviors differ from Prisma 4.
+
+Check the Prisma version before applying version-specific patterns:
+
+```bash
+npx prisma --version
+```
+
+Prisma 5 introduced `relationJoins`, which can load relations via JOIN rather than separate queries depending on query strategy and configuration. The `omit` field modifier and `prisma.$extends` Client Extensions API were also added. Note: `relationJoins` can cause row explosion on large 1:N relations or deep nested `include` — benchmark both approaches when relations may return many rows per parent.
+
+## When to Activate
+
+- Designing or modifying Prisma schema models and relations
+- Writing queries, transactions, or pagination logic
+- Using `updateMany`, `deleteMany`, or any bulk operation
+- Running or planning database migrations
+- Deploying to serverless environments (Vercel, Lambda, Cloudflare Workers)
+- Implementing soft delete or multi-tenant row filtering
+
+## Core Concepts
+
+### ID Strategy
+
+| Strategy | Use When | Avoid When |
+|---|---|---|
+| `@default(cuid())` | Default choice — URL-safe, sortable, no collisions | Sequential IDs needed for external systems |
+| `@default(uuid())` | Interoperability with non-Prisma systems required | High-write tables (random UUIDs fragment B-tree indexes) |
+| `@default(autoincrement())` | Internal join tables, audit logs | Public-facing IDs (exposes record count) |
+
+### Schema Defaults
+
+```prisma
+model User {
+  id        String    @id @default(cuid())
+  email     String    @unique  // @unique already creates an index — no @@index needed
+  name      String
+  role      Role      @default(USER)
+  posts     Post[]
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+  deletedAt DateTime?
+
+  @@index([createdAt])
+  @@index([deletedAt, createdAt]) // composite for soft-delete + sort queries
+}
+```
+
+- Add `@@index` on every foreign key and column used in `WHERE` or `ORDER BY`.
+- Declare `deletedAt DateTime?` upfront when soft delete is a foreseeable requirement — adding it later requires a migration on a live table.
+- `updatedAt @updatedAt` is set automatically by Prisma on `update` and `upsert` only (see Anti-Patterns for bulk update trap).
+
+### `include` vs `select`
+
+| | `include` | `select` |
+|---|---|---|
+| Returns | All scalar fields + specified relations | Only specified fields |
+| Use when | You need most fields plus a relation | Hot paths, large tables, avoiding over-fetch |
+| Performance | May over-fetch on wide tables | Minimal payload, faster on large datasets |
+| Prisma 5 note | Uses JOIN by default (`relationJoins`) | Same |
+
+```ts
+// include — all columns + relation
+const user = await prisma.user.findUnique({
+  where: { id },
+  include: { posts: { select: { id: true, title: true } } },
+});
+
+// select — explicit allowlist
+const user = await prisma.user.findUnique({
+  where: { id },
+  select: { id: true, email: true, name: true },
+});
+```
+
+Never return raw Prisma entities from API responses — map to response DTOs to control exposed fields:
+
+```ts
+// BAD: leaks passwordHash, deletedAt, internal fields
+return await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// GOOD: explicit DTO mapping
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+return { id: user.id, name: user.name, email: user.email };
+```
+
+### Transaction Form Selection
+
+| Situation | Use |
+|---|---|
+| Independent operations, no inter-dependency | Array form |
+| Later step depends on earlier result | Interactive form |
+| External calls (email, HTTP) involved | Outside transaction entirely |
+
+```ts
+// Array form — batched in one round trip
+const [user, post] = await prisma.$transaction([
+  prisma.user.update({ where: { id }, data: { name } }),
+  prisma.post.create({ data: { title, authorId: id } }),
+]);
+
+// Interactive form — use tx client only, never the outer prisma client
+const post = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUniqueOrThrow({ where: { id } });
+  if (user.role !== 'ADMIN') throw new Error('Forbidden');
+  return tx.post.create({ data: { title, authorId: user.id } });
+});
+```
+
+### PrismaClient Singleton
+
+Each `PrismaClient` instance opens its own connection pool. Instantiate once.
+
+```ts
+// lib/prisma.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
+  });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+```
+
+The `globalThis` pattern prevents duplicate instances during hot reload (Next.js, nodemon, ts-node-dev).
+
+### N+1 Problem
+
+Loading relations inside a loop issues one query per row.
+
+```ts
+// BAD: N+1 — one extra query per user
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+
+// GOOD: single query
+const users = await prisma.user.findMany({ include: { posts: true } });
+```
+
+With Prisma 5+ `relationJoins`, the `include` form uses a single JOIN. On large 1:N sets this may increase result set size — benchmark both approaches if the relation can return many rows per parent.
+
+## Code Examples
+
+### Cursor Pagination (preferred for feeds and large datasets)
+
+```ts
+async function getPosts(cursor?: string, limit = 20) {
+  const items = await prisma.post.findMany({
+    where: { published: true },
+    orderBy: [
+      { createdAt: 'desc' },
+      { id: 'desc' }, // secondary sort prevents unstable pagination on duplicate timestamps
+    ],
+    take: limit + 1,
+    ...(cursor && { cursor: { id: cursor }, skip: 1 }),
+  });
+
+  const hasNextPage = items.length > limit;
+  if (hasNextPage) items.pop();
+
+  return { items, nextCursor: hasNextPage ? items[items.length - 1].id : null };
+}
+```
+
+Fetch `limit + 1` and pop — canonical way to detect `hasNextPage` without an extra count query. Always include a unique field (e.g. `id`) as a secondary `orderBy` to prevent unstable pagination when multiple rows share the same timestamp. Use offset pagination only when users need to jump to arbitrary pages (admin tables).
+
+### Soft Delete
+
+```ts
+// Always filter explicitly — do not rely on middleware (hides behavior, hard to debug)
+const activeUsers = await prisma.user.findMany({ where: { deletedAt: null } });
+
+await prisma.user.update({ where: { id }, data: { deletedAt: new Date() } });
+await prisma.user.update({ where: { id }, data: { deletedAt: null } }); // restore
+```
+
+### Error Handling
+
+```ts
+import { Prisma } from '@prisma/client';
+
+try {
+  await prisma.user.create({ data: { email } });
+} catch (e) {
+  if (e instanceof Prisma.PrismaClientKnownRequestError) {
+    if (e.code === 'P2002') throw new ConflictError('Email already exists');
+    if (e.code === 'P2025') throw new NotFoundError('Record not found');
+    if (e.code === 'P2003') throw new BadRequestError('Referenced record does not exist');
+  }
+  throw e;
+}
+```
+
+Common codes: `P2002` unique violation · `P2025` not found · `P2003` foreign key violation.
+
+Catch at the service boundary and translate to domain errors. Never expose raw Prisma messages to API consumers.
+
+### Connection Pool — Serverless
+
+Embed connection params directly in `DATABASE_URL` — string concatenation breaks if the URL already has query parameters (e.g. `?schema=public`):
+
+```bash
+# .env — preferred: embed params in the URL
+DATABASE_URL="postgresql://user:pass@host/db?connection_limit=1&pool_timeout=20"
+
+# With an external pooler (PgBouncer, Supabase pooler)
+DATABASE_URL="postgresql://user:pass@host/db?pgbouncer=true&connection_limit=1"
+```
+
+```ts
+// Vercel, AWS Lambda, and similar serverless runtimes: cap pool to 1 per instance
+// connection_limit and pool_timeout are controlled via DATABASE_URL
+const prisma = new PrismaClient();
+```
+
+## Anti-Patterns
+
+### `updateMany` returns a count, not records
+
+```ts
+// BAD: result is { count: 2 } — users[0] is undefined
+const users = await prisma.user.updateMany({ where: { role: 'GUEST' }, data: { role: 'USER' } });
+
+// GOOD: capture IDs first, then update, then fetch only the affected rows
+const targets = await prisma.user.findMany({
+  where: { role: 'GUEST' },
+  select: { id: true },
+});
+const ids = targets.map((u) => u.id);
+await prisma.user.updateMany({ where: { id: { in: ids } }, data: { role: 'USER' } });
+const updated = await prisma.user.findMany({ where: { id: { in: ids } } });
+```
+
+Same applies to `deleteMany` — returns `{ count: n }`, never the deleted rows.
+
+### `$transaction` interactive form times out after 5 seconds
+
+```ts
+// BAD: external call inside transaction exceeds 5s default → "Transaction already closed"
+await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUniqueOrThrow({ where: { id } });
+  await sendWelcomeEmail(user.email); // external call
+  await tx.user.update({ where: { id }, data: { emailSent: true } });
+});
+
+// GOOD: external calls outside the transaction
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+await sendWelcomeEmail(user.email);
+await prisma.user.update({ where: { id }, data: { emailSent: true } });
+
+// Only raise timeout when bulk processing genuinely needs it
+await prisma.$transaction(async (tx) => { ... }, { timeout: 30_000 });
+```
+
+### `migrate dev` can reset the database
+
+`migrate dev` detects schema drift and may prompt to reset the DB, dropping all data.
+
+```bash
+# NEVER on shared dev, staging, or production
+npx prisma migrate dev --name add_column
+
+# Safe everywhere except local solo dev
+npx prisma migrate deploy
+
+# Check drift without applying
+npx prisma migrate diff \
+  --from-migrations ./prisma/migrations \
+  --to-schema-datamodel ./prisma/schema.prisma \
+  --shadow-database-url "$SHADOW_DATABASE_URL"
+```
+
+### Manually editing a migration file breaks future deploys
+
+Prisma checksums every migration file. Editing after apply causes `P3006 checksum mismatch` on every environment where the original already ran. Create a new migration instead.
+
+### Breaking schema changes require multi-step migration
+
+Adding `NOT NULL` to an existing column or renaming a column in one migration will lock the table or drop data. Use expand-and-contract:
+
+```bash
+# Step 1: create migration locally, then deploy
+npx prisma migrate dev --name add_new_column   # local only
+npx prisma migrate deploy                       # staging / production
+```
+
+```ts
+// Step 2: backfill data (run in a script or migration job, not in the shell)
+await prisma.user.updateMany({ data: { newColumn: derivedValue } });
+```
+
+```bash
+# Step 3: create the NOT NULL constraint migration locally, then deploy
+npx prisma migrate dev --name make_new_column_required  # local only
+npx prisma migrate deploy                               # staging / production
+```
+
+### `@updatedAt` does not fire on `updateMany`
+
+`@updatedAt` is set automatically only on `update` and `upsert`. Bulk writes leave it stale.
+
+```ts
+// BAD: updatedAt stays at its old value
+await prisma.post.updateMany({ where: { authorId }, data: { published: true } });
+
+// GOOD
+await prisma.post.updateMany({
+  where: { authorId },
+  data: { published: true, updatedAt: new Date() },
+});
+```
+
+### Soft delete + `findUniqueOrThrow` leaks deleted records
+
+`findUniqueOrThrow` throws `P2025` only when the row does not exist in the DB. Soft-deleted rows still exist and are returned without error.
+
+`findUniqueOrThrow` requires a unique constraint field in `where` — adding `deletedAt: null` alongside `id` breaks the type because `{ id, deletedAt }` is not a compound unique constraint. Use `findFirstOrThrow` instead.
+
+```ts
+// BAD: returns soft-deleted user
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// BAD: Prisma type error — { id, deletedAt } is not a unique constraint
+const user = await prisma.user.findUniqueOrThrow({ where: { id, deletedAt: null } });
+
+// GOOD: findFirstOrThrow supports arbitrary where conditions
+const user = await prisma.user.findFirstOrThrow({ where: { id, deletedAt: null } });
+```
+
+### `deleteMany` without `where` deletes every row
+
+```ts
+// BAD: silently wipes the table
+await prisma.post.deleteMany();
+
+// GOOD
+await prisma.post.deleteMany({ where: { authorId: userId } });
+```
+
+## Best Practices
+
+| Rule | Reason |
+|---|---|
+| `migrate deploy` in CI/CD, `migrate dev` only locally | `migrate dev` can reset the DB on drift |
+| Map entities to response DTOs | Prevents leaking internal fields |
+| Catch `PrismaClientKnownRequestError` at service boundary | Translate to domain errors |
+| Prefer `*OrThrow` methods over manual null checks | Throws P2025 automatically; use `findFirstOrThrow` when filtering non-unique fields |
+| `connection_limit=1` + external pooler in serverless | Prevents connection exhaustion |
+| Always provide `where` on `deleteMany` | Prevents accidental table wipe |
+| Set `updatedAt: new Date()` manually in `updateMany` | `@updatedAt` skips bulk writes |
+
+## Related Skills
+
+- `nestjs-patterns` — NestJS service layer that integrates Prisma
+- `postgres-patterns` — PostgreSQL-level indexing and connection tuning
+- `database-migrations` — multi-step migration planning for production
+- `backend-patterns` — general API and service layer design

package/src/skills/production-audit/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: production-audit
+description: Local-evidence production readiness audit for shipped apps, pre-launch reviews, post-merge checks, and "what breaks in prod?" questions without sending repo data to an external audit service.
+origin: community
+---
+
+# Production Audit
+
+Use this skill when the user asks whether an application is ready to ship, what
+could break in production, or what must be fixed before a launch. This is a
+maintainer-safe rewrite of the stale community production-audit idea: it keeps
+the useful production-readiness lens and removes unpinned external execution and
+third-party data sharing.
+
+## When to Use
+
+- The user asks "is this production-ready", "what would break in prod", "what
+  did we miss", "audit this repo", or "ready to ship?"
+- A feature was merged and needs a pre-deploy or post-merge risk pass.
+- A public launch, demo, customer rollout, or investor walkthrough is close.
+- CI is green but the user wants production risk, not only test status.
+- A deployed URL, release branch, PR, or current checkout is available for
+  evidence gathering.
+
+## When Not to Use
+
+- During active implementation when the right lens is line-level secure coding;
+  use `security-review` first.
+- For pure libraries, templates, docs-only repos, or scaffolds unless the user
+  wants packaging/release readiness rather than application readiness.
+- When the user asks for a formal compliance audit. This skill is engineering
+  triage, not legal, financial, medical, or regulatory certification.
+- When the only available evidence is a product idea with no repo, deployment,
+  CI, or runtime surface.
+
+## How It Works
+
+Build the audit from local and user-authorized evidence. Do not run unpinned
+remote code, upload repository contents to third-party services, or call
+external scanners unless the user explicitly approves that specific tool and
+data flow.
+
+Use this order:
+
+1. Establish the release surface.
+2. Read recent changes and current branch state.
+3. Inspect runtime, auth, data, payment, background-job, AI, and deployment
+   boundaries that actually exist in the repo.
+4. Check CI, tests, migrations, environment documentation, and rollback path.
+5. Produce a short ship/block recommendation with specific fixes.
+
+## Evidence Checklist
+
+Start with cheap, local signals:
+
+```text
+git status --short --branch
+git log --oneline --decorate -20
+git diff --stat origin/main...HEAD
+```
+
+Then inspect the project-specific surface:
+
+- Package scripts, CI workflows, release scripts, Docker files, and deployment
+  manifests.
+- API routes, webhooks, auth middleware, background workers, cron jobs, and
+  database migrations.
+- Environment variable documentation and startup checks.
+- Observability hooks, error reporting, logs, health checks, and dashboards.
+- Rollback, seed, migration, and backfill instructions.
+- E2E coverage for the user paths that matter most.
+
+If a deployed URL is in scope, use browser or HTTP checks only against that URL
+and avoid credentialed actions unless the user supplies a safe test account.
+
+## Risk Lenses
+
+### Security And Auth
+
+- Are public routes, API routes, and admin routes clearly separated?
+- Are auth and authorization enforced server-side?
+- Are secrets kept out of client bundles, logs, example output, and checked-in
+  files?
+- Are rate limits, CSRF protections, CORS policy, and upload validation present
+  where the app needs them?
+- Does the AI or agent surface defend against prompt injection, tool abuse, and
+  untrusted content crossing into privileged actions?
+
+### Data Integrity
+
+- Do migrations run forward cleanly and have a rollback or recovery plan?
+- Are destructive migrations, backfills, and data imports staged safely?
+- Do database policies, grants, and service-role boundaries match the app's
+  tenancy model?
+- Are retries idempotent for writes, jobs, and webhook handlers?
+
+### Payments And Webhooks
+
+- Are webhook signatures verified before parsing trusted payload fields?
+- Is each payment, subscription, or fulfillment webhook idempotent?
+- Are replay, duplicate delivery, and out-of-order delivery handled?
+- Are test-mode and live-mode credentials separated?
+
+### Operations
+
+- Can the app start from a clean checkout using documented commands?
+- Are required environment variables named, validated, and fail-fast?
+- Is there a health check that proves dependencies are reachable?
+- Are deploy, rollback, and incident-owner paths documented?
+- Are logs useful without leaking secrets or personal data?
+
+### User Experience
+
+- Are the launch-critical paths covered on desktop and mobile?
+- Are forms usable on mobile without input zoom, layout overlap, or blocked
+  submission states?
+- Do loading, empty, error, and permission-denied states tell the user what
+  happened?
+- Is there a support or recovery path when a critical operation fails?
+
+## Scoring
+
+Use scores to force prioritization, not to imply mathematical certainty.
+
+| Band | Score | Meaning |
+| --- | --- | --- |
+| Blocked | 0-49 | Do not ship until the top risks are fixed |
+| Risky | 50-69 | Ship only behind a small rollout or internal beta |
+| Launchable With Caveats | 70-84 | Ship if owners accept the listed risks |
+| Strong | 85-100 | No obvious launch blockers from available evidence |
+
+Cap the score at `69` if any of these are true:
+
+- Authentication or authorization is missing on sensitive data.
+- Payment or fulfillment webhooks are not idempotent.
+- Required migrations cannot be run safely.
+- Secrets are exposed in client bundles, logs, or committed files.
+- There is no rollback path for a high-impact release.
+
+Cap the score at `84` if CI is not green or the launch-critical path was not
+tested end to end.
+
+## Output Format
+
+Lead with one sentence:
+
+```text
+Production audit: 76/100, launchable with caveats, with webhook idempotency and rollback docs as the two risks to fix before public launch.
+```
+
+Then list:
+
+- `Blockers`: must-fix items before deploy.
+- `High-value fixes`: next fixes if the user wants to improve the score.
+- `Evidence checked`: files, commands, CI, deployed URL, or PRs inspected.
+- `Evidence missing`: what would change confidence if provided.
+- `Next action`: one concrete fix or verification step.
+
+Keep strengths short. The user asked for readiness, so the useful answer is the
+remaining risk and the next action.
+
+## Example
+
+User:
+
+```text
+is this ready to ship?
+```
+
+Response:
+
+```text
+Production audit: 68/100, risky, because Stripe webhooks are verified but not idempotent and there is no rollback note for the pending migration.
+
+Blockers:
+- Add idempotency for `checkout.session.completed` before fulfilling orders.
+- Write and test the rollback path for `20260511_add_billing_state.sql`.
+
+High-value fixes:
+- Add a health check that verifies database and payment-provider reachability.
+- Add one E2E path for upgrade, webhook fulfillment, and billing-page refresh.
+
+Evidence checked:
+- `api/stripe/webhook.ts`
+- `db/migrations/20260511_add_billing_state.sql`
+- GitHub Actions run for the release branch
+
+Next action: Want me to patch webhook idempotency first?
+```
+
+## Anti-Patterns
+
+- Running `npx <package>@latest` or a remote scanner as the default audit path.
+- Uploading source, secrets, customer data, or private topology to an external
+  audit service without explicit approval.
+- Producing a score without naming the evidence checked.
+- Treating green CI as production readiness.
+- Ending with a generic "let me know what you want to do."
+
+## See Also
+
+- Skill: `security-review`
+- Skill: `deployment-patterns`
+- Skill: `e2e-testing`
+- Skill: `tdd-workflow`
+- Skill: `verification-loop`

package/src/skills/security-scan/references/agentshield-policy-exception/candidate-playbook.md

@@ -0,0 +1,49 @@
+# AgentShield Policy Exception Playbook
+
+Candidate id: `sarif-backed-timeboxed-exception-review`
+
+Use this playbook when AgentShield organization-policy output produces a
+finding that may need remediation, a time-boxed exception, or explicit
+enforcement.
+
+## Accepted Path
+
+1. Identify the AgentShield finding id, category, severity, affected file or
+   MCP/hook surface, and policy pack or organization baseline.
+2. Retrieve scanner evidence before judgment:
+   - SARIF/code-scanning result, especially `agentshield-policy/*`
+   - JSON/HTML report evidence
+   - terminal or GitHub Action job-summary counts
+3. Record lifecycle fields for any exception request: owner, ticket, scope,
+   expiry, rationale, and whether it is active, expiring soon, or expired.
+4. Keep expired exceptions rejected or enforced until new evidence exists.
+5. Decide whether immediate remediation is possible. If not, only promote a
+   narrow time-boxed exception tied to the named owner, ticket, scope, and
+   expiry.
+6. Keep AgentShield code, policy packs, enforcement settings, release state,
+   and live security posture out of the read-only evaluator run.
+
+## Rejected Path
+
+Do not blanket suppress a policy category, policy pack, or organization gate
+because a finding is inconvenient.
+
+Do not downgrade critical/high findings without SARIF or report evidence and a
+current owner, ticket, scope, and expiry.
+
+Do not treat expired exceptions as active. Expired means the policy gate should
+remain enforced until a maintainer creates a fresh, bounded exception or fixes
+the underlying issue.
+
+## Minimum Validation
+
+- `npx ecc-agentshield scan --format json`
+- AgentShield SARIF/code-scanning artifact or report evidence
+- `npx ecc-agentshield scan --format html` when executive review evidence is
+  needed
+- Current exception lifecycle fields: owner, ticket, scope, expiry, status
+- `node tests/docs/evaluator-rag-prototype.test.js`
+- `git diff --check`
+
+Record the scanner evidence, lifecycle state, policy-pack source, and
+remediation-versus-exception decision in the maintainer PR body or handoff.

package/src/skills/security-scan/references/agentshield-policy-exception/report.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "ecc.evaluator-rag.report.v1",
+  "scenario_id": "agentshield-policy-exception",
+  "run_id": "2026-05-12-agentshield-policy-exception-prototype",
+  "result": "prototype_passed",
+  "read_only": true,
+  "scores": {
+    "sarif_report_evidence": 0.95,
+    "exception_lifecycle": 0.93,
+    "ownership_specificity": 0.9,
+    "remediation_decision": 0.88,
+    "blanket_suppression_safety": 1
+  },
+  "findings": [
+    {
+      "id": "sarif-report-match-required",
+      "severity": "warning",
+      "summary": "AgentShield policy exceptions must name SARIF or report evidence before a remediation or exception playbook can be promoted."
+    },
+    {
+      "id": "expired-exception-enforcement",
+      "severity": "warning",
+      "summary": "Expired exceptions must remain rejected or enforced; the evaluator cannot treat stale approvals as active evidence."
+    },
+    {
+      "id": "bounded-owner-fields",
+      "severity": "info",
+      "summary": "Accepted exceptions preserve owner, ticket, scope, expiry, policy-pack source, and affected surface fields."
+    }
+  ],
+  "recommended_next_action": {
+    "candidate_id": "sarif-backed-timeboxed-exception-review",
+    "action": "Use the promoted playbook for future AgentShield policy exception requests before changing gates, suppressing categories, or accepting security risk."
+  }
+}