code-warden 3.1.1

package/references/planning-gates.md

@@ -0,0 +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.

package/references/research-and-fit.md

@@ -0,0 +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.

package/references/safety.md

@@ -0,0 +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.

package/templates/ci/github-actions.yml

@@ -0,0 +1,66 @@
+# 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 .

package/tools/auto-detect.js

@@ -0,0 +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 };

package/tools/auto-targets.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * auto-targets.js
+ * Target registry for the code-warden auto-installer.
+ * Each entry describes one AI app, how to detect it, and where to install.
+ *
+ * format values:
+ *   'skill-md'      - copy the full skill folder (SKILL.md + references/ + tools/)
+ *   'windsurf-flat' - concatenate into a single .md file via auto-windsurf-adapter.js
+ */
+
+const os   = require('os');
+const path = require('path');
+
+const HOME        = os.homedir();
+const LOCALAPPDATA = process.env.LOCALAPPDATA || '';
+const APPDATA      = process.env.APPDATA      || '';
+
+const TARGETS = [
+  {
+    id:        'claude',
+    name:      'Claude Code',
+    format:    'skill-md',
+    skillsDir: path.join(HOME, '.claude', 'skills'),
+    detect: {
+      binaries: ['claude'],
+      dirs:     [path.join(HOME, '.claude')],
+      apps: {
+        darwin: ['/Applications/Claude.app'],
+        win32:  [path.join(LOCALAPPDATA, 'Programs', 'claude', 'claude.exe')],
+        linux:  [],
+      },
+    },
+  },
+  {
+    id:        'cursor',
+    name:      'Cursor',
+    format:    'skill-md',
+    skillsDir: path.join(HOME, '.cursor', 'skills'),
+    detect: {
+      binaries: ['cursor'],
+      dirs:     [path.join(HOME, '.cursor')],
+      apps: {
+        darwin: ['/Applications/Cursor.app'],
+        win32:  [path.join(LOCALAPPDATA, 'Programs', 'cursor', 'Cursor.exe')],
+        linux:  [path.join(HOME, '.local', 'share', 'cursor')],
+      },
+    },
+  },
+  {
+    id:        'warp',
+    name:      'Warp',
+    format:    'skill-md',
+    skillsDir: path.join(HOME, '.warp', 'skills'),
+    detect: {
+      binaries: ['warp', 'warp-terminal'],
+      dirs:     [path.join(HOME, '.warp')],
+      apps: {
+        darwin: ['/Applications/Warp.app'],
+        win32:  [path.join(LOCALAPPDATA, 'Programs', 'Warp', 'Warp.exe')],
+        linux:  [],
+      },
+    },
+  },
+  {
+    id:        'codex',
+    name:      'OpenAI Codex',
+    format:    'skill-md',
+    skillsDir: path.join(HOME, '.codex', 'skills'),
+    detect: {
+      binaries: ['codex'],
+      dirs:     [path.join(HOME, '.codex')],
+      apps:     { darwin: [], win32: [], linux: [] },
+    },
+  },
+  {
+    id:        'agents',
+    name:      'Generic Agents',
+    format:    'skill-md',
+    skillsDir: path.join(HOME, '.agents', 'skills'),
+    detect: {
+      binaries: [],
+      dirs:     [path.join(HOME, '.agents')],
+      apps:     { darwin: [], win32: [], linux: [] },
+    },
+  },
+  {
+    id:        'windsurf',
+    name:      'Windsurf',
+    format:    'windsurf-flat',
+    skillsDir: path.join(HOME, '.windsurf', 'rules'),
+    detect: {
+      binaries: ['windsurf'],
+      dirs:     [path.join(HOME, '.windsurf')],
+      apps: {
+        darwin: ['/Applications/Windsurf.app'],
+        win32:  [path.join(LOCALAPPDATA, 'Programs', 'Windsurf', 'Windsurf.exe')],
+        linux:  [],
+      },
+    },
+  },
+];
+
+module.exports = { TARGETS };

