code-warden 3.1.1 → 3.3.0

package/references/planning-gates.md

@@ -1,83 +1,83 @@
-# Planning Gates
-
-Two mandatory declaration blocks that fire before implementation begins.
-Neither is a checklist — they are structured outputs the AI produces and
-the user confirms before any code is written.
-
----
-
-## Scope Gate
-
-Fires when: a new session begins, scope is ambiguous, or a request would
-touch files outside the current declared scope.
-
-**AI produces this block. User confirms before proceeding.**
-
-```
-SCOPE GATE
-
-Goal:          [One sentence — what this session will accomplish]
-Non-goals:     [What is explicitly out of scope for this session]
-Files in:      [Complete list of files the AI expects to read or modify]
-Files out:     [Files that must not be touched, with reason]
-Verify after:  [The exact commands that will confirm success]
-Rollback:      [One-step revert — e.g. git checkout HEAD -- <files>]
-```
-
-Rules:
-- Goal must be one sentence. If it cannot be, split into multiple sessions.
-- Files-in list is a contract. Any unlisted file requires a new Scope Gate
-  or explicit user approval before it is touched.
-- Rollback must be a concrete command, not "undo manually."
-- If any field is unknown, write `[UNKNOWN — user must provide]` and halt.
-
----
-
-## Plan Gate
-
-Fires when: the session will touch more than one file, or any single change
-exceeds 30 lines.
-
-**AI produces this block after Scope Gate is confirmed. User confirms before any edits.**
-
-```
-PLAN GATE
-
-Patch order:
-  1. <file> — <one-line description of change>
-  2. <file> — <one-line description of change>
-  ...
-
-Blast radius class:  [CONTAINED | MODERATE | HIGH]
-  CONTAINED  — changes isolated to declared files, no interface changes
-  MODERATE   — shared interfaces or types modified, downstream callers may need updates
-  HIGH       — data-flow changes, schema changes, or deletions of public APIs
-
-Human checkpoint:    [YES | NO]
-  YES if: blast radius is MODERATE or HIGH, or more than 2 files are touched.
-
-Post-patch checks:
-  After step 1: [command or verification]
-  After step 2: [command or verification]
-  After all:    [final verification suite]
-```
-
-Rules:
-- Patch order is sequential. Do not parallelise edits across files unless
-  confirmed safe and explicitly approved.
-- Blast radius class must be declared before the first edit, not assessed after.
-- If Human Checkpoint is YES, pause after the last patch and output
-  `[AWAITING CONFIRMATION]` before marking the task complete.
-- Post-patch checks must be concrete commands, not "verify it works."
-
----
-
-## Gate Failure Response
-
-If either gate cannot be completed:
-
-1. State which field is blocking and why.
-2. Ask for the minimum information needed to fill it.
-3. Do not produce partial gates. Do not proceed without both gates confirmed.
-
-A partial plan is not a plan. Implement nothing until both gates are signed off.
+# Planning Gates
+
+Two mandatory declaration blocks that fire before implementation begins.
+Neither is a checklist — they are structured outputs the AI produces and
+the user confirms before any code is written.
+
+---
+
+## Scope Gate
+
+Fires when: a new session begins, scope is ambiguous, or a request would
+touch files outside the current declared scope.
+
+**AI produces this block. User confirms before proceeding.**
+
+```
+SCOPE GATE
+
+Goal:          [One sentence — what this session will accomplish]
+Non-goals:     [What is explicitly out of scope for this session]
+Files in:      [Complete list of files the AI expects to read or modify]
+Files out:     [Files that must not be touched, with reason]
+Verify after:  [The exact commands that will confirm success]
+Rollback:      [One-step revert — e.g. git checkout HEAD -- <files>]
+```
+
+Rules:
+- Goal must be one sentence. If it cannot be, split into multiple sessions.
+- Files-in list is a contract. Any unlisted file requires a new Scope Gate
+  or explicit user approval before it is touched.
+- Rollback must be a concrete command, not "undo manually."
+- If any field is unknown, write `[UNKNOWN — user must provide]` and halt.
+
+---
+
+## Plan Gate
+
+Fires when: the session will touch more than one file, or any single change
+exceeds 30 lines.
+
+**AI produces this block after Scope Gate is confirmed. User confirms before any edits.**
+
+```
+PLAN GATE
+
+Patch order:
+  1. <file> — <one-line description of change>
+  2. <file> — <one-line description of change>
+  ...
+
+Blast radius class:  [CONTAINED | MODERATE | HIGH]
+  CONTAINED  — changes isolated to declared files, no interface changes
+  MODERATE   — shared interfaces or types modified, downstream callers may need updates
+  HIGH       — data-flow changes, schema changes, or deletions of public APIs
+
+Human checkpoint:    [YES | NO]
+  YES if: blast radius is MODERATE or HIGH, or more than 2 files are touched.
+
+Post-patch checks:
+  After step 1: [command or verification]
+  After step 2: [command or verification]
+  After all:    [final verification suite]
+```
+
+Rules:
+- Patch order is sequential. Do not parallelise edits across files unless
+  confirmed safe and explicitly approved.
+- Blast radius class must be declared before the first edit, not assessed after.
+- If Human Checkpoint is YES, pause after the last patch and output
+  `[AWAITING CONFIRMATION]` before marking the task complete.
+- Post-patch checks must be concrete commands, not "verify it works."
+
+---
+
+## Gate Failure Response
+
+If either gate cannot be completed:
+
+1. State which field is blocking and why.
+2. Ask for the minimum information needed to fill it.
+3. Do not produce partial gates. Do not proceed without both gates confirmed.
+
+A partial plan is not a plan. Implement nothing until both gates are signed off.

