@jokerized/getresearchdone 0.4.1

package/lib/commands/watch.ts

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * GRD Commands/Watch -- Live parallel execution monitor.
+ *
+ * Codex r20 P2: previously polled `.planning/active-execution.json`,
+ * which no existing writer produces. Switched to following
+ * `.planning/autopilot/autopilot.log` — the canonical activity log
+ * written by autopilot/execute-phase/evolve.
+ */
+
+const fs = require('fs') as typeof import('fs');
+const path = require('path') as typeof import('path');
+
+const TAIL_LINES = 30;
+const POLL_MS = 500;
+
+function _readTail(filePath: string, lines: number): string[] {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8') as string;
+    const all = content.split('\n').filter((l: string) => l.trim());
+    return all.slice(-lines);
+  } catch {
+    return [];
+  }
+}
+
+function cmdWatch(cwd: string, raw: boolean): void {
+  const logPath = path.join(cwd, '.planning', 'autopilot', 'autopilot.log');
+  if (!fs.existsSync(logPath)) {
+    process.stdout.write(
+      'No autopilot log found (.planning/autopilot/autopilot.log).\n' +
+      'Start an execution with `gd execute-phase` or `gd autopilot` first.\n'
+    );
+    return;
+  }
+
+  process.stdout.write('\x1B[?25l'); // hide cursor
+  let running = true;
+  process.on('SIGINT', () => { running = false; });
+
+  let lastSize = 0;
+  try { lastSize = fs.statSync(logPath).size; } catch { /* ignore */ }
+  const startSize = lastSize;
+
+  const poll = (): void => {
+    if (!running) {
+      process.stdout.write('\x1B[?25h\n'); // restore cursor
+      return;
+    }
+    let stat: import('fs').Stats;
+    try {
+      stat = fs.statSync(logPath);
+    } catch {
+      process.stdout.write('\x1B[?25h\nLog file gone — execution finished.\n');
+      return;
+    }
+    const tail = _readTail(logPath, TAIL_LINES);
+    const idle = stat.size === lastSize;
+    lastSize = stat.size;
+
+    process.stdout.write('\x1B[H\x1B[2J');
+    process.stdout.write(
+      `GRD Execution Monitor — ${path.relative(cwd, logPath)} (${idle ? 'idle' : 'active'}, ${stat.size - startSize} bytes since start)\n`
+    );
+    process.stdout.write('─'.repeat(72) + '\n');
+    for (const line of tail) process.stdout.write(line + '\n');
+    process.stdout.write('\nPress Ctrl-C to exit.\n');
+
+    if (raw) {
+      const payload = { log: path.relative(cwd, logPath), idle, size: stat.size, tail };
+      process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    }
+    setTimeout(poll, POLL_MS);
+  };
+
+  poll();
+}
+
+module.exports = { cmdWatch };

