@whitehatd/crag 0.2.8 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whitehatd/crag",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "The bedrock layer for AI coding agents. One governance.md. Any project. Never stale.",
   "bin": {
     "crag": "bin/crag.js"

package/src/analyze/stacks.js

@@ -145,8 +145,18 @@ function detectStack(dir, result, options = {}) {
  */
 function detectNestedStacks(dir, result) {
   const containerDirs = [
+    // Classic containers (monorepos, microservice demos, VSCode-style editors)
     'src', 'services', 'packages', 'apps', 'cmd', 'projects', 'microservices',
     'sdk', 'sdks', 'web', 'ui', 'editors', 'extensions', 'clients',
+    // Monolith tier-naming (backend/frontend/mobile layouts are extremely
+    // common in single-repo full-stack projects — e.g. Leyoda, Metabase,
+    // many Y Combinator startups). Without these, `crag analyze` on a
+    // top-level monolith root reports `Stack: unknown` because no root
+    // manifest exists and none of the classic containers are present.
+    'backend', 'frontend', 'api', 'client', 'server', 'worker', 'workers',
+    'mobile', 'ios', 'android', 'desktop', 'cli', 'lib', 'libs', 'shared',
+    // Common AI / data pipeline layouts
+    'signal-engine', 'pipelines', 'ml', 'models', 'agents', 'notebooks',
   ];
 
   const rootHadStacks = result.stack.length > 0;

package/src/commands/analyze.js

@@ -136,9 +136,24 @@ function filterFixtureMembers(members) {
   });
 }
 
+/**
+ * Sanitize a directory basename for use as a project name.
+ *
+ * Drops leading non-alphanumerics (`- Leyoda` → `Leyoda`), trims surrounding
+ * whitespace, and collapses internal whitespace runs. Leaves interior dashes
+ * and underscores intact (`my-cool-project` stays as-is). If the result is
+ * empty (pathological input like `---` or `   `), falls back to the literal
+ * basename so `crag analyze` never produces an empty `- Project:` line.
+ */
+function sanitizeProjectName(basename) {
+  if (typeof basename !== 'string') return String(basename || 'unnamed');
+  const trimmed = basename.trim().replace(/^[^A-Za-z0-9]+/, '').replace(/\s+/g, ' ').trim();
+  return trimmed.length > 0 ? trimmed : basename;
+}
+
 function analyzeProject(dir) {
   const result = {
-    name: path.basename(dir),
+    name: sanitizeProjectName(path.basename(dir)),
     description: '',
     stack: [],
     linters: [],
@@ -450,4 +465,4 @@ function mergeWithExisting(existing, generated) {
   return existing;
 }
 
-module.exports = { analyze, analyzeProject, isGateCommand, mergeWithExisting };
+module.exports = { analyze, analyzeProject, sanitizeProjectName, isGateCommand, mergeWithExisting };

package/src/commands/diff.js

@@ -5,6 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const { parseGovernance, flattenGates } = require('../governance/parse');
 const { extractRunCommands, isGateCommand } = require('../governance/yaml-run');
+const { detectBranchStrategy, classifyGitBranchStrategy } = require('../governance/drift-utils');
 const { cliError, EXIT_USER, EXIT_INTERNAL, readFileOrExit } = require('../cli-errors');
 
 /**
@@ -102,17 +103,12 @@ function checkGateReality(cwd, cmd) {
 }
 
 function checkBranchStrategy(cwd, content, results) {
-  const govStrategy = content.includes('Feature branches') || content.includes('feature branches')
-    ? 'feature-branches' : content.includes('Trunk-based') || content.includes('trunk-based')
-    ? 'trunk-based' : null;
-
+  const govStrategy = detectBranchStrategy(content);
   if (!govStrategy) return;
 
   try {
     const branches = execSync('git branch -a --format="%(refname:short)"', { cwd, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] });
-    const list = branches.trim().split('\n');
-    const featureBranches = list.filter(b => /^(feat|fix|docs|chore|feature|hotfix)\//.test(b));
-    const actual = featureBranches.length > 2 ? 'feature-branches' : 'trunk-based';
+    const actual = classifyGitBranchStrategy(branches);
 
     if (actual !== govStrategy) {
       console.log(`  \x1b[33mDRIFT\x1b[0m   Branch strategy: governance says ${govStrategy}, git shows ${actual}`);

package/src/commands/doctor.js

@@ -21,8 +21,11 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { parseGovernance, flattenGates, extractSection } = require('../governance/parse');
+const { parseGovernance, flattenGates } = require('../governance/parse');
+const { detectBranchStrategy, countFeatureBranches } = require('../governance/drift-utils');
 const { isModified, readFrontmatter } = require('../update/integrity');
+const { detectWorkspace } = require('../workspace/detect');
+const { enumerateMembers } = require('../workspace/enumerate');
 const { EXIT_USER, EXIT_INTERNAL } = require('../cli-errors');
 
 const GREEN = '\x1b[32m';
@@ -45,15 +48,36 @@ const ICON_FAIL = `${RED}✗${RESET}`;
  *               hooks, file presence). Useful in CI where .claude/ is
  *               either absent or freshly generated via `crag analyze`.
  *   --strict    Treat warnings as failures (exit 1 on any warn).
+ *   --workspace Run doctor on every workspace member that has `.claude/`,
+ *               plus the root. Aggregates pass/warn/fail counts across
+ *               members and exits non-zero if ANY member failed.
  */
 function doctor(args) {
   const cwd = process.cwd();
   const jsonOutput = args.includes('--json');
   const ciMode = args.includes('--ci');
   const strict = args.includes('--strict');
+  const workspace = args.includes('--workspace');
 
-  const report = runDiagnostics(cwd, { ciMode });
+  // Workspace mode: run diagnostics on root + every member. Emits one
+  // combined report (JSON) or prints per-member sections (human).
+  if (workspace) {
+    const { reports, combined } = runWorkspaceDiagnostics(cwd, { ciMode });
+    const exitCode = computeExitCode(combined, strict);
+
+    if (jsonOutput) {
+      console.log(JSON.stringify({ mode: 'workspace', reports, combined }, null, 2));
+      process.exit(exitCode);
+    }
+
+    for (const r of reports) {
+      printReport(r, { ciMode, strict });
+    }
+    printWorkspaceSummary(combined);
+    process.exit(exitCode);
+  }
 
+  const report = runDiagnostics(cwd, { ciMode });
   const exitCode = computeExitCode(report, strict);
 
   if (jsonOutput) {
@@ -65,6 +89,45 @@ function doctor(args) {
   process.exit(exitCode);
 }
 
+/**
+ * Run doctor across a workspace.
+ *
+ * Always includes the root (cwd). Then, if the root is a workspace, runs
+ * against each enumerated member. Members without a `.claude/` directory
+ * are skipped — there's nothing for doctor to check in them.
+ *
+ * Returns { reports: Report[], combined: CombinedCounts }.
+ */
+function runWorkspaceDiagnostics(cwd, options = {}) {
+  const reports = [];
+  const rootReport = runDiagnostics(cwd, options);
+  reports.push(rootReport);
+
+  const ws = detectWorkspace(cwd);
+  if (ws.type !== 'none') {
+    const members = enumerateMembers(ws);
+    for (const m of members) {
+      if (!m.hasClaude) continue; // nothing for doctor to see in this member
+      const memberReport = runDiagnostics(m.path, options);
+      reports.push(memberReport);
+    }
+  }
+
+  const combined = reports.reduce(
+    (acc, r) => ({
+      cwd,
+      pass: acc.pass + r.pass,
+      warn: acc.warn + r.warn,
+      fail: acc.fail + r.fail,
+      memberCount: acc.memberCount + 1,
+      ciMode: r.ciMode,
+    }),
+    { cwd, pass: 0, warn: 0, fail: 0, memberCount: 0, ciMode: options.ciMode || false }
+  );
+
+  return { reports, combined };
+}
+
 function computeExitCode(report, strict) {
   if (report.fail > 0) return 1;
   if (strict && report.warn > 0) return 1;
@@ -381,68 +444,6 @@ function diagnoseHooks(cwd) {
 // Section: Drift (reuses crag diff logic)
 // ============================================================================
 
-/**
- * Detect the branch strategy declared in a governance.md document.
- *
- * Scopes the text scan to the `## Branch Strategy` section (avoiding false
- * matches against unrelated prose). Within that section, the FIRST keyword
- * to appear wins — this matches human reading order where the opening
- * statement is the rule and later lines are qualifications.
- *
- * Returns 'feature-branches', 'trunk-based', or null.
- *
- * Exported for unit testing.
- */
-function detectBranchStrategy(content) {
-  if (typeof content !== 'string' || content.length === 0) return null;
-  const section = extractSection(content, 'Branch Strategy');
-  const scope = section || content; // fall back to whole file if section absent
-  const featureIdx = scope.search(/[Ff]eature branches/);
-  const trunkIdx = scope.search(/[Tt]runk-based/);
-  if (featureIdx === -1 && trunkIdx === -1) return null;
-  if (featureIdx === -1) return 'trunk-based';
-  if (trunkIdx === -1) return 'feature-branches';
-  return featureIdx < trunkIdx ? 'feature-branches' : 'trunk-based';
-}
-
-/**
- * Given the raw output of `git branch -a --format="%(refname:short)"`, return
- * the list of unique feature branches (by short name, after stripping any
- * remote prefix).
- *
- * This is the piece that decides whether a repo is practicing feature-branch
- * development. A repo whose LOCAL branches have all been merged+deleted but
- * whose REMOTE still has open feat/* branches is absolutely still practicing
- * feature-branch development — so we count remote-tracking refs as equivalent
- * to local branches, and we dedupe.
- *
- * Exported for unit testing — avoids the need to set up a real git fixture.
- */
-const FEATURE_PREFIXES = ['feat', 'fix', 'docs', 'chore', 'feature', 'hotfix'];
-
-function countFeatureBranches(gitBranchOutput) {
-  if (typeof gitBranchOutput !== 'string' || gitBranchOutput.length === 0) {
-    return [];
-  }
-  const rawList = gitBranchOutput
-    .split('\n')
-    .map(b => b.trim())
-    .filter(Boolean)
-    // Skip symbolic refs like "origin/HEAD" (no payload branch underneath).
-    .filter(b => !b.endsWith('/HEAD'));
-
-  const prefixGroup = FEATURE_PREFIXES.join('|');
-  const remoteStripRe = new RegExp(`^[A-Za-z0-9_.-]+/((?:${prefixGroup})/.+)$`);
-  const featureRe = new RegExp(`^(${prefixGroup})/`);
-
-  const normalized = rawList.map(b => {
-    const m = b.match(remoteStripRe);
-    return m ? m[1] : b;
-  });
-  const unique = [...new Set(normalized)];
-  return unique.filter(b => featureRe.test(b));
-}
-
 function diagnoseDrift(cwd) {
   const checks = [];
   const govPath = path.join(cwd, '.claude', 'governance.md');
@@ -644,4 +645,25 @@ function printReport(report, { ciMode = false, strict = false } = {}) {
   }
 }
 
-module.exports = { doctor, runDiagnostics, countFeatureBranches, detectBranchStrategy };
+/**
+ * Print a per-workspace summary after all individual reports have been
+ * printed. Shows the combined pass/warn/fail counts across the root and
+ * every member that was inspected.
+ */
+function printWorkspaceSummary(combined) {
+  const total = combined.pass + combined.warn + combined.fail;
+  const msg = `  Workspace total — ${combined.pass}/${total} pass, ${combined.warn} warn, ${combined.fail} fail (${combined.memberCount} target${combined.memberCount === 1 ? '' : 's'})`;
+  if (combined.fail > 0) console.log(`${RED}${BOLD}${msg}${RESET}\n`);
+  else if (combined.warn > 0) console.log(`${YELLOW}${BOLD}${msg}${RESET}\n`);
+  else console.log(`${GREEN}${BOLD}${msg}${RESET}\n`);
+}
+
+module.exports = {
+  doctor,
+  runDiagnostics,
+  runWorkspaceDiagnostics,
+  // Re-exported from drift-utils for backward compatibility with existing
+  // tests that import from './commands/doctor'.
+  countFeatureBranches,
+  detectBranchStrategy,
+};

package/src/crag-agent.md

@@ -155,7 +155,7 @@ Create `.claude/hooks/`:
 
 **auto-post-start.sh** — always generate. Gate enforcement safety net. Reads tool input from stdin, checks if the command is a `git commit`, warns if `.claude/.gates-passed` sentinel doesn't exist. Non-blocking (warns, doesn't prevent). Same for all projects.
 
-**sandbox-guard.sh** — always generate. Security hardening. Reads tool input from stdin (PreToolUse on Bash), hard-blocks destructive system commands (rm -rf /, dd, mkfs, DROP TABLE, docker system prune, kubectl delete namespace, curl|bash, force-push to main). Warns on file operations targeting paths outside the project root. Same for all projects.
+**sandbox-guard.sh** — always generate. Security hardening. Reads tool input from stdin (PreToolUse on Bash), hard-blocks destructive system commands (rm -rf /, dd, mkfs, DROP TABLE, docker system prune, kubectl delete namespace, curl|bash, force-push to main). Warns on file operations targeting paths outside the project root. Same for all projects. **MUST include `# rtk-hook-version: 3` as line 2 (right after the shebang)** — without this marker in the first 5 lines, RTK prints "Hook outdated" warnings on every invocation and `crag doctor` flags the hook as warn. Also **strip single-quoted strings before the destructive-pattern grep** (`CHECK=$(echo "$COMMAND" | sed "s/'[^']*'/''/g")`) so data payloads that legitimately mention destructive verbs inside quoted strings (e.g. `python script.py '{"content":"rm -rf / is blocked"}'`) don't false-trip the guard.
 
 **pre-compact-snapshot.sh** — only if MemStack enabled. Use correct project name.
 

package/src/governance/drift-utils.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * Drift-detection helpers shared between `crag doctor` and `crag diff`.
+ *
+ * Both commands need to answer the same two questions:
+ *
+ *   1. What branch strategy does the governance claim? (text scan of the
+ *      `## Branch Strategy` section — first keyword mention wins, so a
+ *      workspace wrapper that says "trunk-based at root, feature branches
+ *      in sub-repos" is classified as trunk-based, which matches its own
+ *      git reality even when sub-repos use feature branches.)
+ *
+ *   2. What does git actually show? (count unique feature branches across
+ *      local + remote refs, stripping `origin/` so a repo whose local
+ *      branches are merged+deleted but whose remote still has open
+ *      `feat/*` refs is correctly classified as feature-branches.)
+ *
+ * Before this module existed, doctor.js and diff.js each had their own
+ * (slightly different, slightly wrong) implementations. The duplication
+ * meant a fix landed in doctor went unapplied in diff and vice-versa —
+ * real bug, caught by stress testing against real repos.
+ *
+ * This module is the single source of truth. Import from here; do not
+ * reimplement.
+ */
+
+const { extractSection } = require('./parse');
+
+const FEATURE_PREFIXES = ['feat', 'fix', 'docs', 'chore', 'feature', 'hotfix'];
+
+/**
+ * Detect the branch strategy declared in a governance.md document.
+ *
+ * Scopes the text scan to the `## Branch Strategy` section (avoiding false
+ * matches against unrelated prose). Within that section, the FIRST keyword
+ * to appear wins — this matches human reading order where the opening
+ * statement is the rule and later lines are qualifications.
+ *
+ * Returns 'feature-branches', 'trunk-based', or null.
+ */
+function detectBranchStrategy(content) {
+  if (typeof content !== 'string' || content.length === 0) return null;
+  const section = extractSection(content, 'Branch Strategy');
+  const scope = section || content; // fall back to whole file if section absent
+  const featureIdx = scope.search(/[Ff]eature branches/);
+  const trunkIdx = scope.search(/[Tt]runk-based/);
+  if (featureIdx === -1 && trunkIdx === -1) return null;
+  if (featureIdx === -1) return 'trunk-based';
+  if (trunkIdx === -1) return 'feature-branches';
+  return featureIdx < trunkIdx ? 'feature-branches' : 'trunk-based';
+}
+
+/**
+ * Given the raw output of `git branch -a --format="%(refname:short)"`, return
+ * the list of unique feature branches (by short name, after stripping any
+ * remote prefix).
+ *
+ * Normalizes remote-tracking refs so `origin/feat/foo` and `feat/foo`
+ * both count as the same feature branch. A repo whose local branches
+ * have been merged-and-deleted but whose remote still has feat/*
+ * branches IS still practicing feature-branch development — callers
+ * MUST NOT misread that as "trunk-based".
+ *
+ * Also skips symbolic refs like `origin/HEAD`.
+ */
+function countFeatureBranches(gitBranchOutput) {
+  if (typeof gitBranchOutput !== 'string' || gitBranchOutput.length === 0) {
+    return [];
+  }
+  const rawList = gitBranchOutput
+    .split('\n')
+    .map(b => b.trim())
+    .filter(Boolean)
+    .filter(b => !b.endsWith('/HEAD')); // skip symbolic refs
+
+  const prefixGroup = FEATURE_PREFIXES.join('|');
+  const remoteStripRe = new RegExp(`^[A-Za-z0-9_.-]+/((?:${prefixGroup})/.+)$`);
+  const featureRe = new RegExp(`^(${prefixGroup})/`);
+
+  const normalized = rawList.map(b => {
+    const m = b.match(remoteStripRe);
+    return m ? m[1] : b;
+  });
+  const unique = [...new Set(normalized)];
+  return unique.filter(b => featureRe.test(b));
+}
+
+/**
+ * Classify a repo as 'feature-branches' or 'trunk-based' based on the
+ * current `git branch -a --format=%(refname:short)` output.
+ *
+ * Threshold: 3+ unique feature branches indicates active feature-branch
+ * workflow. Fewer (or 0) indicates trunk-based — even if history shows
+ * some merge commits from old feat/* branches that have been deleted.
+ */
+function classifyGitBranchStrategy(gitBranchOutput) {
+  const features = countFeatureBranches(gitBranchOutput);
+  return features.length > 2 ? 'feature-branches' : 'trunk-based';
+}
+
+module.exports = {
+  FEATURE_PREFIXES,
+  detectBranchStrategy,
+  countFeatureBranches,
+  classifyGitBranchStrategy,
+};

package/src/governance/yaml-run.js

@@ -71,6 +71,47 @@ function extractRunCommands(content) {
  * (extra gates) are easier to spot than false negatives (missing gates).
  */
 function isGateCommand(cmd) {
+  if (typeof cmd !== 'string' || cmd.length === 0) return false;
+
+  // ---------------------------------------------------------------------
+  // Early excludes — NEVER gates, regardless of keyword substring matches.
+  //
+  // A workflow step like `echo "Install: npm install -g foo"` contains
+  // the substring "npm install" even though it's shell plumbing (emitting
+  // a string to stdout). The old isGateCommand relied entirely on positive
+  // regex matches and so flagged these as gates, which `crag diff` then
+  // reported as EXTRA — noisy false positives.
+  //
+  // This first pass rejects obvious non-gates: variable assignments,
+  // echoes, git plumbing, release-specific scripts, and GitHub Actions
+  // output-writing. If ANY of these match, the command is definitively
+  // not a gate regardless of what it mentions downstream.
+  // ---------------------------------------------------------------------
+  const excludePatterns = [
+    // Shell I/O plumbing
+    /^\s*echo(\s|$)/,
+    /^\s*printf(\s|$)/,
+    // Shell variable assignment: NAME=value or NAME=$(subshell)
+    /^\s*[A-Z_][A-Z0-9_]*=/,
+    // Git mutations and introspection (deploy/release, not gates)
+    /^\s*git\s+(config|push|pull|fetch|add|commit|tag|merge|rebase|reset|checkout|stash|clone|init|remote|log|status)\b/,
+    // npm release/distribution verbs — not gates
+    /^\s*npm\s+(publish|pack|view|audit|login|logout|adduser|deprecate|owner|team|whoami|access)\b/,
+    // Release scripts live under scripts/ and are NOT gates themselves
+    /^\s*node\s+scripts\/(bump-version|release|publish|sync-)/,
+    /^\s*npm\s+run\s+(release|publish|sync-|prepublish|postpublish|prepare)\b/,
+    // GitHub Actions output streams — these are CI plumbing, not gates
+    /\$GITHUB_(STEP_SUMMARY|OUTPUT|ENV|PATH)/,
+    // Conditional / control flow keywords on their own line
+    /^\s*(if|then|else|elif|fi|while|do|done|for|case|esac|break|continue|return)\s*$/,
+    /^\s*(if|for|while|case)\s+/,
+    // Filesystem setup that is not a gate
+    /^\s*(mkdir|rmdir|touch|ln|cp|mv|chmod|chown)\s/,
+  ];
+  for (const rx of excludePatterns) {
+    if (rx.test(cmd)) return false;
+  }
+
   const patterns = [
     // Node ecosystem
     /\bnpm (run |ci|test|install)/,

package/src/skills/post-start-validation.md

@@ -1,6 +1,6 @@
 ---
 name: post-start-validation
-version: 0.2.2
+version: 0.2.10
 source_hash: 5a64dfe68b13577dff818fa63ddb6185be360c80b100f205bc586aac39e19e80
 description: Universal validation and knowledge capture. Detects what changed, runs governance gates, captures knowledge, verifies deployment. Works for any project.
 ---

package/src/skills/pre-start-context.md

@@ -1,7 +1,7 @@
 ---
 name: pre-start-context
-version: 0.2.2
-source_hash: b7be8434b99d5b189c904263e783d573c82109218725cc31fbd4fa1bf81538b6
+version: 0.2.10
+source_hash: 4ace3388804f528a7e7a446466a506ca5f0da4c23e42b540b9ae8923eaf35e4e
 description: Universal context loader. Discovers any project's stack, architecture, and state at runtime. Reads governance.md for project-specific rules. Works for any language, framework, or deployment target.
 ---
 
@@ -54,17 +54,20 @@ Detect OS and shell. Use appropriate syntax (Unix forward slashes if Git Bash on
 
 ## 0.05. Skill Currency Check
 
-Check installed skill version:
+Check whether installed skills are behind the crag CLI:
 
+// turbo
 ```
-Read .claude/skills/pre-start-context/SKILL.md
+crag upgrade --check
 ```
 
-If the file has a `version:` frontmatter field, compare it to the expected version (0.2.0). If outdated:
-- Report: `"Pre-start skill vX.Y.Z is outdated (v0.2.0 available). Run: crag upgrade"`
-- Continue with current version — never block startup.
+If the output lists any skill as needing an upgrade (e.g. `0.2.x → 0.2.y`):
+- Report: `"Skills outdated — run: crag upgrade"`
+- Continue with the current version — never block startup.
 
-> This check costs one Read call. If skills are current, no action needed.
+> This check uses `crag upgrade --check` so the skill never has to hard-code
+> its own version number; it asks the CLI, which is always in lockstep with
+> the package. If `crag` is not on PATH (bare CI runner), skip silently.
 
 ---