code-warden 3.1.1

package/CONFIGURE.md

@@ -0,0 +1,39 @@
+# Configuration Guide
+
+CodeWarden now uses a machine-readable configuration file: `codewarden.json`.
+Every threshold is tunable through this file, making it easy to share settings across your team.
+
+---
+
+## The `codewarden.json` File
+
+Located at the root of the skill folder. Default configuration:
+
+```json
+{
+  "thresholds": {
+    "max_file_length": 400,
+    "pre_flight_trigger_lines": 150,
+    "human_checkpoint_files": 2
+  },
+  "safety": {
+    "exempt_from_blast_radius": ["tests/", "docs/", "scripts/"]
+  }
+}
+```
+
+| Setting | Default | Rationale |
+|---------|---------|-----------|
+| `max_file_length` | 400 | Keeps files reviewable in a single pass. The `warden-lint.js` script enforces this. |
+| `pre_flight_trigger_lines` | 150 | Forces a JSON manifest before large outputs. |
+| `human_checkpoint_files` | 2 | Requires human `[AWAITING CONFIRMATION]` before modifying this many files simultaneously. |
+| `exempt_from_blast_radius` | (list) | Skips strict rewriting rollback plans on these file directories. |
+
+---
+
+## How to Customize
+
+1. **Open** `codewarden.json` in your `.claude/skills/code-warden/` directory.
+2. **Modify** the specific rule or threshold inside the JSON structural fields.
+3. The executable tools (`tools/warden-lint.js`, etc.) read these limits dynamically so no Markdown files need to be edited to enforce limits.
+4. **Log the change** in `DECISIONS.md` so your team knows why the default was overridden.

package/DECISIONS.md