package/references/research-and-fit.md

@@ -1,51 +1,51 @@
-# Research and Fit
-
-## Live Research Gate
-
-Do not rely on model training data when a decision depends on current facts.
-Run live research first when the task involves:
-- Current package versions, APIs, pricing, licenses, limits, or deprecations.
-- Framework, runtime, cloud, database, or platform recommendations.
-- Security, legal, policy, compliance, or financial claims.
-- Recently released tools, libraries, models, protocols, or standards.
-- Anything the user describes as latest, current, modern, today, new, or changed.
-
-Research standard:
-- Prefer official docs, release notes, standards, or source repositories.
-- Use registry metadata for package versions and license facts.
-- Capture the date-sensitive fact, source, and date accessed in the response or decision log.
-- If live research is unavailable, say so and treat the claim as unverified.
-
-## Default-Pattern Challenge
-
-Before choosing a stack, architecture, or product shape, challenge familiar defaults.
-Do not pick Node, Next.js, React, a SaaS dashboard, CRUD admin, or auth-first app
-unless the project context makes that choice fit.
-
-Required fit check:
-- User goal: what is the thing being built?
-- Primary user: who uses it and under what constraints?
-- Runtime/environment: browser, desktop, mobile, server, embedded, game engine, CLI, or hybrid.
-- Data shape: static, local-first, collaborative, realtime, batch, transactional, analytical, or media-heavy.
-- Interaction shape: workflow tool, creative tool, game, simulation, content site, dashboard, automation, API, or library.
-- Operational constraints: deployment target, offline needs, privacy, performance, budget, and maintenance burden.
-
-## Recommendation Discipline
-
-When recommending an approach over alternatives:
-- Name at least two viable alternatives unless the user already chose the stack.
-- Explain why the chosen approach fits the project's constraints better.
-- Identify the main tradeoff or downside.
-- Do not optimize for what is easiest for the model to generate.
-
-## Product-Shape Guardrail
-
-Do not assume every app is a SaaS dashboard.
-Match the first screen and navigation to the domain:
-- Operational tools can be dense and workflow-first.
-- Creative tools should put the canvas or creation surface first.
-- Games should open on the playable loop, not a marketing page.
-- Content sites should prioritize the content object or story.
-- Developer tools should expose the core command, API, or artifact early.
-
-If the shape is unclear, make a small fit assessment before designing or coding.
+# Research and Fit
+
+## Live Research Gate
+
+Do not rely on model training data when a decision depends on current facts.
+Run live research first when the task involves:
+- Current package versions, APIs, pricing, licenses, limits, or deprecations.
+- Framework, runtime, cloud, database, or platform recommendations.
+- Security, legal, policy, compliance, or financial claims.
+- Recently released tools, libraries, models, protocols, or standards.
+- Anything the user describes as latest, current, modern, today, new, or changed.
+
+Research standard:
+- Prefer official docs, release notes, standards, or source repositories.
+- Use registry metadata for package versions and license facts.
+- Capture the date-sensitive fact, source, and date accessed in the response or decision log.
+- If live research is unavailable, say so and treat the claim as unverified.
+
+## Default-Pattern Challenge
+
+Before choosing a stack, architecture, or product shape, challenge familiar defaults.
+Do not pick Node, Next.js, React, a SaaS dashboard, CRUD admin, or auth-first app
+unless the project context makes that choice fit.
+
+Required fit check:
+- User goal: what is the thing being built?
+- Primary user: who uses it and under what constraints?
+- Runtime/environment: browser, desktop, mobile, server, embedded, game engine, CLI, or hybrid.
+- Data shape: static, local-first, collaborative, realtime, batch, transactional, analytical, or media-heavy.
+- Interaction shape: workflow tool, creative tool, game, simulation, content site, dashboard, automation, API, or library.
+- Operational constraints: deployment target, offline needs, privacy, performance, budget, and maintenance burden.
+
+## Recommendation Discipline
+
+When recommending an approach over alternatives:
+- Name at least two viable alternatives unless the user already chose the stack.
+- Explain why the chosen approach fits the project's constraints better.
+- Identify the main tradeoff or downside.
+- Do not optimize for what is easiest for the model to generate.
+
+## Product-Shape Guardrail
+
+Do not assume every app is a SaaS dashboard.
+Match the first screen and navigation to the domain:
+- Operational tools can be dense and workflow-first.
+- Creative tools should put the canvas or creation surface first.
+- Games should open on the playable loop, not a marketing page.
+- Content sites should prioritize the content object or story.
+- Developer tools should expose the core command, API, or artifact early.
+
+If the shape is unclear, make a small fit assessment before designing or coding.

