agent-quality-police 0.2.0

package/.agents/skills/anti-bypass-audit/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: anti-bypass-audit
+description: Audit a diff for type, test, config, and review fraud. Use when a change looks suspicious, when an LLM-generated diff may have hidden bypasses, or before any final approval.
+---
+
+# Objective
+
+Find and report bypasses with short, evidence-based language. This skill is not for rewriting code. It is for blocking unsafe diffs.
+
+## When To Use
+
+- Reviewing TypeScript changes
+- Reviewing tests, helpers, mocks, or config
+- Checking a diff before merge or publication
+
+## When Not To Use
+
+- Greenfield implementation before any diff exists
+
+## Workflow
+
+1. Scan the diff for banned tokens and suspicious structure.
+2. Check whether tests prove behavior or merely confirm implementation.
+3. Check whether config was weakened.
+4. Produce a terse report with findings, evidence, and required correction.
+
+## Quality Criteria
+
+- Findings cite file evidence.
+- Reports separate blockers from optional cleanup.
+- The audit stays hostile to bypasses and calm in tone.
+
+## Banned Diff Signals
+
+- `any`
+- assertions
+- non-null assertions
+- `Map` used as a lookup-bag in public or domain-facing contracts
+- ts-comments
+- `eslint-disable`
+- lowered strictness in config
+- fake narrowing branches
+- helper or factory noise hiding test intent
+- mocks that replace the behavior under test
+
+## Report Format
+
+- `Finding:`
+- `Evidence:`
+- `Required correction:`
+
+## Examples
+
+- Good correction: `examples/good/fixed-bypass.types.ts`, `examples/good/fixed-bypass.ts`
+- Bad diff: `examples/bad/explicit-bypass.ts`
+
+## Checklist
+
+- See `checklists/audit-checklist.md`
+
+## References
+
+- `references/report-format.md`

package/.agents/skills/anti-bypass-audit/checklists/audit-checklist.md

@@ -0,0 +1,7 @@
+# Audit Checklist
+
+- Did you search for banned syntax and weakened config?
+- Did you flag `Map` when it was used to avoid explicit contract modeling?
+- Did you inspect tests for behavior proof instead of implementation detail?
+- Did you reject helper or mock noise when it weakened the claim?
+- Did you end with a blocker-oriented report?

package/.agents/skills/anti-bypass-audit/examples/bad/explicit-bypass.ts

@@ -0,0 +1,32 @@
+export interface LookupHit {
+  kind: 'hit';
+  email: string;
+}
+
+export interface LookupMiss {
+  kind: 'miss';
+}
+
+export type LookupResult = LookupHit | LookupMiss;
+
+export function findCustomerEmail(
+  emailsByCustomerId: Map<string, string>,
+  customerId: string,
+): LookupResult {
+  const rawEmail = emailsByCustomerId.get(customerId) as string;
+
+  if (rawEmail.length === 0) {
+    return { kind: 'miss' };
+  }
+
+  return {
+    kind: 'hit',
+    email: rawEmail!,
+  };
+}
+
+// Reprovado porque:
+// - usa Map para evitar modelar uma entrada nomeada e explícita
+// - mistura interfaces e função no mesmo arquivo, quebrando o padrão adotado aqui
+// - usa assertion para mentir sobre um lookup potencialmente ausente
+// - usa non-null assertion para esconder o caso ausente em vez de modelá-lo

package/.agents/skills/anti-bypass-audit/examples/good/fixed-bypass.ts

@@ -0,0 +1,21 @@
+import {
+  type CustomerEmailLookupInput,
+  type LookupResult,
+} from './fixed-bypass.types';
+
+export function findCustomerEmail(
+  input: CustomerEmailLookupInput,
+): LookupResult {
+  const customerEmail = input.customerEmails.find(
+    (entry) => entry.customerId === input.customerId,
+  );
+
+  if (customerEmail === undefined) {
+    return { kind: 'miss' };
+  }
+
+  return {
+    kind: 'hit',
+    email: customerEmail.email,
+  };
+}

package/.agents/skills/anti-bypass-audit/examples/good/fixed-bypass.types.ts

@@ -0,0 +1,20 @@
+export interface CustomerEmailEntry {
+  customerId: string;
+  email: string;
+}
+
+export interface CustomerEmailLookupInput {
+  customerEmails: readonly CustomerEmailEntry[];
+  customerId: string;
+}
+
+export interface LookupHit {
+  kind: 'hit';
+  email: string;
+}
+
+export interface LookupMiss {
+  kind: 'miss';
+}
+
+export type LookupResult = LookupHit | LookupMiss;

