@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/audit-fe-api/SKILL.md

@@ -0,0 +1,458 @@
+---
+name: audit-fe-api
+description: >
+  Audit frontend API calls against backend implementation for contract alignment
+  and network shape. Use when "API audit", "FE-BE contract", or "review frontend
+  API integration". Live 4xx/5xx reproduction → debug-fe-be-integration.
+license: MIT
+effort: high
+---
+
+# Frontend API Audit Skill
+
+**Degree of freedom: MIXED** — Steps 0, 1, 3–6 `[HIGH freedom]`; Step 2
+Sentry queries and schema SQL `[LOW freedom — run exactly]`.
+
+Read-only. Present findings; the Phase 6 snippets are the fix shape to
+recommend, not edits to make in this pass.
+
+## How to reason
+
+1. **Observe** — quote the FE call site, BE route, and response/error
+2. **Interpret** — does the contract match (path, method, params, types)?
+3. **Classify** — missing route / mismatch / untyped / cache-gap / correct
+4. **Severity** — 404/401/type-mismatch in prod = Critical; cache/prefetch = opportunity
+
+## Worked example
+
+> **Observe:** `useUser` GETs `/api/users/${id}`; no `app/api/users/[id]/route.ts`;
+> Sentry 25× 404 in 14d.
+> **Interpret:** FE calls a route the BE never registered.
+> **Classify:** missing route (Critical).
+> **Severity:** Critical — guaranteed 404.
+> **Finding:** `hooks/useUser.ts` | GET `/api/users/:id` | Critical | no BE route.
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Evidenced** — FE file + BE route or Sentry event, not "probably 500"
+2. **Contract, not taste** — staleTime advice needs a freshness reason
+3. **Severity justified** — Critical = broken contract in prod
+4. **Right owner** — live 4xx/5xx repro → `debug-fe-be-integration`; DB shape → `audit-db-schema`
+5. **Both sides named** — every mismatch lists FE file and BE path (or NOT FOUND)
+
+---
+
+## Step 0: Auto-Detect API Layer
+
+### 0a. Detect Frontend Stack
+
+| Dependency | Technology |
+|------------|-----------|
+| `@tanstack/react-query` | TanStack Query (React Query) |
+| `swr` | SWR |
+| `@reduxjs/toolkit` with `createApi` | RTK Query |
+| `axios` | Axios HTTP client |
+| `ky` | Ky HTTP client |
+| `ofetch` or `$fetch` | Nuxt/ofetch |
+| `@trpc/client` | tRPC (type-safe RPC) |
+| `graphql-request` or `@apollo/client` | GraphQL |
+| `openapi-fetch` or `openapi-typescript` | OpenAPI typed client |
+
+### 0b. Detect Backend Stack
+
+
+```
+Glob: **/app/api/**/route.ts → Next.js App Router API routes
+Glob: **/pages/api/**/*.ts → Next.js Pages Router API routes
+Glob: **/src/routes/**/*.ts → Express/Hono/Fastify routes
+Glob: **/server/api/**/*.ts → Nuxt server routes
+Glob: **/src/app.py → Flask/Django
+Glob: **/main.go → Go backend
+```
+
+### 0c. Find API Service Files
+
+```
+Glob: **/services/*api*.ts → API service files
+Glob: **/services/*service*.ts → Service files
+Glob: **/api/*.ts → API client files
+Glob: **/hooks/use*.ts → Custom hooks (may contain API calls)
+Glob: **/lib/api*.ts → API client config
+Glob: **/features/*/api.* → Feature-specific API files
+```
+
+### 0d. Detect Dev Server Port
+
+```
+Grep: "dev" in package.json scripts → extract port (3000, 3001, 5173, 8080, etc.)
+Grep: "PORT" in .env or .env.local
+```
+
+### 0e. Record Discovery
+
+```
+API LAYER DISCOVERY:
+- HTTP client: [axios/fetch/ky/ofetch]
+- State management: [TanStack Query/SWR/RTK Query/none]
+- API style: [REST/GraphQL/tRPC]
+- Backend framework: [Next.js API routes/Express/Hono/etc.]
+- API service files: [list paths]
+- API hooks: [list paths]
+- Dev server: http://localhost:[port]
+- API docs: [path or URL if detected]
+```
+
+---
+
+## Step 1: Research API Best Practices
+
+### 1a. Context7 — Library Documentation
+
+```json
+context7:resolve-library-id
+{
+ "libraryName": "<DETECTED_LIBRARY>",
+ "query": "caching deduplication error handling best practices"
+}
+```
+
+```json
+context7:query-docs
+{
+ "libraryId": "<RESOLVED_ID>",
+ "query": "staleTime cacheTime retry error handling optimistic updates"
+}
+```
+
+Run for each major dependency (e.g., `@tanstack/react-query`, `axios`, `zod`).
+
+### 1b. Firecrawl — Current API Patterns
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<FRAMEWORK> API integration best practices [current year]",
+ "limit": 5,
+ "sources": [{ "type": "web" }]
+}
+```
+
+| Topic | Query |
+|-------|-------|
+| Caching | `<state library> caching strategy staleTime production` |
+| Error handling | `<framework> API error handling patterns retry` |
+| Type safety | `<framework> type-safe API client OpenAPI Zod` |
+| Performance | `frontend API request optimization batching deduplication` |
+
+---
+
+## Step 2: Check Production API Errors (Sentry)
+
+### 2a. Find API-Related Production Errors
+
+```json
+sentry:search_issues
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "query": "API errors 4xx 5xx fetch axios network from the last 14 days",
+ "projectSlugOrId": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "limit": 25
+}
+```
+
+### 2b. Find Slowest API Calls
+
+```json
+sentry:search_events
+{
+ "organizationSlug": "<ORG_SLUG>",
+ "projectSlug": "<PROJECT_SLUG>",
+ "regionUrl": "<REGION_URL>",
+ "dataset": "spans",
+ "query": "span.op:http.client",
+ "sort": "-span.duration",
+ "limit": 15
+}
+```
+
+### 2c. Cross-Reference with Frontend Code
+
+For each Sentry error: identify the endpoint, `Grep` the FE caller, check error/retry/types.
+
+---
+
+## Phase 3: Discover Frontend API Calls
+
+### 3a. Find All API Calls
+
+Grep (not bash grep):
+
+```
+Grep: pattern "fetch\(|axios\.|api\.(get|post|patch|put|delete)" glob "*.{ts,tsx,js,jsx}"
+Grep: pattern "useQuery|useMutation|useInfiniteQuery|useSuspenseQuery" glob "*.{ts,tsx}"
+Grep: pattern "createApi|injectEndpoints" glob "*.{ts,tsx}"
+```
+
+### 3b. Create API Call Inventory
+
+
+| File | Function/Hook | Method | Endpoint | Params | Used By |
+|------|---------------|--------|----------|--------|---------|
+| `services/user.ts` | `getUsers` | GET | `/api/users` | `page`, `limit` | `UserList.tsx` |
+| `hooks/useUser.ts` | `useUser` | GET | `/api/users/:id` | `id` | `UserProfile.tsx` |
+
+---
+
+## Phase 4: Validate Against Backend
+
+### 4a. Check Endpoint Existence
+
+```
+Grep: pattern "<ENDPOINT_PATH>" glob "*.{ts,js,py,go,rb}" — in backend source
+```
+
+App Router: `app/api/<path>/route.ts` must exist.
+
+### 4b. Check Parameter Correctness
+
+| Check | How |
+|-------|-----|
+| Required params sent | Compare FE call params with BE validation schema (Zod, Yup, Joi) |
+| Naming convention match | FE camelCase vs BE snake_case — check if transform exists |
+| Type match | FE sends string but BE expects number, or vice versa |
+| Body shape match | Compare FE request body with BE expected schema |
+
+### 4c. Verify Schema with Supabase MCP
+
+If the backend reads from Supabase, verify the DB schema matches what the frontend expects:
+
+```json
+supabase:execute_sql
+{
+ "query": "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = '<TABLE>' ORDER BY ordinal_position"
+}
+```
+
+Compare columns/types to FE TypeScript interfaces.
+
+---
+
+## Phase 5: Identify Issues
+
+### Critical Issues
+
+| Issue | Impact | Detection |
+|-------|--------|-----------|
+| Endpoint does not exist | 404 errors | Grep backend for route — not found |
+| Missing required parameter | 500/422 errors | Compare FE params with BE schema |
+| Wrong HTTP method | 405 errors | FE uses GET, BE expects POST |
+| Auth header missing | 401 errors | Check API client interceptor |
+| Type mismatch | Runtime errors | FE interface vs BE response shape |
+
+### Warnings
+
+| Issue | Impact | Detection |
+|-------|--------|-----------|
+| Parameter name mismatch | Silently ignored params | camelCase vs snake_case comparison |
+| Deprecated endpoint | Future breakage | Version markers in BE routes |
+| Missing error handling | Poor UX | useQuery without error state handling |
+| No loading state | Poor UX | No `isLoading` / `isPending` check |
+
+### Optimization Opportunities
+
+| Issue | Impact | Detection |
+|-------|--------|-----------|
+| Duplicate requests | Wasted bandwidth | Same queryKey in multiple components |
+| No caching configured | Slow UX | `staleTime` not set (default 0) |
+| No request batching | Too many requests | N+1 query pattern in lists |
+| Missing prefetch | Slow navigation | No prefetchQuery on hover/focus |
+| No optimistic updates | Slow mutations | Mutation waits for server response |
+
+---
+
+## Phase 6: Frontend Optimizations
+
+### 6a. Caching Strategy
+
+```typescript
+// Per-query staleTime based on data freshness needs
+const { data } = useQuery({
+ queryKey: ['user', userId],
+ queryFn: () => getUser(userId),
+ staleTime: 1000 * 60 * 10, // User data: 10 minutes
+});
+
+const { data: settings } = useQuery({
+ queryKey: ['settings'],
+ queryFn: getSettings,
+ staleTime: Infinity, // Settings rarely change
+});
+```
+
+### 6b. Optimistic Updates
+
+```typescript
+const mutation = useMutation({
+ mutationFn: updateUser,
+ onMutate: async (newData) => {
+ await queryClient.cancelQueries({ queryKey: ['user', userId] });
+ const previous = queryClient.getQueryData(['user', userId]);
+ queryClient.setQueryData(['user', userId], newData);
+ return { previous };
+ },
+ onError: (_err, _newData, context) => {
+ queryClient.setQueryData(['user', userId], context?.previous);
+ },
+ onSettled: () => {
+ queryClient.invalidateQueries({ queryKey: ['user', userId] });
+ },
+});
+```
+
+### 6c. Prefetching
+
+```typescript
+const prefetchUser = (userId: string) => {
+ queryClient.prefetchQuery({
+ queryKey: ['user', userId],
+ queryFn: () => getUser(userId),
+ });
+};
+
+// On hover or focus
+<Link onMouseEnter={() => prefetchUser(userId)} to={`/users/${userId}`}>
+ View User
+</Link>
+```
+
+### 6d. Error Handling
+
+```typescript
+const { data, error, isError, isLoading } = useQuery({
+ queryKey: ['users'],
+ queryFn: getUsers,
+ retry: 3,
+ retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
+});
+
+if (isLoading) return <Skeleton />;
+if (isError) return <ErrorDisplay error={error} />;
+if (!data?.length) return <EmptyState message="No users found" />;
+```
+
+### 6e. Response Validation (Zod)
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+ id: z.string().uuid(),
+ email: z.string().email(),
+ name: z.string(),
+ createdAt: z.string().datetime(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+const getUser = async (id: string): Promise<User> => {
+ const response = await api.get(`/api/users/${id}`);
+ return UserSchema.parse(response.data);
+};
+```
+
+---
+
+## Output Template
+
+```markdown
+## Frontend API Audit Report
+
+**Audited:** [date]
+**Framework:** [detected framework]
+**API client:** [detected client]
+**State management:** [detected library]
+
+---
+
+### Production Error Summary (Sentry)
+
+| Endpoint | Error | Frequency | Has Error Handling |
+|----------|-------|-----------|-------------------|
+| [endpoint] | [error type] | [events/week] | [YES/NO] |
+
+---
+
+### Critical Issues (Must Fix)
+
+#### 1. [Endpoint/File] — [Issue Type]
+- **Current:** `[current implementation]`
+- **Problem:** [description]
+- **Fix:** `[correct implementation]`
+
+---
+
+### Warnings (Should Fix)
+
+#### 1. [Issue description]
+- **File:** `[file path]`
+- **Impact:** [what could go wrong]
+- **Recommendation:** [how to fix]
+
+---
+
+### Optimization Opportunities
+
+#### 1. Caching
+- **Missing staleTime:** [list endpoints]
+- **Recommendation:** [suggested values per data type]
+
+#### 2. Prefetching
+- **Candidates:** [navigation links that could prefetch]
+
+#### 3. Batching
+- **N+1 patterns found:** [list]
+- **Backend batch endpoint exists:** [YES/NO]
+
+---
+
+### API Inventory
+
+| Endpoint | Method | Frontend File | Backend Route | Status | Notes |
+|----------|--------|---------------|---------------|--------|-------|
+| `/api/users` | GET | `user-service.ts` | `app/api/users/route.ts` | VALID | — |
+| `/api/reports` | GET | `report-hook.ts` | NOT FOUND | MISSING | Remove or implement |
+
+---
+
+### Type Safety Status
+
+| Service | Typed Response | Zod Validation | Notes |
+|---------|---------------|----------------|-------|
+| `user-service.ts` | YES | NO | Add runtime validation |
+| `auth-service.ts` | Partial | NO | Missing error response types |
+
+---
+
+### Research Findings Applied
+- [Pattern]: [how it applies]
+- [Best practice]: [gap identified]
+
+---
+
+### Next Steps
+
+1. [ ] Fix critical: [list]
+2. [ ] Add missing parameters: [list]
+3. [ ] Configure caching: [list with suggested staleTime values]
+4. [ ] Add error handling: [files]
+5. [ ] Add Zod validation: [services]
+```
+
+---
+
+## Related
+
+- `debug-fe-be-integration` — live 4xx/5xx reproduction from BE logs
+- `audit-db-schema` — FE types vs DB columns
+- `debug-sentry-monitor` — production error volume on the same endpoints