@@ -0,0 +1,107 @@
+# DECISIONS.md
+
+Decision log for this project. Maintained per the code-warden cleanup protocol.
+
+## Format
+
+Each entry:
+- **Date**: YYYY-MM-DD
+- **Decision**: What was decided
+- **Alternatives**: What else was considered
+- **Reasoning**: Why this choice was made, with links where applicable
+- **Files Affected**: List of files changed
+
+---
+
+<!-- Append new decisions below this line -->
+
+---
+
+## 2026-05-15 - Codex partial hook enforcement — apply_patch and Bash (ADR)
+
+- **Decision**: Ship Codex hook support as "partial hard enforcement" covering `apply_patch` and `Bash` tool calls. Claude hooks are moved to `tools/hooks/claude/`. Codex hooks live at `tools/hooks/codex/`. Each runtime gets its own installer/uninstaller. `install.js` dispatches dynamically via `require('./tools/hooks/${id}/install-hooks')`.
+- **Alternatives considered**:
+  - Full Codex parity with Claude (Write/Edit blocking). Rejected: Codex does not expose Write/Edit as hookable tool calls. `apply_patch` and `Bash` are the only available hook surfaces.
+  - Single hooks/ directory without runtime subdirs. Rejected: creates naming collisions and makes the difference in behavior invisible.
+  - TOML config for Codex. Rejected: `~/.codex/hooks.json` (JSON) avoids a TOML parser dependency and matches the installer pattern already proven with `settings.json`.
+- **Reasoning**: Codex exposes two tool surfaces at PreToolUse — `apply_patch` (for file writes) and `Bash` (for shell execution). Both are realistic vectors for hardcoded secrets. The `apply_patch` hook also estimates resulting file size where a target path is extractable. This covers the most dangerous Codex operations without claiming full parity with the Claude hook surface.
+- **Consequence**: Codex cannot block oversized line counts for net-new files created via `cat >>` or `tee` in Bash. This gap is documented in the README compatibility matrix. CI enforcement (`npm run lint`) closes it at the pipeline level.
+- **Files affected**: `tools/hooks/claude/` (renamed from `tools/hooks/`), `tools/hooks/codex/warden-apply-patch-hook.js`, `tools/hooks/codex/warden-bash-hook.js`, `tools/hooks/codex/install-hooks.js`, `tools/hooks/codex/uninstall-hooks.js`, `install.js`, `package.json`, `SKILL.md`, `DECISIONS.md`
+
+---
+
+## 2026-05-15 - Claude hooks live inside the installed skill path (ADR)
+
+- **Decision**: Code-warden Claude hooks (`warden-lint-hook.js`, `warden-secrets-hook.js`) are installed from and referenced at `~/.claude/skills/code-warden/tools/hooks/`. Hook scripts are not copied to a neutral directory (e.g. `~/.claude/hooks/code-warden/`). The absolute path to the skill directory is written into `~/.claude/settings.json` at hook install time.
+- **Alternatives considered**:
+  - Neutral directory (`~/.claude/hooks/code-warden/`). Rejected: requires copying hook scripts to a second location on install, syncing them on update, and maintaining a separate removal path. Creates a split-brain problem with two artifact trees.
+  - Relative path via `${CLAUDE_PROJECT_DIR}`. Rejected: hooks are user-level (global), not project-level. No stable relative root exists at user scope.
+- **Reasoning**: Hooks are part of the code-warden skill distribution. They version with the skill and are updated by the same installer (`node install.js --hooks=claude`). One source of truth, one update path, one health-check target.
+- **Consequence**: If the skill directory is deleted manually, `~/.claude/settings.json` may contain dangling hook entries pointing at missing scripts. `--doctor`, `--verify-target=claude`, and `--uninstall-hooks=claude` all detect and repair this condition. The risk is visible and recoverable.
+- **Files affected**: `tools/hooks/warden-lint-hook.js`, `tools/hooks/warden-secrets-hook.js`, `tools/hooks/install-hooks.js`, `tools/hooks/uninstall-hooks.js`, `install.js`, `DECISIONS.md`
+
+---
+
+## 2026-05-14 - Research and fit governance
+
+- **Decision**: Added `references/research-and-fit.md` and wired it into the core skill, cognitive routing, drift signals, README files, and governed-session example. The layer forces live research for current/version-specific facts and requires a fit check before defaulting to familiar stacks or product shapes.
+- **Alternatives considered**:
+  - Expand only the existing "Don't Guess Syntax" rule. Rejected because syntax accuracy is narrower than the failure mode; the agent can know syntax and still choose the wrong stack or app shape.
+  - Put all research rules in `operations.md`. Rejected because operational evidence governs completion and source control, while research/fit governs choice formation before implementation.
+- **Reasoning**: AI coding agents often over-index on familiar defaults like Node, React, SaaS dashboards, CRUD admins, or auth-first scaffolds. The skill now makes project fit and current-source research explicit gates instead of relying on generic uncertainty language.
+- **Files affected**: `SKILL.md`, `references/research-and-fit.md`, `references/cognition.md`, `references/anti-drift.md`, `README.md`, root `README.md`, `examples/governed-session.md`, `package.json`
+
+---
+
+## 2026-05-14 - Operational governance layer
+
+- **Decision**: Added `references/operations.md` and wired it into the core skill, drift signals, README files, and governed-session example. The layer covers verification-before-completion, source-control hygiene, dependency and supply-chain control, and evidence standards for technical claims.
+- **Alternatives considered**:
+  - Fold these rules into `references/safety.md`. Rejected because safety already covers execution risk, secrets, patch-first editing, and dependency freeze; adding verification, git hygiene, and citations there would blur the file's responsibility.
+  - Add separate files for verification, source control, dependencies, and evidence. Rejected for now because each layer is short and operationally coupled; one focused operational reference avoids unnecessary reference sprawl.
+- **Reasoning**: The existing skill prevented many bad coding moves, but it did not make final verification evidence, dirty-worktree ownership, dependency changes, or sourced technical claims explicit stop conditions. These are common failure modes in AI coding sessions and deserve first-class governance.
+- **Files affected**: `SKILL.md`, `references/operations.md`, `references/anti-drift.md`, `README.md`, root `README.md`, `examples/governed-session.md`, `package.json`
+
+---
+
+## 2026-05-14 - Codex setup and shared-agent install path
+
+- **Decision**: Treat `~/.agents/skills/code-warden` as the default install target while preserving `codex` and `claude` installer options. Added `AGENTS.md` context discovery, refreshed README setup paths, normalized tool output to ASCII status tags, and bumped package metadata to `2.3.1`.
+- **Alternatives considered**:
+  - Keep `~/.claude/skills/code-warden` as the only install path. Rejected because the active local environment loads user skills from `~/.agents/skills`.
+  - Add a separate Codex-only fork. Rejected because one portable skill with target-specific installers is easier to maintain and audit.
+- **Reasoning**: The skill should be usable by Codex now without breaking Claude Code users. `AGENTS.md` is the local instruction surface for Codex-style repositories, and ASCII tool output avoids terminal encoding failures in Windows PowerShell.
+- **Files affected**: `AGENTS.md`, `README.md`, `SKILL.md`, `package.json`, `install.ps1`, `install.sh`, `tools/get-context.js`, `tools/warden-lint.js`, `tools/verify-secrets.js`
+
+---
+
+## 2026-03-26 - Polish pass: secret patterns, Windows installer, README, version sync
+
+- **Decision**: Strengthened `verify-secrets.js` with 13 named patterns: OpenAI `sk-`, GitHub `ghp_`/`gho_`/`ghs_`/`ghx_`, AWS `AKIA`, Stripe `sk_live_`/`sk_test_`, bearer tokens, and generic key/password assignments. Added `README.md`. Added `install.ps1` for Windows. Bumped metadata `version` to `2.3.0`. Added `CLAUDE.md` and `.claude/CLAUDE.md` to `get-context.js` candidate list.
+- **Alternatives considered**:
+  - Build additional enforcement tools such as a pre-flight counter, blast-radius reporter, and human checkpoint enforcer. Rejected after ROI analysis: these rules are enforced more reliably by the existing prompt governance layer; tool output can only shape context if the agent runs the tool and reads the result.
+  - Keep `install.sh` only. Rejected because the project owner is on Windows and `install.sh` is not enough for the platform.
+- **Reasoning**: The changes were low-debt and high-value. Secret pattern expansion directly improved the only tool that scans third-party code. The Windows installer removed a real friction point for the author. The README provided an onboarding path that was absent. The version sync eliminated a confusing discrepancy. `CLAUDE.md` support aligned with Claude Code project conventions.
+- **Files affected**: `tools/verify-secrets.js`, `install.ps1`, `README.md`, `SKILL.md`, `tools/get-context.js`
+
+---
+
+## 2026-03-25 - Align Human Checkpoint threshold with Think Before Coding rule
+
+- **Decision**: Changed `[AWAITING CONFIRMATION]` trigger from >3 files to >2 files across `cognition.md` and the Drift Signals table in `SKILL.md`.
+- **Alternatives considered**:
+  - Raise Think Before Coding to >3 files. Rejected because it was too permissive and allowed unconfirmed 3-file changes.
+  - Keep both thresholds as-is and document the gap as intentional. Rejected because the gap created ambiguous behavior: a plan was required at 2 files but no pause was enforced until 3.
+- **Reasoning**: The safer boundary is to require explicit confirmation at the same point planning is required. A user reading both rules would expect them to be consistent. Stricter wins.
+- **Files affected**: `references/cognition.md`, `SKILL.md`
+
+---
+
+## 2026-03-25 - Modular references split introduced in v2.1.0
+
+- **Decision**: Separated governance rules into five domain files under `references/` instead of a single monolithic `SKILL.md`.
+- **Alternatives considered**:
+  - Single flat `SKILL.md` with all rules inline. Rejected because it is token-heavy and loads irrelevant rules every session.
+  - Two files: core rules and extended rules. Rejected because it was not granular enough for targeted loading.
+- **Reasoning**: Lazy-loading reference files keeps session token cost low. The model only reads the files relevant to the current task type. Each file has a single stated domain, which mirrors the one-concern-per-file rule the skill itself enforces.
+- **Files affected**: `references/architecture.md`, `references/safety.md`, `references/cognition.md`, `references/cleanup.md`, `references/anti-drift.md`, `SKILL.md`

