/code-quality-guardrails

name: code-quality-guardrails
description: Apply deterministic quality checks to the code John produces — catch the 80% of issues (leaked API keys, hardcoded prod URLs, broken imports, missing dependencies, infinite spinners, dead error states, debug logs in production) without invoking the LLM at all; only fall back to LLM-driven repair for the residual edge cases. Use this skill whenever you're about to ship produced-app code, after a build phase completes, when the user mentions code quality / security review / production readiness, or when [[ralph-loop]] approaches a deploy phase. Cheap, fast, deterministic-first — guardrails are the floor before the polish.
metadata:
  triggers:
    - code quality
    - security check
    - leaked api keys
    - production readiness
    - lint
    - review the code
    - check the build
    - dependencies declared
    - guardrails

code-quality-guardrails

The produced app is the deliverable. The user trusts it not to leak credentials, not to ship debug noise, not to crash on the first run. This skill is the discipline that makes that trust possible — adapted from a production app-builder's quality patterns: inherit the methods, but skill-ify them rather than hardcoding a pipeline.

The principle: **deterministic checks first, LLM repair second.**

The pattern

When you're about to ship produced-app code (end of a build/polish phase, before deploy, or any time the user signals "is this ready?"):

1. **Run the deterministic checks.** Grep for leaked secrets, check the build, verify imports resolve, lint, smoke-test the entrypoint. These are cheap, fast, predictable. They catch the bulk of real issues. See `references/common-guardrails.md` for categories. 2. **Apply automated fixes where possible.** Dependency missing → install. Import path wrong → fix the path. Leaked secret in a string → flag for user (do NOT auto-redact without confirmation; you might break a config). Many guardrails have obvious fixes; apply them. 3. **For residual issues, dispatch the cross-validation subagent.** A separate reviewer reads the produced code + the design intent (from PLAN.md), flags issues a grep can't catch (subtle UX bugs, missing error states, security-via-obscurity, etc.). See `references/cross-validation-pattern.md`. 4. **Surface to the user** anything still unresolved after steps 1-3.

The reason for the order: deterministic checks are cheap and reliable; LLM checks are expensive and probabilistic. Spend the cheap ones first; reserve the expensive ones for what they're uniquely good at.

When a guardrail fires but the fix isn't obvious

Deterministic checks are good at pattern matching, not at semantic judgment. When a guardrail fires, decide:

1. **Check context.** Is `api_key` in a comment? In a `.env.example` placeholder? In a test config? In production? Same pattern, different decisions. 2. **If context is ambiguous, flag to user** with the match + line number. Don't auto-fix. 3. **If context is clear, fix and log.** "Leaked sk-* in committed file" is unambiguous; "missing dep in package.json that imports require" is unambiguous; fix.

Examples:

• Match: `api_key = "sk-test-placeholder-12345"` in `.env.example` → flag (might be intentional placeholder).
• Match: `import foo` but `foo` not in package.json → fix (always wrong if foo isn't a stdlib module).
• Match: `console.log("debug")` in `src/` production code → fix (almost always should be removed).
• Match: `localhost:3000` in deploy config → flag (might be intentional for staging).

If false-positive rates are high in a particular category, surface the pattern to the user — the guardrail itself may need adjustment.

The four guardrail categories

`references/common-guardrails.md` has details; the categories:

• **Security**: leaked API keys / tokens / passwords; hardcoded production URLs / IPs; permissive CORS; unescaped user input rendered as HTML.
• **Code quality**: missing dependencies in package.json/requirements.txt; broken imports; unused imports flagged by linters; obvious syntax errors; type errors (if typed language).
• **UX**: error states unhandled (what if the API returns 500?); infinite spinners (no failure path); long-running jobs that die with the browser connection (no task registry — see [[job-runtime]]); running jobs nothing can ever reclaim (no lease, no queue/generation timeout split); console.log/print statements that should be debug-only; placeholder text not replaced.
• **Deployment**: build succeeds (`npm run build`, `python -m build`, etc.); smoke test passes (entrypoint runs without crashing); Dockerfile (if applicable) builds.

For each category, the produced-app phase should run at least one check. Templates can ship more category-specific guardrails (e.g., a slide-deck template might check that the produced HTML opens cleanly in a browser).

The internal-leak guard (the produced app's public surface)

A knowledge-dense app is built from internal scaffolding — schema keys, chunk IDs, skill names, `.john/` paths, raw JSON, the source language's machine-words. None of it belongs in what the end-user sees, and a shipped app surfacing `chapter_id` in a heading or a stray `{"schema_version": …}` in the UI is a recurring, embarrassing failure. It's deterministically catchable, so catch it.

Before phase-done or ship, scan the **produced app's user-facing output** (built/rendered files — never `.john/` working state) for leaked internals:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/app_first_contracts.py" scan-ui-leaks <produced-app-dir> [--language zh]

It returns `{success, check: "source_heuristic", violations}` — flagging raw JSON, internal identifiers (`schema_version` / `chapter_id` / `chunk_id` / skill names), `.john/` or filesystem paths, and — for a non-English app (`--language zh`) — bare English machine-words (`chapter`, `schema`, `chunk`, `json`) showing up as user-facing labels. A missing, invalid, or empty target fails. Treat violations