package/tools/auto-windsurf-adapter.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * auto-windsurf-adapter.js
+ * Converts the modular code-warden skill into a single flat markdown file
+ * compatible with Windsurf's rules format (.windsurf/rules/).
+ *
+ * Concatenation order:
+ *   SKILL.md -> planning-gates -> architecture -> safety -> cognition -> cleanup
+ *             -> anti-drift -> operations -> research-and-fit
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const REFERENCE_ORDER = [
+  'planning-gates',
+  'architecture',
+  'safety',
+  'cognition',
+  'cleanup',
+  'anti-drift',
+  'operations',
+  'research-and-fit',
+];
+
+const OUTPUT_FILENAME = 'code-warden.md';
+
+/**
+ * Reads a file and returns its content.
+ * - SKILL.md missing: throws (hard fail — output is meaningless without it)
+ * - Reference missing: warns to stderr, inserts a comment, continues
+ */
+function readSafe(filePath, label) {
+  if (!fs.existsSync(filePath)) {
+    if (label === 'SKILL.md') {
+      throw new Error(`SKILL.md not found at ${filePath} — cannot generate Windsurf output.`);
+    }
+    console.warn(`[CodeWarden] WARN  ${label} not found, skipping.`);
+    return `\n<!-- [CodeWarden] WARNING: ${label} not found — section omitted -->\n`;
+  }
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+/**
+ * Builds and writes the flat Windsurf rules file.
+ * @param {string} sourceDir - root of the code-warden skill source
+ * @param {string} destDir   - target directory (e.g. ~/.windsurf/rules)
+ * @returns {string} - full path of the written file
+ */
+function installWindsurf(sourceDir, destDir) {
+  const sections = [];
+
+  sections.push('<!-- Generated by code-warden auto-installer. Do not edit manually. -->');
+  sections.push('<!-- Source: https://github.com/Kodaxadev/Code-Warden -->');
+  sections.push('');
+
+  const skillMdPath = path.join(sourceDir, 'SKILL.md');
+  sections.push(readSafe(skillMdPath, 'SKILL.md'));
+
+  for (const ref of REFERENCE_ORDER) {
+    const refPath = path.join(sourceDir, 'references', `${ref}.md`);
+    sections.push(`\n---\n`);
+    sections.push(readSafe(refPath, `references/${ref}.md`));
+  }
+
+  const output = sections.join('\n');
+
+  fs.mkdirSync(destDir, { recursive: true });
+  const outPath = path.join(destDir, OUTPUT_FILENAME);
+  fs.writeFileSync(outPath, output, 'utf8');
+
+  return outPath;
+}
+
+module.exports = { installWindsurf };

package/tools/get-context.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const candidates = [
+  'AGENTS.md',
+  '.codex/AGENTS.md',
+  'ARCHITECTURE.md',
+  'docs/ARCHITECTURE.md',
+  '.agents/AGENTS.md',
+  '.claude/CLAUDE.md',
+  'CLAUDE.md',
+  'README.md',
+  'docs/README.md',
+  'PRD.md',
+];
+
+function findContextFile(startDir) {
+  let currDir = path.resolve(startDir);
+
+  while (true) {
+    for (const candidate of candidates) {
+      const fullPath = path.join(currDir, candidate);
+      if (fs.existsSync(fullPath)) {
+        return fullPath;
+      }
+    }
+
+    const parentDir = path.dirname(currDir);
+    if (parentDir === currDir) {
+      return null;
+    }
+    currDir = parentDir;
+  }
+}
+
+const contextFile = findContextFile(process.cwd());
+
+if (contextFile) {
+  console.log(`Found architectural context at: ${contextFile}\n`);
+  const content = fs.readFileSync(contextFile, 'utf8');
+  if (content.length > 5000) {
+    console.log(`${content.substring(0, 5000)}\n...[Content truncated]`);
+  } else {
+    console.log(content);
+  }
+} else {
+  console.log('[WARN] No AGENTS.md, architecture doc, CLAUDE.md, PRD, or README found in the repository hierarchy.');
+  process.exit(1);
+}

package/tools/hooks/claude/install-hooks.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * install-hooks.js
+ * Merges code-warden PreToolUse hook entries into ~/.claude/settings.json.
+ *
+ * Idempotent: removes any existing code-warden entries by description marker,
+ * then inserts current entries. Replace, not skip — ensures paths stay current
+ * after reinstalls or version moves.
+ *
+ * Requires the skill to already be installed at skillDir before writing
+ * settings — avoids dangling settings pointing at a missing skill directory.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const MARKER_PREFIX  = 'code-warden:';
+const SETTINGS_PATH  = path.join(os.homedir(), '.claude', 'settings.json');
+
+// ---------------------------------------------------------------------------
+// Settings I/O
+// ---------------------------------------------------------------------------
+
+function readSettings() {
+  if (!fs.existsSync(SETTINGS_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+  } catch (err) {
+    throw new Error(`settings.json exists but could not be parsed (${SETTINGS_PATH}): ${err.message}`);
+  }
+}
+
+function writeSettings(settings) {
+  const tmp = `${SETTINGS_PATH}.tmp`;
+  fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, SETTINGS_PATH);
+}
+
+// ---------------------------------------------------------------------------
+// Hook entry helpers
+// ---------------------------------------------------------------------------
+
+function stripCodeWardenHooks(preToolUse) {
+  return preToolUse
+    .map(matcher => ({
+      ...matcher,
+      hooks: (matcher.hooks || []).filter(
+        h => !String(h.description || '').startsWith(MARKER_PREFIX)
+      ),
+    }))
+    .filter(matcher => (matcher.hooks || []).length > 0);
+}
+
+function buildEntries(skillDir) {
+  return [
+    {
+      type:        'command',
+      command:     'node',
+      args:        [path.join(skillDir, 'tools', 'hooks', 'claude', 'warden-lint-hook.js')],
+      description: 'code-warden: file length gate',
+      timeout:     30,
+    },
+    {
+      type:        'command',
+      command:     'node',
+      args:        [path.join(skillDir, 'tools', 'hooks', 'claude', 'warden-secrets-hook.js')],
+      description: 'code-warden: zero-trust secrets gate',
+      timeout:     30,
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Install
+// ---------------------------------------------------------------------------
+
+function installHooks(skillDir) {
+  // Guard: skill must be installed before settings are written
+  const required = [
+    path.join(skillDir, 'SKILL.md'),
+    path.join(skillDir, 'tools', 'hooks', 'claude', 'warden-lint-hook.js'),
+    path.join(skillDir, 'tools', 'hooks', 'claude', 'warden-secrets-hook.js'),
+  ];
+  for (const p of required) {
+    if (!fs.existsSync(p)) {
+      console.error('[CodeWarden] Hooks require an installed Claude target.');
+      console.error(`[CodeWarden] Missing: ${p}`);
+      console.error('[CodeWarden] Run: node install.js --target=claude --all');
+      process.exit(1);
+    }
+  }
+
+  const settings  = readSettings();
+  settings.hooks  = settings.hooks || {};
+  const existing  = settings.hooks.PreToolUse || [];
+
+  // Remove stale code-warden entries, then append fresh block
+  const cleaned   = stripCodeWardenHooks(existing);
+  settings.hooks.PreToolUse = [
+    ...cleaned,
+    { matcher: 'Write|Edit', hooks: buildEntries(skillDir) },
+  ];
+
+  writeSettings(settings);
+  return SETTINGS_PATH;
+}
+
+module.exports = { installHooks };