@whitehatd/crag 0.2.6 → 0.2.8

package/README.md

@@ -6,7 +6,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node](https://img.shields.io/node/v/%40whitehatd%2Fcrag)](https://nodejs.org)
 [![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)
-[![323 tests](https://img.shields.io/badge/tests-323%20passing-brightgreen)](./test)
+[![357 tests](https://img.shields.io/badge/tests-357%20passing-brightgreen)](./test)
+[![40/40 grade A](https://img.shields.io/badge/benchmark-40%2F40%20grade%20A-brightgreen)](./benchmarks/results.md)
 
 > **One `governance.md`. Any project. Generated in 250 ms.**
 >
@@ -19,7 +20,7 @@ npx @whitehatd/crag analyze            # Generate governance.md from an existing
 npx @whitehatd/crag compile --target all  # Turn it into CI + 12 downstream configs
 ```
 
-Zero dependencies. Node 18+. Validated across [20 OSS projects](#validation-on-real-repos).
+Zero dependencies. Node 18+. Validated across [40 OSS projects](#validation-on-real-repos) (100% grade A).
 
 ---
 
@@ -37,22 +38,46 @@ The result is a single source of truth for your rules that stays in lock-step wi
 
 ## Validation on real repos
 
-Unlike most tools in this space, crag ships with a reproducible cross-repo benchmark. `crag analyze --dry-run` was run against 20 diverse open-source projects:
+Unlike most tools in this space, crag ships with a reproducible cross-repo benchmark. `crag analyze --dry-run` was run against **40 diverse open-source projects** in two tiers:
 
-| Grade | Count | Meaning |
-|---|---:|---|
-| **A** — ship-ready governance | **17 / 20 (85%)** | Stack + test + lint + build gates captured. Minimal noise. Ready to commit with light review. |
-| **B** — usable after cleanup | 3 / 20 (15%) | Stack correct, some gates need pruning or adding. Still faster than writing from scratch. |
-| **C** — rework needed | **0 / 20 (0%)** | — |
+- **Tier 1** — 20 well-known libraries across 7 language families (Node, Python, Rust, Go, Java, Ruby, PHP).
+- **Tier 2** — 20 dense repos picked for **density over storage**: multi-language, matrix-heavy CI, polyglot microservices, and workspace layouts (pnpm monorepos, Cargo workspaces, Gradle multi-module).
 
-Repos tested: `expressjs/express`, `chalk/chalk`, `fastify/fastify`, `axios/axios`, `prettier/prettier`, `vitejs/vite`, `psf/requests`, `pallets/flask`, `pallets/click`, `tiangolo/fastapi`, `BurntSushi/ripgrep`, `clap-rs/clap`, `rust-lang/mdBook`, `tokio-rs/axum`, `spf13/cobra`, `gin-gonic/gin`, `charmbracelet/bubbletea`, `spring-projects/spring-petclinic`, `sinatra/sinatra` (Ruby), `slimphp/Slim` (PHP).
+| Grade | Tier 1 | Tier 2 | Combined | Meaning |
+|---|---:|---:|---:|---|
+| **A** — ship-ready governance | **20 / 20** | **20 / 20** | **40 / 40 (100%)** | Stack + test + lint + build gates captured. Minimal noise. Ready to commit with light review. |
+| **B** — usable after cleanup | 0 | 0 | **0 / 40 (0%)** | — |
+| **C** — rework needed | 0 | 0 | **0 / 40 (0%)** | — |
+
+**Tier 1 repos:** `expressjs/express`, `chalk/chalk`, `fastify/fastify`, `axios/axios`, `prettier/prettier`, `vitejs/vite`, `psf/requests`, `pallets/flask`, `pallets/click`, `tiangolo/fastapi`, `BurntSushi/ripgrep`, `clap-rs/clap`, `rust-lang/mdBook`, `tokio-rs/axum`, `spf13/cobra`, `gin-gonic/gin`, `charmbracelet/bubbletea`, `spring-projects/spring-petclinic`, `sinatra/sinatra`, `slimphp/Slim`.
+
+**Tier 2 repos:** `GoogleCloudPlatform/microservices-demo` (11-language polyglot), `vercel/turbo`, `swc-project/swc`, `dagger/dagger` (8-stack density max), `cloudflare/workers-sdk`, `tailwindlabs/tailwindcss`, `rust-lang/cargo`, `rust-lang/rust-analyzer`, `denoland/deno`, `nushell/nushell`, `withastro/astro`, `nrwl/nx` (7-stack pnpm monorepo), `mastodon/mastodon` (6-stack Rails+Node+Docker), `phoenixframework/phoenix_live_view`, `celery/celery`, `laravel/framework`, `grafana/k6`, `prometheus/prometheus`, `nats-io/nats-server`, `open-telemetry/opentelemetry-collector`.
+
+### Full-capability run on the 10 hardest repos
+
+Beyond `analyze`, the 10 densest repos across both tiers were exercised against every command in crag's surface — **80 / 80 operations succeeded**:
+
+| Command | Result |
+|---|---|
+| `crag analyze --dry-run` | 10 / 10 ✓ |
+| `crag analyze` (writes governance.md) | 10 / 10 ✓ |
+| `crag analyze --workspace --dry-run` | 10 / 10 ✓ (vite: 79 members in 322 ms) |
+| `crag workspace --json` | 10 / 10 ✓ |
+| `crag diff` | 10 / 10 ✓ |
+| `crag doctor --ci` | 10 / 10 ✓ |
+| `crag compile --target github` | 10 / 10 ✓ |
+| `crag compile --target agents-md` | 10 / 10 ✓ |
+
+### Coverage
 
 | Metric | Value |
 |---|---|
-| Mean `crag analyze` time | **238 ms** per repo |
-| Success rate | **20 / 20 exit 0** |
-| Language families covered | Node, Python, Rust, Go, Java, Ruby, PHP |
-| Zero-gate failures | **0** |
+| Repos tested | **40** |
+| Mean `crag analyze` time | **≈ 250 ms** per repo |
+| Grade A | **40 / 40 (100%)** |
+| Language families detected | Node, TypeScript, React, Next.js, Astro, Hono, Python, Rust, Go, Java (Maven + Gradle), Kotlin, Ruby (+Rails/Sinatra), PHP (+Laravel/Symfony/Slim), Elixir (+Phoenix), .NET, Swift, C# |
+| CI systems parsed | 10 — GitHub Actions, GitLab CI, CircleCI, Travis, Azure Pipelines, Buildkite, Drone, Woodpecker, Bitbucket, Jenkins |
+| Workspace types detected | pnpm, npm, cargo, go, gradle, maven, bazel, nx, turbo, git-submodules, independent-repos, subservices |
 
 Full methodology, grading rubric, per-repo results, and raw outputs: [`benchmarks/results.md`](./benchmarks/results.md).
 
@@ -151,9 +176,16 @@ Real target mining — not placeholders. Canonical test/lint/build targets extra
 
 ### Workspaces
 
-Eleven workspace types, enumerated at discovery time:
+Twelve workspace types, enumerated at discovery time:
+
+pnpm · npm/yarn · Cargo · Go · Gradle · Maven · Nx · Turborepo · Bazel · git submodules · independent nested repos · **subservices** (polyglot microservices under `src/*`, `services/*`, `packages/*`, `apps/*`, etc. — no root manifest required)
+
+### Nested stack detection
+
+When a project has no root-level manifest but ships code under conventional container directories, crag scans one level down for per-service manifests and merges the detected stacks. This handles:
 
-pnpm · npm/yarn · Cargo · Go · Gradle · Maven · Nx · Turborepo · Bazel · git submodules · independent nested repos
+- **Polyglot microservice monorepos** — e.g. `src/frontend/go.mod`, `src/cartservice/*.csproj`, `src/emailservice/pyproject.toml` — detected as a 6-stack `subservices` workspace
+- **Auxiliary subdirectory stacks** — e.g. `web/ui/package.json` (React UI), `editors/code/package.json` (VSCode extension), `sdk/typescript/package.json` (SDK) — surfaced as additional stacks alongside the root language
 
 ### Frameworks
 
@@ -183,6 +215,10 @@ crag compile --target all        # Compile to all 12 targets at once
 crag compile                     # List available targets
 
 crag diff                        # Compare governance against codebase reality
+crag doctor                      # Deep diagnostic — governance integrity, drift, hook validity, security
+crag doctor --ci                 # CI mode: skips checks that need runtime infrastructure
+crag doctor --json               # Machine-readable output
+crag doctor --strict             # Treat warnings as failures
 crag upgrade                     # Update universal skills to latest version
 crag upgrade --check             # Dry-run: show what would change
 crag check                       # Verify Claude Code infrastructure is in place
@@ -301,7 +337,7 @@ npx @whitehatd/crag <command>
 
 - **Node.js 18+** — uses built-in `https`, `crypto`, `fs`, `child_process`. No runtime dependencies.
 - **Git** — for branch strategy inference and the discovery cache.
-- **Claude Code CLI** — only needed for the interactive `crag init` flow. `analyze`, `compile`, `diff`, `upgrade`, `workspace`, `check` all run standalone.
+- **Claude Code CLI** — only needed for the interactive `crag init` flow. `analyze`, `compile`, `diff`, `doctor`, `upgrade`, `workspace`, `check` all run standalone.
 
 The package is published under `@whitehatd/crag` but the binary name is plain `crag` after install.
 
@@ -330,17 +366,18 @@ To skip a release on a specific push, put `crag:skip-release` on its own line in
 ## Honest status
 
 - **Published:** 2026-04-04 as `@whitehatd/crag` on npm. Scoped public package.
-- **Tests:** 323 unit tests, passing on Ubuntu/macOS/Windows × Node 18/20/22.
-- **Benchmark:** 17/20 grade A, 0/20 grade C across the 20 reference repos. Reproducible via `benchmarks/results.md`.
+- **Tests:** 357 unit tests, passing on Ubuntu/macOS/Windows × Node 18/20/22.
+- **Benchmark:** **40/40 grade A** across 20 tier-1 + 20 tier-2 reference repos. **80/80 operations succeeded** on the 10 hardest repos across every command (analyze, analyze --workspace, workspace, diff, doctor --ci, compile). Reproducible via `benchmarks/results.md`.
 - **Languages fully supported:** Node, Deno, Bun, Python, Rust, Go, Java, Kotlin, Ruby, PHP, .NET, Swift, Elixir (+ Terraform/Helm/K8s infra gates).
-- **CI systems parsed:** 9 (GitHub Actions, GitLab CI, CircleCI, Travis, Azure Pipelines, Buildkite, Drone, Woodpecker, Bitbucket).
+- **CI systems parsed:** **10** — GitHub Actions, GitLab CI, CircleCI, Travis, Azure Pipelines, Buildkite, Drone, Woodpecker, Bitbucket, **Jenkins** (declarative + scripted pipelines).
 - **Compile targets:** 12 (GitHub Actions, husky, pre-commit, AGENTS.md, Cursor, Gemini, Copilot, Cline, Continue, Windsurf, Zed, Cody).
+- **Nested stack detection:** Scans `src/*`, `services/*`, `packages/*`, `apps/*`, `sdk/*`, `web/*`, `ui/*`, `editors/*`, `extensions/*`, `clients/*` one level deep for per-service manifests. Handles polyglot microservice monorepos (`microservices-demo`) and auxiliary subdirectories (`prometheus/web/ui`, `rust-analyzer/editors/code`, `dagger/sdk/typescript`).
+- **`crag doctor`:** Deep diagnostic command — validates governance integrity, skill currency, hook validity, drift vs git, and runs a security smoke test (8 secret patterns: Stripe, AWS, GitHub PAT/OAuth, Slack, PEM keys). Wired into crag's own CI via `--ci` mode.
 
 ### Known limitations
 
-- **FastAPI and similar repos** where CI runs via `uv run ./scripts/*.py` data-pipeline scripts: crag captures the script invocations as gates. A user reviewing the output should prune the ones that aren't quality checks.
-- **Complex CI matrix template expansions** (clap's `make test-${{matrix.features}}` pattern): line-based extraction captures one variant per template; multi-line YAML join is not implemented yet.
-- **Jenkinsfile** (Groovy): CI system is detected but step extraction is not attempted.
+- **Kotlin via `.kt` source files only (no Gradle kotlin plugin)** isn't detected. Most Kotlin projects use Gradle + the plugin, so this is rare in practice.
+- **`crag analyze --workspace` still needs to be opted in.** Workspaces are auto-detected and reported, but per-member governance is only emitted when the flag is passed — an intentional guard against surprising enumeration on fixture-heavy monorepos.
 - **No telemetry, no network calls** beyond the optional `crag upgrade --check` npm registry ping (24h cached, 3s timeout, graceful offline).
 
 ### What crag does not do

package/package.json

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

package/src/analyze/ci-extractors.js

@@ -13,6 +13,7 @@
  *   - Drone              (.drone.yml)
  *   - Woodpecker         (.woodpecker.yml, .woodpecker/*.yml)
  *   - Bitbucket          (bitbucket-pipelines.yml)
+ *   - Jenkins            (Jenkinsfile — Groovy declarative + scripted)
  *
  * Each extractor returns a list of raw shell command strings. The CI
  * normalizer (normalize.js) dedups and filters them uniformly regardless
@@ -116,9 +117,15 @@ function extractCiCommands(dir) {
     commands.push(...extractBitbucketCommands(safeRead(bbFile)));
   }
 
-  // Jenkins — Jenkinsfiles are Groovy, not YAML. We do not try to parse them.
-  if (fs.existsSync(path.join(dir, 'Jenkinsfile'))) {
-    primary = primary || 'jenkins';
+  // Jenkins — Jenkinsfile is Groovy, not YAML. We parse `sh/bat/pwsh`
+  // step invocations from declarative and scripted pipelines.
+  const jenkinsFiles = ['Jenkinsfile', 'jenkins/Jenkinsfile', 'ci/Jenkinsfile'];
+  for (const jf of jenkinsFiles) {
+    const p = path.join(dir, jf);
+    if (fs.existsSync(p)) {
+      primary = primary || 'jenkins';
+      commands.push(...extractJenkinsfileCommands(safeRead(p)));
+    }
   }
 
   return { system: primary, commands };
@@ -253,6 +260,90 @@ function extractBitbucketCommands(content) {
   return extractYamlListField(content, ['script']);
 }
 
+// --- Jenkinsfile (Groovy) --------------------------------------------------
+
+/**
+ * Extract shell commands from a Jenkinsfile (declarative or scripted).
+ *
+ * Supported step invocations:
+ *   sh 'cmd'               (Unix inline, single-quoted)
+ *   sh "cmd"               (Unix inline, double-quoted)
+ *   sh '''...'''           (Unix multi-line, triple-single-quoted)
+ *   sh """..."""           (Unix multi-line, triple-double-quoted)
+ *   sh(script: 'cmd')      (map form — rare but valid)
+ *   bat 'cmd'              (Windows batch)
+ *   bat '''...'''          (Windows multi-line)
+ *   pwsh 'cmd' | powershell 'cmd' (PowerShell)
+ *
+ * Skipped constructs (not gates):
+ *   credentials(...)       (Jenkins credentials binding)
+ *   environment { ... }    (env block — not commands)
+ *   withCredentials { ... } (wrapper, but inner steps still parsed)
+ *
+ * Multi-line strings are split on newlines and each non-empty line returned
+ * as a separate command, matching the convention of other CI extractors.
+ */
+function extractJenkinsfileCommands(content) {
+  const commands = [];
+  const text = String(content);
+  const lines = text.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Skip comment lines
+    const trimmed = line.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('#')) continue;
+
+    // Map form: sh(script: 'cmd') or sh(script: "cmd")
+    const mapMatch = line.match(/\b(sh|bat|pwsh|powershell)\s*\(\s*script\s*:\s*(['"])([^'"]*?)\2\s*\)/);
+    if (mapMatch) {
+      const cmd = mapMatch[3].trim();
+      if (cmd) commands.push(cmd);
+      continue;
+    }
+
+    // Inline: step 'cmd' or step "cmd" on a single line
+    // Matches: sh 'foo', sh "foo", bat 'bar', pwsh "baz"
+    const inlineMatch = line.match(/\b(sh|bat|pwsh|powershell)\s*\(?(['"])([^'"]*?)\2\)?/);
+    if (inlineMatch) {
+      // But only if the string is NOT the start of a triple-quoted block
+      // (triple quotes: the char after the match end should not be another
+      // matching quote)
+      const afterIdx = inlineMatch.index + inlineMatch[0].length;
+      const beforeIdx = line.indexOf(inlineMatch[2] + inlineMatch[3] + inlineMatch[2]);
+      if (line[afterIdx] !== inlineMatch[2] && line[beforeIdx - 1] !== inlineMatch[2]) {
+        const cmd = inlineMatch[3].trim();
+        if (cmd) commands.push(cmd);
+      }
+    }
+
+    // Multi-line triple-quoted: sh ''' ... ''' or sh """ ... """
+    const tripleMatch = line.match(/\b(sh|bat|pwsh|powershell)\s*\(?\s*(?:script:\s*)?('''|""")\s*$/);
+    if (tripleMatch) {
+      const delim = tripleMatch[2];
+      // Collect lines until the closing triple delimiter
+      for (let j = i + 1; j < lines.length; j++) {
+        const inner = lines[j];
+        if (inner.trim().startsWith(delim) || inner.includes(delim)) {
+          i = j; // skip past the closing delimiter
+          break;
+        }
+        const innerTrimmed = inner.trim();
+        if (innerTrimmed && !innerTrimmed.startsWith('#') && !innerTrimmed.startsWith('//')) {
+          commands.push(innerTrimmed);
+        }
+      }
+      continue;
+    }
+
+    // Triple-quote on a previous line was handled by the loop above — no
+    // additional handling needed here.
+  }
+
+  return commands;
+}
+
 // --- Generic YAML list field extractor -------------------------------------
 
 /**
@@ -314,4 +405,4 @@ function extractYamlListField(content, fields) {
   return commands;
 }
 
-module.exports = { extractCiCommands, walkYaml, extractYamlListField };
+module.exports = { extractCiCommands, walkYaml, extractYamlListField, extractJenkinsfileCommands };

package/src/analyze/stacks.js

@@ -85,8 +85,17 @@ function parseSimpleToml(content) {
  * Detect languages, frameworks, and package managers in `dir`.
  * Mutates `result.stack`, `result.name`, `result.description`, and attaches
  * `result._manifests` for downstream gate detection.
+ *
+ * When `recursive` is true (default), also scans conventional subservice
+ * directories (`src/`, `services/`, `packages/`, `apps/`, `cmd/`, `sdk/`,
+ * `web/`, `ui/`, `editors/`, `extensions/`, `projects/`, `microservices/`)
+ * to pick up polyglot microservice layouts (e.g. GoogleCloudPlatform's
+ * microservices-demo, or auxiliary subdirectories like prometheus's
+ * `web/ui` React app and rust-analyzer's `editors/code` VSCode extension).
+ * The recursive call is one level only to prevent infinite recursion.
  */
-function detectStack(dir, result) {
+function detectStack(dir, result, options = {}) {
+  const { recursive = true } = options;
   result._manifests = result._manifests || {};
 
   detectNode(dir, result);
@@ -104,6 +113,107 @@ function detectStack(dir, result) {
   detectPhp(dir, result);
   detectDocker(dir, result);
   detectInfrastructure(dir, result);
+
+  if (recursive) {
+    detectNestedStacks(dir, result);
+  }
+}
+
+/**
+ * Scan conventional subservice/auxiliary directories one level deep for
+ * manifests. Adds unique detected stacks to `result.stack` and stores the
+ * per-subservice breakdown in `result._manifests.subservices`.
+ *
+ * Two cases this handles:
+ *
+ *   1. Polyglot microservices monorepo (no root manifests):
+ *        root/src/adservice/pom.xml        → java/maven
+ *        root/src/cartservice/x.csproj     → dotnet
+ *        root/src/frontend/go.mod          → go
+ *        root/src/emailservice/pyproject.toml → python
+ *      → result.stack = [java/maven, dotnet, go, python, ...]
+ *      → workspaceType = subservices
+ *
+ *   2. Auxiliary subdirectory stack (root manifests present):
+ *        root/go.mod                       → go (primary)
+ *        root/web/ui/package.json          → node, react, typescript (aux)
+ *      → result.stack = [go, node, react, typescript]
+ *      → subservices list records the breakdown for reporting
+ *
+ * Scans two depths below each container: container/manifest (depth 1) and
+ * container/<child>/manifest (depth 2). Does NOT recurse further.
+ */
+function detectNestedStacks(dir, result) {
+  const containerDirs = [
+    'src', 'services', 'packages', 'apps', 'cmd', 'projects', 'microservices',
+    'sdk', 'sdks', 'web', 'ui', 'editors', 'extensions', 'clients',
+  ];
+
+  const rootHadStacks = result.stack.length > 0;
+  const subservices = [];
+
+  for (const container of containerDirs) {
+    const containerPath = path.join(dir, container);
+    if (!fs.existsSync(containerPath)) continue;
+
+    // Depth 1: container itself has a manifest (e.g. web/ui/package.json where
+    // the container is `ui` directly, or sdk/package.json)
+    scanOneSubdir(containerPath, container, result, subservices);
+
+    // Depth 2: container/<child>/manifest (the common microservices pattern)
+    let children;
+    try {
+      children = fs.readdirSync(containerPath, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name);
+    } catch { continue; }
+
+    // Cap children scan at a reasonable number to avoid pathological
+    // enumeration on huge directories (monorepos with hundreds of packages)
+    const capped = children.slice(0, 64);
+    for (const child of capped) {
+      const childPath = path.join(containerPath, child);
+      const relPath = container + '/' + child;
+      scanOneSubdir(childPath, relPath, result, subservices);
+    }
+  }
+
+  if (subservices.length > 0) {
+    result._manifests.subservices = subservices;
+    if (!rootHadStacks) {
+      // Root had no manifests — this is a subservice-only project (e.g.
+      // microservices-demo). Flag for downstream reporting.
+      result._manifests.workspaceType = result._manifests.workspaceType || 'subservices';
+    }
+  }
+}
+
+/**
+ * Run non-recursive stack detection on `subdir` and merge unique stacks into
+ * the main `result`. Records the subservice in `subservices` if any stacks
+ * were detected.
+ */
+function scanOneSubdir(subdir, relPath, result, subservices) {
+  if (!fs.existsSync(subdir)) return;
+  try {
+    const st = fs.statSync(subdir);
+    if (!st.isDirectory()) return;
+  } catch { return; }
+
+  const subResult = { stack: [], _manifests: {} };
+  detectStack(subdir, subResult, { recursive: false });
+
+  if (subResult.stack.length === 0) return;
+
+  subservices.push({
+    name: path.basename(subdir),
+    path: relPath,
+    stacks: subResult.stack,
+  });
+
+  for (const s of subResult.stack) {
+    if (!result.stack.includes(s)) result.stack.push(s);
+  }
 }
 
 // --- Node ------------------------------------------------------------------

package/src/cli.js

@@ -5,6 +5,7 @@ const { check } = require('./commands/check');
 const { compile } = require('./commands/compile');
 const { analyze } = require('./commands/analyze');
 const { diff } = require('./commands/diff');
+const { doctor } = require('./commands/doctor');
 const { upgrade } = require('./commands/upgrade');
 const { workspace } = require('./commands/workspace');
 const { checkOnce } = require('./update/version-check');
@@ -19,6 +20,7 @@ function printUsage() {
     crag init         Interview → generate governance, hooks, agents
     crag analyze      Generate governance from existing project (no interview)
     crag check        Verify infrastructure is complete
+    crag doctor       Deep diagnostic: governance integrity, drift, hook validity, security
     crag compile      Compile governance.md → CI, hooks, AGENTS.md, Cursor, Gemini
     crag diff         Compare governance against codebase reality
     crag upgrade      Update universal skills to latest version
@@ -93,6 +95,7 @@ function run(args) {
     case 'compile':   compile(args); break;
     case 'analyze':   analyze(args); break;
     case 'diff':      diff(args); break;
+    case 'doctor':    doctor(args.slice(1)); break;
     case 'upgrade':   upgrade(args); break;
     case 'workspace': workspace(args); break;
     case 'version': case '--version': case '-v':

package/src/commands/analyze.js

@@ -60,6 +60,27 @@ function analyze(args) {
     } else {
       console.log(`  Workspace detected: ${ws.type}. Pass --workspace for per-member gates.\n`);
     }
+  } else if (analysis.subservices && analysis.subservices.length > 0) {
+    // No canonical workspace marker, but recursive stack detection found
+    // subservice manifests under src/ / services/ / packages/ / apps/ / etc.
+    // Treat as an independent-subservices workspace.
+    const count = analysis.subservices.length;
+    analysis.workspaceType = 'subservices';
+    if (workspaceFlag) {
+      console.log(`  Subservices detected: ${count} service${count === 1 ? '' : 's'} across src/ services/ packages/ apps/ directories\n`);
+      analysis.workspace = { type: 'subservices', members: [] };
+      for (const sub of analysis.subservices) {
+        const subPath = path.join(cwd, sub.path);
+        const subAnalysis = analyzeProject(subPath);
+        analysis.workspace.members.push({
+          name: sub.name,
+          relativePath: sub.path,
+          ...subAnalysis,
+        });
+      }
+    } else {
+      console.log(`  Subservices detected: ${count} service${count === 1 ? '' : 's'}. Pass --workspace for per-service gates.\n`);
+    }
   }
 
   const governance = generateGovernance(analysis, cwd);
@@ -165,6 +186,11 @@ function analyzeProject(dir) {
     result.advisories.push(...result._advisories);
     delete result._advisories;
   }
+  // Promote subservices (from recursive stack detection) to a public field
+  // so analyze command can print a hint and --workspace can enumerate them.
+  if (result._manifests && result._manifests.subservices) {
+    result.subservices = result._manifests.subservices;
+  }
   // Drop the internal manifests attachment before returning
   delete result._manifests;
 

package/src/commands/doctor.js

@@ -0,0 +1,647 @@
+'use strict';
+
+/**
+ * crag doctor — deep diagnostic command.
+ *
+ * Where `crag check` verifies file presence, `crag doctor` validates
+ * content, governance integrity, skill currency, hook validity, drift,
+ * and environment. It's the command you run when something feels off
+ * and you need a second opinion about your crag setup.
+ *
+ * Each check returns one of three statuses:
+ *   pass  (green ✓)  — everything is correct
+ *   warn  (yellow !) — advisory, non-blocking
+ *   fail  (red ✗)    — blocks a clean crag setup, needs fixing
+ *
+ * Exit codes:
+ *   0 — no failures (warnings allowed)
+ *   1 — one or more failures
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { parseGovernance, flattenGates, extractSection } = require('../governance/parse');
+const { isModified, readFrontmatter } = require('../update/integrity');
+const { EXIT_USER, EXIT_INTERNAL } = require('../cli-errors');
+
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+const ICON_PASS = `${GREEN}✓${RESET}`;
+const ICON_WARN = `${YELLOW}!${RESET}`;
+const ICON_FAIL = `${RED}✗${RESET}`;
+
+/**
+ * CLI entry point.
+ *
+ * Flags:
+ *   --json      Machine-readable output
+ *   --ci        Skip checks that require runtime infrastructure (skills,
+ *               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).
+ */
+function doctor(args) {
+  const cwd = process.cwd();
+  const jsonOutput = args.includes('--json');
+  const ciMode = args.includes('--ci');
+  const strict = args.includes('--strict');
+
+  const report = runDiagnostics(cwd, { ciMode });
+
+  const exitCode = computeExitCode(report, strict);
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(exitCode);
+  }
+
+  printReport(report, { ciMode, strict });
+  process.exit(exitCode);
+}
+
+function computeExitCode(report, strict) {
+  if (report.fail > 0) return 1;
+  if (strict && report.warn > 0) return 1;
+  return 0;
+}
+
+/**
+ * Run all diagnostics and return a structured report.
+ * Exported for testing.
+ *
+ * When `ciMode` is true, skips sections that rely on runtime infrastructure
+ * (Infrastructure, Skills, Hooks) — those checks require files that only
+ * exist on a developer's machine or after `crag init`/`crag compile`, not
+ * in a bare CI runner.
+ */
+function runDiagnostics(cwd, options = {}) {
+  const { ciMode = false } = options;
+
+  const sections = ciMode ? [
+    diagnoseGovernance(cwd),
+    diagnoseDrift(cwd),
+    diagnoseSecurity(cwd),
+    diagnoseEnvironment(cwd),
+  ] : [
+    diagnoseInfrastructure(cwd),
+    diagnoseGovernance(cwd),
+    diagnoseSkills(cwd),
+    diagnoseHooks(cwd),
+    diagnoseDrift(cwd),
+    diagnoseSecurity(cwd),
+    diagnoseEnvironment(cwd),
+  ];
+
+  let pass = 0, warn = 0, fail = 0;
+  for (const section of sections) {
+    for (const check of section.checks) {
+      if (check.status === 'pass') pass++;
+      else if (check.status === 'warn') warn++;
+      else if (check.status === 'fail') fail++;
+    }
+  }
+
+  return { cwd, sections, pass, warn, fail, ciMode };
+}
+
+// ============================================================================
+// Section: Infrastructure
+// ============================================================================
+
+function diagnoseInfrastructure(cwd) {
+  const checks = [];
+  const CORE = [
+    ['.claude/skills/pre-start-context/SKILL.md', 'Pre-start skill'],
+    ['.claude/skills/post-start-validation/SKILL.md', 'Post-start skill'],
+    ['.claude/governance.md', 'Governance file'],
+    ['.claude/hooks/sandbox-guard.sh', 'Sandbox guard hook'],
+    ['.claude/settings.local.json', 'Settings with hooks'],
+  ];
+  const OPTIONAL = [
+    ['.claude/hooks/drift-detector.sh', 'Drift detector (optional)'],
+    ['.claude/hooks/circuit-breaker.sh', 'Circuit breaker (optional)'],
+    ['.claude/agents/test-runner.md', 'Test runner agent (optional)'],
+    ['.claude/agents/security-reviewer.md', 'Security reviewer agent (optional)'],
+    ['.claude/ci-playbook.md', 'CI playbook (optional)'],
+  ];
+
+  for (const [file, name] of CORE) {
+    const present = fs.existsSync(path.join(cwd, file));
+    checks.push({
+      name,
+      status: present ? 'pass' : 'fail',
+      detail: present ? null : `missing: ${file}`,
+      fix: present ? null : `run 'crag init' or 'crag analyze' then 'crag compile --target all'`,
+    });
+  }
+
+  for (const [file, name] of OPTIONAL) {
+    const present = fs.existsSync(path.join(cwd, file));
+    checks.push({
+      name,
+      status: present ? 'pass' : 'warn',
+      detail: present ? null : `missing: ${file}`,
+      fix: null,
+    });
+  }
+
+  return { title: 'Infrastructure', checks };
+}
+
+// ============================================================================
+// Section: Governance integrity
+// ============================================================================
+
+function diagnoseGovernance(cwd) {
+  const checks = [];
+  const govPath = path.join(cwd, '.claude', 'governance.md');
+
+  if (!fs.existsSync(govPath)) {
+    checks.push({
+      name: 'governance.md exists',
+      status: 'fail',
+      detail: '.claude/governance.md not found',
+      fix: `run 'crag analyze' to generate one`,
+    });
+    return { title: 'Governance', checks };
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(govPath, 'utf-8');
+  } catch (err) {
+    checks.push({
+      name: 'governance.md readable',
+      status: 'fail',
+      detail: `cannot read: ${err.message}`,
+      fix: 'check file permissions',
+    });
+    return { title: 'Governance', checks };
+  }
+
+  // Parse
+  const parsed = parseGovernance(content);
+  const warnings = parsed.warnings || [];
+  checks.push({
+    name: 'parses cleanly',
+    status: warnings.length === 0 ? 'pass' : 'warn',
+    detail: warnings.length === 0 ? null : `${warnings.length} parser warning${warnings.length === 1 ? '' : 's'}: ${warnings[0]}${warnings.length > 1 ? '...' : ''}`,
+    fix: warnings.length > 0 ? 'review parser warnings in governance.md structure' : null,
+  });
+
+  // Required sections
+  const requiredSections = ['Identity', 'Gates', 'Branch Strategy', 'Security'];
+  for (const section of requiredSections) {
+    const present = new RegExp(`^##\\s+${section}`, 'm').test(content);
+    checks.push({
+      name: `has ${section} section`,
+      status: present ? 'pass' : 'fail',
+      detail: present ? null : `missing ## ${section}`,
+      fix: present ? null : `add a '## ${section}' section to governance.md`,
+    });
+  }
+
+  // Gate count
+  const gates = flattenGates(parsed.gates);
+  const gateCount = Object.values(gates).flat().length;
+  checks.push({
+    name: 'has gate commands',
+    status: gateCount > 0 ? 'pass' : 'fail',
+    detail: `${gateCount} gate${gateCount === 1 ? '' : 's'} declared`,
+    fix: gateCount === 0 ? 'add gate commands under ### Lint / ### Test / ### Build' : null,
+  });
+
+  // Project identity
+  checks.push({
+    name: 'project identity set',
+    status: parsed.name ? 'pass' : 'warn',
+    detail: parsed.name ? `name: ${parsed.name}` : 'no project name in - Project:',
+    fix: parsed.name ? null : `add '- Project: <name>' under ## Identity`,
+  });
+
+  return { title: 'Governance', checks };
+}
+
+// ============================================================================
+// Section: Skill currency
+// ============================================================================
+
+function diagnoseSkills(cwd) {
+  const checks = [];
+  const skills = ['pre-start-context', 'post-start-validation'];
+
+  for (const skill of skills) {
+    const skillPath = path.join(cwd, '.claude', 'skills', skill, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      checks.push({
+        name: `${skill} installed`,
+        status: 'fail',
+        detail: `${skillPath} missing`,
+        fix: `run 'crag upgrade' to install`,
+      });
+      continue;
+    }
+
+    const parsed = readFrontmatter(skillPath);
+    if (!parsed || !parsed.version) {
+      checks.push({
+        name: `${skill} frontmatter`,
+        status: 'warn',
+        detail: parsed ? 'no version field in frontmatter' : 'no frontmatter found',
+        fix: `run 'crag upgrade --force' to refresh`,
+      });
+      continue;
+    }
+
+    // Self-integrity check: does the installed body hash match the stored
+    // source_hash? (isModified returns true when body was locally modified
+    // OR when the hash is missing)
+    const modified = isModified(skillPath);
+
+    checks.push({
+      name: `${skill} v${parsed.version}`,
+      status: modified ? 'warn' : 'pass',
+      detail: modified ? 'locally modified since install (body hash differs from source_hash)' : 'integrity verified',
+      fix: modified ? `run 'crag upgrade --check' to see what changed, or 'crag upgrade --force' to reset` : null,
+    });
+  }
+
+  return { title: 'Skills', checks };
+}
+
+// ============================================================================
+// Section: Hooks
+// ============================================================================
+
+function diagnoseHooks(cwd) {
+  const checks = [];
+  const hooksDir = path.join(cwd, '.claude', 'hooks');
+
+  if (!fs.existsSync(hooksDir)) {
+    checks.push({
+      name: 'hooks directory',
+      status: 'warn',
+      detail: '.claude/hooks/ does not exist',
+      fix: `run 'crag compile --target github' or 'crag init' to generate`,
+    });
+    return { title: 'Hooks', checks };
+  }
+
+  // Sandbox guard is the most important hook
+  const sandboxPath = path.join(hooksDir, 'sandbox-guard.sh');
+  if (fs.existsSync(sandboxPath)) {
+    const content = fs.readFileSync(sandboxPath, 'utf-8');
+    const hasShebang = content.startsWith('#!');
+    const hasRtkMarker = /#\s*rtk-hook-version:/m.test(content.split('\n').slice(0, 5).join('\n'));
+
+    checks.push({
+      name: 'sandbox-guard.sh installed',
+      status: hasShebang ? 'pass' : 'fail',
+      detail: hasShebang ? null : 'missing shebang line (#!/usr/bin/env bash)',
+      fix: hasShebang ? null : `run 'crag compile --target github' to regenerate`,
+    });
+
+    checks.push({
+      name: 'sandbox-guard has rtk-hook-version marker',
+      status: hasRtkMarker ? 'pass' : 'warn',
+      detail: hasRtkMarker ? null : '# rtk-hook-version marker not in first 5 lines (causes "Hook outdated" warnings)',
+      fix: hasRtkMarker ? null : `add '# rtk-hook-version: 3' near the top of the hook file`,
+    });
+
+    // On Unix, check executable bit
+    if (process.platform !== 'win32') {
+      try {
+        const stat = fs.statSync(sandboxPath);
+        const executable = (stat.mode & 0o111) !== 0;
+        checks.push({
+          name: 'sandbox-guard executable',
+          status: executable ? 'pass' : 'fail',
+          detail: executable ? null : `mode ${(stat.mode & 0o777).toString(8)} (not executable)`,
+          fix: executable ? null : `run 'chmod +x .claude/hooks/sandbox-guard.sh'`,
+        });
+      } catch { /* skip */ }
+    }
+  } else {
+    checks.push({
+      name: 'sandbox-guard.sh installed',
+      status: 'fail',
+      detail: 'no sandbox-guard.sh (hard-block of destructive commands is disabled)',
+      fix: `run 'crag compile --target github' to generate the hook`,
+    });
+  }
+
+  // Settings references hooks
+  const settingsPath = path.join(cwd, '.claude', 'settings.local.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+      const hasHooks = settings.hooks && typeof settings.hooks === 'object' && Object.keys(settings.hooks).length > 0;
+      checks.push({
+        name: 'settings.local.json wires hooks',
+        status: hasHooks ? 'pass' : 'warn',
+        detail: hasHooks ? `${Object.keys(settings.hooks).length} hook event(s) configured` : 'no hooks section — hooks will not fire',
+        fix: hasHooks ? null : `run 'crag compile --target github' to wire hooks into settings`,
+      });
+
+      // Check for hardcoded paths in the `hooks` section only. User-local
+      // permissions allowlist (`permissions.allow`) can legitimately contain
+      // machine-specific paths like /c/Users/... and should not be flagged.
+      if (hasHooks) {
+        const hookJson = JSON.stringify(settings.hooks);
+        const hookHardcoded = /[A-Z]:[\\/]|\/home\/|\/Users\//.test(hookJson);
+        if (hookHardcoded) {
+          checks.push({
+            name: 'hook commands use $CLAUDE_PROJECT_DIR',
+            status: 'warn',
+            detail: 'hardcoded absolute paths in hooks section — prefer $CLAUDE_PROJECT_DIR',
+            fix: `replace hardcoded paths in settings.local.json hooks with $CLAUDE_PROJECT_DIR/...`,
+          });
+        }
+      }
+    } catch (err) {
+      checks.push({
+        name: 'settings.local.json valid JSON',
+        status: 'fail',
+        detail: `parse error: ${err.message}`,
+        fix: `check syntax of .claude/settings.local.json`,
+      });
+    }
+  }
+
+  return { title: 'Hooks', checks };
+}
+
+// ============================================================================
+// 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');
+  if (!fs.existsSync(govPath)) {
+    return { title: 'Drift', checks: [{ name: 'drift check skipped', status: 'warn', detail: 'no governance.md', fix: null }] };
+  }
+
+  const content = fs.readFileSync(govPath, 'utf-8');
+
+  // Branch strategy alignment — detect from the `## Branch Strategy` section
+  // rather than the whole file so unrelated prose ("feature branches in each
+  // sub-repo") doesn't override a workspace wrapper's actual trunk-based
+  // policy. Within that section, the FIRST keyword to appear wins: this
+  // matches the human reading order where the opening bullet states the rule.
+  const govBranchStrategy = detectBranchStrategy(content);
+
+  if (govBranchStrategy) {
+    try {
+      const branches = execSync('git branch -a --format="%(refname:short)"', {
+        cwd, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const featureBranches = countFeatureBranches(branches);
+      const actualStrategy = featureBranches.length > 2 ? 'feature-branches' : 'trunk-based';
+
+      checks.push({
+        name: 'branch strategy matches git',
+        status: actualStrategy === govBranchStrategy ? 'pass' : 'warn',
+        detail: actualStrategy === govBranchStrategy
+          ? `${govBranchStrategy} (${featureBranches.length} feature branches)`
+          : `governance says ${govBranchStrategy}, git shows ${actualStrategy}`,
+        fix: actualStrategy === govBranchStrategy ? null
+          : `update governance.md to '${actualStrategy === 'trunk-based' ? 'Trunk-based development' : 'Feature branches'}'`,
+      });
+    } catch { /* skip — not a git repo or git unavailable */ }
+  }
+
+  // Commit convention alignment
+  const govConvention = content.includes('Conventional commits') || content.includes('conventional commits')
+    ? 'conventional'
+    : content.includes('Free-form') || content.includes('free-form')
+    ? 'free-form'
+    : null;
+
+  if (govConvention) {
+    try {
+      const log = execSync('git log --oneline -20', { cwd, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] });
+      const lines = log.trim().split('\n');
+      const conventional = lines.filter(l => /\b(feat|fix|docs|chore|style|refactor|test|build|ci|perf|revert)[\(:!]/.test(l));
+      const actual = conventional.length > lines.length * 0.3 ? 'conventional' : 'free-form';
+
+      checks.push({
+        name: 'commit convention matches git',
+        status: actual === govConvention ? 'pass' : 'warn',
+        detail: actual === govConvention ? `${govConvention} (${conventional.length}/${lines.length} recent commits match)` : `governance says ${govConvention}, git shows ${actual}`,
+        fix: actual === govConvention ? null : `update governance.md to '${actual === 'conventional' ? 'Conventional commits' : 'Free-form commits'}'`,
+      });
+    } catch { /* skip */ }
+  }
+
+  return { title: 'Drift', checks };
+}
+
+// ============================================================================
+// Section: Security smoke
+// ============================================================================
+
+function diagnoseSecurity(cwd) {
+  const checks = [];
+
+  // governance.md should not contain literal secrets
+  const govPath = path.join(cwd, '.claude', 'governance.md');
+  if (fs.existsSync(govPath)) {
+    const content = fs.readFileSync(govPath, 'utf-8');
+    const SECRET_PATTERNS = [
+      { pattern: /sk_live_[a-zA-Z0-9]{16,}/, label: 'Stripe live secret key' },
+      { pattern: /sk_test_[a-zA-Z0-9]{16,}/, label: 'Stripe test secret key' },
+      { pattern: /AKIA[A-Z0-9]{16}/, label: 'AWS access key ID' },
+      { pattern: /ghp_[a-zA-Z0-9]{36}/, label: 'GitHub personal access token' },
+      { pattern: /gho_[a-zA-Z0-9]{36}/, label: 'GitHub OAuth token' },
+      { pattern: /ghu_[a-zA-Z0-9]{36}/, label: 'GitHub user token' },
+      { pattern: /xox[baprs]-[a-zA-Z0-9-]{10,}/, label: 'Slack token' },
+      { pattern: /-----BEGIN (RSA|EC|DSA|OPENSSH) PRIVATE KEY-----/, label: 'Private key' },
+    ];
+    const leaks = [];
+    for (const { pattern, label } of SECRET_PATTERNS) {
+      if (pattern.test(content)) leaks.push(label);
+    }
+
+    checks.push({
+      name: 'governance.md secret-free',
+      status: leaks.length === 0 ? 'pass' : 'fail',
+      detail: leaks.length === 0 ? null : `found: ${leaks.join(', ')}`,
+      fix: leaks.length === 0 ? null : 'remove the secret and rotate it immediately',
+    });
+  }
+
+  // Root-level .env files should not be tracked in git. This is the most
+  // common place for real secret leaks. Subdirectory .env files are typically
+  // build config (React CRA PUBLIC_URL, Vite VITE_*), monorepo package
+  // overrides, or test fixtures — too many legitimate uses to flag blindly.
+  // For those, rely on the secret-pattern scan below if they ever matter.
+  try {
+    const tracked = execSync('git ls-files', {
+      cwd, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const files = tracked.split('\n');
+
+    // Only flag root-level .env / .env.local / .env.production (not sample).
+    const risky = files.filter(f => /^\.env(\.local|\.production)?$/.test(f));
+
+    checks.push({
+      name: 'root .env files not tracked',
+      status: risky.length === 0 ? 'pass' : 'fail',
+      detail: risky.length === 0 ? null : `tracked: ${risky.join(', ')}`,
+      fix: risky.length === 0 ? null : `git rm --cached ${risky[0]} && add to .gitignore, then rotate any secrets inside`,
+    });
+  } catch { /* skip — not a git repo */ }
+
+  return { title: 'Security', checks };
+}
+
+// ============================================================================
+// Section: Environment
+// ============================================================================
+
+function diagnoseEnvironment(cwd) {
+  const checks = [];
+
+  // Node version
+  const nodeVersion = process.version;
+  checks.push({
+    name: 'node version',
+    status: 'pass',
+    detail: nodeVersion,
+    fix: null,
+  });
+
+  // crag's own engines requirement
+  try {
+    const cragPkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8'));
+    const required = cragPkg.engines && cragPkg.engines.node;
+    if (required) {
+      const minMatch = required.match(/>=\s*(\d+)/);
+      if (minMatch) {
+        const minMajor = parseInt(minMatch[1], 10);
+        const currentMajor = parseInt(nodeVersion.replace(/^v/, '').split('.')[0], 10);
+        checks.push({
+          name: `node >= ${minMajor}`,
+          status: currentMajor >= minMajor ? 'pass' : 'fail',
+          detail: currentMajor >= minMajor ? null : `installed v${currentMajor}, need >= ${minMajor}`,
+          fix: currentMajor >= minMajor ? null : `upgrade Node.js to version ${minMajor} or later`,
+        });
+      }
+    }
+  } catch { /* skip */ }
+
+  // Git presence
+  try {
+    const gitVersion = execSync('git --version', { encoding: 'utf-8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    checks.push({ name: 'git available', status: 'pass', detail: gitVersion, fix: null });
+  } catch {
+    checks.push({ name: 'git available', status: 'fail', detail: 'git not on PATH', fix: 'install git' });
+  }
+
+  return { title: 'Environment', checks };
+}
+
+// ============================================================================
+// Output
+// ============================================================================
+
+function printReport(report, { ciMode = false, strict = false } = {}) {
+  const modeLabel = ciMode ? ' (--ci mode)' : '';
+  console.log(`\n  ${BOLD}crag doctor${RESET}${modeLabel} — ${report.cwd}\n`);
+
+  for (const section of report.sections) {
+    console.log(`  ${BOLD}${section.title}${RESET}`);
+    for (const check of section.checks) {
+      const icon = check.status === 'pass' ? ICON_PASS
+        : check.status === 'warn' ? ICON_WARN
+        : ICON_FAIL;
+      console.log(`    ${icon} ${check.name}${check.detail ? ` ${DIM}— ${check.detail}${RESET}` : ''}`);
+      if (check.fix && check.status !== 'pass') {
+        console.log(`      ${DIM}fix:${RESET} ${check.fix}`);
+      }
+    }
+    console.log();
+  }
+
+  // Summary
+  const total = report.pass + report.warn + report.fail;
+  const summary = `  ${report.pass}/${total} pass, ${report.warn} warn, ${report.fail} fail`;
+  if (report.fail > 0) {
+    console.log(`${RED}${BOLD}${summary}${RESET}\n`);
+  } else if (report.warn > 0) {
+    console.log(`${YELLOW}${BOLD}${summary}${RESET}\n`);
+  } else {
+    console.log(`${GREEN}${BOLD}${summary}${RESET}\n`);
+  }
+}
+
+module.exports = { doctor, runDiagnostics, countFeatureBranches, detectBranchStrategy };

package/src/governance/parse.js

@@ -107,8 +107,40 @@ function parseGovernance(content) {
   if (gatesBody) {
     let section = 'default';
     let sectionMeta = { path: null, condition: null };
+    // Fenced code blocks (```bash / ```sh / ```shell) are treated as an
+    // alternative command carrier: every non-blank, non-comment line inside
+    // is extracted as a MANDATORY command for the current section. This
+    // matches the very common markdown pattern of documenting gate commands
+    // in a bash fence instead of a bullet list.
+    let inCodeBlock = false;
 
     for (const line of gatesBody.split('\n')) {
+      // Fence toggle. Accepts ``` , ```bash , ```sh , ```shell (and any other
+      // language tag) — we treat all fenced blocks inside ## Gates as gate
+      // command carriers. A non-shell language tag would be unusual here.
+      if (/^\s*```/.test(line)) {
+        inCodeBlock = !inCodeBlock;
+        continue;
+      }
+
+      if (inCodeBlock) {
+        const cmd = line.trim();
+        // Skip blanks and pure comments. Do NOT strip inline comments from
+        // the tail of a command — shell parsers treat `#` mid-line as a
+        // comment only when preceded by whitespace, and losing the rest of
+        // the line could silently drop logic like `echo "# header"`.
+        if (!cmd || cmd.startsWith('#')) continue;
+        if (!result.gates[section]) {
+          result.gates[section] = {
+            commands: [],
+            path: sectionMeta.path,
+            condition: sectionMeta.condition,
+          };
+        }
+        result.gates[section].commands.push({ cmd, classification: 'MANDATORY' });
+        continue;
+      }
+
       // Match ### Section or ### Section (path: dir/) or ### Section (if: file)
       const sub = line.match(/^### (.+?)(?:\s*\((?:(path|if):\s*(.+?))\))?\s*$/);
       if (sub) {