@wooojin/forgen 0.4.10 → 0.4.12

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).',
@@ -579,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)
@@ -593,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.');
@@ -565,6 +589,20 @@ export async function runDoctor(opts = {}) {
         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/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>;

package/dist/core/health-cli.js

@@ -0,0 +1,86 @@
+/**
+ * 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%
+ */
+import { computeStats } from './stats-cli.js';
+const isTTY = process.stdout.isTTY;
+const C = {
+    reset: isTTY ? '\x1b[0m' : '',
+    bold: isTTY ? '\x1b[1m' : '',
+    dim: isTTY ? '\x1b[2m' : '',
+    green: isTTY ? '\x1b[32m' : '',
+    yellow: isTTY ? '\x1b[33m' : '',
+    red: isTTY ? '\x1b[31m' : '',
+    cyan: isTTY ? '\x1b[36m' : '',
+};
+export function computeHealth() {
+    const s = computeStats();
+    // 1. Utilization (30%): % of solutions matched in last 7d, capped at 100%
+    const utilization = Math.min(1, s.solutionHealth.utilization7d) * 30;
+    // 2. Effectiveness (25%): if blocks happened, what % were acknowledged
+    let effectiveness;
+    if (s.blocks7d === 0) {
+        effectiveness = 25; // no blocks = no problems
+    }
+    else {
+        effectiveness = (s.acks7d / s.blocks7d) * 25;
+    }
+    // 3. Growth (20%): extractions this week (1 extraction = 10pts, cap at 20)
+    const growth = Math.min(20, s.weeklyTrend.extractionsThisWeek * 10);
+    // 4. Coverage (15%): active rules (1 rule = 3pts, cap at 15)
+    const coverage = Math.min(15, s.activeRules * 3);
+    // 5. Profile (10%): has profile + has philosophy + axis scores populated
+    let profile = 0;
+    if (s.philosophy) {
+        profile += 4; // profile exists
+        if (s.philosophy.basePacks.length > 0)
+            profile += 3;
+        if (Object.keys(s.philosophy.axisScores).length >= 4)
+            profile += 3;
+    }
+    const total = Math.round(utilization + effectiveness + growth + coverage + profile);
+    const grade = total >= 80 ? 'A' : total >= 60 ? 'B' : total >= 40 ? 'C' : total >= 20 ? 'D' : 'F';
+    return {
+        total,
+        components: {
+            utilization: Math.round(utilization),
+            effectiveness: Math.round(effectiveness),
+            growth: Math.round(growth),
+            coverage: Math.round(coverage),
+            profile: Math.round(profile),
+        },
+        grade,
+    };
+}
+function gradeColor(grade) {
+    if (grade === 'A')
+        return C.green;
+    if (grade === 'B')
+        return C.cyan;
+    if (grade === 'C')
+        return C.yellow;
+    return C.red;
+}
+function bar(value, max, width = 10) {
+    const filled = Math.round((value / max) * width);
+    return '█'.repeat(Math.max(0, filled)) + '░'.repeat(Math.max(0, width - filled));
+}
+export async function handleHealth() {
+    const h = computeHealth();
+    const gc = gradeColor(h.grade);
+    console.log('');
+    console.log(`  ${C.bold}forgen health${C.reset}  ${gc}${C.bold}${h.grade}${C.reset}  ${gc}${h.total}/100${C.reset}`);
+    console.log('');
+    console.log(`    Utilization    ${bar(h.components.utilization, 30)}  ${h.components.utilization}/30   ${C.dim}solution match rate (7d)${C.reset}`);
+    console.log(`    Effectiveness  ${bar(h.components.effectiveness, 25)}  ${h.components.effectiveness}/25   ${C.dim}block→ack ratio${C.reset}`);
+    console.log(`    Growth         ${bar(h.components.growth, 20)}  ${h.components.growth}/20   ${C.dim}extractions this week${C.reset}`);
+    console.log(`    Coverage       ${bar(h.components.coverage, 15)}  ${h.components.coverage}/15   ${C.dim}active rules${C.reset}`);
+    console.log(`    Profile        ${bar(h.components.profile, 10)}  ${h.components.profile}/10   ${C.dim}personalization depth${C.reset}`);
+    console.log('');
+}

package/dist/core/probe-workflow-cli.d.ts

@@ -0,0 +1,72 @@
+/**
+ * forgen probe-workflow — ADR-009 §1 결정적 미확인 변수 실측 도구.
+ *
+ * 질문: dynamic workflow **내부** 에이전트에 대해 SubagentStart/Stop·PostToolUse
+ *       훅이 발화하는가? (워크플로우 런타임은 "대화와 분리된 격리 백그라운드"로
+ *       명시되어 있어 발화 여부가 문서로 미확인.)
+ *
+ * 이 답이 ADR-009 §2(훅 라우트로 워크플로우까지 검증 가능) vs §3(워크플로우
+ * 품질은 템플릿 라우트로만 도달)의 선택을 가른다. forgen 프로젝트 룰상 가정
+ * 위에 §2 를 구현할 수 없으므로, 실제 실행 증거를 먼저 수집한다.
+ *
+ * 신호원 (훅이 부작용으로 남기는 state 파일 — forgen 자체 timing 계측의 공백과
+ * 무관하게 직접 관측 가능):
+ *   - SubagentStart/Stop → ~/.forgen/state/active-agents-*.json (agents[])
+ *   - PostToolUse        → ~/.forgen/state/modified-files-*.json (mtime)
+ *   - (보조) hook-timing.jsonl 의 event 별 엔트리
+ *
+ * 절차 (2단계 — 런타임이 격리되어 있어 단일 프로세스로는 트리거 불가):
+ *   1. `forgen probe-workflow arm`    → baseline 마커 기록 + 안내 출력
+ *   2. 사용자가 Claude Code 에서 워크플로우 1회 실행 (그 사이 다른 작업 금지)
+ *   3. `forgen probe-workflow report` → baseline 이후 신호 수집 → verdict 박제
+ *
+ * 가정 (detailed-communication): arm~report 사이에 사용자가 **워크플로우만**
+ * 실행했다고 전제한다. 일반 Task-tool subagent 를 같이 돌리면 신호가 섞인다.
+ */
+export interface ProbeBaseline {
+    armedAtMs: number;
+    armedIso: string;
+}
+export interface AgentObservation {
+    agentId: string;
+    agentType?: string;
+    model?: string;
+    startedAtMs: number;
+    stoppedAtMs?: number;
+}
+export interface ProbeObservations {
+    agents: AgentObservation[];
+    /** baseline 이후 modified-files-*.json 이 갱신됨 (PostToolUse 발화 신호). */
+    postToolUseFired: boolean;
+    /** hook-timing.jsonl 에서 baseline 이후 관측된 event 이름들. */
+    hookEvents: string[];
+}
+export type ProbeOutcome = 'workflow-hooks-fire' | 'workflow-hooks-absent' | 'inconclusive';
+export interface ProbeVerdict {
+    subagentStartStopFired: boolean;
+    postToolUseFired: boolean;
+    agentCount: number;
+    maxConcurrency: number;
+    agentTypes: string[];
+    outcome: ProbeOutcome;
+    recommendation: string;
+}
+/**
+ * 구간 [start, stop) 들의 최대 동시 겹침 수. stoppedAt 미지정(진행 중) 은 +∞ 로 간주.
+ * sweep-line: start 이벤트 +1, stop 이벤트 -1 을 시간순 정렬 후 누적 최대.
+ * 동일 시각에서는 start(+1) 를 stop(-1) 보다 먼저 처리해 겹침을 과소평가하지 않는다.
+ */
+export declare function maxConcurrency(agents: AgentObservation[]): number;
+/**
+ * Pure core — baseline + 관측치 → verdict. IO 없음 (단위 테스트 대상).
+ *
+ * 판정:
+ *   - 에이전트 0 → 'workflow-hooks-absent' (단 "워크플로우를 실제로 띄웠는가"
+ *     확인 전제 — recommendation 에 명시). §2 는 워크플로우 내부에 도달 못 함.
+ *   - 에이전트 >0 → 'workflow-hooks-fire'. 동시 ≥11 이면 워크플로우 강한 신호.
+ *     §2(SubagentStop 검증)가 워크플로우까지 커버 가능.
+ */
+export declare function analyzeProbe(obs: ProbeObservations): ProbeVerdict;
+/** baseline 이후 신호 수집 (IO 셸). */
+export declare function collectObservations(baselineMs: number): ProbeObservations;
+export declare function handleProbeWorkflow(args: string[]): Promise<void>;