package/references/safety.md

@@ -1,31 +1,31 @@
-# Execution and Safety
-
-## Blast Radius Check
-
-Before deleting or rewriting any working code, define:
-1. **What might break** - list affected modules and interfaces.
-2. **How it will be tested** - specific test strategy or smoke test.
-3. **Rollback procedure** - one-step command or revert method.
-
-Example: `git checkout HEAD -- path/to/file`
-
-Never skip for any rewrite touching core logic.
-
-## Patch-First Editing
-
-- Prefer diff/patch edits over full file rewrites.
-- Only rewrite an entire file when structural changes affect >50% of its content.
-- All full rewrites require a Blast Radius Check first.
-- Surgical edits reduce accidental deletions, regression bugs, and context loss.
-
-## Zero-Trust Secrets
-
-- Never generate code with hardcoded API keys, passwords, tokens, or placeholder secrets.
-- Always default to environment variables such as `.env` or secure vault implementations.
-- No "TODO: replace later" escape hatches. Ever.
-
-## Dependency Freeze
-
-- Before any structural changes, list all current dependency versions.
-- Do not silently upgrade packages during a refactor.
-- Flag outdated dependencies separately. Do not fix without explicit confirmation.
+# Execution and Safety
+
+## Blast Radius Check
+
+Before deleting or rewriting any working code, define:
+1. **What might break** - list affected modules and interfaces.
+2. **How it will be tested** - specific test strategy or smoke test.
+3. **Rollback procedure** - one-step command or revert method.
+
+Example: `git checkout HEAD -- path/to/file`
+
+Never skip for any rewrite touching core logic.
+
+## Patch-First Editing
+
+- Prefer diff/patch edits over full file rewrites.
+- Only rewrite an entire file when structural changes affect >50% of its content.
+- All full rewrites require a Blast Radius Check first.
+- Surgical edits reduce accidental deletions, regression bugs, and context loss.
+
+## Zero-Trust Secrets
+
+- Never generate code with hardcoded API keys, passwords, tokens, or placeholder secrets.
+- Always default to environment variables such as `.env` or secure vault implementations.
+- No "TODO: replace later" escape hatches. Ever.
+
+## Dependency Freeze
+
+- Before any structural changes, list all current dependency versions.
+- Do not silently upgrade packages during a refactor.
+- Flag outdated dependencies separately. Do not fix without explicit confirmation.

package/templates/ci/github-actions.yml

