paw

PAW Skill

PAW: quality-enforcement framework between Copilot + codebase. Runs gates on every file edit, blocks tool use until violations fixed. Real-time linter at agent level.

Layout

.github/PAW/          ← Core (runtime, adapters, types, sync)
  hooks/              ← Defaults (copied to .paw/ on sync)
  templates/          ← Assets (skills, agents, prompts, tsconfig)
  adapters/           ← Surfaces (extension, cli, sdk)
  cli/                ← Commands (status, violations, gates, unblock)
  docs/               ← Docs

.paw/                 ← Project install (gitignored)
  hooks/              ← Active (synced from .github/PAW/hooks/)
  gates/              ← Quality gates (*.gate.ts, auto-discovered)
  plugins/            ← Plugins (.paw/plugins/{hook-name}/*.ts)
  config.json         ← Surface + domain config
  paw.sqlite          ← Violation DB
  paw.log             ← Hook log

.pawignore            ← Glob patterns, skip entirely
.github/hooks/hooks.json ← Generated by sync, VS Code reads

Enforcement Loop

1. Agent edits file
2. PostToolUse hook fires → runs gates on file
3. Violations found? → write to paw.sqlite, warn agent
4. Next tool call:
   a. PreToolUse fires → query paw.sqlite
   b. Violations exist + tool NOT on violated file → DENIED
   c. Tool targets violated file (or derived fix) → ALLOWED
5. Agent fixes → PostToolUse re-runs gates → resolved
6. PreToolUse: no violations → all tools unblocked

Deadlock Rules

1. Fix violations immediately

See violation → fix that file BEFORE anything else. Enforcement loop blocks all other tools until file clean.

2. Violations scoped to session

Session A violations ≠ block Session B. No session ID = project-scoped (blocks all).

Project-scoped fix: Anyone can fix. No session ID violation → YOU violated rule + refused fix. As ephemeral agent, no recollection, but fact. FIX with no exceptions. Can't fix → ask user npm run paw:unblock. Last resort.

3. Read-only tools always allowed

read_file, grep_search, file_search, semantic_search, list_dir, get_errors, get_terminal_output, memory, manage_todo_list, vscode_askQuestions, fetch_webpage → never blocked.

4. PAW-ignored files always allowed

Files matching .pawignore or PAW built-ins (.github/PAW/, .paw/) → always editable, even during enforcement.

5. Indirect-fix findings unlock all tools

Gates can mark findings indirectFix: true = can't fix by editing violated file (e.g. missing test → create new file). When ALL violations = indirect-fix → PAW allows all tools.

6. User unblock last resort

npm run paw:unblock clears all violations. Requires password. Last resort only.

.pawignore

A .pawignore file at the project root uses glob syntax (similar to .gitignore) to exclude files from PAW's enforcement. Files matching these patterns:

• Are skipped by PostToolUse (no gates run)
• Are always editable during PreToolUse enforcement
• Are excluded from session-end health checks

Example .pawignore:

node_modules
.next
.git
coverage
dist
temp
.ignore

Built-in exclusions (always ignored, no .pawignore needed):

• .github/PAW/ — framework core
• .paw/ — project install directory

Gates

Gates are quality checks in .paw/gates/*.gate.ts. They implement the QualityGate interface and are auto-discovered (no manifest needed).

Each gate exports: id, name, severity (critical | warning), appliesTo (glob patterns), and a check(context) method returning GateResult.

Critical gates block the agent. Warning gates report but don't block. Individual findings can set indirectFix: true to declare that the fix requires creating a new file rather than editing the violated file — these findings become non-blocking even from critical gates when they're the only violations remaining.

Hooks

Hooks live in .paw/hooks/ and map to Copilot lifecycle events:

• preToolUse.mjs — Runs before each tool call (enforcement)
• postToolUse.mjs — Runs after each tool call (violation detection)
• sessionEnd*.mjs — Runs when the session closes

paw sync copies defaults from .github/PAW/hooks/ and regenerates .github/hooks/hooks.json for VS Code.

Plugins

Project-specific logic in .paw/plugins/{hook-name}/*.ts. Plugins survive paw sync --force (they're not overwritten). They receive the hook input and can return additional messages.

Common Commands

Command	Purpose
npm run paw:install	First-time setup — installs deps, compiles CLI, syncs hooks, inits DB
npm run paw:status	Show PAW status and active violations
npm run paw:violations	List current violations
npm run paw:violations prune	Remove stale/orphaned violations
npm run paw:gates	List available gates
npm run paw:unblock	Emergency: clear all violations (password-protected)

When Extending PAW

• New gate (TypeScript): Create .paw/gates/my-gate.gate.ts implementing QualityGate
• New gate (other language): Create .paw/gates/my-gate.gate.{ext}, add runner to config.json
• New hook: Create .paw/hooks/my-hook.ts, run paw sync to register
• New plugin: Create .paw/plugins/{hook-name}/my-plugin.ts
• Ignore a path: Add pattern to .pawignore
• Suppress a finding inline: Use /* paw:gate:{id}:{rule} ignore */ in the source file

Gate Ignore Directives

To suppress a specific violation in a file, add a paw:gate: ignore comment. This is processed by the PAW orchestrator (pawGates.ts) via gate-ignore.ts — it is not gate-specific code and works for every gate uniformly.

Syntax

/* paw:gate:{id} ignore */                 suppress all rules for that gate (whole file)
/* paw:gate:{id}:{rule} ignore */          suppress one rule for that gate (whole file)
/* paw:gate:{id} ignore-nextline */        suppress next line only
/* paw:gate:{id}:{rule} ignore-nextline */ suppress one rule on next line only
/* paw:gate:* ignore */                    suppress ALL gates (whole file)

Also valid in MDX JSX comments {/* … */} and HTML comments <!-- … -->.

Examples

/* paw:gate:* ignore */
// Use only on generated files — suppresses every gate for the whole file

/* paw:gate:antipatterns:console-log ignore */
// Suppress only the console-log rule from the antipatterns gate

{/* paw:gate:content-format:missing-h1 ignore */}

Rules

• Never use paw:gate:* ignore in hand-authored files. Reserve it for generated output.
• Prefer the narrowest scope: gate:rule over gate:*, ignore-nextline over ignore.
• Never suppress missing-test — create the test file instead.
• health:check-ignore is deprecated. Do not use it in new files.