package/skills/audit-gate-logic/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: audit-gate-logic
+description: >
+  Read-only audit of CI gate logic: silent bypass, ratchet gaming,
+  required-but-not, duplicate gates. Use when "can CI be bypassed" or "why did
+  a regression pass CI". Cost → audit-cicd. Rule content → audit-doctrine.
+license: MIT
+effort: high
+---
+
+# audit-gate-logic — Does the gate actually stop what it claims?
+
+**Degree of freedom: MIXED** — Phases 0–2.5 `[HIGH freedom]`; Phase 3
+history/probe `[LOW freedom — run exactly]` (no scratch branch unless asked).
+
+Read-only. `audit-cicd` asks "is the pipeline fast, cheap, and safe to run."
+This asks **"does the gate stop what it claims to stop."** A green check is a
+claim. The expensive failures are the ones where CI passed and shouldn't have.
+
+Present findings. Do not edit workflows, branch protection, or baselines.
+Consolidation of the archaeology map → `housekeep-gates`. Rule-to-mechanical
+gaps → `enhance-agent-guardrails`. Whether the *rule content* is right
+(remedy, named token, Tier-D practice) → `audit-doctrine`.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **audit-gate-logic** (this) | Bypass, ratchet integrity, conflicts, required-vs-actual, archaeology map |
+| `housekeep-gates` | *Executes* the map — aggregator, delete losers, prove |
+| `audit-cicd` | Pipeline cost, speed, storage, runner safety |
+| `workflow-quality-gate` | *Runs* the pre-release sweep — does not audit its soundness |
+| `enhance-agent-guardrails` | *Installs* new gates; does not audit existing gate logic |
+| `burndown-full` / `workflow-green-repo` | Execute MATCH/DONE or green the repo — ratchet holes stay here |
+| `audit-codemod-safety` | Bulk-transform behavior; if CI waved a semantic bug through, that is also a finding here |
+| `test-mutation` | Assertion-strength gate this map should name if coverage is the only test metric |
+
+**Degrade honestly.** Highest-value "is it actually required" checks need
+branch-protection / rulesets via the repo settings API (`gh api`), not just
+YAML. If settings are invisible, audit the workflow files and say so — you
+can still catch `continue-on-error` and ratchet classes, but you cannot
+confirm the required-check list.
+
+## How to reason
+
+1. **Observe** — quote the `if:`, `continue-on-error`, required-check list, or history
+2. **Interpret** — can a merge go green while the claimed check did not run or failed?
+3. **Classify** — silent bypass / ratchet game / conflict / archaeology / correct-as-is
+4. **Severity** — ships-broken-green = critical
+
+## Worked example
+
+> **Observe:** `lint` job has `continue-on-error: true` and is the only
+> required status check named "Lint".
+> **Interpret:** lint can fail and the required check still reports success.
+> **Classify:** silent bypass (`continue-on-error`).
+> **Severity:** critical — ships-broken-green.
+> **Finding:** lint | continue-on-error | critical | `.github/workflows/ci.yml:24`
+
+---
+
+## Phase 0 — Map every gate and its enforcement  [HIGH freedom]
+
+Inventory the full gating surface, not just the obvious jobs:
+
+- **Workflows & jobs** (`.github/workflows/*`, or GitLab/CircleCI equivalent):
+  each job, its triggers (`on:`), its `if:` conditions, path/branch filters.
+- **Required status checks** (branch protection / rulesets): which checks
+  *actually* block merge vs which merely run.
+- **Ratchets / baselines**: coverage floors, lint-error baselines, bundle
+  budgets, type-error counts, MATCH/DONE burndown, `workflow-green-repo`
+  green baseline.
+- **Pre-commit / pre-push hooks**: local gates that may not mirror CI.
+- **Bot gates**: CodeRabbit / Sonar / Danger — block vs advise.
+
+For each gate record: what it checks, what happens on failure (block / warn /
+silently pass), and whether it is enforced server-side or only by convention.
+
+---
+
+## Phase 1 — Silent-bypass failure modes  [HIGH freedom]
+
+**`continue-on-error` / soft failure** — `continue-on-error: true`, `|| true`,
+`exit 0` swallowing, or `if: always()` masking a failure. The check runs,
+"passes", and enforces nothing.
+
+**Required-in-name-only** — Runs in CI but is not in the required list →
+mergeable while failing. Or a required check whose *job* can be skipped
+(`if:`) so it reports success-by-absence. A skipped required check often
+counts as passed.
+
+**Path/branch filters that skip the wrong changes** — `paths:` /
+`paths-ignore:` that exclude a gate for the files that needed it (security
+scan skips `.github/`, so a PR that disables the scan is not scanned).
+Filters that never run on the default branch, or only on PRs and not on
+direct pushes.
+
+**Condition conflicts** — Two workflows whose `if:` / triggers **both fire**
+on the same event (duplicate work, race on a shared resource, contradictory
+status posts) or **both skip** (each assumes the other ran). Missing
+concurrency groups so two runs race and the loser's failure is discarded.
+
+**Fork / permissions bypass** — `pull_request_target` running privileged with
+untrusted code, or gates that do not run on external-contributor PRs.
+
+**Event mismatch** — Gate triggers on `push` but merges use squash/PR (or
+vice versa), so the enforced commit was never the gated one.
+
+---
+
+## Phase 2 — Ratchet and baseline soundness  [HIGH freedom]
+
+**One-way that isn't** — Can the baseline be regenerated in the same PR that
+regresses (`--update-snapshot`, `coverage --update-baseline` committed
+alongside the drop), locking the regression in as the new floor? Baseline
+moves should be a separate, reviewed act.
+
+**Exclusion gaming** — Coverage/lint passes because the dropped files are in
+`.eslintignore`, `coveragePathIgnorePatterns`, or `// istanbul ignore`. A
+ratchet that measures a shrinking surface always passes.
+
+**Threshold vs reality** — Floor so far below actual that a real drop still
+clears it (60% gate, 90% actual → 89% "passes"). Global thresholds hiding
+per-file collapse. Bundle budgets set above current so growth is free.
+
+**Baseline staleness / drift** — Never regenerated (no longer reflects the
+codebase) or auto-regenerated every run (never actually ratchets).
+
+**Direction bugs** — Comparison operator backwards (passes when *worse*), or
+comparing against `main` after `main` already absorbed the regression.
+
+**Burndown ratchet integrity** — Can MATCH/DONE mark an item DONE without
+verification evidence? Can the count go down (work un-done) without failing?
+Cross-check `completion-judge` / `burndown-full`.
+
+---
+
+## Phase 2.5 — Gate archaeology (accreted gates from multiple sessions)  [HIGH freedom]
+
+Gates accumulate: each dev, agent session, or "let's add a check" iteration
+layers another workflow without removing the last. Audit the *set*:
+
+**Duplicate gates, different vintages** — Two+ jobs checking the same
+thing (two lint jobs with disagreeing configs, ESLint and Biome both
+wired, an old `test.yml` and a newer `ci.yml` both running the suite).
+For each pair: which actually blocks, whether configs disagree, which is
+vestigial.
+
+**Competing baselines / ratchets** — Multiple floors for one metric (jest
+threshold + codecov + a committed floor), updated at different times. The
+agent satisfies whichever loaded; the strictest one silently stopped
+being the real gate.
+
+**Hook-vs-CI divergence** — Pre-commit / pre-push enforcing a different
+ruleset than CI, so "passes locally" and "passes CI" are different claims
+and people learn `--no-verify`.
+
+**Dead gates** — Triggers that can no longer fire (renamed branches,
+removed paths, disabled but not deleted). Still cost comprehension:
+every reader must reason about a gate that does nothing.
+
+**Best-of selection** — For each duplicate cluster, name the winner:
+
+1. Server-side-enforced beats convention
+2. Aggregator-gate pattern (one required check that `needs:` all others) beats N scattered required checks
+3. Merge-queue-compatible (`merge_group` + matching check names) beats PR-only
+4. Auto-tightening ratchet with reviewed resets beats a static threshold
+5. AST / structural checks beat regex greps
+6. Owned + recently maintained beats abandoned
+
+Record winner + losers per cluster — this is the input `housekeep-gates`
+executes.
+
+---
+
+## Phase 3 — Verify against history (where possible)  [LOW freedom — do not invent a branch]
+
+Where CI history is inspectable, look for a merged PR that introduced a
+failure the gate should have caught. Each one is a proven hole, not a
+hypothetical.
+
+Optional cheap probe on a **scratch branch the user already has**: introduce
+a deliberate violation the gate claims to catch and confirm it blocks. A
+gate never tested against a real violation has unknown efficacy. Do not
+create that branch or push it unless the user asked.
+
+---
+
+## Definition of Done
+
+- [ ] Every gate inventoried with on-failure behavior and server-side vs convention
+- [ ] All `continue-on-error` / soft-fail / `always()` masking found
+- [ ] Required-check list cross-checked against what actually runs — or explicitly skipped because settings were invisible
+- [ ] Path / branch / event filters checked for excluding the changes that most need gating
+- [ ] Cross-workflow both-fire / both-skip / races surfaced; concurrency groups checked
+- [ ] Fork / `pull_request_target` / external-PR bypass assessed
+- [ ] Every ratchet checked for same-PR overwrite, exclusion gaming, slack threshold, staleness, direction bug
+- [ ] Burndown / completion ratchet integrity checked against its evidence requirement
+- [ ] History scanned for regressions-shipped-green; deliberate-violation probe noted or skipped with reason
+- [ ] Duplicate-gate clusters, competing baselines, hook-vs-CI divergence, and dead gates mapped; a winner named per cluster
+- [ ] Read-only — findings presented, gates not edited; consolidation handed to `housekeep-gates`
+
+## Self-critique before reporting  [LOW freedom — do not skip]
+
+1. **Evidenced** — YAML line, `gh api` result, or merged PR — not "probably bypassable"
+2. **Settings honesty** — if branch protection was invisible, say so; do not invent the required list
+3. **Severity justified** — critical = ships-broken-green
+4. **Right owner** — consolidation → `housekeep-gates`; cost → `audit-cicd`
+5. **Winner named** — every duplicate cluster has a winner + why
+
+## Output format
+
+1. **Gate inventory** — gate | checks what | on-failure (block/warn/silent) | enforced where
+2. **Bypass findings** — gate | failure mode | severity (critical = ships-broken-green) | evidence
+3. **Ratchet findings** — ratchet | weakness | can it lock in / be gamed? | fix
+4. **Conflict map** — workflow A × workflow B | both-fire / both-skip / race
+5. **Archaeology map** — duplicate cluster | members | winner (+ why) | losers to retire
+6. **Proven holes** — merged PR / probe that passed a gate it shouldn't have
+7. **Fix plan** — silent-bypass first, then ratchet integrity, then conflicts. Consolidation → `housekeep-gates`; pipeline-side → `audit-cicd`; rule-to-mechanical gaps → `enhance-agent-guardrails`. Present and stop.