@@ -1,66 +1,83 @@
-# Code-Warden Quality Gate — Project Template
-# https://github.com/Kodaxadev/Code-Warden
-#
-# Copy this file to .github/workflows/code-warden.yml in your project.
-#
-# What it enforces:
-#   - File length limits (warden-lint.js, default 400 lines per codewarden.json)
-#   - Zero-trust secrets (verify-secrets.js, hardcoded-credential patterns)
-#
-# How code-warden is made available in CI (choose one):
-#
-#   Option A — Download from release (recommended, no files to commit)
-#     Set CODE_WARDEN_VERSION below to pin a specific release.
-#     The "Install Code-Warden" step downloads and extracts automatically.
-#
-#   Option B — Commit to your repo
-#     Run: node /path/to/code-warden/install.js --target=claude
-#     Add .claude/skills/code-warden/ to git tracking.
-#     Set CODE_WARDEN_PATH: .claude/skills/code-warden
-#     Remove the "Install Code-Warden" step.
-#
-# Customise thresholds in codewarden.json after install:
-#   max_file_length          (default 400 lines)
-#   pre_flight_trigger_lines (default 150 lines)
-#   human_checkpoint_files   (default 2 files)
-
-name: Code-Warden Quality Gate
-
-on:
-  push:
-    branches: [main, master]
-  pull_request:
-    branches: [main, master]
-
-env:
-  CODE_WARDEN_VERSION: v3.1.0
-  CODE_WARDEN_PATH: .code-warden-ci
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-
-jobs:
-  code-warden:
-    name: Code-Warden Quality Gate
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-
-      # Option A: download from GitHub release (remove if using Option B)
-      - name: Install Code-Warden
-        run: |
-          curl -fsSL -o cw.zip \
-            "https://github.com/Kodaxadev/Code-Warden/releases/download/${{ env.CODE_WARDEN_VERSION }}/code-warden-${{ env.CODE_WARDEN_VERSION }}.zip"
-          mkdir -p ${{ env.CODE_WARDEN_PATH }}
-          unzip -q cw.zip -d ${{ env.CODE_WARDEN_PATH }}
-
-      - name: Lint — enforce file length limits
-        run: node ${{ env.CODE_WARDEN_PATH }}/tools/warden-lint.js .
-
-      - name: Secrets — zero-trust scan
-        run: node ${{ env.CODE_WARDEN_PATH }}/tools/verify-secrets.js .
+# Code-Warden Quality Gate — Project Template
+# https://github.com/Kodaxadev/Code-Warden
+#
+# Copy this file to .github/workflows/code-warden.yml in your project.
+#
+# What it enforces:
+#   - File length limits (default 400 lines per codewarden.json)
+#   - Zero-trust secrets (hardcoded-credential patterns)
+#   - Behavioral tests (scanner and hook pass/fail verification)
+#   - Source integrity (required files present)
+#
+# What it produces:
+#   - .code-warden-report.json — machine-readable governance artifact
+#   - Markdown summary on the workflow run / PR (via GITHUB_STEP_SUMMARY)
+#   - Uploaded artifact for audit trail (90-day retention)
+#
+# How code-warden is made available in CI (choose one):
+#
+#   Option A — Download from release (recommended, no files to commit)
+#     Set CODE_WARDEN_VERSION below to pin a specific release.
+#     The "Install Code-Warden" step downloads and extracts automatically.
+#
+#   Option B — Commit to your repo
+#     Run: node /path/to/code-warden/install.js --target=claude
+#     Add .claude/skills/code-warden/ to git tracking.
+#     Set CODE_WARDEN_PATH: .claude/skills/code-warden
+#     Remove the "Install Code-Warden" step.
+#
+# Customise thresholds in codewarden.json after install:
+#   max_file_length          (default 400 lines)
+#   pre_flight_trigger_lines (default 150 lines)
+#   human_checkpoint_files   (default 2 files)
+
+name: Code-Warden Quality Gate
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+env:
+  CODE_WARDEN_VERSION: v3.2.0
+  CODE_WARDEN_PATH: .code-warden-ci
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  code-warden:
+    name: Code-Warden Quality Gate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      # Option A: download from GitHub release (remove if using Option B)
+      - name: Install Code-Warden
+        run: |
+          curl -fsSL -o cw.zip \
+            "https://github.com/Kodaxadev/Code-Warden/releases/download/${{ env.CODE_WARDEN_VERSION }}/code-warden-${{ env.CODE_WARDEN_VERSION }}.zip"
+          mkdir -p ${{ env.CODE_WARDEN_PATH }}
+          unzip -q cw.zip -d ${{ env.CODE_WARDEN_PATH }}
+
+      - name: Governance report
+        run: node ${{ env.CODE_WARDEN_PATH }}/tools/governance-report.js .
+
+      - name: Publish governance summary
+        if: always()
+        run: node ${{ env.CODE_WARDEN_PATH }}/tools/governance-report.js . --format=md >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload governance artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: code-warden-report
+          path: .code-warden-report.json
+          if-no-files-found: ignore
+          retention-days: 90

