@wooojin/forgen 0.4.9 → 0.4.11

package/dist/cli.js

@@ -279,12 +279,13 @@ const commands = [
     },
     {
         name: 'doctor',
-        description: 'Diagnostics (--prune-state to GC stale session files, --repair to auto-fix plugin cache)',
+        description: 'Diagnostics (--quick for fast check, --prune-state to GC, --repair to auto-fix)',
         handler: async (args) => {
             const { runDoctor } = await import('./core/doctor.js');
             await runDoctor({
                 pruneState: args.includes('--prune-state'),
                 repair: args.includes('--repair'),
+                quick: args.includes('--quick'),
             });
         },
     },
@@ -341,6 +342,54 @@ const commands = [
             await handleStats(args);
         },
     },
+    {
+        name: 'watch',
+        description: 'Real-time hook event stream (hook firings, blocks, solution matches)',
+        handler: async () => {
+            const { handleWatch } = await import('./core/watch-cli.js');
+            await handleWatch();
+        },
+    },
+    {
+        name: 'health',
+        description: 'Single-line health score (0-100) combining utilization, effectiveness, growth.',
+        handler: async () => {
+            const { handleHealth } = await import('./core/health-cli.js');
+            await handleHealth();
+        },
+    },
+    {
+        name: 'probe-workflow',
+        description: 'ADR-009 §1: measure whether dynamic-workflow subagents fire forgen hooks (arm|report|status).',
+        handler: async (args) => {
+            const { handleProbeWorkflow } = await import('./core/probe-workflow-cli.js');
+            await handleProbeWorkflow(args);
+        },
+    },
+    {
+        name: 'workflows',
+        description: 'Install/list forgen dynamic-workflow templates (install [--project] | list).',
+        handler: async (args) => {
+            const { handleWorkflows } = await import('./core/workflows-cli.js');
+            await handleWorkflows(args);
+        },
+    },
+    {
+        name: 'explain',
+        description: 'Explain the most recent block — what rule, why, and how to resolve.',
+        handler: async (args) => {
+            const { handleExplain } = await import('./core/explain-cli.js');
+            await handleExplain(args);
+        },
+    },
+    {
+        name: 'changelog',
+        description: 'Auto-summarize changes since last release tag (conventional commits).',
+        handler: async () => {
+            const { handleChangelog } = await import('./core/changelog-cli.js');
+            await handleChangelog();
+        },
+    },
     {
         name: 'last-block',
         description: 'Show the most recent Mech-A/B block event with rule detail (R6-UX2).',
@@ -365,6 +414,14 @@ const commands = [
             await handleMigrate(args);
         },
     },
