@jamie-tam/forge 6.0.0

package/skills/quality-code-review/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: quality-code-review
+description: "Use when code has been written — orchestrates the review chain (safety → craft → reachability → gotcha-hunter) with risk-based escalation. Triggers on 'review my code', 'check this PR', 'is this ready', 'audit this diff'. Optional Codex adversarial cross-check fires when consent is on."
+---
+
+# Code Review
+
+## Overview
+
+Code review is not one pass — it is a chain of focused reviewers, each with its own context window. Safety, craft, reachability, and prior-art recall are different bug classes; conflating them dilutes every reviewer. This skill dispatches the chain in sequence, gathers findings, and produces a unified report.
+
+**Core principle:** find what breaks first, then improve what works, then prove what runs, then check what we already learned.
+
+**Announce at start:** "I'm using the quality-code-review skill to review this code."
+
+## When to Use
+
+- After completing a TDD cycle (per-task review).
+- Before creating a PR (final review).
+- When requested for ad-hoc code review.
+- During `/feature`, `/bugfix`, `/refactor` commands at the review phase.
+
+## The Review Chain
+
+Each link in the chain is a separate subagent dispatch. Subagents do not share context — main session aggregates their reports.
+
+```
+[risk-classify] → [code-reviewer]   → [craft-reviewer]   → [support-runtime-reachability] → [gotcha-hunter]   → [Codex adversarial] → [aggregate + decide]
+                  Pass 1: safety      Pass 2: craft        per-slice wiring gate              prior-art recall    optional cross-check
+```
+
+### Step 0: Codex consent
+
+Run the Codex consent flow from `protocols/codex.md` before dispatching. The choice gates Pass 2.5 (adversarial cross-check), not the rest of the chain.
+
+- **Takeover:** Skip Pass 1 + Pass 2; dispatch Codex `adversarial-review` for the entire diff. Continue to reachability after.
+- **Verify:** Run the chain normally; Codex adversarial-reviews Claude's findings at Pass 2.5.
+- **Skip / unavailable:** Run the chain normally; no adversarial step.
+
+### Step 1: Risk classification
+
+Classify before dispatching anything — risk level decides which links of the chain run.
+
+| Risk | Trigger | Chain |
+|---|---|---|
+| **Low** | Style, docs, config, non-functional | code-reviewer (light) + gotcha-hunter |
+| **Medium** | Business logic, API endpoints, data processing, UI with state | full chain |
+| **High** | Auth/authz, payments, PII, encryption, user-input rendering, query construction from user input, SSRF surfaces, new external integrations | full chain + escalate to `quality-security-audit` |
+| **Critical** | Infrastructure, deploy config, DB migrations, CI/CD | full chain + security audit + human approval before merge |
+
+`gotcha-hunter` runs at every risk level — recall is cheap (the agent only reads markdown), and a "config" change that matches a known recurring failure pattern is exactly what the catalog exists to surface. Skip only `craft-reviewer` and `support-runtime-reachability` at low risk.
+
+See **Risk Classification Guide** below for the full mapping.
+
+### Step 2: Pass 1 — code-reviewer (safety)
+
+Dispatch `code-reviewer` subagent. It owns: SQL safety, race conditions, auth boundaries, secret exposure, injection vulnerabilities, data-loss risks, unhandled async errors. Returns `[CRITICAL]` findings and a SAFETY REVIEW SUMMARY.
+
+If `code-reviewer` returns `BLOCK`, halt the chain. Surface findings; require fixes before re-running.
+
+### Step 3: Pass 2 — craft-reviewer
+
+Dispatch `craft-reviewer` subagent. It owns: library idiom adherence (Context7-verified), codebase pattern conformance, stub detection. Returns severity-tagged findings and a CRAFT REVIEW SUMMARY.
+
+`craft-reviewer` does not block the chain on its own — its findings inform the final decision.
+
+### Step 4: Per-slice runtime reachability gate
+
+Invoke the `support-runtime-reachability` skill. It walks the slice diff, finds exports, and verifies each has a production caller (or escape-hatch annotation). Writes the per-slice `runtime-reach` gate result to the manifest.
+
+If the gate fails, halt the chain. Orphan exports must be wired, annotated, or removed before review continues.
+
+### Step 5: Gotcha hunter — prior-art recall
+
+Dispatch the `gotcha-hunter` subagent with the diff scope. It scans `aiwiki/gotchas/` (project) and `~/.claude/gotchas/` (global), matches entries against the diff, and returns a ranked relevance list. Each surfaced gotcha cites the existing prevention.
+
+`gotcha-hunter` does not block the chain. Use its findings to:
+- check whether earlier passes missed a known recurring failure mode,
+- include the cited gotcha files in the final review report so the developer reads the prior lesson, not just the verdict.
+
+If the agent reports `promotion-pending` entries, treat that as a separate warning — those are draft rules awaiting session-start review (see `support-gotcha` Step 6); the chain continues but the user should resolve them before the next slice closes.
+
+### Step 6: Pass 2.5 — Codex adversarial cross-check (Verify mode only)
+
+If the user selected **Verify** at Step 0, dispatch Codex `adversarial-review` to cross-check what Claude's chain found. Codex is looking for: gaps Claude missed, dead code, cross-module inconsistencies, security concerns the chain didn't surface.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" adversarial-review --scope branch \
+  "Review the diff for gaps, dead code, cross-module inconsistencies, and security concerns the prior chain missed. Focus on what is WRONG or MISSING, not style."
+```
+
+Surface Codex's findings alongside Claude's; flag disagreements for the user to resolve.
+
+### Step 7: Plan alignment
+
+Verify the implementation aligns with the plan:
+
+1. Read the task from `.forge/work/{type}/{name}/tasks.md`.
+2. Compare implementation against the task description.
+3. Check API contracts at `.forge/work/{type}/{name}/architecture/api-contract.md`.
+4. Check DB schema at `.forge/work/{type}/{name}/architecture/db-schema.md`.
+5. Verify decision log consistency at `aiwiki/decisions/`.
+
+Flag deviations. Intentional deviations go in the decision log.
+
+### Step 8: Aggregate and decide
+
+Combine findings from all subagents into a unified report (see **Review Report Format** below). The main session decides — never blindly accept a subagent verdict.
+
+## Subagent Dispatch
+
+| Subagent | Owns | When |
+|---|---|---|
+| `code-reviewer` | Pass 1 safety | Always (unless Codex Takeover) |
+| `craft-reviewer` | Pass 2 craft + idioms + stubs | Medium / High / Critical risk |
+| `support-runtime-reachability` (skill) | Slice wiring gate | Medium / High / Critical risk; per-slice gate before final approval |
+| `gotcha-hunter` | Prior-art recall (project + global gotcha catalogs) | Always — runs after the chain's other passes (after the wiring gate when present, otherwise immediately after `code-reviewer`); surfaces relevant gotchas + any promotion-pending warnings |
+| Codex `adversarial-review` | Cross-check (gaps/dead-code/inconsistencies) | If user selected Verify or Takeover |
+
+Each subagent receives: changed files, test results, architecture artifacts, decision log. Each runs in its own context window so the main session stays lean.
+
+## Risk Classification Guide
+
+| Change Area | Default Risk | Escalate If |
+|---|---|---|
+| README, comments | Low | Never |
+| CSS, styling | Low | Involves user input (XSS) |
+| Config files | Low | Secrets, deploy targets |
+| Business logic | Medium | Handles money or PII |
+| API endpoints | Medium | Auth-required endpoints |
+| Database queries | Medium | Schema changes, migrations |
+| Auth/authz | High | Always |
+| Payment/billing | High | Always |
+| User data handling | High | PII, GDPR-relevant |
+| Encryption/hashing | High | Always |
+| User-input rendering | High | Output to HTML/templates without encoding |
+| Query construction | High | User input in SQL/NoSQL/LDAP/command strings |
+| Server-side requests | High | User-controlled URL or hostname |
+| External integrations | High | New third-party service, auth token, or webhook |
+| Infrastructure/deploy | Critical | Always |
+| CI/CD pipeline | Critical | Always |
+| Database migrations | Critical | Production database |
+
+When the diff touches a High row, escalate to `quality-security-audit` after the chain. When the diff touches a Critical row, require human approval before merge.
+
+## Auto-Fix vs Ask
+
+| Issue Type | Action |
+|---|---|
+| Formatting, whitespace | Auto-fix silently |
+| Obvious naming improvements | Auto-fix, mention in report |
+| Missing error handling | Auto-fix if pattern is clear from the codebase |
+| Architecture decisions | Ask user (batch all questions into one) |
+| Tradeoffs (performance vs readability) | Ask user with recommendation |
+| Convention conflicts | Check decision log first; ask if no precedent |
+
+Batch all "ask user" items into a single question. Do not ask one at a time.
+
+## Review Report Format
+
+```markdown
+## Code Review Report
+
+**Scope:** [files reviewed]
+**Risk:** [Low / Medium / High / Critical]
+**Reviewers:** code-reviewer, craft-reviewer, support-runtime-reachability, gotcha-hunter[, Codex]
+
+### Pass 1 — Safety (code-reviewer)
+- SQL safety: PASS
+- Race conditions: PASS
+- Auth boundaries: PASS
+- Secret exposure: PASS
+- Injection vulnerabilities: PASS
+- Data-loss risks: 1 finding (auto-fixed)
+
+### Pass 2 — Craft (craft-reviewer)
+- Idiom adherence: PASS (axios v1.7 verified)
+- Pattern conformance: 1 finding (existing pattern at src/handlers/users.ts:22)
+- Stub detection: PASS
+
+### Slice gate — runtime-reach (support-runtime-reachability)
+- 4 exports checked, all wired ✓
+
+### Prior-art recall (gotcha-hunter)
+- Project gotchas relevant: 0
+- Global gotchas relevant: 1 — Stub logger silently drops events (~/.claude/gotchas/{YYYY-MM-DD}-{slug}.md)
+- Promotion-pending: 0
+
+### Pass 2.5 — Codex adversarial (if Verify)
+- 1 finding: dead import in src/lib/utils.ts
+
+### Plan Alignment
+- Matches task description ✓
+- API contract compliant ✓
+- Decision log consistent ✓
+
+### Findings
+| # | Reviewer | Severity | Description | Status |
+|---|---|---|---|---|
+| 1 | code-reviewer | Critical | Missing transaction in createOrder | Auto-fixed |
+| 2 | craft-reviewer | Important | Throws bare Error for validation | Awaiting user |
+| 3 | gotcha-hunter | Advisory | Logger stub pattern matches a global gotcha — confirm via console-tee | Cited |
+| 4 | Codex | Important | Dead import `formatDate` in utils.ts | Auto-fixed |
+
+### Decision
+**APPROVED** / **APPROVED WITH CONCERNS** / **CHANGES REQUESTED** / **BLOCKED**
+```
+
+## Decision Outcomes
+
+| Decision | Meaning | Action |
+|---|---|---|
+| APPROVED | No issues, or all issues auto-fixed | Proceed |
+| APPROVED WITH CONCERNS | Non-blocking issues documented | Proceed; log concerns |
+| CHANGES REQUESTED | Issues must be fixed | Return to `build-tdd` |
+| BLOCKED | Critical safety, runtime-reach failure, or architecture problem | Escalate to user |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Reviewing without running tests first | Tests must pass before review starts |
+| Conflating safety, craft, and reachability into one pass | Dispatch the four subagents separately; each owns its concern |
+| Skipping `craft-reviewer` because Pass 1 was clean | Pass 2 catches different bugs; safety alone isn't enough |
+| Treating runtime-reach as optional | The wiring gate is per-slice; orphan exports block the slice |
+| Skipping `gotcha-hunter` because nothing felt familiar | The catalog exists because we already forgot — the agent is recall, not intuition |
+| Asking questions one at a time | Batch all "ask user" items into a single message |
+| Auto-fixing architecture decisions | Architecture changes require user approval |
+
+## Red Flags
+
+**Never:**
+- Skip the safety pass.
+- Auto-fix security or architecture decisions.
+- Proceed with critical safety findings unresolved.
+- Pass the runtime-reach gate by adding a no-op caller.
+
+**Always:**
+- Run safety first; halt the chain on a `BLOCK`.
+- Classify risk before dispatching.
+- Aggregate findings from all reviewers — don't hide one to make the report look clean.
+- Verify plan alignment after the chain runs.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Implementation code + passing tests, architecture artifacts (`.forge/work/{type}/{name}/architecture/`), decision log (`aiwiki/decisions/`) |
+| **Produces** | Unified review report (in conversation or `.forge/work/{type}/{name}/review-report.md`), auto-fixes applied to code |
+| **Feeds into** | `quality-test-execution` (final review), next TDD task (per-task review), `build-pr-workflow` (PR gate) |
+| **Updates manifest** | `slice_graph.slices.<id>.gates.{code-review, runtime-reach}` per-slice; `phases.quality.code-review-final.gate-passed: true` at manifest level |
+
+## Graphify Context
+
+**Protocol:** `protocols/graphify.md` | **Guard:** Run the status check from the protocol before Step 2.
+
+Graph context reveals cross-module blast radius — surface to the subagents in their dispatch prompts:
+
+- **Communities** identify subsystems the diff touches; cross-community changes are higher risk.
+- **God nodes** get extra scrutiny.
+- **EXTRACTED edges** trace dependency paths.
+
+CLI queries (if graph exists):
+- `graphify query "what depends on [changed file]" --budget 1000 --graph graphify-out/graph.json`
+- `graphify explain "[changed module]" --graph graphify-out/graph.json`
+
+## Integration
+
+**Called by:**
+- `/feature` (per-task review + final review)
+- `/bugfix` (review before PR)
+- `/refactor` (review before PR)
+- On-demand
+
+**Dispatches:**
+- `code-reviewer` (Pass 1 safety)
+- `craft-reviewer` (Pass 2 craft)
+- `support-runtime-reachability` skill (per-slice gate)
+- `gotcha-hunter` (prior-art recall)
+- Codex `adversarial-review` (optional cross-check)
+
+**Pairs with:**
+- `build-tdd` — feeds the diff to review
+- `quality-security-audit` — escalation for High/Critical risk
+- `quality-test-execution` — runs after final review approves
+- `build-pr-workflow` — approved review gates PR creation

package/skills/quality-security-audit/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: quality-security-audit
+description: "Use when deploying auth/data-handling code, when code-review escalates high-risk findings, or when changes touch auth, crypto, or integrations."
+---
+
+# Security Audit
+
+## Overview
+
+Perform a focused security audit covering the most critical vulnerability categories. Every finding includes a realistic exploit scenario -- not just "best practice" warnings.
+
+**Core principle:** If you cannot describe how an attacker would exploit it, it is not a real finding. If you can describe the exploit, it must be fixed.
+
+**Announce at start:** "I'm using the quality-security-audit skill to audit this code for security vulnerabilities."
+
+## When to Use
+
+- Before deployment to production
+- When `quality-code-review` escalates to security audit (High/Critical risk)
+- On-demand when the user requests a security review
+- After adding authentication, authorization, payment, or data handling code
+- When integrating third-party packages or services
+
+**Not for:**
+- General code quality (that is quality-code-review)
+- Performance issues (that is quality-code-review performance section)
+- Non-security configuration issues
+
+## When to load references
+
+- **`references/owasp-checks.md`** — full OWASP Top 10 (A01-A10): per-category check lists and realistic exploit scenarios. Load this when starting Phase 1.
+- **`references/audit-report-template.md`** — canonical markdown structure for the audit report, plus the finding format used in every phase. Load this when writing the report or recording any finding.
+
+## Agent Dispatch
+
+Dispatch the **security-reviewer** subagent for the audit. It specializes in OWASP Top 10 analysis with exploit scenarios and runs an independent review. The security-reviewer determines the appropriate depth based on the scope of changes.
+
+## The Audit Process
+
+### Phase 0: Codex Mode Check
+
+Run the Codex consent flow from `protocols/codex.md` before proceeding.
+
+- **Takeover selected:** Dispatch Codex `adversarial-review` to execute the full OWASP audit and all 6 phases. Claude reviews Codex's findings at the end.
+- **Verify selected** or **Skip / Codex unavailable:** Proceed with Phases 1-6 below. If Verify was selected, the Codex Adversarial Review step at the end will dispatch Codex to check Claude's findings.
+
+### Phase 1: OWASP Top 10 Check
+
+Systematically check the code against each OWASP Top 10 category. Load **`references/owasp-checks.md`** for the full per-category check lists and exploit scenarios.
+
+| ID | Category | Sample check |
+|---|---|---|
+| A01 | Broken Access Control | IDOR, missing authorization, CORS misconfig, directory traversal |
+| A02 | Cryptographic Failures | Weak hashes, plaintext secrets, missing TLS, weak RNG |
+| A03 | Injection | SQL/NoSQL/command/LDAP/template/header injection |
+| A04 | Insecure Design | Missing rate limiting, race conditions, business logic flaws |
+| A05 | Security Misconfiguration | Debug in prod, default credentials, missing security headers |
+| A06 | Vulnerable Components | CVEs in deps, abandoned packages — run `npm audit` / `pip audit` / `govulncheck` / `cargo audit` |
+| A07 | Auth Failures | Weak passwords, session fixation, hardcoded JWT secret |
+| A08 | Data Integrity Failures | Unsigned updates, untrusted deserialization |
+| A09 | Logging & Monitoring Failures | Missing audit logs, PII in logs, no alerting |
+| A10 | SSRF | User-controlled URLs, internal network access, cloud metadata endpoint exposure |
+
+For every finding at MEDIUM or above, include a realistic exploit scenario using the finding format in `references/audit-report-template.md`.
+
+### Phase 2: Secrets Scanning
+
+Scan the entire codebase for hardcoded secrets.
+
+**Search patterns:**
+
+```
+# API keys
+grep -rn "api[_-]?key.*=.*['\"][a-zA-Z0-9]" --include="*.ts" --include="*.js" --include="*.py"
+
+# AWS credentials
+grep -rn "AKIA[0-9A-Z]{16}" .
+grep -rn "aws[_-]?secret" --include="*.ts" --include="*.js" --include="*.py" --include="*.env*"
+
+# JWT secrets
+grep -rn "jwt[_-]?secret.*=.*['\"]" .
+
+# Generic passwords
+grep -rn "password.*=.*['\"][^$]" --include="*.ts" --include="*.js" --include="*.py"
+
+# Private keys
+grep -rn "BEGIN.*PRIVATE KEY" .
+
+# Connection strings with credentials
+grep -rn "://[^/]*:.*@" --include="*.ts" --include="*.js" --include="*.py"
+```
+
+**Check these files specifically:**
+- All `.env` files (should not be committed)
+- Configuration files (config.ts, settings.py, etc.)
+- Test fixtures and seed data
+- Docker-compose files
+- CI/CD configuration files
+- README and documentation
+
+### Phase 3: Dependency Vulnerabilities
+
+Run automated tools and manually review results.
+
+```bash
+# Step 1: Run audit tool
+npm audit --json > audit-results.json
+# or: pip audit --format json > audit-results.json
+
+# Step 2: Analyze severity distribution
+# Critical: Patch immediately
+# High: Patch before deployment
+# Medium: Patch within sprint
+# Low: Track and patch in maintenance cycle
+```
+
+Record each vulnerability using the finding format in `references/audit-report-template.md`, including a BLOCKED line that notes whether anything prevents the upgrade.
+
+### Phase 4: Supply Chain Risks
+
+Review dependencies for supply chain attack vectors.
+
+**Check for:**
+- **Typosquatting:** Package names similar to popular packages (e.g., `lodashe` instead of `lodash`)
+- **Unpinned versions:** Using `^` or `*` instead of exact versions in production dependencies
+- **Very new packages:** Published within last 30 days with no established track record
+- **Single maintainer packages:** Bus factor of 1 for critical dependencies
+- **Excessive permissions:** Packages requesting unnecessary filesystem or network access
+- **Install scripts:** Packages with postinstall scripts that run arbitrary code
+
+```bash
+# Check for install scripts
+npm ls --json | jq '.dependencies | to_entries[] | select(.value.scripts.postinstall)'
+
+# Check package age and download counts
+npm view <package> time.created
+npm view <package> --json | jq '.dist-tags, .maintainers'
+```
+
+### Phase 5: Auth/Authz Boundary Verification
+
+Systematically map and verify authentication and authorization boundaries.
+
+**Process:**
+
+1. **List all endpoints/routes** with their required auth level
+2. **Verify each endpoint** has appropriate middleware/guards
+3. **Test boundary conditions:**
+   - Unauthenticated access to protected endpoints
+   - Authenticated user accessing another user's resources
+   - Regular user accessing admin endpoints
+   - Expired token handling
+   - Invalid token handling
+
+```markdown
+| Endpoint | Required Auth | Actual Auth | IDOR Check | Status |
+|----------|--------------|-------------|------------|--------|
+| GET /api/users | Admin | Admin middleware | N/A | PASS |
+| GET /api/users/:id | Owner or Admin | Auth middleware only | FAIL - no owner check | FAIL |
+| POST /api/users | Public | None | N/A | PASS |
+| PUT /api/users/:id | Owner | Auth middleware only | FAIL - no owner check | FAIL |
+| DELETE /api/users/:id | Admin | Auth middleware | N/A | PASS |
+```
+
+### Phase 6: Data Exposure Review
+
+Check for unintentional data exposure.
+
+**Check these locations:**
+- **Log output:** Search for PII (email, phone, address, SSN) in log statements
+- **Error messages:** Ensure errors do not expose stack traces, SQL queries, or internal paths
+- **API responses:** Verify responses do not include fields not in the API contract (e.g., password hash, internal IDs)
+- **Client-side bundles:** Check that server-only data is not included in frontend builds
+- **Debug endpoints:** Ensure no debug/test endpoints exist in production code
+- **Database backups:** Verify backup strategy does not expose data
+
+## Audit Report
+
+Write the report following the structure in **`references/audit-report-template.md`**. The template covers metadata, executive summary, findings (by severity), dependency audit, supply chain review, auth boundary map, secrets scan, recommendations, and the quality gate.
+
+## Codex Adversarial Review
+
+After completing all 6 phases, check the mode recorded at Phase 0. If **Verify** was selected, dispatch `adversarial-review` to find authorization gaps, cross-package permission mismatches, and security primitives defined but not enforced. Merge Claude + Codex findings in the final report. If **Takeover** was selected, skip this step (Codex already ran the audit). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.
+
+## Severity Classification
+
+| Severity | Criteria | Response Time |
+|----------|----------|---------------|
+| CRITICAL | Active exploitation possible, data breach risk | Fix before any deployment |
+| HIGH | Exploitable with moderate effort, significant impact | Fix before production deployment |
+| MEDIUM | Exploitable with significant effort, limited impact | Fix within current sprint |
+| LOW | Theoretical risk, minimal impact | Track and fix in maintenance |
+| INFO | Best practice recommendation, no exploit scenario | Optional improvement |
+
+**Rule:** INFO-level findings with no exploit scenario are acceptable. MEDIUM and above MUST have a realistic exploit scenario.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| "Best practice" warnings without exploit | Every finding needs a realistic exploit scenario |
+| Skipping dependency audit | Always run the automated audit tool |
+| Only checking new code | Audit the full attack surface, not just changes |
+| Missing auth boundary verification | Systematically map and verify every endpoint |
+| Not checking logs for PII | Logs are a common data leak vector |
+| Accepting "we'll fix it later" for critical findings | Critical findings block deployment. Period. |
+| Not checking supply chain | Dependency attacks are increasingly common |
+
+## Red Flags
+
+**Never:**
+- Report findings without exploit scenarios (except INFO level)
+- Skip any of the 6 phases
+- Allow deployment with CRITICAL findings
+- Ignore dependency vulnerabilities
+- Accept "we'll add auth later" for protected endpoints
+
+**Always:**
+- Check all OWASP Top 10 categories
+- Run automated dependency audit
+- Verify auth boundaries systematically
+- Check for secrets in code
+- Provide realistic exploit scenarios
+- Prioritize findings by severity
+- Include fix recommendations
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Implementation code, dependency manifests (package.json, requirements.txt, go.mod), deployment configuration (if applicable) |
+| **Produces** | Security audit report (`.forge/work/{type}/{name}/security-audit.md` or in conversation) |
+| **Returns to** | `quality-code-review` (escalation response — findings returned to caller for fixing) |
+| **Feeds into** | `deliver-deploy` (security gate) |
+| **Updates manifest** | `gates-passed.security-audit: true/false` |
+
+## Graphify Context (Optional)
+
+**Protocol:** `protocols/graphify.md` | **Guard:** Run the status check from the protocol before Phase 1.
+
+Security audits benefit heavily from graph context — community boundaries reveal cross-package permission patterns, and dependency tracing exposes auth chain gaps.
+
+**How graph data maps to this skill:**
+- **God nodes** → highest-risk components, audit these first
+- **Community boundaries** → cross-community edges reveal permission chain gaps
+- **EXTRACTED edges** → trusted dependency paths for auth flow verification
+- **INFERRED edges** → flag as potential hidden auth bypasses
+
+**CLI queries** (if graph exists and CLI available):
+- `graphify path "auth" "billing" --graph graphify-out/graph.json` — trace permission chains across packages
+- `graphify path "middleware" "routes" --graph graphify-out/graph.json` — verify auth middleware covers all route groups
+- `graphify query "what routes lack authentication" --budget 1500 --graph graphify-out/graph.json` — find unprotected endpoints
+
+**Codex bridge:** Pass graph community boundaries and permission chain traces to the Codex verify step below. Graph signals materially improve Codex's recall on cross-package authorization gaps.
+
+---
+
+## Codex Integration
+
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md` | **Command:** `adversarial-review`
+
+- **Verify:** Claude runs the OWASP audit, Codex adversarial-reviews for gaps.
+- **Takeover:** Codex runs the full security audit, Claude reviews findings.
+
+**When:** After Claude's security-reviewer completes the OWASP audit (sequential, not parallel). This is the highest-value Codex integration point — the Codex + graph combination consistently surfaces authorization gaps that the primary security-reviewer misses — including cross-package permission mismatches and unused security primitives.
+
+**Invocation:**
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" adversarial-review --scope branch "authorization gaps, permission mismatches across packages, security primitives defined but not enforced. Find what the existing review missed."
+```
+
+**What Codex reviews:**
+- Authorization gaps (weaker checks on some routes vs others)
+- Cross-package permission mismatches
+- Unused security primitives (defined but unenforced limits, uncalled validators)
+- Secrets or credentials in code
+
+**Presentation:** Claude security findings + Codex security findings + disagreements. User resolves before gate passes.
+
+---
+
+## Integration
+
+**Called by:**
+- `quality-code-review` (escalation from High/Critical risk classification)
+- `/feature` command (before deployment, if project profile requires it)
+- On-demand by user request
+
+**Pairs with:**
+- `quality-code-review` (reviews feed back for fixing)
+- `deliver-deploy` (security audit is a deployment gate)
+- `build-tdd` (security fixes follow TDD cycle)

package/skills/quality-security-audit/references/audit-report-template.md

@@ -0,0 +1,89 @@
+# Audit report template
+
+The canonical structure for the security audit report. Output to `.forge/work/{type}/{name}/security-audit.md` or surface in the conversation.
+
+```markdown
+# Security Audit Report: {Feature/Project Name}
+
+## Metadata
+- **Date:** {date}
+- **Scope:** {files/components audited}
+- **Auditor:** security-reviewer subagent
+
+## Executive Summary
+- **Critical findings:** {count}
+- **High findings:** {count}
+- **Medium findings:** {count}
+- **Low findings:** {count}
+- **Overall risk:** {Critical / High / Medium / Low}
+- **Deployment recommendation:** {BLOCK / PROCEED WITH FIXES / PROCEED}
+
+## Findings
+
+### CRITICAL
+
+#### [SEC-001] SQL Injection in search endpoint
+- **Category:** A03 - Injection
+- **File:** src/products/repository.ts:45
+- **Exploit scenario:** [detailed exploit as shown above]
+- **Impact:** Full database read access
+- **Fix:** Use parameterized queries
+- **Status:** OPEN
+
+### HIGH
+
+#### [SEC-002] Missing rate limiting on login
+- **Category:** A04 - Insecure Design
+- **File:** src/auth/routes.ts
+- **Exploit scenario:** [detailed exploit]
+- **Impact:** Account takeover via brute force
+- **Fix:** Add rate limiting middleware
+- **Status:** OPEN
+
+[...continue for all findings...]
+
+## Dependency Audit
+| Package | CVE | Severity | Fix Available | Status |
+|---------|-----|----------|---------------|--------|
+| lodash@4.17.20 | CVE-2024-XXXX | HIGH | Yes (4.17.21) | OPEN |
+
+## Supply Chain Review
+| Package | Risk | Details | Status |
+|---------|------|---------|--------|
+| express@^4.18.0 | MEDIUM | Unpinned version | OPEN |
+
+## Auth Boundary Map
+[Endpoint auth verification table]
+
+## Secrets Scan
+| Location | Type | Status |
+|----------|------|--------|
+| No secrets found in codebase | - | PASS |
+
+## Recommendations
+1. [Prioritized list of fixes]
+2. [Ordered by severity then effort]
+
+## Quality Gate
+**PASS / FAIL**
+- Zero critical findings: {PASS/FAIL}
+- Zero high findings unaddressed: {PASS/FAIL}
+- All dependencies up to date: {PASS/FAIL}
+- No secrets in codebase: {PASS/FAIL}
+```
+
+## Finding format (for any phase)
+
+When recording an individual finding (in any phase, not just OWASP), use this shape:
+
+```
+FINDING: {short title}
+FILE: {file:line}
+CODE: {the offending snippet}
+EXPLOIT: {how an attacker would exploit this — required for MEDIUM and above}
+IMPACT: {what attacker gains}
+SEVERITY: {CRITICAL | HIGH | MEDIUM | LOW | INFO}
+FIX: {concrete remediation}
+```
+
+INFO-level findings (best-practice recommendations with no realistic exploit) may omit the EXPLOIT line.