package/README.md

@@ -0,0 +1,137 @@
+# code-warden
+
+> Portable AI Coding Governance Layer
+
+Code-Warden is a portable governance layer for AI coding agents. It enforces scoped planning, patch discipline, file-size limits, the zero-trust secrets policy, verification evidence, install health, and optional Claude Code pre-tool-use blocking.
+
+## Four Layers
+
+<p align="center">
+  <img src="../logo/layers-diagram.png" alt="Code-Warden Four Layers" width="100%" />
+</p>
+
+| Layer | What it does |
+|-------|-------------|
+| **Skill governance** | Scope Gate, Plan Gate, blast-radius checks, patch-first editing, research gates, drift signals, verification evidence |
+| **Local verification** | `warden-lint`, `verify-secrets`, `get-context` — directory-aware, no external deps |
+| **Installer and health** | Cross-app auto-installer, manifest-backed installs, `--doctor`, `--verify-target`, Windsurf adapter |
+| **Hard enforcement** | Claude Code `PreToolUse` hooks — block oversized writes and hardcoded secrets before the file system is touched |
+
+## Install
+
+```bash
+git clone https://github.com/Kodaxadev/Code-Warden.git
+cd Code-Warden/code-warden
+node install.js
+```
+
+### Installer commands
+
+| Command | Purpose |
+|---------|---------|
+| `node install.js` | Scan, prompt, install to detected apps |
+| `node install.js --all` | Install without prompt |
+| `node install.js --dry-run` | Preview installs, write nothing |
+| `node install.js --list` | Show detected apps and detection method |
+| `node install.js --doctor` | Verify source integrity + per-target install health |
+| `node install.js --target=claude,cursor` | Force specific targets (warns if not detected) |
+| `node install.js --verify-target=claude` | Strict health check — exits nonzero if not installed |
+| `node install.js --hooks=claude` | Install PreToolUse hooks into `~/.claude/settings.json` |
+| `node install.js --uninstall-hooks=claude` | Remove code-warden hook entries from settings |
+
+Supported targets: **Claude Code**, **Cursor**, **Warp**, **OpenAI Codex**, **Windsurf**, **Generic Agents**.
+
+Each install writes a `.code-warden-install.json` manifest (version, target, format, timestamp).
+
+### npm scripts
+
+```bash
+npm run lint            # warden-lint on full project tree
+npm run check-secrets   # verify-secrets on full project tree
+npm run install-auto    # node install.js
+npm run install-dry-run # node install.js --dry-run
+npm run install-list    # node install.js --list
+npm run install-doctor  # node install.js --doctor
+npm run test            # behavioral tests (8 scanner/hook pass/fail cases)
+npm run ci              # lint + secrets + test + doctor
+```
+
+## Usage
+
+Load at the start of any coding session. Trigger phrases:
+
+- `"load code-warden"` / `"load protocol"`
+- `"begin coding"` / `"new session"` / `"governance check"`
+- `"start a new module"` / `"review this before we write"`
+
+The session sequence is enforced before any implementation:
+
+<p align="center">
+  <img src="../logo/session-flow.png" alt="Code-Warden Session Start Sequence" width="100%" />
+</p>
+
+1. Architecture State (Re-injection Rule)
+2. Session Scope (Session Scoping Rule)
+3. Reference Files (Blueprint Rule)
+4. **Scope Gate** — goal, non-goals, files in/out, verify commands, rollback
+5. **Plan Gate** — patch order, blast radius class, post-patch checks
+
+See [`examples/governed-session.md`](examples/governed-session.md) for an annotated example.
+
+## Optional Claude Code Hooks
+
+<p align="center">
+  <img src="../logo/hook-flow.png" alt="Code-Warden Hook Enforcement Flow" width="100%" />
+</p>
+
+Install hard enforcement that runs at the `PreToolUse` level — before writes happen:
+
+```bash
+# Requires Claude Code target to be installed first
+node install.js --hooks=claude
+```
+
+| Hook | Trigger | Policy |
+|------|---------|--------|
+| `warden-lint-hook.js` | `Write` or `Edit` | Blocks if resulting file exceeds line limit |
+| `warden-secrets-hook.js` | `Write` or `Edit` | Hardcoded credential scanner — blocks if content matches any secret pattern |
+
+Both hooks use exec form (`node /path/to/hook.js`) — no shell differences across platforms.
+
+Thresholds are read from `codewarden.json` in the installed skill directory.
+
+```bash
+node install.js --uninstall-hooks=claude  # remove hook entries from settings.json
+```
+
+Doctor and `--verify-target=claude` validate hook script paths when hooks are registered.
+
+## Configuration
+
+All thresholds in [`codewarden.json`](codewarden.json):
+
+| Setting | Default | What it controls |
+|---------|---------|-----------------|
+| `thresholds.max_file_length` | 400 | Lines before `warden-lint.js` flags a file |
+| `thresholds.pre_flight_trigger_lines` | 150 | Lines before a pre-flight manifest is required |
+| `thresholds.human_checkpoint_files` | 2 | Files touched before `[AWAITING CONFIRMATION]` is required |
+| `safety.exempt_from_blast_radius` | `tests/`, `docs/`, `scripts/` | Paths excluded from rollback-plan rule |
+
+See [`CONFIGURE.md`](CONFIGURE.md) for team-size profiles and tuning rationale.
+
+## Reference Files
+
+| File | Domain |
+|------|--------|
+| `references/planning-gates.md` | Scope Gate and Plan Gate contracts |
+| `references/architecture.md` | Blueprint Rule, Re-injection, State Update |
+| `references/safety.md` | Blast Radius, Patch-First, Zero-Trust, Dependency Freeze |
+| `references/cognition.md` | Think Before Coding, Don't Guess Syntax, Human Checkpoint |
+| `references/cleanup.md` | Tech Debt format, Test Contract, Decision Log |
+| `references/anti-drift.md` | Anchor Check, Session Scoping, Drift Trigger Protocol |
+| `references/operations.md` | Verification, source-control hygiene, dependency control |
+| `references/research-and-fit.md` | Live research gate, stack fit, product-shape guardrails |
+
+## Author
+
+Justin Davis — MIT License