package/tools/auto-detect.js

@@ -1,91 +1,91 @@
-#!/usr/bin/env node
-/**
- * auto-detect.js
- * Detection logic for the code-warden auto-installer.
- * Exports scanTargets(targets) -> targets annotated with detected/method fields.
- *
- * Detection order per target:
- *   1. Binary found in PATH (where / which)
- *   2. Config directory exists in HOME
- *   3. App install path exists (platform-specific)
- */
-
-const fs           = require('fs');
-const { execSync } = require('child_process');
-
-/**
- * Returns true if a CLI binary is resolvable via PATH.
- * Uses 'where' on Windows, 'which' on Unix.
- */
-function commandExists(bin) {
-  try {
-    const cmd = process.platform === 'win32' ? `where ${bin}` : `which ${bin}`;
-    execSync(cmd, { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Returns true if a path exists and is a directory.
- */
-function dirExists(p) {
-  try {
-    return fs.existsSync(p) && fs.statSync(p).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Returns true if a path exists (file or directory).
- */
-function pathExists(p) {
-  try {
-    return fs.existsSync(p);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Checks all detection signals for a single target.
- * Returns { detected: boolean, method: string|null }
- */
-function isInstalled(target) {
-  for (const bin of (target.detect.binaries || [])) {
-    if (commandExists(bin)) {
-      return { detected: true, method: `binary:${bin}` };
-    }
-  }
-
-  for (const dir of (target.detect.dirs || [])) {
-    if (dirExists(dir)) {
-      return { detected: true, method: `dir:${dir}` };
-    }
-  }
-
-  const platformApps = (target.detect.apps || {})[process.platform] || [];
-  for (const appPath of platformApps) {
-    if (pathExists(appPath)) {
-      return { detected: true, method: `app:${appPath}` };
-    }
-  }
-
-  return { detected: false, method: null };
-}
-
-/**
- * Scans all targets and annotates each with detection results.
- * @param {Array} targets - TARGETS array from auto-targets.js
- * @returns {Array} - same array with detected and method fields added
- */
-function scanTargets(targets) {
-  return targets.map(target => {
-    const result = isInstalled(target);
-    return { ...target, ...result };
-  });
-}
-
-module.exports = { scanTargets, isInstalled, commandExists };
+#!/usr/bin/env node
+/**
+ * auto-detect.js
+ * Detection logic for the code-warden auto-installer.
+ * Exports scanTargets(targets) -> targets annotated with detected/method fields.
+ *
+ * Detection order per target:
+ *   1. Binary found in PATH (where / which)
+ *   2. Config directory exists in HOME
+ *   3. App install path exists (platform-specific)
+ */
+
+const fs           = require('fs');
+const { execSync } = require('child_process');
+
+/**
+ * Returns true if a CLI binary is resolvable via PATH.
+ * Uses 'where' on Windows, 'which' on Unix.
+ */
+function commandExists(bin) {
+  try {
+    const cmd = process.platform === 'win32' ? `where ${bin}` : `which ${bin}`;
+    execSync(cmd, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if a path exists and is a directory.
+ */
+function dirExists(p) {
+  try {
+    return fs.existsSync(p) && fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if a path exists (file or directory).
+ */
+function pathExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks all detection signals for a single target.
+ * Returns { detected: boolean, method: string|null }
+ */
+function isInstalled(target) {
+  for (const bin of (target.detect.binaries || [])) {
+    if (commandExists(bin)) {
+      return { detected: true, method: `binary:${bin}` };
+    }
+  }
+
+  for (const dir of (target.detect.dirs || [])) {
+    if (dirExists(dir)) {
+      return { detected: true, method: `dir:${dir}` };
+    }
+  }
+
+  const platformApps = (target.detect.apps || {})[process.platform] || [];
+  for (const appPath of platformApps) {
+    if (pathExists(appPath)) {
+      return { detected: true, method: `app:${appPath}` };
+    }
+  }
+
+  return { detected: false, method: null };
+}
+
+/**
+ * Scans all targets and annotates each with detection results.
+ * @param {Array} targets - TARGETS array from auto-targets.js
+ * @returns {Array} - same array with detected and method fields added
+ */
+function scanTargets(targets) {
+  return targets.map(target => {
+    const result = isInstalled(target);
+    return { ...target, ...result };
+  });
+}
+
+module.exports = { scanTargets, isInstalled, commandExists };