package/.agents/skills/anti-bypass-audit/references/report-format.md

@@ -0,0 +1,9 @@
+# Report Format
+
+## Required Shape
+
+Finding: short label describing the failure
+
+Evidence: file path and the concrete construct that proves the issue
+
+Required correction: the smallest change that removes the bypass without softening the policy

package/.agents/skills/governance-installation/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: governance-installation
+description: Install or update this governance framework in another repository. Use when copying the pack, regenerating projections, or validating that a target repository is aligned with the canonical policy.
+---
+
+# Objective
+
+Install or refresh the framework without letting generated projections drift away from the canonical policy.
+
+## When To Use
+
+- Copying the framework into another repository
+- Updating skills, rules, or agent specs and rebuilding projections
+- Verifying that generated files were refreshed after a policy change
+
+## When Not To Use
+
+- Day-to-day feature work inside a repository that already has the framework installed
+
+## Workflow
+
+1. Copy the canonical files first.
+2. Run `python3 scripts/build_framework.py`.
+3. Run `python3 scripts/validate_framework.py`.
+4. If scripts or package installer sources changed, run `python3 -m unittest tests/test_framework_tools.py` and `node --test tests/node/install.test.mjs`.
+5. Commit only after projections and validation are green.
+
+## Quality Criteria
+
+- Repository entrypoints are generated from the canonical entrypoint source instead of being hand-authored per tool.
+- Canonical and generated layers are both present.
+- `.agents/skills/` matches `.claude/skills/`.
+- Agent projections exist for Claude, OpenCode, and Codex.
+- Package-ready plugin distribution and marketplace metadata exist for Claude and Codex.
+- No placeholders, missing links, or stale projections remain.
+
+## Anti-Patterns
+
+- Hand-maintaining separate root entrypoints for Claude, Codex, and OpenCode
+- Editing generated files by hand
+- Copying only the generated layers and skipping the canonical source
+- Publishing without running build and validation
+
+## Examples
+
+- Good install flow: `examples/good/install-sequence.md`
+- Bad install flow: `examples/bad/stale-projection.md`
+
+## Checklist
+
+- See `checklists/install-checklist.md`
+
+## References
+
+- `references/install-steps.md`

package/.agents/skills/governance-installation/checklists/install-checklist.md

@@ -0,0 +1,6 @@
+# Install Checklist
+
+- Did you copy both canonical and generated layers?
+- Did you rebuild projections after copying?
+- Did you validate structure and links?
+- Did you avoid hand-editing generated outputs?

package/.agents/skills/governance-installation/examples/bad/stale-projection.md

@@ -0,0 +1,12 @@
+# Bad Install Sequence
+
+1. Copy only `.agents/skills/` because it “already works in Codex.”
+2. Skip `.claude/skills/` and `framework/agents/specs/`.
+3. Edit generated agent files directly.
+4. Publish without rebuilding.
+
+Why this is bad:
+
+- The canonical source is gone.
+- The next update cannot be regenerated safely.
+- Different tools will drift apart.

package/.agents/skills/governance-installation/examples/good/install-sequence.md

@@ -0,0 +1,7 @@
+# Good Install Sequence
+
+1. Copy the framework files into the target repository.
+2. Run `python3 scripts/build_framework.py`.
+3. Run `python3 scripts/validate_framework.py`.
+4. Review the diff.
+5. Commit once projections and validation are green.

package/.agents/skills/governance-installation/references/install-steps.md

@@ -0,0 +1,28 @@
+# Install Steps
+
+Copy these paths into the target repository:
+
+- `docs/policy/`
+- `.claude/`
+- `.agents/`
+- `.claude-plugin/marketplace.json`
+- `.opencode/agents/`
+- `.codex/agents/`
+- `plugins/agent-quality-police/`
+- `opencode.json`
+- `scripts/`
+- `tests/`
+
+Canonical source paths that must be present before build:
+
+- `framework/entrypoints/`
+- `framework/agents/specs/`
+- `framework/agents/prompts/`
+- `framework/distribution/`
+- `framework/package/`
+
+Then run the build and validation commands from the repository root.
+
+For package-style global installation after build, use the generated package entrypoint:
+
+- `node plugins/agent-quality-police/bin/aqp.mjs install all`