package/lib/complexity.ts

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * GRD Complexity -- Task complexity estimator for adaptive model-tier
+ * routing.
+ *
+ * Pure function that takes an agent type + optional signals and returns
+ * a ComplexityLevel ('low' | 'medium' | 'high'). Used by the Spec 4
+ * adaptive routing chain before resolveModelForAgent.
+ *
+ * Does NOT read files, config, or scheduler state. All inputs are
+ * pre-gathered by the caller.
+ */
+
+import type { ComplexityLevel } from './types';
+
+/**
+ * Baseline complexity per agent type, seeded from the existing
+ * MODEL_PROFILES 'quality' tier as a proxy for "how much reasoning
+ * does this agent typically need."
+ */
+export const AGENT_BASELINE_COMPLEXITY: Record<string, ComplexityLevel> = {
+  'grd-planner': 'high',
+  'grd-roadmapper': 'high',
+  'grd-phase-researcher': 'high',
+  'grd-product-owner': 'high',
+  'grd-feasibility-analyst': 'high',
+  'grd-surveyor': 'high',
+  'grd-deep-diver': 'high',
+  'grd-executor': 'medium',
+  'grd-debugger': 'medium',
+  'grd-integration-checker': 'medium',
+  'grd-research-synthesizer': 'medium',
+  'grd-project-researcher': 'medium',
+  'grd-plan-checker': 'medium',
+  'grd-migrator': 'medium',
+  'grd-eval-planner': 'medium',
+  'grd-codebase-mapper': 'low',
+  'grd-verifier': 'low',
+  'grd-baseline-assessor': 'low',
+  'grd-knowledge-miner': 'low',
+  'grd-code-reviewer': 'low',
+  'grd-eval-reporter': 'low',
+};
+
+/**
+ * Configurable thresholds for estimateComplexity's internal heuristics.
+ * All fields are optional; unspecified fields use DEFAULT_HEURISTICS values.
+ */
+export interface ComplexityHeuristics {
+  prompt_length_high_threshold?: number;
+  sample_demote_high_to_medium?: number;
+  sample_demote_medium_to_low?: number;
+  min_samples_for_demotion?: number;
+}
+
+/** Default values matching the previously hardcoded constants. */
+const DEFAULT_HEURISTICS: Required<ComplexityHeuristics> = {
+  prompt_length_high_threshold: 20_000,
+  sample_demote_high_to_medium: 3_000,
+  sample_demote_medium_to_low: 1_500,
+  min_samples_for_demotion: 3,
+};
+
+/**
+ * Estimates task complexity based on agent type, prompt length, and
+ * recent sample history. Returns 'low' | 'medium' | 'high'.
+ *
+ * Decision order:
+ *   1. Start with baselineOverride (if provided), else
+ *      AGENT_BASELINE_COMPLEXITY[agentType], else 'medium'.
+ *   2. If promptLength > PROMPT_LENGTH_HIGH_THRESHOLD (20k chars),
+ *      return 'high' regardless of baseline.
+ *   3. If >= MIN_SAMPLES_FOR_DEMOTION recent samples and average
+ *      tokenEstimate is small, demote by one level:
+ *      - high → medium if avg < SAMPLE_DEMOTE_HIGH_TO_MEDIUM (3k)
+ *      - medium → low if avg < SAMPLE_DEMOTE_MEDIUM_TO_LOW (1.5k)
+ *      - low stays low
+ *   4. Otherwise return baseline.
+ */
+export function estimateComplexity(opts: {
+  agentType: string;
+  promptLength?: number;
+  recentSamples?: { duration: number; tokenEstimate: number }[];
+  baselineOverride?: ComplexityLevel;
+  heuristics?: ComplexityHeuristics;
+}): ComplexityLevel {
+  const h: Required<ComplexityHeuristics> = {
+    ...DEFAULT_HEURISTICS,
+    ...(opts.heuristics || {}),
+  };
+
+  const baseline: ComplexityLevel =
+    opts.baselineOverride ?? AGENT_BASELINE_COMPLEXITY[opts.agentType] ?? 'medium';
+
+  if (opts.promptLength !== undefined && opts.promptLength > h.prompt_length_high_threshold) {
+    return 'high';
+  }
+
+  if (opts.recentSamples && opts.recentSamples.length >= h.min_samples_for_demotion) {
+    const avgTokens =
+      opts.recentSamples.reduce((sum, s) => sum + s.tokenEstimate, 0) / opts.recentSamples.length;
+    if (baseline === 'high' && avgTokens < h.sample_demote_high_to_medium) {
+      return 'medium';
+    }
+    if (baseline === 'medium' && avgTokens < h.sample_demote_medium_to_low) {
+      return 'low';
+    }
+  }
+
+  return baseline;
+}
+
+module.exports = {
+  estimateComplexity,
+  AGENT_BASELINE_COMPLEXITY,
+};

package/lib/context/agents.ts

