omniconductor 0.6.0 → 1.0.1

package/adapters/windsurf/transform.sh

@@ -24,13 +24,14 @@
 #   core/recipes/*.md (selected)   →  <target>/.devin/rules/*.md     (front-matter stripped)
 #   core/docs-templates/*.md       →  <target>/docs/*.md             (CURRENT_WORK, REMAINING_TASKS, etc.)
 #   core/hooks/*.sh.template       →  SKIPPED (Reflector hook emitted via --recipes=self-improvement, ADR-032; other guards Claude-only, ADR-034)
-#   core/roles/*.md                →  SKIPPED (Windsurf has no sub-agent dispatch)
+#   core/roles/*.md                →  SKIPPED (role emission is Claude-only today; Windsurf supports sub-agents natively — ADR-031)
 #   adapters/claude/hookify-...    →  SKIPPED (Claude-only plugin)
 #
-# Windsurf has NO per-pattern glob scoping (all files in .devin/rules/ load
-# together) and NO sub-agents. CONDUCTOR emits the Reflector hook when
-# --recipes=self-improvement (ADR-032); other guards remain Claude-only (ADR-034)
-# and are noted in .windsurfrules.
+# This adapter emits no per-pattern glob scoping (all files in .devin/rules/ load
+# together) and no agent personas — Windsurf supports hooks/sub-agents natively
+# (ADR-031); full emission is Phase 2. CONDUCTOR emits the Reflector hook when
+# --recipes=self-improvement (ADR-032); other guards remain Claude-only emission
+# (ADR-034) and are noted in .windsurfrules.
 
 set -eu
 
@@ -38,6 +39,7 @@ set -eu
 
 TARGET=""
 RECIPES=""
+MODE="full"
 DRY_RUN="false"
 NO_PROMPT="false"
 UNINSTALL="false"
@@ -49,6 +51,7 @@ WIZARD_APPLY_RULES="true"
 while [ $# -gt 0 ]; do
   case "$1" in
     --recipes=*) RECIPES="${1#--recipes=}" ;;
+    --mode=*)    MODE="${1#--mode=}" ;;
     --dry-run)   DRY_RUN="true" ;;
     --no-prompt) NO_PROMPT="true" ;;
     --uninstall|--rollback) UNINSTALL="true" ;;
@@ -59,6 +62,11 @@ Usage: bash adapters/windsurf/transform.sh <target-project> [options]
 
 Options:
   --recipes=A,B,C       Comma-separated list of recipes to install
+  --mode=<m>            Install preset (ADR-044): full (default) | minimal (rules text +
+                        docs only; no Reflector runtime) | strict (abort if .windsurfrules or
+                        .devin/rules/ already exists) | recipes-only (ONLY the selected recipe
+                        files into .devin/rules/; requires --recipes=) | reflector-only
+                        (self-improvement loop standalone)
   --dry-run             Preview only — no files written
   --no-prompt           Skip all interactive prompts; apply sensible defaults (CI-safe)
   --uninstall           Revert a previous install using <target>/.conductor-manifest.json
@@ -71,7 +79,7 @@ Recipes available: web-mobile-parity, i18n, monorepo, branch-strategy, auto-mock
 
 What this adapter does NOT install (per ADR-004 honesty + ADR-021):
   - Hook guards (CONDUCTOR emits the Reflector hook when --recipes=self-improvement, ADR-032; other guards remain Claude-only, ADR-034)