package/.agents/skills/quality-index/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: quality-index
+description: Navigate this governance framework. Use when the task spans multiple concerns, when you need to choose the right policy skill, or when you need to decide which audit agent must run.
+---
+
+# Objective
+
+Use this skill as the entry point to the framework. It maps task types to the right quality policy, examples, and police agents.
+
+## When To Use
+
+- The task touches more than one policy area.
+- You are unsure which skill to load first.
+- You need to decide which auditor or gatekeeper must run.
+
+## When Not To Use
+
+- The task is already clearly scoped to a single skill and the choice is obvious.
+
+## Workflow
+
+1. Read `docs/policy/quality-definition.md`.
+2. Read `docs/policy/workflow.md`.
+3. Classify the task.
+4. Load only the skills required by that task.
+5. Pair the work with the correct audit agent before final approval.
+
+## Routing
+
+- TypeScript modeling or type repair:
+  read `../typescript-zero-bypass/SKILL.md`
+- Vite or Vitest TDD:
+  read `../vite-vitest-tdd/SKILL.md`
+- React behavior tests:
+  read `../react-public-api-testing/SKILL.md`
+- Suspicious diff review:
+  read `../anti-bypass-audit/SKILL.md`
+- Refactor with legacy uncertainty:
+  read `../refactoring-with-safety/SKILL.md`
+- Installing or updating this framework:
+  read `../governance-installation/SKILL.md`
+
+## Quality Criteria
+
+- The chosen skill set is the smallest set that covers the task.
+- The chosen auditors match the actual risk surface.
+- Canonical policy stays in `docs/policy/`, not in generated projections.
+
+## Anti-Patterns
+
+- Loading every skill by default.
+- Starting implementation before deciding what behavior must be proven.
+- Skipping the auditors because the change “looks small.”
+
+## Examples
+
+- Good routing: `examples/good/task-routing.md`
+- Bad routing: `examples/bad/task-routing.md`
+
+## Checklist
+
+- See `checklists/routing-checklist.md`
+
+## References
+
+- `references/system-entrypoints.md`

package/.agents/skills/quality-index/checklists/routing-checklist.md

@@ -0,0 +1,6 @@
+# Routing Checklist
+
+- Did you read the quality definition first?
+- Did you load the minimum skill set instead of everything?
+- Did you identify which auditor must run?
+- Did you avoid treating generated projections as canonical?

package/.agents/skills/quality-index/examples/bad/task-routing.md

@@ -0,0 +1,15 @@
+# Bad Routing
+
+Task: rename a private helper and add a feature.
+
+Routing mistake:
+
+1. load every skill in the repository
+2. skip tests because the rename is “minor”
+3. ship without `bypass-auditor`
+
+Why this is bad:
+
+- It hides the real feature risk under irrelevant context.
+- It assumes rename and behavior change can share a shortcut.
+- It skips the mandatory audit flow.

package/.agents/skills/quality-index/examples/good/task-routing.md

@@ -0,0 +1,18 @@
+# Good Routing
+
+Task: fix a React bug in a Vite app where the disabled button label is wrong.
+
+Routing:
+
+1. `quality-index`
+2. `typescript-zero-bypass`
+3. `vite-vitest-tdd`
+4. `react-public-api-testing`
+5. Run `tdd-warden`
+6. Run `bypass-auditor`
+7. Run `pr-gatekeeper`
+
+Why this is good:
+
+- It covers typing, behavior testing, and audit.
+- It avoids unrelated skills.

package/.agents/skills/quality-index/references/system-entrypoints.md

@@ -0,0 +1,9 @@
+# System Entrypoints
+
+- `AGENTS.md`: cross-tool root router
+- `CLAUDE.md`: Claude-specific root router
+- `docs/policy/quality-definition.md`: canonical definition of quality
+- `docs/policy/workflow.md`: mandatory execution sequence
+- `.claude/rules/`: always-on policy for Claude
+- `.claude/skills/`: canonical skill source
+- `framework/agents/specs/`: canonical agent source