@@ -0,0 +1,505 @@
+'use strict';
+
+/**
+ * GRD Context/Agents -- Init context builders for agent aliases and operation workflows
+ *
+ * Contains: cmdInitDebug, cmdInitIntegrationCheck, cmdInitMigrate, cmdInitPlanCheck,
+ *           cmdInitBaselineAssessor, cmdInitCodeReviewer, cmdInitCodebaseMapper,
+ *           cmdInitDebugger, cmdInitDeepDiver, cmdInitEvalPlanner, cmdInitEvalReporter,
+ *           cmdInitExecutor, cmdInitFeasibilityAnalyst, cmdInitIntegrationChecker,
+ *           cmdInitMigrator, cmdInitPhaseResearcher, cmdInitPlanChecker,
+ *           cmdInitProductOwner, cmdInitProjectResearcher, cmdInitResearchSynthesizer,
+ *           cmdInitRoadmapper, cmdInitSurveyor, cmdInitVerifier
+ *
+ * Agent aliases are thin wrappers that delegate to canonical cmdInit* functions
+ * in sibling modules (execute, research, project).
+ *
+ * Dependencies: base.ts, execute.ts, research.ts, project.ts, utils.ts, backend.ts, paths.ts
+ */
+
+
+import type { GrdConfig, PhaseInfo, MilestoneInfo, BackendCapabilities } from '../types';
+
+const {
+  fs,
+  path,
+  safeReadMarkdown,
+  loadConfig,
+  findPhaseInternal,
+  resolveModelInternal,
+  pathExistsInternal,
+  getMilestoneInfo,
+  resolveModelForAgent,
+  resolveEffortForAgent,
+  output,
+  error,
+}: {
+  fs: typeof import('fs');
+  path: typeof import('path');
+  safeReadMarkdown: (p: string) => string | null;
+  loadConfig: (cwd: string) => GrdConfig;
+  findPhaseInternal: (cwd: string, phase: string) => PhaseInfo | null;
+  resolveModelInternal: (cwd: string, agent: string) => string;
+  pathExistsInternal: (cwd: string, target: string) => boolean;
+  getMilestoneInfo: (cwd: string) => MilestoneInfo;
+  resolveModelForAgent: (config: GrdConfig, agent: string, cwd?: string) => string;
+  resolveEffortForAgent: (config: GrdConfig, agentType: string, cwd?: string) => string | null;
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (msg: string) => never;
+} = require('../utils');
+
+const {
+  detectBackend,
+  getBackendCapabilities,
+}: {
+  detectBackend: (cwd: string) => string;
+  getBackendCapabilities: (b: string) => BackendCapabilities;
+} = require('../backend');
+
+const {
+  planningDir: getPlanningDir,
+  phasesDir: getPhasesDirPath,
+  researchDir: getResearchDirPath,
+  codebaseDir: getCodebaseDirPath,
+  milestonesDir: getMilestonesDirPath,
+}: {
+  planningDir: (cwd: string) => string;
+  phasesDir: (cwd: string) => string;
+  researchDir: (cwd: string) => string;
+  codebaseDir: (cwd: string) => string;
+  milestonesDir: (cwd: string) => string;
+} = require('../paths');
+
+const {
+  buildInitContext,
+}: {
+  buildInitContext: (cwd: string, overrides: Record<string, unknown>) => Record<string, unknown>;
+} = require('./base');
+
+// Import sibling module functions for agent aliases
+const {
+  cmdInitCodeReview,
+  cmdInitPhaseResearch,
+}: {
+  cmdInitCodeReview: (cwd: string, phase: string, raw: boolean) => void;
+  cmdInitPhaseResearch: (cwd: string, phase: string, includes: Set<string>, raw: boolean) => void;
+} = require('./execute');
+
+const {
+  rankKnowhowByPhaseGoal,
+  parseKnowhowEntries: _parseKnowhowEntries,
+}: {
+  rankKnowhowByPhaseGoal: (goal: string, entries: import('../types').KnowhowEntry[], topN?: number) => import('../types').KnowhowEntry[];
+  parseKnowhowEntries: (content: string) => import('../types').KnowhowEntry[];
+} = require('../knowledge');
+
+const { safeReadFile: _safeReadFile }: { safeReadFile: (p: string) => string | null } = require('../utils');
+
+const {
+  cmdInitMapCodebase,
+}: {
+  cmdInitMapCodebase: (cwd: string, raw: boolean) => void;
+} = require('./project');
+
+const {
+  cmdInitAssessBaseline,
+  cmdInitDeepDive,
+  cmdInitEvalPlan,
+  cmdInitEvalReport,
+  cmdInitFeasibility,
+  cmdInitProductOwner: _cmdInitProductOwner,
+  cmdInitProjectResearcher: _cmdInitProjectResearcher,
+  cmdInitResearchSynthesizer: _cmdInitResearchSynthesizer,
+  cmdInitRoadmapper: _cmdInitRoadmapper,
+  cmdInitSurveyor: _cmdInitSurveyor,
+  cmdInitVerifier: _cmdInitVerifier,
+}: {
+  cmdInitAssessBaseline: (cwd: string, raw: boolean) => void;
+  cmdInitDeepDive: (cwd: string, topic: string, raw: boolean) => void;
+  cmdInitEvalPlan: (cwd: string, phase: string | null, raw: boolean) => void;
+  cmdInitEvalReport: (cwd: string, phase: string | null, raw: boolean) => void;
+  cmdInitFeasibility: (cwd: string, topic: string, raw: boolean) => void;
+  cmdInitProductOwner: (cwd: string, raw: boolean) => void;
+  cmdInitProjectResearcher: (cwd: string, topic: string, raw: boolean) => void;
+  cmdInitResearchSynthesizer: (cwd: string, raw: boolean) => void;
+  cmdInitRoadmapper: (cwd: string, raw: boolean) => void;
+  cmdInitSurveyor: (cwd: string, topic: string, raw: boolean) => void;
+  cmdInitVerifier: (cwd: string, phase: string | null, raw: boolean) => void;
+} = require('./research');
+
+// ─── Debug Init ──────────────────────────────────────────────────────────────
+
+/**
+ * CLI command: Initialize debug context with phase info, debug files, and project state.
+ */
+function cmdInitDebug(cwd: string, phase: string | null, raw: boolean): void {
+  const backend = detectBackend(cwd);
+  const milestone = getMilestoneInfo(cwd);
+  const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
+  const planningDir = getPlanningDir(cwd);
+
+  let debugFiles: string[] = [];
+  try {
+    const entries: string[] = fs.readdirSync(planningDir);
+    debugFiles = entries.filter((f: string) => f.startsWith('DEBUG-') && f.endsWith('.md'));
+  } catch {
+    // .planning/ may not exist
+  }
+
+  const result: Record<string, unknown> = {
+    backend,
+    backend_capabilities: getBackendCapabilities(backend),
+    phase_found: !!phaseInfo,
+    phase_dir: phaseInfo?.directory || null,
+    phase_number: phaseInfo?.phase_number || null,
+    phase_name: phaseInfo?.phase_name || null,
+    debug_files: debugFiles,
+    active_debug_file:
+      debugFiles.length > 0 ? path.join('.planning', debugFiles[debugFiles.length - 1]) : null,
+    milestone_version: milestone.version,
+    milestone_name: milestone.name,
+    state_exists: pathExistsInternal(cwd, path.join(planningDir, 'STATE.md')),
+    roadmap_exists: pathExistsInternal(cwd, path.join(planningDir, 'ROADMAP.md')),
+    phases_dir: path.relative(cwd, getPhasesDirPath(cwd)),
+    research_dir: path.relative(cwd, getResearchDirPath(cwd)),
+  };
+  output(
+    result,
+    raw,
+    `Backend: ${result.backend}, debug_files: ${debugFiles.length}${phase ? ', phase: ' + phase : ''}`
+  );
+}
+
+// ─── Integration-Check Init ──────────────────────────────────────────────────
+
+/**
+ * CLI command: Initialize integration-check context with phase inventory and deferred validations.
+ */
+function cmdInitIntegrationCheck(cwd: string, phase: string | null, raw: boolean): void {
+  const backend = detectBackend(cwd);
+  const milestone = getMilestoneInfo(cwd);
+  const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
+  const planningDir = getPlanningDir(cwd);
+
+  const phasesDir = getPhasesDirPath(cwd);
+  let phaseCount = 0;
+  let summaryCount = 0;
+  try {
+    const entries: { name: string; isDirectory: () => boolean }[] = fs.readdirSync(phasesDir, {
+      withFileTypes: true,
+    });
+    const phaseDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    phaseCount = phaseDirs.length;
+    for (const d of phaseDirs) {
+      try {
+        const files: string[] = fs.readdirSync(path.join(phasesDir, d));
+        summaryCount += files.filter((f: string) => f.endsWith('-SUMMARY.md')).length;
+      } catch {
+        /* skip unreadable dirs */
+      }
+    }
+  } catch {
+    /* phases dir may not exist */
+  }
+
+  const result: Record<string, unknown> = {
+    backend,
+    backend_capabilities: getBackendCapabilities(backend),
+    phase_found: !!phaseInfo,
+    phase_dir: phaseInfo?.directory || null,
+    phase_number: phaseInfo?.phase_number || null,
+    phase_name: phaseInfo?.phase_name || null,
+    phase_count: phaseCount,
+    summary_count: summaryCount,
+    milestone_version: milestone.version,
+    milestone_name: milestone.name,
+    state_exists: pathExistsInternal(cwd, path.join(planningDir, 'STATE.md')),
+    roadmap_exists: pathExistsInternal(cwd, path.join(planningDir, 'ROADMAP.md')),
+    baseline_exists: pathExistsInternal(cwd, path.join(planningDir, 'BASELINE.md')),
+    phases_dir: path.relative(cwd, phasesDir),
+    research_dir: path.relative(cwd, getResearchDirPath(cwd)),
+    codebase_dir: path.relative(cwd, getCodebaseDirPath(cwd)),
+  };
+  output(
+    result,
+    raw,
+    `Backend: ${result.backend}, milestone: ${result.milestone_version}, ${phaseCount} phases`
+  );
+}
+
+// ─── Migrate Init ────────────────────────────────────────────────────────────
+
+/**
+ * CLI command: Initialize migrate context with planning directory layout inventory.
+ */
+function cmdInitMigrate(cwd: string, raw: boolean): void {
+  const planningDir = getPlanningDir(cwd);
+  const milestonesDir = getMilestonesDirPath(cwd);
+
+  let flatMilestoneFiles: string[] = [];
+  try {
+    const entries: { name: string; isFile: () => boolean }[] = fs.readdirSync(milestonesDir, {
+      withFileTypes: true,
+    });
+    flatMilestoneFiles = entries
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => path.join(path.relative(cwd, milestonesDir), e.name));
+  } catch {
+    /* milestones dir may not exist */
+  }
+
+  let legacyPhaseDirs: string[] = [];
+  try {
+    const entries: { name: string; isDirectory: () => boolean }[] = fs.readdirSync(milestonesDir, {
+      withFileTypes: true,
+    });
+    legacyPhaseDirs = entries
+      .filter((e) => e.isDirectory() && /^\d{2}-/.test(e.name))
+      .map((e) => path.join(path.relative(cwd, milestonesDir), e.name));
+  } catch {
+    /* milestones dir may not exist */
+  }
+
+  const result = buildInitContext(cwd, {
+    flat_milestone_files: flatMilestoneFiles,
+    legacy_phase_dirs: legacyPhaseDirs,
+    complex_items_count: flatMilestoneFiles.length + legacyPhaseDirs.length,
+    state_exists: pathExistsInternal(cwd, path.join(planningDir, 'STATE.md')),
+    roadmap_exists: pathExistsInternal(cwd, path.join(planningDir, 'ROADMAP.md')),
+    planning_dir: path.relative(cwd, planningDir),
+    milestones_dir: path.relative(cwd, milestonesDir),
+  });
+  output(result, raw, `Backend: ${result.backend}, complex_items: ${result.complex_items_count}`);
+}
+
+// ─── Plan-Check Init ─────────────────────────────────────────────────────────
+
+/**
+ * CLI command: Initialize plan-check context with phase plan files and roadmap goal.
+ */
+function cmdInitPlanCheck(cwd: string, phase: string, raw: boolean): void {
+  if (!phase) {
+    error(
+      'phase required for init plan-check. Usage: init plan-check <phase-number>. Provide a phase number, e.g.: init plan-check 2'
+    );
+    return;
+  }
+
+  const config = loadConfig(cwd);
+  const backend = detectBackend(cwd);
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  const planningDir = getPlanningDir(cwd);
+
+  const result: Record<string, unknown> = {
+    backend,
+    backend_capabilities: getBackendCapabilities(backend),
+    checker_model: resolveModelForAgent(config, 'planner'),
+    checker_effort: resolveEffortForAgent(config, 'grd-plan-checker', cwd),
+    phase_found: !!phaseInfo,
+    phase_dir: phaseInfo?.directory || null,
+    phase_number: phaseInfo?.phase_number || null,
+    phase_name: phaseInfo?.phase_name || null,
+    plans: phaseInfo?.plans || [],
+    plan_count: phaseInfo?.plans?.length || 0,
+    has_research: phaseInfo?.has_research || false,
+    has_context: phaseInfo?.has_context || false,
+    has_eval: (phaseInfo as unknown as Record<string, unknown> | null)?.has_eval || false,
+    roadmap_exists: pathExistsInternal(cwd, path.join(planningDir, 'ROADMAP.md')),
+    requirements_exists: pathExistsInternal(cwd, path.join(planningDir, 'REQUIREMENTS.md')),
+    phases_dir: path.relative(cwd, getPhasesDirPath(cwd)),
+  };
+  output(
+    result,
+    raw,
+    `Backend: ${result.backend}, phase: ${result.phase_number || 'unknown'}, plans: ${result.plan_count}`
+  );
+}
+
+// ─── Executor Init ───────────────────────────────────────────────────────────
+
+/**
+ * CLI command: Initialize executor context with phase plans, STATE, and ROADMAP.
+ */
+function cmdInitExecutor(cwd: string, phase: string, includes: Set<string>, raw: boolean): void {
+  if (!phase) {
+    error(
+      'phase required for init executor. Usage: init executor <phase-number>. Provide a phase number, e.g.: init executor 2'
+    );
+    return;
+  }
+
+  const config = loadConfig(cwd);
+  const backend = detectBackend(cwd);
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  const milestone = getMilestoneInfo(cwd);
+  const planningDir = getPlanningDir(cwd);
+
+  const result: Record<string, unknown> = {
+    backend,
+    backend_capabilities: getBackendCapabilities(backend),
+    executor_model: resolveModelInternal(cwd, 'grd-executor'),
+    executor_effort: resolveEffortForAgent(config, 'grd-executor', cwd),
+    commit_docs: config.commit_docs,
+    parallelization: config.parallelization,
+    use_teams: config.use_teams,
+    team_timeout_minutes: config.team_timeout_minutes,
+    phase_found: !!phaseInfo,
+    phase_dir: phaseInfo?.directory || null,
+    phase_number: phaseInfo?.phase_number || null,
+    phase_name: phaseInfo?.phase_name || null,
+    phase_slug: phaseInfo?.phase_slug || null,
+    plans: phaseInfo?.plans || [],
+    summaries: phaseInfo?.summaries || [],
+    incomplete_plans: phaseInfo?.incomplete_plans || [],
+    plan_count: phaseInfo?.plans?.length || 0,
+    incomplete_count: phaseInfo?.incomplete_plans?.length || 0,
+    milestone_version: milestone.version,
+    milestone_name: milestone.name,
+    state_exists: pathExistsInternal(cwd, path.join(planningDir, 'STATE.md')),
+    roadmap_exists: pathExistsInternal(cwd, path.join(planningDir, 'ROADMAP.md')),
+    principles_exists: pathExistsInternal(cwd, path.join(planningDir, 'PRINCIPLES.md')),
+    phases_dir: path.relative(cwd, getPhasesDirPath(cwd)),
+    research_dir: path.relative(cwd, getResearchDirPath(cwd)),
+  };
+
+  if (includes && includes.has('state')) {
+    result.state_content = safeReadMarkdown(path.join(cwd, '.planning', 'STATE.md'));
+  }
+  if (includes && includes.has('roadmap')) {
+    result.roadmap_content = safeReadMarkdown(path.join(cwd, '.planning', 'ROADMAP.md'));
+  }
+
+  // Inject top-5 KNOWHOW entries ranked by relevance to the phase goal (TF-IDF).
+  // Codex r18 P2: KNOWHOW lives under the milestone (and per-phase),
+  // not the project root. Scan all known locations and merge entries.
+  result.knowhow_block = (() => {
+    const candidates: string[] = [];
+    candidates.push(path.join(cwd, '.planning', 'KNOWHOW.md'));
+    candidates.push(path.join(cwd, 'KNOWHOW.md'));
+    const milestonesDir = path.join(cwd, '.planning', 'milestones');
+    try {
+      for (const ms of require('fs').readdirSync(milestonesDir) as string[]) {
+        candidates.push(path.join(milestonesDir, ms, 'KNOWHOW.md'));
+        candidates.push(path.join(milestonesDir, ms, 'research', 'KNOWHOW.md'));
+        const phasesBase = path.join(milestonesDir, ms, 'phases');
+        try {
+          for (const ph of require('fs').readdirSync(phasesBase) as string[]) {
+            candidates.push(path.join(phasesBase, ph, 'KNOWHOW.md'));
+          }
+        } catch { /* skip */ }
+      }
+    } catch { /* skip */ }
+
+    const allEntries: ReturnType<typeof _parseKnowhowEntries> = [];
+    for (const p of candidates) {
+      const content = _safeReadFile(p);
+      if (!content || !content.trim()) continue;
+      allEntries.push(..._parseKnowhowEntries(content));
+    }
+    if (allEntries.length === 0) return null;
+    const entries = allEntries;
+    const goal = [phaseInfo?.phase_name, phaseInfo?.phase_number ? `phase ${phaseInfo.phase_number}` : ''].filter(Boolean).join(' ');
+    const ranked = rankKnowhowByPhaseGoal(goal || 'implementation', entries, 5);
+    if (ranked.length === 0) return null;
+    const body = ranked.map((e) =>
+      `### ${e.pattern_name}\n- **applicability:** ${e.applicability}\n- **source:** ${e.source}\n`
+    ).join('\n');
+    return `<knowhow_context>\n${body}\n</knowhow_context>`;
+  })();
+
+  output(
+    result,
+    raw,
+    `Backend: ${result.backend}, phase: ${result.phase_number || 'unknown'}, plans: ${result.plan_count}`
+  );
+}
+
+// ─── Agent Aliases ───────────────────────────────────────────────────────────
+// Thin wrappers delegating to canonical cmdInit* functions in sibling modules.
+
+function cmdInitBaselineAssessor(cwd: string, raw: boolean): void {
+  return cmdInitAssessBaseline(cwd, raw);
+}
+function cmdInitCodeReviewer(cwd: string, phase: string, raw: boolean): void {
+  return cmdInitCodeReview(cwd, phase, raw);
+}
+function cmdInitCodebaseMapper(cwd: string, raw: boolean): void {
+  return cmdInitMapCodebase(cwd, raw);
+}
+function cmdInitDebugger(cwd: string, phase: string | null, raw: boolean): void {
+  return cmdInitDebug(cwd, phase, raw);
+}
+function cmdInitDeepDiver(cwd: string, topic: string, raw: boolean): void {
+  return cmdInitDeepDive(cwd, topic, raw);
+}
+function cmdInitEvalPlanner(cwd: string, phase: string | null, raw: boolean): void {
+  return cmdInitEvalPlan(cwd, phase, raw);
+}
+function cmdInitEvalReporter(cwd: string, phase: string | null, raw: boolean): void {
+  return cmdInitEvalReport(cwd, phase, raw);
+}
+function cmdInitFeasibilityAnalyst(cwd: string, topic: string, raw: boolean): void {
+  return cmdInitFeasibility(cwd, topic, raw);
+}
+function cmdInitIntegrationChecker(cwd: string, phase: string | null, raw: boolean): void {
+  return cmdInitIntegrationCheck(cwd, phase, raw);
+}
+function cmdInitMigrator(cwd: string, raw: boolean): void {
+  return cmdInitMigrate(cwd, raw);
+}
+function cmdInitPhaseResearcher(
+  cwd: string,
+  phase: string,
+  includes: Set<string>,
+  raw: boolean
+): void {
+  return cmdInitPhaseResearch(cwd, phase, includes, raw);
+}
+function cmdInitPlanChecker(cwd: string, phase: string, raw: boolean): void {
+  return cmdInitPlanCheck(cwd, phase, raw);
+}
+function cmdInitProductOwner(cwd: string, raw: boolean): void {
+  return _cmdInitProductOwner(cwd, raw);
+}
+function cmdInitProjectResearcher(cwd: string, topic: string, raw: boolean): void {
+  return _cmdInitProjectResearcher(cwd, topic, raw);
+}
+function cmdInitResearchSynthesizer(cwd: string, raw: boolean): void {
+  return _cmdInitResearchSynthesizer(cwd, raw);
+}
+function cmdInitRoadmapper(cwd: string, raw: boolean): void {
+  return _cmdInitRoadmapper(cwd, raw);
+}
+function cmdInitSurveyor(cwd: string, topic: string, raw: boolean): void {
+  return _cmdInitSurveyor(cwd, topic, raw);
+}
+function cmdInitVerifier(cwd: string, phase: string | null, raw: boolean): void {
+  return _cmdInitVerifier(cwd, phase, raw);
+}
+
+module.exports = {
+  cmdInitDebug,
+  cmdInitIntegrationCheck,
+  cmdInitMigrate,
+  cmdInitPlanCheck,
+  cmdInitExecutor,
+  // Agent aliases
+  cmdInitBaselineAssessor,
+  cmdInitCodeReviewer,
+  cmdInitCodebaseMapper,
+  cmdInitDebugger,
+  cmdInitDeepDiver,
+  cmdInitEvalPlanner,
+  cmdInitEvalReporter,
+  cmdInitFeasibilityAnalyst,
+  cmdInitIntegrationChecker,
+  cmdInitMigrator,
+  cmdInitPhaseResearcher,
+  cmdInitPlanChecker,
+  cmdInitProductOwner,
+  cmdInitProjectResearcher,
+  cmdInitResearchSynthesizer,
+  cmdInitRoadmapper,
+  cmdInitSurveyor,
+  cmdInitVerifier,
+};