-  - Sub-agent personas (Windsurf has no sub-agent dispatch — single chat session per task)
+  - Sub-agent personas (not yet emitted for Windsurf — the tool supports sub-agents natively, ADR-031; agent emission is Phase 2)
   - Per-pattern glob scoping (all .devin/rules/*.md load together)
   - Hookify rule templates (Claude-only plugin)
 EOF
@@ -95,11 +103,31 @@ if [ -z "$TARGET" ]; then
   exit 1
 fi
 
+case "$MODE" in
+  full|minimal|strict|recipes-only|reflector-only) : ;;
+  *) echo "Error: unknown --mode '$MODE' (one of: full, minimal, strict, recipes-only, reflector-only)" >&2; exit 1 ;;
+esac
+if [ "$MODE" = "reflector-only" ]; then
+  if [ -n "$RECIPES" ] && [ "$RECIPES" != "self-improvement" ]; then
+    echo "NOTE: --mode=reflector-only ignores --recipes (installs self-improvement only)" >&2
+  fi
+  RECIPES="self-improvement"
+fi
+if [ "$MODE" = "recipes-only" ] && [ -z "$RECIPES" ] && [ "$UNINSTALL" != "true" ]; then
+  echo "Error: --mode=recipes-only requires --recipes=A,B,..." >&2
+  exit 1
+fi
+
 # Resolve CONDUCTOR root (where this script lives: adapters/windsurf/).
 CONDUCTOR_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 CORE_ROOT="$CONDUCTOR_ROOT/core"
 [ -d "$CORE_ROOT" ] || { echo "Error: core/ not found at $CORE_ROOT" >&2; exit 1; }
 
+# CONDUCTOR package version for the manifest — parsed at runtime from package.json
+# so releases never drift the manifest (falls back to "unknown" on any error).
+CONDUCTOR_VERSION="$(/usr/bin/sed -n -E 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' "$CONDUCTOR_ROOT/package.json" 2>/dev/null | /usr/bin/head -n 1)"
+[ -n "$CONDUCTOR_VERSION" ] || CONDUCTOR_VERSION="unknown"
+
 if [ "$DRY_RUN" = "true" ]; then
   mkdir -p "$TARGET"
 fi
@@ -148,18 +176,7 @@ emit_rule() {
 # downstream step overwrites it. Honors DRY_RUN. Idempotent across re-installs.
 # Origin: ADR-019 (Claude adapter pattern, mirrored here per ADR-021).
 backup_if_exists() {
-  local dest="$1"
-  if [ -f "$dest" ]; then
-    local ts
-    ts="$(/bin/date +%Y%m%d-%H%M%S)"
-    local backup="${dest}.conductor-backup-${ts}"
-    if [ "$DRY_RUN" = "true" ]; then
-      log "would back up existing $dest -> $backup"
-    else
-      /bin/cp "$dest" "$backup"
-      log "  backed up existing $dest -> $backup"
-    fi
-  fi
+  conductor_manifest_backup_and_remember "$1"
 }
 
 # ----- manifest tracking (ADR-020, mirrored per ADR-021) ------------------
@@ -171,6 +188,9 @@ MANIFEST_STAGE_PATH=""
 MANIFEST_TS=""
 MANIFEST_LAST_BACKUP=""
 
+# shellcheck source=../../tools/manifest-safety.sh
+. "$CONDUCTOR_ROOT/tools/manifest-safety.sh"
+
 init_manifest() {
   if [ "$DRY_RUN" = "true" ]; then
     log "would init manifest staging at $MANIFEST_PATH.staging"
@@ -189,12 +209,13 @@ record_emit() {
   local relpath="$1" src="$2" backup="${3:-}"
   local had_backup="false"
   [ -n "$backup" ] && had_backup="true"
-  local esc_path esc_src esc_backup
+  local esc_path esc_src esc_backup emitted_sha
   esc_path="$(printf '%s' "$relpath" | /usr/bin/sed 's/\\/\\\\/g; s/"/\\"/g')"
   esc_src="$(printf '%s' "$src" | /usr/bin/sed 's/\\/\\\\/g; s/"/\\"/g')"
   esc_backup="$(printf '%s' "$backup" | /usr/bin/sed 's/\\/\\\\/g; s/"/\\"/g')"
-  printf '    {"path": "%s", "source": "%s", "had_backup": %s, "backup_path": "%s"},\n' \
-    "$esc_path" "$esc_src" "$had_backup" "$esc_backup" >> "$MANIFEST_STAGE_PATH"
+  emitted_sha="$(conductor_sha256_file "$TARGET_ABS/$relpath")"
+  printf '    {"path": "%s", "source": "%s", "had_backup": %s, "backup_path": "%s", "sha256": "%s"},\n' \
+    "$esc_path" "$esc_src" "$had_backup" "$esc_backup" "$emitted_sha" >> "$MANIFEST_STAGE_PATH"
 }
 
 finalize_manifest() {
@@ -238,8 +259,9 @@ finalize_manifest() {
 
   /bin/cat > "$MANIFEST_PATH" <<EOF
 {
-  "version": "v0.2.0",
+  "version": "v$CONDUCTOR_VERSION",
   "adapter": "windsurf",
+  "mode": "$MODE",
   "install_timestamp": "$MANIFEST_TS",
   "conductor_root": "$CONDUCTOR_ROOT",
   "recipes_enabled": $recipes_json,
@@ -253,19 +275,19 @@ EOF
 }
 
 backup_and_remember() {
-  MANIFEST_LAST_BACKUP=""
-  if [ -f "$1" ]; then
-    if [ "$DRY_RUN" = "true" ]; then
-      log "would back up existing $1 -> $1.conductor-backup-<ts>"
-      MANIFEST_LAST_BACKUP=""
-    else
-      local ts
-      ts="$(/bin/date +%Y%m%d-%H%M%S)"
-      local backup="$1.conductor-backup-$ts"
-      /bin/cp "$1" "$backup"
-      log "  backed up existing $1 -> $backup"
-      MANIFEST_LAST_BACKUP="${backup#$TARGET_ABS/}"
-    fi
+  conductor_manifest_backup_and_remember "$1"
+}
+
+# ----- framework detection (ADR-044 — suggest, NEVER auto-switch) ----------
+
+detect_coexisting_frameworks() {
+  local found=""
+  [ -d "$TARGET_ABS/.specify" ] && found="$found Spec-Kit"
+  { [ -d "$TARGET_ABS/_bmad" ] || [ -d "$TARGET_ABS/.bmad-core" ]; } && found="$found BMAD"
+  if [ -n "$found" ] && [ "$MODE" = "full" ]; then
+    log "NOTE: detected coexisting framework(s):$found"
+    log "      Consider --mode=recipes-only or --mode=reflector-only to coexist without"
+    log "      overlapping workflow rules (suggestion only — nothing was changed)."
   fi
 }
 
@@ -303,6 +325,7 @@ do_uninstall() {
   local restored=0
   local deleted=0
   local missing=0
+  local preserved=0
 
   while IFS= read -r line; do
     case "$line" in
@@ -311,16 +334,27 @@ do_uninstall() {
       *) continue ;;
     esac
     entries_count=$((entries_count + 1))
-    local rel_path src had_backup backup_path
+    local rel_path src had_backup backup_path expected_sha
     rel_path="$(printf '%s' "$line" | /usr/bin/sed -E 's/.*"path": *"([^"]*)".*/\1/')"
     src="$(printf '%s' "$line" | /usr/bin/sed -E 's/.*"source": *"([^"]*)".*/\1/')"
     had_backup="$(printf '%s' "$line" | /usr/bin/sed -E 's/.*"had_backup": *(true|false).*/\1/')"
     backup_path="$(printf '%s' "$line" | /usr/bin/sed -E 's/.*"backup_path": *"([^"]*)".*/\1/')"
+    expected_sha="$(conductor_manifest_field "$line" sha256 2>/dev/null || true)"
 
     local abs_dest="$TARGET_ABS/$rel_path"
     local abs_backup=""
     [ -n "$backup_path" ] && abs_backup="$TARGET_ABS/$backup_path"
 
+    if [ -f "$abs_dest" ] && ! conductor_manifest_file_matches "$abs_dest" "$expected_sha"; then
+      if [ -z "$expected_sha" ]; then
+        log "  WARNING: preserving $rel_path (legacy manifest has no checksum)"
+      else
+        log "  WARNING: preserving user-modified $rel_path"
+      fi
+      preserved=$((preserved + 1))
+      continue
+    fi
+
     if [ "$had_backup" = "true" ] && [ -n "$abs_backup" ]; then
       if [ -f "$abs_backup" ]; then
         if [ "$DRY_RUN" = "true" ]; then
@@ -393,6 +427,7 @@ do_uninstall() {
   echo "  Backups restored: $restored"
   echo "  Files deleted: $deleted"
   echo "  Backup-missing deletes: $missing"
+  [ "$preserved" -gt 0 ] && echo "  User-modified files preserved: $preserved"
   echo "========================================================"
 }
 
@@ -427,6 +462,20 @@ if [ -d "$TARGET_ABS/.windsurf" ] || [ -f "$TARGET_ABS/.windsurfrules" ]; then
   IS_ADOPTER_CASE="true"
 fi
 
+detect_coexisting_frameworks
+
+# --mode=strict: never touch an existing rules surface (ADR-044).
+if [ "$MODE" = "strict" ] && { [ -f "$TARGET_ABS/.windsurfrules" ] || [ -d "$TARGET_ABS/.devin/rules" ]; }; then
+  echo "Error (--mode=strict): .windsurfrules or .devin/rules/ already exists in $TARGET_ABS — strict mode aborts instead of writing next to an existing baseline." >&2
+  echo "  Use --mode=full (timestamped backups + manifest-based restore), or move them first." >&2
+  exit 3
+fi
+
+# À-la-carte modes are non-interactive by design.
+if [ "$MODE" != "full" ] && [ "$MODE" != "strict" ]; then
+  NO_PROMPT="true"
+fi
+
 if [ "$IS_ADOPTER_CASE" = "true" ] && [ "$NO_PROMPT" = "false" ] && [ "$DRY_RUN" = "false" ]; then
   echo ""
   echo "========================================================"
@@ -474,9 +523,13 @@ init_manifest
 
 UNIVERSAL_RULES="workflow spec-as-you-go quality-gates operations meta-discipline"
 
-log "Step 1/4: synthesize .windsurfrules (always-loaded baseline)"
 WINDSURFRULES_DEST="$TARGET_ABS/.windsurfrules"
 
+if [ "$MODE" = "recipes-only" ] || [ "$MODE" = "reflector-only" ]; then
+  log "Step 1/4: .windsurfrules baseline — skipped (--mode=$MODE is à la carte)"
+elif true; then
+log "Step 1/4: synthesize .windsurfrules (always-loaded baseline)"
+
 if [ -f "$WINDSURFRULES_DEST" ]; then
   log "  $WINDSURFRULES_DEST exists — SKIP (exists), leaving in place"
 elif [ "$DRY_RUN" = "true" ]; then
@@ -494,10 +547,12 @@ else
 You are the orchestrator: plan first, act deliberately, verify before declaring done.
 당신은 오케스트레이터입니다: 먼저 계획하고, 신중하게 실행하고, 완료 선언 전에 검증하세요.
 
-Windsurf runs a single chat session per task (no sub-agent dispatch). You play
+Windsurf supports sub-agent dispatch natively (ADR-031), but CONDUCTOR does not
+emit agent personas here yet (Phase 2). You play
 both planner and implementer; keep the plan explicit so it survives context resets.
-Windsurf 는 작업당 단일 채팅 세션으로 동작합니다 (서브에이전트 디스패치 없음). 계획을
-명시적으로 유지해 컨텍스트 리셋에도 살아남게 하세요.
+Windsurf 는 서브에이전트 디스패치를 네이티브로 지원하지만 (ADR-031), CONDUCTOR 는 아직
+에이전트 페르소나를 생성하지 않습니다 (Phase 2). 여기서는 계획자와 구현자 역할을 모두
+수행하며, 계획을 명시적으로 유지해 컨텍스트 리셋에도 살아남게 하세요.
 
 ## ABSOLUTE rules / 절대 규칙 (read before every change)
 
@@ -546,22 +601,29 @@ per-pattern glob scoping). Selected recipes are emitted there too.
 
 ## Not enforced on Windsurf / Windsurf 에서 미강제
 
-Windsurf has no hooks and no sub-agent dispatch. The following are self-policed
-reminders here (on Claude Code they are enforced by hooks):
-Windsurf 는 훅과 서브에이전트 디스패치가 없습니다. 다음 항목은 여기서는 자율 준수 사항입니다
-(Claude Code 에서는 훅으로 강제됨):
+Windsurf supports hooks and sub-agents natively (ADR-031), but CONDUCTOR's
+Windsurf adapter currently emits rule text only — full hook/agent emission is
+Phase 2. The following are self-policed
+reminders here (on Claude Code they are enforced by CONDUCTOR-emitted hooks):
+Windsurf 는 훅과 서브에이전트를 네이티브로 지원하지만 (ADR-031), CONDUCTOR 의 Windsurf
+adapter 는 현재 rule 텍스트만 생성합니다 (hook/agent 자동 생성은 Phase 2). 다음 항목은
+여기서는 자율 준수 사항입니다 (Claude Code 에서는 CONDUCTOR 가 생성한 훅으로 강제됨):
 
-- Spec-as-you-go same-turn update — no Stop hook to block stale docs.
+- Spec-as-you-go same-turn update — CONDUCTOR emits no Stop hook here yet to block stale docs.
 - Two-stage code review (pre-commit / pre-merge) — pair with a git pre-commit hook for mechanical enforcement.
-- Model routing — Windsurf uses a single model per session; choose deliberately.
+- Model routing — Windsurf supports per-task model choice natively (ADR-031); CONDUCTOR does not automate it here yet — choose deliberately.
 EOF
-  record_emit ".windsurfrules" "<synthesized>" ""
+  record_emit ".windsurfrules" "<synthesized>" "$MANIFEST_LAST_BACKUP"
   log "  wrote $WINDSURFRULES_DEST"
 fi
 
+fi
+
 # ----- step 2: universal rules -> .devin/rules/*.md ----------------------
 
-if [ "$WIZARD_APPLY_RULES" = "true" ]; then
+if [ "$MODE" = "recipes-only" ] || [ "$MODE" = "reflector-only" ]; then
+  log "Step 2/4: universal-rules — skipped (--mode=$MODE is à la carte)"
+elif [ "$WIZARD_APPLY_RULES" = "true" ]; then
   log "Step 2/4: universal-rules → .devin/rules/ (preferred; legacy .windsurf/rules/ still read)"
   mkdir_if_real "$TARGET_ABS/.devin/rules"
 
@@ -616,7 +678,19 @@ fi
 
 # ----- step 3.5: self-improvement runtime (only with --recipes=self-improvement) ----
 
-case ",$RECIPES," in
+if [ "$MODE" = "recipes-only" ] && [ -z "${INSTALLED_RECIPES// /}" ] && [ "$DRY_RUN" != "true" ]; then
+  echo "Error: --mode=recipes-only resolved ZERO valid recipes from '--recipes=$RECIPES' — nothing to install (check the names)." >&2
+  /bin/rm -f "$MANIFEST_STAGE_PATH"
+  exit 1
+fi
+
+if [ "$MODE" = "minimal" ]; then
+  RECIPES_FOR_RUNTIME=""
+  log "Step: self-improvement runtime — skipped (--mode=minimal ships text only)"
+else
+  RECIPES_FOR_RUNTIME="$RECIPES"
+fi
+case ",$RECIPES_FOR_RUNTIME," in
   *",self-improvement,"*)
     log "Step: self-improvement (Reflector) → hook/workflow/rule"
     if [ "$DRY_RUN" != "true" ]; then
@@ -664,6 +738,9 @@ esac
 
 # ----- step 4: docs templates --------------------------------------------
 
+if [ "$MODE" = "recipes-only" ] || [ "$MODE" = "reflector-only" ]; then
+  log "Step 4/4: docs templates — skipped (--mode=$MODE is à la carte; docs ship with full/minimal)"
+else
 log "Step 4/4: docs templates → docs/"
 mkdir_if_real "$TARGET_ABS/docs"
 mkdir_if_real "$TARGET_ABS/docs/specs"
@@ -698,6 +775,8 @@ if [ -f "$CORE_ROOT/docs-templates/specs/_example.md" ]; then
 fi
 
 # Finalize manifest after all emits.
+fi
+
 finalize_manifest
 
 # ----- completion summary -------------------------------------------------
@@ -707,13 +786,18 @@ echo "========================================================"
 echo " Done."
 echo "  Target: $TARGET_ABS"
 echo "  Adapter: windsurf"
-echo "  Always-loaded baseline: .windsurfrules"
-echo "  Universal rules: 5 (.devin/rules/*.md, front-matter stripped)"
+echo "  Mode: $MODE"
+if [ "$MODE" = "recipes-only" ] || [ "$MODE" = "reflector-only" ]; then
+  echo "  Universal rules: 0 (à la carte — no .windsurfrules baseline)"
+else
+  echo "  Always-loaded baseline: .windsurfrules"
+  echo "  Universal rules: 5 (.devin/rules/*.md, front-matter stripped)"
+fi
 echo "  Recipes installed:${INSTALLED_RECIPES:- (none)}"
 echo ""
 echo " Skipped (per ADR-004 honesty):"
 echo "  - Hooks: CONDUCTOR emits the Reflector hook when --recipes=self-improvement (ADR-032); other guards remain Claude-only (ADR-034)."
-echo "  - Sub-agent personas: Windsurf has no sub-agent dispatch — single chat session per task."
+echo "  - Sub-agent personas: not yet emitted for Windsurf (tool supports sub-agents natively — ADR-031; Phase 2)."
 echo "  - Per-pattern glob scoping: all .devin/rules/*.md load together."
 echo "  - Hookify rule templates: Claude-only plugin."
 echo ""
@@ -722,6 +806,6 @@ echo "========================================================"
 echo ""
 echo "Next steps for the project:"
 echo "  1. Open $TARGET_ABS in Windsurf."
-echo "  2. Edit docs/CURRENT_WORK.md with your project's current state."
+[ -d "$TARGET_ABS/docs" ] && echo "  2. Edit docs/CURRENT_WORK.md with your project's current state."
 echo "  3. Verify rule loading: confirm .windsurfrules + all .devin/rules/*.md show in the rule indicator."
 echo "  4. Add .memory/ to .gitignore if you adopt the DIY memory pattern."

package/bin/doctor.js

@@ -0,0 +1,257 @@
+'use strict';
+
+/*
+ * omniconductor doctor — read-only health check for an installed project (ADR-041).
+ *
+ * Anchors on <target>/.conductor-manifest.json and NEVER writes anything.
+ * The bash adapters remain the single source of truth for install logic
+ * (ADR-002/023/025) — doctor only inspects their output.
+ *
+ * Check groups:
+ *   D1 manifest validity     — exists, parses, has version + emitted_files
+ *   D2 version drift         — manifest version vs the running package version
+ *   D3 file integrity        — every manifest-emitted file still exists
+ *   D4 stale legacy paths    — adapter's legacy paths present in the target
+ *   D5 hook validity         — emitted .json parse; emitted .sh executable + `bash -n`
+ *   D6 doc-link liveness     — relative markdown links in emitted docs resolve
+ *   D7 stale claims          — emitted files scanned against tools/stale-tokens.txt
+ *
+ * Severity: FAIL = broken install · WARN = degraded/attention · OK.
+ * Exit codes: 0 = all OK · 1 = warnings only · 2 = failures (or unusable target).
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function readPkgVersion() {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version || null; }
+  catch { return null; }
+}
+
+function loadAdapterMetadata(adapter) {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'adapters', adapter, 'metadata.json'), 'utf8')); }
+  catch { return null; }
+}
+
+// tools/stale-tokens.txt: pattern \t reason \t hint \t allow_regex?  (# = comment)
+function loadStaleTokens() {
+  let raw;
+  try { raw = fs.readFileSync(path.join(ROOT, 'tools', 'stale-tokens.txt'), 'utf8'); }
+  catch { return []; }
+  const rules = [];
+  for (const line of raw.split('\n')) {
+    const l = line.replace(/\r$/, '');
+    if (!l || l.startsWith('#')) continue;
+    const [pattern, reason, hint, allow] = l.split('\t');
+    if (!pattern) continue;
+    rules.push({ pattern, reason: reason || '', hint: hint || '', allow: allow || null });
+  }
+  return rules;
+}
+
+function inferAdapter(manifest, targetAbs) {
+  if (manifest && typeof manifest.adapter === 'string') return manifest.adapter;
+  // Pre-0.8.0 claude manifests carry no adapter field — infer from footprint.
+  if (fs.existsSync(path.join(targetAbs, '.claude', 'rules'))) return 'claude';
+  return null;
+}
+
+function run(targetDir, opts) {
+  const json = !!(opts && opts.json);
+  const results = []; // {id, status: 'OK'|'WARN'|'FAIL', detail}
+  const add = (id, status, detail) => results.push({ id, status, detail });
+
+  const targetAbs = path.resolve(process.cwd(), targetDir || '.');
+  const finish = () => {
+    const counts = { OK: 0, WARN: 0, FAIL: 0 };
+    for (const r of results) counts[r.status]++;
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        doctor: readPkgVersion(), target: targetAbs, checks: results, summary: counts,
+      }, null, 2) + '\n');
+    } else {
+      for (const r of results) {
+        const pad = r.status === 'OK' ? 'OK  ' : (r.status === 'WARN' ? 'WARN' : 'FAIL');
+        process.stdout.write(`${pad} [${r.id}] ${r.detail}\n`);
+      }
+      process.stdout.write(`\n${counts.FAIL ? 'FAIL' : counts.WARN ? 'WARN' : 'OK'} — ${counts.OK} ok, ${counts.WARN} warn, ${counts.FAIL} fail (${targetAbs})\n`);
+      if (counts.FAIL || counts.WARN) {
+        process.stdout.write(`Re-install (safe: backups + manifest): npx omniconductor init --target=<tool> ${targetDir || '.'}\n`);
+      }
+    }
+    return counts.FAIL ? 2 : (counts.WARN ? 1 : 0);
+  };
+
+  if (!fs.existsSync(targetAbs) || !fs.statSync(targetAbs).isDirectory()) {
+    add('D1', 'FAIL', `target directory does not exist: ${targetAbs}`);
+    return finish();
+  }
+
+  // ---- D1 manifest validity ------------------------------------------------
+  const manifestPath = path.join(targetAbs, '.conductor-manifest.json');
+  let manifest = null;
+  if (!fs.existsSync(manifestPath)) {
+    add('D1', 'FAIL', `no .conductor-manifest.json in ${targetAbs} — not a CONDUCTOR install (or installed pre-manifest / uninstalled)`);
+    return finish();
+  }
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    add('D1', 'FAIL', `.conductor-manifest.json does not parse: ${e.message}`);
+    return finish();
+  }
+  if (typeof manifest.version !== 'string' || !Array.isArray(manifest.emitted_files)) {
+    add('D1', 'FAIL', `.conductor-manifest.json missing 'version' or 'emitted_files'`);
+    return finish();
+  }
+  if (manifest.emitted_files.length === 0) {
+    add('D1', 'FAIL', `.conductor-manifest.json has an empty 'emitted_files' — a real install always tracks files (manifest damaged or hand-edited?)`);
+    return finish();
+  }
+  // Every tracked path must be a non-empty RELATIVE path that stays inside the
+  // target — a forged/merge-damaged manifest must not let doctor read (or later
+  // checks reason about) files outside the install root.
+  const badPaths = [];
+  for (const ef of manifest.emitted_files) {
+    const p = ef && ef.path;
+    if (typeof p !== 'string' || !p.trim() || path.isAbsolute(p)) { badPaths.push(String(p)); continue; }
+    const resolved = path.resolve(targetAbs, p);
+    if (resolved !== targetAbs && !resolved.startsWith(targetAbs + path.sep)) badPaths.push(p);
+  }
+  if (badPaths.length) {
+    add('D1', 'FAIL', `manifest contains ${badPaths.length} invalid/escaping path(s): ${badPaths.slice(0, 4).join(', ')}${badPaths.length > 4 ? ', …' : ''}`);
+    return finish();
+  }
+  add('D1', 'OK', `manifest valid — ${manifest.emitted_files.length} tracked files, recipes: ${(manifest.recipes_enabled || []).join(', ') || '(none)'}`);
+
+  const adapter = inferAdapter(manifest, targetAbs);
+  const meta = adapter ? loadAdapterMetadata(adapter) : null;
+
+  // ---- D2 version drift ------------------------------------------------------
+  const pkgVersion = readPkgVersion();
+  const installedVersion = String(manifest.version).replace(/^v/, '');
+  if (!pkgVersion) {
+    add('D2', 'WARN', 'cannot read the running package version');
+  } else if (installedVersion === 'unknown' || installedVersion === '') {
+    add('D2', 'WARN', `manifest has no usable version stamp ('${manifest.version}')`);
+  } else if (installedVersion !== pkgVersion) {
+    add('D2', 'WARN', `installed by v${installedVersion}, running CLI is v${pkgVersion} — re-run init to refresh (backups + manifest keep it safe)`);
+  } else {
+    add('D2', 'OK', `install version matches running CLI (v${pkgVersion})`);
+  }
+
+  // ---- D3 file integrity -----------------------------------------------------
+  const missing = [];
+  for (const ef of manifest.emitted_files) {
+    if (!ef || typeof ef.path !== 'string') continue;
+    if (!fs.existsSync(path.join(targetAbs, ef.path))) missing.push(ef.path);
+  }
+  if (missing.length) {
+    add('D3', 'FAIL', `${missing.length} manifest-tracked file(s) missing: ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? ', …' : ''}`);
+  } else {
+    add('D3', 'OK', 'all manifest-tracked files exist');
+  }
+
+  // ---- D4 stale legacy paths ---------------------------------------------------
+  if (!adapter) {
+    add('D4', 'WARN', 'manifest has no adapter field and footprint is ambiguous — skipping legacy-path check');
+  } else if (!meta) {
+    add('D4', 'WARN', `no metadata for adapter '${adapter}' in this package — skipping legacy-path check`);
+  } else {
+    const emitted = new Set(manifest.emitted_files.map((e) => e && e.path).filter(Boolean));
+    const staleLegacy = (meta.legacy_paths || []).filter((lp) => {
+      if (fs.existsSync(path.join(targetAbs, lp)) === false) return false;
+      // Intentional legacy emissions are manifest-tracked (e.g. --legacy-cursorrules).
+      if (emitted.has(lp) || manifest.legacy_cursorrules === true && lp === '.cursorrules') return false;
+      return true;
+    });
+    if (staleLegacy.length) {
+      add('D4', 'WARN', `legacy path(s) present alongside the modern install: ${staleLegacy.join(', ')} — the tool may read both; consider removing after migrating content`);
+    } else {
+      add('D4', 'OK', `no stale legacy paths (adapter: ${adapter})`);
+    }
+  }
+
+  // ---- D5 hook validity ---------------------------------------------------------
+  let hookProblems = 0, hookChecked = 0;
+  let bashAvailable = true;
+  for (const ef of manifest.emitted_files) {
+    if (!ef || typeof ef.path !== 'string') continue;
+    const abs = path.join(targetAbs, ef.path);
+    if (!fs.existsSync(abs)) continue; // D3 already reported it
+    if (ef.path.endsWith('.json')) {
+      hookChecked++;
+      try { JSON.parse(fs.readFileSync(abs, 'utf8')); }
+      catch (e) { hookProblems++; add('D5', 'FAIL', `${ef.path} is not valid JSON: ${e.message}`); }
+    } else if (ef.path.endsWith('.sh')) {
+      hookChecked++;
+      try { fs.accessSync(abs, fs.constants.X_OK); }
+      catch { hookProblems++; add('D5', 'FAIL', `${ef.path} is not executable (chmod +x)`); }
+      if (bashAvailable) {
+        const r = spawnSync('bash', ['-n', abs], { stdio: 'pipe' });
+        if (r.error) { bashAvailable = false; add('D5', 'WARN', 'bash not available — skipping syntax checks'); }
+        else if (r.status !== 0) { hookProblems++; add('D5', 'FAIL', `${ef.path} has a bash syntax error`); }
+      }
+    }
+  }
+  if (hookProblems === 0) add('D5', 'OK', `hook/config surfaces sane (${hookChecked} .json/.sh file(s) checked)`);
+
+  // ---- D6 doc-link liveness -------------------------------------------------------
+  let deadLinks = 0, docsChecked = 0;
+  const linkRe = /\[[^\]]*\]\(([^)\s]+)\)/g;
+  for (const ef of manifest.emitted_files) {
+    if (!ef || typeof ef.path !== 'string' || !ef.path.endsWith('.md')) continue;
+    const abs = path.join(targetAbs, ef.path);
+    if (!fs.existsSync(abs)) continue;
+    docsChecked++;
+    const src = fs.readFileSync(abs, 'utf8');
+    let m;
+    while ((m = linkRe.exec(src)) !== null) {
+      const href = m[1];
+      if (/^(https?:|mailto:|#)/.test(href)) continue;
+      const dest = path.resolve(path.dirname(abs), href.split('#')[0]);
+      if (!fs.existsSync(dest)) {
+        deadLinks++;
+        if (deadLinks <= 5) add('D6', 'WARN', `${ef.path}: dead relative link → ${href}`);
+      }
+    }
+  }
+  if (deadLinks === 0) add('D6', 'OK', `relative links resolve in ${docsChecked} emitted doc(s)`);
+  else if (deadLinks > 5) add('D6', 'WARN', `…and ${deadLinks - 5} more dead link(s)`);
+
+  // ---- D7 stale claims ---------------------------------------------------------------
+  const rules = loadStaleTokens();
+  if (!rules.length) {
+    add('D7', 'WARN', 'tools/stale-tokens.txt not found in this package — skipping stale-claim scan');
+  } else {
+    let staleHits = 0;
+    for (const ef of manifest.emitted_files) {
+      if (!ef || typeof ef.path !== 'string') continue;
+      if (!/\.(md|sh|mdc|json|toml)$/.test(ef.path) && !/(^|\/)\.(windsurfrules|cursorrules)$/.test(ef.path)) continue;
+      const abs = path.join(targetAbs, ef.path);
+      if (!fs.existsSync(abs)) continue;
+      const lines = fs.readFileSync(abs, 'utf8').split('\n');
+      for (const rule of rules) {
+        let allowRe = null;
+        if (rule.allow) { try { allowRe = new RegExp(rule.allow); } catch { allowRe = null; } }
+        for (const line of lines) {
+          if (!line.includes(rule.pattern)) continue;
+          if (line.includes('stale-ok:')) continue;
+          if (allowRe && allowRe.test(line)) continue;
+          staleHits++;
+          if (staleHits <= 5) add('D7', 'WARN', `${ef.path}: stale claim '${rule.pattern}' (${rule.reason}) — re-install to refresh`);
+          break; // one report per rule per file
+        }
+      }
+    }
+    if (staleHits === 0) add('D7', 'OK', 'no known-stale claims in emitted files');
+    else if (staleHits > 5) add('D7', 'WARN', `…and ${staleHits - 5} more stale claim(s)`);
+  }
+
+  return finish();
+}
+
+module.exports = { run };