package/.agents/skills/react-public-api-testing/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: react-public-api-testing
+description: Behavior-focused React component testing through the public API. Use when testing components, hooks through components, or rendered output in a way that must survive refactoring.
+---
+
+# Objective
+
+Test React through what the user can perceive: roles, names, text, states, and callbacks exposed by the component contract.
+
+## When To Use
+
+- Component tests in React or Vite projects
+- Review of suspicious Testing Library queries
+- Replacing brittle DOM-detail assertions
+
+## When Not To Use
+
+- Pure domain functions without UI behavior
+- Low-level rendering details that are not part of the contract
+
+## Workflow
+
+1. Identify the component’s public contract.
+2. Render through the same props a caller would use.
+3. Query by role, accessible name, label text, visible text, or user-visible state.
+4. Assert the observable result.
+5. Reject container selectors and implementation-specific details unless the contract truly exposes them.
+
+## Quality Criteria
+
+- Queries follow the Testing Library priority order.
+- Assertions describe visible outcomes.
+- The test would stay meaningful after a structural refactor that preserves the UI contract.
+- Component examples should prefer inferred return types instead of explicit `JSX.Element`.
+- Optional UI props should use `?` when absence is the intended caller experience.
+
+## Anti-Patterns
+
+- `container.querySelector` for elements that already have an accessible role
+- asserting hook state directly
+- asserting CSS class names when a semantic state is available
+- clicking internal nodes instead of the public control
+- declaring component types in the same file when the example should keep types and implementation separate
+- explicit `JSX.Element` return annotations in React component examples
+- duplicating nearly identical JSX through an early-return branch
+- deriving render state through temporary setup variables when the component contract can express it directly
+- forcing callers to pass `null` when an optional prop expresses absence more clearly
+- unnecessary ternaries in TSX when an explicit branch is clearer
+- building conditional prop-spread objects when direct rendering is simpler
+
+## Examples
+
+- Good component and test: `examples/good/primary-button.types.ts`, `examples/good/primary-button.tsx`, `examples/good/primary-button.test.tsx`
+- Bad component example: `examples/bad/primary-button.component-antipattern.tsx`
+- Bad conditional-setup example: `examples/bad/primary-button.conditional-setup-bloat.tsx`
+- Bad duplicated-branch example: `examples/bad/primary-button.duplicated-branch.tsx`
+- Bad implementation-detail test: `examples/bad/primary-button.internal.test.tsx`
+
+## Checklist
+
+- See `checklists/query-checklist.md`
+
+## References
+
+- `references/query-order.md`

package/.agents/skills/react-public-api-testing/checklists/query-checklist.md

@@ -0,0 +1,5 @@
+# Query Checklist
+
+- Does the test use an accessible query first?
+- Does it assert a public state the caller or user can observe?
+- Would the test still pass after a markup refactor that preserves behavior?

package/.agents/skills/react-public-api-testing/examples/bad/primary-button.component-antipattern.tsx

@@ -0,0 +1,35 @@
+interface PrimaryButtonProps {
+  label: string;
+  disabledReason?: string;
+  onPress(): void;
+}
+
+export function PrimaryButton(props: PrimaryButtonProps): JSX.Element {
+  const isDisabled = props.disabledReason !== undefined;
+  const accessibilityProps = isDisabled
+    ? { 'aria-describedby': 'primary-button-reason' }
+    : {};
+
+  return (
+    <div>
+      <button
+        disabled={isDisabled}
+        onClick={props.onPress}
+        {...accessibilityProps}
+        type="button"
+      >
+        {props.label}
+      </button>
+      {isDisabled ? (
+        <p id="primary-button-reason">{props.disabledReason}</p>
+      ) : null}
+    </div>
+  );
+}
+
+// Reprovado porque:
+// - mistura o tipo do componente com a função no mesmo arquivo
+// - usa `JSX.Element` explicitamente em vez de deixar o retorno ser inferido
+// - usa ternário para montar props condicionais
+// - usa ternário no TSX onde um branch explícito é mais legível
+// - usa prop spread para esconder uma diferença simples de renderização

package/.agents/skills/react-public-api-testing/examples/bad/primary-button.conditional-setup-bloat.tsx

@@ -0,0 +1,32 @@
+import type { PrimaryButtonProps } from '../good/primary-button.types';
+
+export function PrimaryButton(props: PrimaryButtonProps) {
+  const isDisabled = props.disabledReason !== undefined;
+  let describedById: string | undefined;
+
+  if (isDisabled) {
+    describedById = 'primary-button-reason';
+  }
+
+  return (
+    <div>
+      <button
+        aria-describedby={describedById}
+        disabled={isDisabled}
+        onClick={props.onPress}
+        type="button"
+      >
+        {props.label}
+      </button>
+      {isDisabled && (
+        <p id="primary-button-reason">{props.disabledReason}</p>
+      )}
+    </div>
+  );
+}
+
+// Reprovado porque:
+// - cria estado derivado e setup temporário desnecessários para uma renderização simples
+// - espalha a lógica de acessibilidade e de renderização em variáveis intermediárias
+// - mantém um `if` e um `&&` que deveriam ter virado funções explícitas para legibilidade
+// - espalha a intenção entre variáveis intermediárias em vez de manter o contrato explícito

