Code warden

code-warden v4.0.0

Production-grade AI development governance skill. Load at the start of every session involving code generation, refactoring, or architectural changes.

Session Start - HARD GATE

Do not ask implementation questions. Do not gather requirements. Do not proceed past this block until all outputs are produced and confirmed by the user.

Mandatory sequence — produce in order, each confirmed before the next:

1. Architecture State (below)
2. Session Scope (below)
3. Reference Files (below)
4. Scope Gate — see references/planning-gates.md
5. Plan Gate — see references/planning-gates.md (fires after Scope Gate confirmed)

Before responding, execute node <installed-skill-dir>/tools/get-context.js if you lack architectural context.

Common install directories:

• Codex shared agents: ~/.agents/skills/code-warden
• Codex local skills: ~/.codex/skills/code-warden
• Claude Code: ~/.claude/skills/code-warden

Output this block as your first response before anything else:

---

ARCHITECTURE STATE (Re-injection Rule)

[Paste the context found by get-context.js or provided by user. If none found, write:]

[WARN] No architecture doc found - applying Re-injection Fallback:

• Last known files: [list any files mentioned in this session]
• Current data flow: [unknown - user must provide before proceeding]

REQUEST: Paste your architecture doc, PRD, or a 3-sentence scope summary before we continue.

SESSION SCOPE (Session Scoping Rule)

This session is scoped to: [module/feature name] Files in scope: [list] Files explicitly OUT of scope: [everything else]

[If scope is unknown, write:]

[WARN] Scope undefined - user must confirm before proceeding.

REFERENCE FILES LOADED (Blueprint Rule)

For this task, loading: [list relevant references/ files] Status: [PASS found | WARN missing from install - rules enforced from prompt]

---

Do not proceed until the user replies "confirmed" or provides the missing information above.

Quick Rules

• Scope Gate: Required before every session. Declare goal, non-goals, files in/out, verify commands, rollback plan. See references/planning-gates.md.
• Scope Lock: Ask the user to run code-warden scope set --goal="..." <paths...> after the Scope Gate is confirmed. While locked, hooks deny writes outside the declared paths; expansion goes through the user-run code-warden scope add <path>. Never edit .code-warden/ directly — hooks deny it unconditionally.
• Plan Gate: Required before any multi-file or >30-line change. Declare patch order, blast radius class, post-patch checks. See references/planning-gates.md.
• Command risk: Destructive commands (force push, hard reset, recursive root delete, pipe-to-shell) are denied by the Command Risk Gate; high-risk ones (dependency changes, push, publish) ask first on Claude. Do not work around a denial — surface it.
• Audit + receipts: Governed sessions append to a hash-chained .code-warden/audit.jsonl. Close sessions with code-warden receipt --from-audit --out=<file> so the receipt is corroborated by ledger evidence, then validate it.
• Baseline ratchet: In brownfield repos, code-warden report --baseline fails only NEW or WORSENED violations; never grow a baselined file or add a fresh secret.
• Max file size: Enforced by warden-lint.js (default 400 lines). Split into modules at the limit.
• Editing mode: Patch/diff first. No full rewrites without blast radius check.
• Feedback mode: Adversarial. Correctness over comfort; push back on weak logic.
• Secrets: Zero-trust. Enforced by verify-secrets.js; no hardcoded keys.
• Uncertainty: Say so. Never guess niche syntax or stale API behavior.
• Concerns: One responsibility per file. Support human auditing.
• Verification: Run meaningful checks before claiming completion; report command and result.
• Evidence providers: Treat SARIF, attestations, provenance, and scanner output as scoped evidence with explicit trust limits.
• Receipts: Use code-warden receipt --template --out=<file> and validate completed receipts when a durable gate artifact is needed.
• Risk tiers: Treat dependency, network, release, destructive, and secret-bearing actions according to risk_policy.
• MCP governance: Approve MCP servers by source, toolset, credential scope, data egress, and rollback before use.
• Reference selection: Use code-warden references <paths...> to recommend focused governance references for touched paths.
• Source control: Inspect dirty state where available; never revert user changes without explicit request.
• Dependencies: Do not add, remove, upgrade, or replace packages without evidence and explicit reasoning.
• Evidence: Ground technical claims in local files, command output, official docs, or clear uncertainty.
• Research: Use live research for current, version-specific, or fast-changing facts.
• Fit over defaults: Challenge familiar stack and product-shape defaults before choosing Node, React, dashboards, or CRUD patterns.

Reference Files

Load these when relevant to the current task:

• Scope Gate, Plan Gate, blast radius class, patch order -> references/planning-gates.md
• Architecture decisions, Blueprint Rule, Re-injection -> references/architecture.md
• Blast Radius, Patch-First, Zero-Trust, Dependency Freeze -> references/safety.md
• Think Before Coding, Don't Guess Syntax, Human Checkpoint -> references/cognition.md
• Tech Debt flag format, Test Contract, Decision Log -> references/cleanup.md
• Anchor Check, Session Scoping, Drift Trigger -> references/anti-drift.md
• Verification, git hygiene, dependency control, evidence -> references/operations.md
• External evidence providers, provenance, attestations, SARIF, and trust limits -> references/evidence-providers.md
• Live research, anti-default stack choices, product-shape fit -> references/research-and-fit.md
• MCP server approval, toolset scope, credentials, consent, and audit evidence -> references/mcp-governance.md

Drift Signals - Hard Stop

Stop and re-anchor immediately if any of these appear:

Signal	Action
Began implementing without a confirmed Scope Gate	Stop, produce Scope Gate, await confirmation
Began implementing without a confirmed Plan Gate	Stop, produce Plan Gate, await confirmation
Touched a file not declared in Scope Gate	Stop, declare scope expansion, await approval
Write denied by the Scope Lock or Command Risk Gate	Stop, report the denial verbatim, ask the user to expand scope or approve — never bypass
Guessed library syntax without searching docs	Search live docs, correct output
Used stale training data for current facts	Run live research or mark unverified
Chose a default stack/product shape without fit check	Compare alternatives against project constraints
Unexplained contiguous block > limit	Run warden-lint.js, split if needed
Skipped Blast Radius Check before a rewrite	Run check before proceeding
Claimed completion without verification evidence	Run relevant checks or state residual risk
Changed dependencies without version/source evidence	Stop, inspect package metadata and lockfile
Edited in a dirty repo without checking ownership	Inspect status and preserve user changes
No [AWAITING CONFIRMATION] before >2-file change	Pause and request confirmation
Monolithic file output without module split	Refactor into separated concerns

All limits and thresholds are defined in codewarden.json.