package/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: code-warden
+description: >
+  AI development governance protocol for Codex, Claude Code, and Cowork.
+  Enforces modular architecture, adversarial feedback, patch-first editing,
+  blast radius safety, zero-trust secrets, and context drift prevention. Use at
+  the start of any coding session, when generating or modifying modules, when
+  refactoring existing code, when making architectural changes, or when any of
+  the following are said: "load protocol", "apply dev rules", "check the rules",
+  "start a new module", "review this before we write", "are we following the
+  rules", "new session", "begin coding", "load code-warden", "governance check",
+  or any request to begin writing code.
+metadata:
+  author: Justin Davis
+  version: 3.1.1
+  category: development-governance
+  changelog: |
+    v3.1.1 (2026-05-15): Stabilization. Behavioral tests (8 scanner/hook pass/fail
+      cases via node:test). Shared policy modules: lib/line-count.js, lib/secret-patterns.js,
+      lib/file-collection.js, lib/config.js. Line-count off-by-one fixed (trailing newline).
+      Secret-pattern drift fixed (GitHub token gh[posx]_ → gh[pousr]_ unified across all consumers).
+      README wording: zero-trust secrets policy (governance) vs hardcoded credential scanner (impl).
+    v3.1.0 (2026-05-15): Codex partial hook enforcement. --hooks=codex installs
+      PreToolUse hooks for apply_patch (secrets + estimated size) and Bash (secrets).
+      Hooks live in tools/hooks/codex/. Claude hooks moved to tools/hooks/claude/.
+      Doctor and verify-target validate Codex hook paths via ~/.codex/hooks.json.
+    v3.0.0 (2026-05-15): Optional Claude Code hooks package. --hooks=claude installs
+      PreToolUse hooks that block writes violating file-length or zero-trust secrets
+      policy before they happen. --uninstall-hooks=claude removes them. Doctor and
+      verify-target validate hook script paths when hooks are registered.
+    v2.8.0 (2026-05-15): Added --verify-target=<id> strict per-target health check.
+      Unknown target IDs exit nonzero. Known but not-installed targets exit nonzero.
+      Added npm scripts: install-list, install-doctor.
+    v2.7.1 (2026-05-15): Added Scope Gate and Plan Gate pre-implementation declaration
+      blocks. Both gates must be confirmed before any code is written. Covers goal,
+      non-goals, files in/out, patch order, blast radius class, and post-patch checks.
+    v2.7.0 (2026-05-15): Added GitHub Actions CI template and npm run ci script.
+      Code-Warden now enforces file length and zero-trust secrets outside the chat session.
+    v2.6.0 (2026-05-15): Added cross-platform auto-installer with app detection,
+      atomic install, --doctor health checks, and Windsurf flat-file adapter.
+    v2.5.0 (2026-05-14): Added Research and Fit governance to force live research
+      for current facts and challenge default stack/product assumptions.
+    v2.4.0 (2026-05-14): Added operational governance for verification evidence,
+      source-control hygiene, dependency control, and technical claim sourcing.
+    v2.3.1 (2026-05-14): Added Codex/shared-agent install support, AGENTS.md context discovery,
+      ASCII tool output for reliable terminals, and refreshed setup docs.
+    v2.3.0 (2026-03-26): Added stronger secret scanner, Windows installer, README, version sync,
+      and broader Claude context discovery.
+    v2.2.3 (2026-03-25): Replaced soft checklist with mandatory Hard Gate output block.
+    v2.2.2 (2026-03-25): Added verifiable Pre-Flight manifest, CONFIGURE.md, and examples.
+    v2.2.1 (2026-03-25): Fixed reference paths, triggers, DECISIONS.md stub, and checkpoint threshold.
+    v2.2.0: Added anti-drift.md, Anchor Check, and Drift Trigger Response Protocol.
+    v2.1.0: Added modular references for safety, cognition, cleanup, architecture, and anti-drift.
+    v2.0.0: Initial production release.
+---
+
+# code-warden v3.1.1
+
+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](references/planning-gates.md)
+5. **Plan Gate** — see [references/planning-gates.md](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`.
+- **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`.
+- **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.
+- **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](references/planning-gates.md)
+- Architecture decisions, Blueprint Rule, Re-injection -> [references/architecture.md](references/architecture.md)
+- Blast Radius, Patch-First, Zero-Trust, Dependency Freeze -> [references/safety.md](references/safety.md)
+- Think Before Coding, Don't Guess Syntax, Human Checkpoint -> [references/cognition.md](references/cognition.md)
+- Tech Debt flag format, Test Contract, Decision Log -> [references/cleanup.md](references/cleanup.md)
+- Anchor Check, Session Scoping, Drift Trigger -> [references/anti-drift.md](references/anti-drift.md)
+- Verification, git hygiene, dependency control, evidence -> [references/operations.md](references/operations.md)
+- Live research, anti-default stack choices, product-shape fit -> [references/research-and-fit.md](references/research-and-fit.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 |
+| 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`.

package/codewarden.json

@@ -0,0 +1,14 @@
+{
+  "thresholds": {
+    "max_file_length": 400,
+    "pre_flight_trigger_lines": 150,
+    "human_checkpoint_files": 2
+  },
+  "safety": {
+    "exempt_from_blast_radius": [
+      "tests/",
+      "docs/",
+      "scripts/"
+    ]
+  }
+}

package/examples/governed-session.md

@@ -0,0 +1,132 @@
+# Example: Governed Session Transcript
+
+This is an annotated example of a code-warden governed session.
+It shows how the rules activate in practice during a real feature request.
+
+---
+
+## Session: Add user authentication middleware
+
+**User:** Let's add JWT authentication middleware to the API. It should protect all `/api/v1/` routes.
+
+---
+
+**Assistant (Re-injection Check):**
+> Before writing anything, per the Re-injection Rule, let me restate the current architecture:
+> - `src/server.ts` - Express app entry point, mounts routers
+> - `src/routes/api.ts` - All `/api/v1/` route definitions
+> - `src/middleware/` - Existing middleware directory, currently only `logger.ts`
+> - No architecture doc found -> applying Re-injection Fallback
+>
+> **Research/Fit check:** User requested JWT middleware inside an existing Express API.
+> The project already has an API runtime and route structure, so adding focused
+> middleware fits better than introducing a new auth framework or reshaping the
+> app into a dashboard.
+>
+> **Session scope:** Adding JWT auth middleware. Touching: `middleware/`, `routes/api.ts`, possibly `server.ts`.
+> That's 3 files, which crosses the >2 file threshold.
+>
+> **[AWAITING CONFIRMATION]** - Plan before proceeding:
+> 1. Create `src/middleware/auth.ts` - JWT verification logic only
+> 2. Create `src/types/auth.types.ts` - Token payload type definition
+> 3. Patch `src/routes/api.ts` - Apply middleware to `/api/v1/` router
+>
+> Blast Radius:
+> - **What might break:** Any route under `/api/v1/` that lacks a valid JWT will begin returning 401. No other routes affected.
+> - **Test strategy:** Add unit test for `auth.ts`; smoke test unauthenticated request to `/api/v1/users`.
+> - **Rollback:** `git checkout HEAD -- src/routes/api.ts && rm src/middleware/auth.ts src/types/auth.types.ts`
+>
+> Confirm to proceed?
+
+---
+
+**User:** Yes, go ahead.
+
+---
+
+**Assistant:**
+> **Pre-flight:**
+> - **File:** `src/middleware/auth.ts` - **Lines:** ~35 / 400 max
+> - **Concern:** JWT token verification and request gating
+> - **Secrets:** env-var sourced: `JWT_SECRET`
+> - **Files changed this action:** `auth.ts` (new), `auth.types.ts` (new), `api.ts` (patch)
+
+**`src/middleware/auth.ts`** (new file, ~35 lines)
+```ts
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import { TokenPayload } from '../types/auth.types';
+
+export function requireAuth(req: Request, res: Response, next: NextFunction): void {
+  const header = req.headers.authorization;
+
+  if (!header || !header.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing or malformed Authorization header' });
+    return;
+  }
+
+  const token = header.slice(7);
+  const secret = process.env.JWT_SECRET;
+
+  if (!secret) {
+    // Zero-Trust: never fall back to a default secret
+    res.status(500).json({ error: 'Server misconfiguration' });
+    return;
+  }
+
+  try {
+    const payload = jwt.verify(token, secret) as TokenPayload;
+    (req as any).user = payload;
+    next();
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' });
+  }
+}
+```
+
+**`src/types/auth.types.ts`** (new file, ~10 lines)
+```ts
+export interface TokenPayload {
+  sub: string;
+  email: string;
+  iat: number;
+  exp: number;
+}
+```
+
+**Patch for `src/routes/api.ts`** (diff only):
+```diff
++ import { requireAuth } from '../middleware/auth';
+
+- router.use('/api/v1', apiRouter);
++ router.use('/api/v1', requireAuth, apiRouter);
+```
+
+> TECH DEBT FLAGGED: `src/routes/api.ts:14` Route file mounts all sub-routers inline.
+> Consider splitting into domain-specific router files, such as `routes/users.ts`
+> or `routes/orders.ts`, as the API grows. Do not fix now; logged for next cleanup pass.
+>
+> Decision logged to DECISIONS.md because the change affects 3 files and alters request data flow.
+>
+> Verification run:
+> - `npm test -- auth`
+> - Result: passing authentication middleware tests and route protection smoke test.
+
+---
+
+## What this example demonstrates
+
+| Rule | Where it fired |
+|------|----------------|
+| Re-injection Rule | Session opened with architecture restatement |
+| Re-injection Fallback | No architecture doc found; fell back to last 3 dependencies |
+| Research and Fit | Existing Express API shape was honored instead of introducing a default stack or dashboard pattern |
+| Think Before Coding | Execution plan written before any code |
+| Human Checkpoint | `[AWAITING CONFIRMATION]` issued at >2-file change |
+| Blast Radius Check | Defined before touching existing route file |
+| Zero-Trust Secrets | `JWT_SECRET` read from `process.env`, hard failure if missing |
+| Patch-First Editing | `api.ts` change delivered as a diff, not a full rewrite |
+| Tech Debt Flagged | Inline router mounting noted in correct format |
+| Decision Log | Multi-file + data flow change triggers DECISIONS.md entry |
+| Anchor Check (Pre-Flight) | Verifiable manifest prepended before code output |
+| Verification Before Completion | Command and result reported before claiming the work is done |