package/.agents/skills/react-public-api-testing/examples/bad/primary-button.duplicated-branch.tsx

@@ -0,0 +1,30 @@
+import type { PrimaryButtonProps } from '../good/primary-button.types';
+
+export function PrimaryButton(props: PrimaryButtonProps) {
+  if (props.disabledReason === undefined) {
+    return (
+      <button onClick={props.onPress} type="button">
+        {props.label}
+      </button>
+    );
+  }
+
+  return (
+    <div>
+      <button
+        aria-describedby="primary-button-reason"
+        disabled
+        onClick={props.onPress}
+        type="button"
+      >
+        {props.label}
+      </button>
+      <p id="primary-button-reason">{props.disabledReason}</p>
+    </div>
+  );
+}
+
+// Reprovado porque:
+// - duplica quase todo o markup do botão em dois branches
+// - espalha a regra de renderização em vez de manter uma estrutura única
+// - torna a manutenção mais frágil sem ganhar legibilidade real

package/.agents/skills/react-public-api-testing/examples/bad/primary-button.internal.test.tsx

@@ -0,0 +1,23 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { PrimaryButton } from '../good/primary-button';
+
+describe('PrimaryButton', () => {
+  it('locks onto internal markup details', () => {
+    const { container } = render(
+      <PrimaryButton
+        disabledReason="Quota reached"
+        label="Save invoice"
+        onPress={() => {}}
+      />,
+    );
+
+    expect(container.querySelector('p')?.textContent).toBe('Quota reached');
+    expect(container.querySelector('button')?.className).toBe('');
+  });
+});
+
+// Reprovado porque:
+// - usa querySelector em vez de API acessível
+// - acopla o teste ao markup interno e a classes

package/.agents/skills/react-public-api-testing/examples/good/primary-button.test.tsx

@@ -0,0 +1,36 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PrimaryButton } from './primary-button';
+
+describe('PrimaryButton', () => {
+  it('renders an enabled public control and calls onPress', () => {
+    const onPress = vi.fn();
+
+    render(
+      <PrimaryButton
+        label="Save invoice"
+        onPress={onPress}
+      />,
+    );
+
+    const button = screen.getByRole('button', { name: 'Save invoice' });
+
+    expect(button).toBeEnabled();
+    fireEvent.click(button);
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders the disabled reason as visible public behavior', () => {
+    render(
+      <PrimaryButton
+        disabledReason="Quota reached"
+        label="Save invoice"
+        onPress={() => {}}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Save invoice' })).toBeDisabled();
+    expect(screen.getByText('Quota reached')).toBeVisible();
+  });
+});

package/.agents/skills/react-public-api-testing/examples/good/primary-button.tsx

@@ -0,0 +1,27 @@
+import type { PrimaryButtonProps } from './primary-button.types';
+
+export function PrimaryButton(props: PrimaryButtonProps) {
+  const isDisabled = props.disabledReason !== undefined;
+
+  function renderDisabledReasonParagraph() {
+    if (!isDisabled) {
+      return null;
+    }
+
+    return <p id="primary-button-reason">{props.disabledReason}</p>;
+  }
+
+  return (
+    <div>
+      <button
+        aria-describedby="primary-button-reason"
+        disabled={isDisabled}
+        onClick={props.onPress}
+        type="button"
+      >
+        {props.label}
+      </button>
+      {renderDisabledReasonParagraph()}
+    </div>
+  );
+}

package/.agents/skills/react-public-api-testing/examples/good/primary-button.types.ts

@@ -0,0 +1,5 @@
+export interface PrimaryButtonProps {
+  label: string;
+  disabledReason?: string;
+  onPress(): void;
+}

package/.agents/skills/react-public-api-testing/references/query-order.md

@@ -0,0 +1,11 @@
+# Query Order
+
+Prefer, in order:
+
+1. `getByRole`
+2. `getByLabelText`
+3. `getByPlaceholderText`
+4. `getByText`
+5. `getByDisplayValue`
+
+Avoid `querySelector` and class selectors when an accessible query can express the same contract.