+    {
+        name: 'regress-map',
+        description: 'Top fix-touched files in the last N days (--days 30 --top 10 --json).',
+        handler: async (args) => {
+            const { handleRegressMap } = await import('./core/regress-map-cli.js');
+            await handleRegressMap(args);
+        },
+    },
     {
         name: 'suppress-rule',
         description: '[alias: rule suppress] Disable a rule by id/prefix. Hard rules refused.',
@@ -571,6 +628,12 @@ function printHelp() {
     forgen rule <list|suppress|activate|scan|health-scan|classify>
                                     Rule management (see: forgen rule help)
     forgen stats                    One-screen trust-layer dashboard (+ philosophy)
+    forgen health                   Single-line health score (0-100) with grade
+    forgen probe-workflow arm|report  Measure if dynamic-workflow subagents fire hooks (ADR-009 §1)
+    forgen workflows install|list   Install forgen dynamic-workflow templates to .claude/workflows/
+    forgen watch                    Real-time hook event stream (tail logs live)
+    forgen explain [N]              Explain the last N block(s) — rule, reason, resolution
+    forgen changelog                Auto-summarize commits since last release tag
     forgen last-block               Show the most recent block event
     forgen recall [--limit N] [--show]
                                     최근 compound 주입 이력 (solution body preview)
@@ -585,7 +648,7 @@ function printHelp() {
     forgen mcp                      MCP server management
     forgen skill promote|list       Skill management
     forgen notepad show|add|clear   Session notepad
-    forgen doctor [--prune-state]   System diagnostics (+ daily T4 decay on prune)
+    forgen doctor [--quick|--prune-state|--repair]   System diagnostics
     forgen uninstall                Remove forgen
 
   Harness mode (default):

package/dist/core/changelog-cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * forgen changelog — auto-summarize changes since last release tag.
+ *
+ * Reads git log between the latest vX.Y.Z tag and HEAD, groups by
+ * conventional commit type, and outputs a ready-to-paste changelog.
+ */
+export declare function handleChangelog(): Promise<void>;

package/dist/core/changelog-cli.js

@@ -0,0 +1,100 @@
+/**
+ * forgen changelog — auto-summarize changes since last release tag.
+ *
+ * Reads git log between the latest vX.Y.Z tag and HEAD, groups by
+ * conventional commit type, and outputs a ready-to-paste changelog.
+ */
+import { execFileSync } from 'node:child_process';
+const isTTY = process.stdout.isTTY;
+const C = {
+    reset: isTTY ? '\x1b[0m' : '',
+    bold: isTTY ? '\x1b[1m' : '',
+    dim: isTTY ? '\x1b[2m' : '',
+    cyan: isTTY ? '\x1b[36m' : '',
+    green: isTTY ? '\x1b[32m' : '',
+    yellow: isTTY ? '\x1b[33m' : '',
+};
+function getLatestTag() {
+    try {
+        return execFileSync('git', ['describe', '--tags', '--abbrev=0'], {
+            encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function getCommitsSince(tag) {
+    try {
+        const args = tag
+            ? ['log', `${tag}..HEAD`, '--oneline', '--no-merges']
+            : ['log', '--oneline', '--no-merges', '-30'];
+        return execFileSync('git', args, {
+            encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim().split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+function parseCommit(line) {
+    const match = line.match(/^([a-f0-9]+)\s+(\w+)(?:\(([^)]*)\))?:\s*(.+)$/);
+    if (match) {
+        return { hash: match[1], type: match[2], scope: match[3] ?? '', subject: match[4] };
+    }
+    const parts = line.split(/\s+/, 2);
+    return { hash: parts[0], type: 'other', scope: '', subject: parts.slice(1).join(' ') || line };
+}
+const TYPE_ORDER = {
+    feat: { label: 'Features', order: 0 },
+    fix: { label: 'Bug Fixes', order: 1 },
+    refactor: { label: 'Refactoring', order: 2 },
+    test: { label: 'Tests', order: 3 },
+    ci: { label: 'CI/CD', order: 4 },
+    docs: { label: 'Documentation', order: 5 },
+    chore: { label: 'Maintenance', order: 6 },
+    other: { label: 'Other', order: 7 },
+};
+export async function handleChangelog() {
+    const tag = getLatestTag();
+    const rawCommits = getCommitsSince(tag);
+    if (rawCommits.length === 0) {
+        console.log(`\n  ${C.dim}No commits since ${tag ?? 'beginning'}.${C.reset}\n`);
+        return;
+    }
+    const commits = rawCommits.map(parseCommit);
+    const grouped = new Map();
+    for (const c of commits) {
+        const key = TYPE_ORDER[c.type] ? c.type : 'other';
+        if (!grouped.has(key))
+            grouped.set(key, []);
+        grouped.get(key)?.push(c);
+    }
+    const sorted = [...grouped.entries()].sort((a, b) => {
+        return (TYPE_ORDER[a[0]]?.order ?? 99) - (TYPE_ORDER[b[0]]?.order ?? 99);
+    });
+    console.log('');
+    console.log(`  ${C.bold}Changelog${C.reset}  ${C.dim}${tag ?? 'start'}..HEAD${C.reset}  ${C.dim}(${commits.length} commits)${C.reset}`);
+    console.log('');
+    for (const [type, items] of sorted) {
+        const label = TYPE_ORDER[type]?.label ?? type;
+        console.log(`  ${C.cyan}### ${label}${C.reset}`);
+        for (const c of items) {
+            const scope = c.scope ? `${C.yellow}(${c.scope})${C.reset} ` : '';
+            console.log(`    ${C.dim}${c.hash}${C.reset} ${scope}${c.subject}`);
+        }
+        console.log('');
+    }
+    // Markdown output for copy-paste
+    console.log(`  ${C.dim}── Markdown (copy-paste ready) ──${C.reset}`);
+    console.log('');
+    for (const [type, items] of sorted) {
+        const label = TYPE_ORDER[type]?.label ?? type;
+        console.log(`  ### ${label}`);
+        for (const c of items) {
+            const scope = c.scope ? `**${c.scope}**: ` : '';
+            console.log(`  - ${scope}${c.subject}`);
+        }
+        console.log('');
+    }
+}

package/dist/core/doctor.d.ts

@@ -12,5 +12,8 @@ export interface DoctorOptions {
      * doctor 흐름은 정상 종료.
      */
     repair?: boolean;
+    /** When true, run only essential checks (Tools + Plugins + Directories +
+     *  Initialization Status) for fast onboarding verification. ~10 lines output. */
+    quick?: boolean;
 }
 export declare function runDoctor(opts?: DoctorOptions): Promise<void>;

package/dist/core/doctor.js

@@ -7,6 +7,8 @@ import { FORGEN_HOME, LAB_DIR, ME_BEHAVIOR, ME_DIR, ME_SOLUTIONS, ME_RULES, ME_S
 import { getTimingStats } from '../hooks/shared/hook-timing.js';
 import { countSessionScopedFiles, pruneState } from './state-gc.js';
 import { summarizeAllByHost } from '../store/host-mismatch.js';
+import { readForgeLoopState } from '../hooks/shared/forge-loop-state.js';
+import { effortAdvisory } from './effort-advisory.js';
 /** ~/.claude/projects/ — Claude Code 세션 저장 경로 */
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
 let currentSection = '';
@@ -189,6 +191,28 @@ export async function runDoctor(opts = {}) {
         }
     }
     console.log();
+    section('Initialization Status');
+    const profilePath = path.join(ME_DIR, 'forge-profile.json');
+    const profileOk = exists(profilePath);
+    check('Profile exists (forge-profile.json)', profileOk, 'No profile — run `forgen` to complete onboarding');
+    const hooksWired = forgenPluginCacheOk || pluginRegistered;
+    if (hooksWired && !profileOk) {
+        check('Hooks wired + profile ready', false, 'Hooks are active but personalization is disabled — run `forgen` to onboard');
+    }
+    else if (hooksWired && profileOk) {
+        check('Hooks wired + profile ready', true);
+    }
+    console.log();
+    if (opts.quick) {
+        console.log();
+        if (failedChecks.length === 0) {
+            console.log('  All essential checks passed.\n');
+        }
+        else {
+            console.log(`  ${failedChecks.length} issue(s) found. Run \`forgen doctor\` for full diagnostics.\n`);
+        }
+        return;
+    }
     section('Environment');
     check('Inside tmux session', !!process.env.TMUX, 'FORGEN auto-compound relies on tmux. Launch: tmux new -s forgen');
     check('FORGEN_HARNESS env var', (process.env.FORGEN_HARNESS ?? process.env.COMPOUND_HARNESS) === '1', 'Set by `forgen` / `fgx` launcher. Hooks assume harness mode is active.');
@@ -491,12 +515,18 @@ export async function runDoctor(opts = {}) {
     }
     // P4 셀프 가드: fix:feat 비율 30% 초과 시 회귀 패턴 의심 경고.
     try {
-        const { computeFixFeatRatio, formatFixRatio } = await import('./git-stats.js');
+        const { computeFixFeatRatio, formatFixRatio, computeRegressMap } = await import('./git-stats.js');
         const ratio = computeFixFeatRatio();
         if (ratio.available) {
             console.log(`  ${formatFixRatio(ratio)}`);
             if (ratio.exceedsThreshold) {
                 console.log('  ⚠ fix:feat 비율이 임계값을 초과했습니다. "이거 고치면 저거 버그난다" 패턴 의심 — 검증 레이어 invariant 점검 권장.');
+                const map = computeRegressMap(process.cwd(), 30, 3);
+                if (map.available && map.hotspots.length > 0) {
+                    const top = map.hotspots.map((h) => `${h.path} (${h.fixHits})`).join(', ');
+                    console.log(`  → 진앙 후보 top 3: ${top}`);
+                    console.log('  → 전체 보기: forgen regress-map');
+                }
             }
         }
     }
@@ -529,6 +559,50 @@ export async function runDoctor(opts = {}) {
     // [Codex Parity] — parity-result.json 신선도 검사 (v0.4.2 패턴 확장)
     renderCodexParity();
     console.log();
+    // [ψ-long] — within-conversation compound 효과 측정 (v0.4.10)
+    // 측정 시간이 길어 ship-gate 는 advisory. 신선도(<= 14d) + psiLong > 0 만 확인.
+    console.log('  [ψ-long compound]');
+    try {
+        const psiLongPath = path.join(STATE_DIR, 'psi-long-result.json');
+        if (!fs.existsSync(psiLongPath)) {
+            console.log('  ○ no measurement yet — `pnpm --filter @wooojin/forgen-eval psi:long` 권장');
+        }
+        else {
+            const raw = fs.readFileSync(psiLongPath, 'utf-8');
+            const data = JSON.parse(raw);
+            const ageMs = data.at ? Date.now() - new Date(data.at).getTime() : Number.POSITIVE_INFINITY;
+            const ageDays = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+            const psiLong = data.psiLong ?? 0;
+            const passed = !!data.passed;
+            const freshTag = ageDays <= 14 ? 'fresh' : `${ageDays}d stale`;
+            const gateLabel = passed ? '✓ PASS' : '✗ FAIL';
+            console.log(`  ${gateLabel}  ψ_long=${psiLong.toFixed(3)}  N=${data.N ?? '?'}  (${freshTag})`);
+            if (!passed) {
+                console.log('  ⚠ within-session compound 효과 미관측 — correction injection / rule trigger 경로 점검');
+            }
+            else if (ageDays > 14) {
+                console.log('  △ 측정 14일 초과 — 재측정 권장 (`pnpm --filter @wooojin/forgen-eval psi:long`)');
+            }
+        }
+    }
+    catch (e) {
+        console.log(`  Unable to read psi-long state: ${e instanceof Error ? e.message : 'unknown'}`);
+    }
+    console.log();
+    // [Effort (Opus 4.8)] — ADR-009 §5. nudge-only: forgen 은 effort 를 직접 설정할 수
+    // 없으므로 long-running 컨텍스트(forge-loop)에서 xhigh/ultracode 를 권고만 한다.
+    console.log('  [Effort (Opus 4.8)]');
+    try {
+        const loopActive = !!readForgeLoopState()?.active;
+        const adv = effortAdvisory({ longRunningActive: loopActive });
+        const icon = adv.recommend === 'xhigh' ? '→' : '✓';
+        console.log(`  ${icon} recommend: ${adv.recommend}`);
+        console.log(`    ${adv.reason}`);
+    }
+    catch {
+        console.log('  Unable to compute effort advisory.');
+    }
+    console.log();
     // [Summary] — 최종 상태 요약과 복구 액션을 한눈에 보이게
     console.log('  [Summary]');
     if (failedChecks.length === 0) {

package/dist/core/effort-advisory.d.ts

@@ -0,0 +1,23 @@
+/**
+ * forgen effort advisory (ADR-009 §5) — nudge-only.
+ *
+ * Claude Opus 4.8 은 effort(high/xhigh)·ultracode 를 도입했다. forgen 은 hook
+ * 인터페이스를 통해 동작하므로 Claude 의 effort 를 **프로그램적으로 설정할 수 없다**.
+ * 따라서 이 모듈은 *권고만* 한다 — long-running/비동기 작업(forge-loop, 대규모
+ * 워크플로우)에서는 xhigh/ultracode 가 유리하다는 힌트를 사용자에게 노출한다.
+ *
+ * 순수 함수 (IO 없음) — doctor 등에서 surface.
+ */
+export interface EffortAdvisory {
+    recommend: 'high' | 'xhigh';
+    reason: string;
+}
+export interface EffortContext {
+    /** forge-loop 등 장시간 무인 실행이 활성인가. */
+    longRunningActive: boolean;
+}
+/**
+ * effort 권고를 반환한다. long-running 컨텍스트면 xhigh, 아니면 high(기본).
+ * 4.8 기본값이 이미 high 이므로 일상 작업엔 추가 권고가 불필요하다.
+ */
+export declare function effortAdvisory(ctx: EffortContext): EffortAdvisory;

package/dist/core/effort-advisory.js

@@ -0,0 +1,29 @@
+/**
+ * forgen effort advisory (ADR-009 §5) — nudge-only.
+ *
+ * Claude Opus 4.8 은 effort(high/xhigh)·ultracode 를 도입했다. forgen 은 hook
+ * 인터페이스를 통해 동작하므로 Claude 의 effort 를 **프로그램적으로 설정할 수 없다**.
+ * 따라서 이 모듈은 *권고만* 한다 — long-running/비동기 작업(forge-loop, 대규모
+ * 워크플로우)에서는 xhigh/ultracode 가 유리하다는 힌트를 사용자에게 노출한다.
+ *
+ * 순수 함수 (IO 없음) — doctor 등에서 surface.
+ */
+/**
+ * effort 권고를 반환한다. long-running 컨텍스트면 xhigh, 아니면 high(기본).
+ * 4.8 기본값이 이미 high 이므로 일상 작업엔 추가 권고가 불필요하다.
+ */
+export function effortAdvisory(ctx) {
+    if (ctx.longRunningActive) {
+        return {
+            recommend: 'xhigh',
+            reason: 'long-running 컨텍스트 감지(forge-loop). Opus 4.8 은 어려운/비동기 작업에 ' +
+                'xhigh(=extra) 또는 /effort ultracode 를 권장 — forgen 은 effort 를 직접 설정할 수 ' +
+                '없으니 /effort 로 수동 전환하세요. (nudge-only)',
+        };
+    }
+    return {
+        recommend: 'high',
+        reason: 'Opus 4.8 기본 effort=high 로 충분. 대규모 마이그레이션/리팩터/감사 시에만 ' +
+            '/effort xhigh|ultracode 고려.',
+    };
+}

package/dist/core/explain-cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * forgen explain — explain the most recent block in detail.
+ *
+ * Shows: what rule fired, why, what Claude said, and how to resolve.
+ */
+export declare function handleExplain(args: string[]): Promise<void>;

package/dist/core/explain-cli.js

@@ -0,0 +1,99 @@
+/**
+ * forgen explain — explain the most recent block in detail.
+ *
+ * Shows: what rule fired, why, what Claude said, and how to resolve.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR } from './paths.js';
+const isTTY = process.stdout.isTTY;
+const C = {
+    reset: isTTY ? '\x1b[0m' : '',
+    bold: isTTY ? '\x1b[1m' : '',
+    dim: isTTY ? '\x1b[2m' : '',
+    red: isTTY ? '\x1b[31m' : '',
+    green: isTTY ? '\x1b[32m' : '',
+    yellow: isTTY ? '\x1b[33m' : '',
+    cyan: isTTY ? '\x1b[36m' : '',
+    magenta: isTTY ? '\x1b[35m' : '',
+};
+function readViolations() {
+    const p = path.join(STATE_DIR, 'enforcement', 'violations.jsonl');
+    if (!fs.existsSync(p))
+        return [];
+    const out = [];
+    for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
+function readAcknowledgments() {
+    const p = path.join(STATE_DIR, 'enforcement', 'acknowledgments.jsonl');
+    if (!fs.existsSync(p))
+        return [];
+    const out = [];
+    for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
+function formatTime(iso) {
+    try {
+        const d = new Date(iso);
+        return d.toLocaleString('en-GB', { dateStyle: 'short', timeStyle: 'medium' });
+    }
+    catch {
+        return iso;
+    }
+}
+export async function handleExplain(args) {
+    const violations = readViolations();
+    if (violations.length === 0) {
+        console.log(`\n  ${C.green}No blocks recorded.${C.reset} forgen hasn't blocked Claude yet.\n`);
+        return;
+    }
+    const count = Math.min(Number(args[0]) || 1, 5);
+    const targets = violations.slice(-count);
+    const acks = readAcknowledgments();
+    for (const v of targets) {
+        const ruleId = v.rule_id ?? v.rule ?? v.guard ?? 'unknown';
+        const source = v.source ?? 'unknown';
+        const kind = v.kind ?? 'block';
+        const when = v.at ? formatTime(v.at) : 'unknown time';
+        const reason = v.reason ?? v.reason_preview ?? v.message_preview ?? v.pattern_preview ?? '(no reason recorded)';
+        // Check if this block was acknowledged
+        const blockTime = v.at ? new Date(v.at).getTime() : 0;
+        const wasAcked = acks.some(a => {
+            if (!a.at)
+                return false;
+            const ackTime = new Date(a.at).getTime();
+            return ackTime > blockTime && ackTime - blockTime < 300_000; // within 5 min
+        });
+        console.log('');
+        console.log(`  ${C.red}${C.bold}BLOCK${C.reset}  ${C.dim}${when}${C.reset}`);
+        console.log(`  ${C.cyan}Rule:${C.reset}    ${ruleId}`);
+        console.log(`  ${C.cyan}Source:${C.reset}  ${source} (${kind})`);
+        if (v.tool) {
+            console.log(`  ${C.cyan}Tool:${C.reset}    ${v.tool}`);
+        }
+        console.log(`  ${C.cyan}Reason:${C.reset}`);
+        for (const line of reason.split('\n').slice(0, 5)) {
+            console.log(`    ${C.dim}${line}${C.reset}`);
+        }
+        console.log(`  ${C.cyan}Resolved:${C.reset} ${wasAcked ? `${C.green}Yes — Claude retracted and resubmitted with evidence${C.reset}` : `${C.yellow}No acknowledgment found${C.reset}`}`);
+        console.log('');
+        console.log(`  ${C.dim}To suppress this rule: forgen suppress-rule ${ruleId}${C.reset}`);
+        console.log(`  ${C.dim}To bypass one turn:    set FORGEN_USER_CONFIRMED=1${C.reset}`);
+    }
+    console.log('');
+}

package/dist/core/git-stats.d.ts

@@ -34,3 +34,26 @@ export declare function computeFixFeatRatio(cwd?: string, windowSize?: number, t
 export declare function parseGitLog(rawLog: string, windowSize?: number, threshold?: number): FixRatioStats;
 /** 사람용 한 줄 라벨. */
 export declare function formatFixRatio(s: FixRatioStats): string;
+export interface RegressHotspot {
+    path: string;
+    fixHits: number;
+    lastFixSha: string;
+    lastFixDate: string;
+}
+export interface RegressMap {
+    windowDays: number;
+    fixCommits: number;
+    hotspots: RegressHotspot[];
+    available: boolean;
+}
+/**
+ * 지난 N일 동안 fix 커밋이 닿은 파일 hot-list.
+ *
+ * doctor 가 fix:feat 비율로 "회귀 패턴 의심" 시그널은 주지만, 진앙은 안 보여준다.
+ * regress-map 은 fix 커밋의 changed-files 를 카운트해 top-N hotspot 을 추출 →
+ * "이거 고치면 저거 깨진다" 의 *저거* 후보를 한 화면에 노출.
+ *
+ * 제외 scope (fix:feat 와 동일): fix(test|tests|docs|doc) — 노이즈.
+ */
+export declare function computeRegressMap(cwd?: string, windowDays?: number, topN?: number): RegressMap;
+export declare function parseRegressLog(raw: string, windowDays: number, topN: number): RegressMap;

package/dist/core/git-stats.js

@@ -77,3 +77,53 @@ export function formatFixRatio(s) {
     const flag = s.exceedsThreshold ? `  ⚠ over ${thresholdPct}%` : '';
     return `fix:feat ratio    ${pct}%   (${s.fixCount}/${s.fixCount + s.featCount} in last ${s.windowSize})${flag}`;
 }
+/**
+ * 지난 N일 동안 fix 커밋이 닿은 파일 hot-list.
+ *
+ * doctor 가 fix:feat 비율로 "회귀 패턴 의심" 시그널은 주지만, 진앙은 안 보여준다.
+ * regress-map 은 fix 커밋의 changed-files 를 카운트해 top-N hotspot 을 추출 →
+ * "이거 고치면 저거 깨진다" 의 *저거* 후보를 한 화면에 노출.
+ *
+ * 제외 scope (fix:feat 와 동일): fix(test|tests|docs|doc) — 노이즈.
+ */
+export function computeRegressMap(cwd = process.cwd(), windowDays = 30, topN = 10) {
+    try {
+        const since = `--since=${windowDays}.days.ago`;
+        const out = execFileSync('git', ['log', '--no-merges', since, '--name-only', '--pretty=format:%x1fCOMMIT%x1f%h%x1f%cs%x1f%s'], { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 32 * 1024 * 1024 });
+        return parseRegressLog(out, windowDays, topN);
+    }
+    catch {
+        return { windowDays, fixCommits: 0, hotspots: [], available: false };
+    }
+}
+export function parseRegressLog(raw, windowDays, topN) {
+    const blocks = raw.split('\x1fCOMMIT\x1f').slice(1);
+    const counter = new Map();
+    let fixCommits = 0;
+    for (const block of blocks) {
+        const [sha, date, rest = ''] = block.split('\x1f');
+        const nl = rest.indexOf('\n');
+        const subject = nl === -1 ? rest : rest.slice(0, nl);
+        const files = nl === -1 ? [] : rest.slice(nl + 1).split('\n').map((s) => s.trim()).filter(Boolean);
+        const m = subject.match(/^(fix|feat)(?:\(([^)]+)\))?:/);
+        if (!m || m[1] !== 'fix')
+            continue;
+        const scope = (m[2] ?? '').toLowerCase().trim();
+        if (SCOPE_EXCLUSIONS.has(scope))
+            continue;
+        fixCommits++;
+        for (const f of files) {
+            const existing = counter.get(f);
+            if (existing) {
+                existing.fixHits++;
+            }
+            else {
+                counter.set(f, { path: f, fixHits: 1, lastFixSha: sha, lastFixDate: date });
+            }
+        }
+    }
+    const hotspots = Array.from(counter.values())
+        .sort((a, b) => b.fixHits - a.fixHits || a.path.localeCompare(b.path))
+        .slice(0, topN);
+    return { windowDays, fixCommits, hotspots, available: true };
+}

package/dist/core/health-cli.d.ts

@@ -0,0 +1,23 @@
+/**
+ * forgen health — single-line health score (0-100).
+ *
+ * Combines:
+ *   - Solution utilization (7d match rate)      30%
+ *   - Block→ack effectiveness                   25%
+ *   - Knowledge growth (extractions this week)   20%
+ *   - Rule coverage (active rules)               15%
+ *   - Profile completeness                       10%
+ */
+export interface HealthScore {
+    total: number;
+    components: {
+        utilization: number;
+        effectiveness: number;
+        growth: number;
+        coverage: number;
+        profile: number;
+    };
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+}
+export declare function computeHealth(): HealthScore;
+export declare function handleHealth(): Promise<void>;