@wooojin/forgen 0.4.12 → 0.5.0

package/dist/hooks/solution-injector.js

@@ -12,6 +12,7 @@ import * as path from 'node:path';
 import { readStdinJSON } from './shared/read-stdin.js';
 import { isHookEnabled } from './hook-config.js';
 import { matchSolutions } from '../engine/solution-matcher.js';
+import { RELEVANCE_MATCH_GATE } from '../engine/relevance-gate.js';
 import { extractTags } from '../engine/solution-format.js';
 import { defaultNormalizer } from '../engine/term-normalizer.js';
 import { logMatchDecision } from '../engine/match-eval-log.js';
@@ -26,6 +27,7 @@ import { withFileLock, withFileLockSync, FileLockError } from './shared/file-loc
 import { calculateBudget } from './shared/context-budget.js';
 import { writeSignal } from './shared/plugin-signal.js';
 import { approve, approveWithContext, failOpenWithTracking } from './shared/hook-response.js';
+import { truncateContent } from './shared/injection-caps.js';
 import { STATE_DIR } from '../core/paths.js';
 import { recordHookTiming } from './shared/hook-timing.js';
 import { appendPending, flushAccept } from '../engine/solution-outcomes.js';
@@ -52,8 +54,11 @@ const MAX_SOLUTIONS_PER_SESSION = 10;
  * If fitness data is unavailable (fresh install, empty outcomes/),
  * every solution falls into the default 0.3 bucket — identical to the
  * pre-0.3.2 gate. No cold-start regression.
+ *
+ * W3-2 리뷰(SEV-3 #1): 0.3 리터럴을 relevance-gate.RELEVANCE_MATCH_GATE 로 단일화 —
+ * 교정 클러스터링 τ 와 같은 소스를 공유해 근거-정직성 드리프트를 코드로 방지.
  */
-export const MIN_INJECT_RELEVANCE = 0.3;
+export const MIN_INJECT_RELEVANCE = RELEVANCE_MATCH_GATE;
 export const MIN_INJECT_RELEVANCE_TRUSTED = 0.25;
 /**
  * v0.4.1 — cold-start 사용자 threshold. outcomes 이벤트가 거의 없는 신규 사용자
@@ -305,6 +310,111 @@ async function detectActOnFromPriorSurface(sessionId, promptLower) {
         log.debug('detectActOnFromPriorSurface 실패', e);
     }
 }
+// ── Progressive Disclosure tiers (claude-mem 스타일 index→summary→full 대응) ──
+//
+// forgen은 이미 Tier 3(전문)를 compound-read MCP tool로 갖고 있었다 (fs 안 읽고
+// on-demand pull). 이번 변경은 Tier 0~2 배분만 다시 나눈다: 매치가 여러 건일 때
+// 상위 랭크만 두껍게(Tier 2 요약) 주입하고, 나머지는 포인터 한 줄(Tier 1 인덱스)만
+// 준다 — claude-mem이 상위만 전개하고 나머지는 인덱스로 남겨 ~10x 토큰을 아끼는
+// 것과 같은 원리. 매치가 정확히 1건이면 굳이 요약할 필요가 없으므로 전문이
+// 작으면(Tier 0) 통째로 준다.
+//
+// 상위 몇 건이 Tier 2를 받는지 — 세션당 솔루션 수(2~3)를 감안해 1건만 두껍게 두면
+// 3건 매치 시나리오에서 인덱스 라인 2개로 대체되어 눈에 띄는 절감이 난다.
+const TOP_TIER_COUNT = 1;
+/** Tier 2(요약 블록): 헤더 + 핵심 최대 3줄. 이전 "Tier 2.5"와 동일한 예산 유지. */
+const SUMMARY_MAX_CHARS = 300;
+/**
+ * Tier 1(인덱스 라인): one-liner 부분만의 캡 — 힌트는 별도.
+ * 인덱스 라인은 의도적으로 type/confidence 헤더를 생략한다(포인터 성격 —
+ * 상세는 compound-read pull). 3건 매치 시 "1×Tier2 + N×Tier1"이 구 방식
+ * "N×Tier2" 대비 ≥50% 절감되도록 하는 예산의 핵심 변수.
+ */
+const INDEX_ONE_LINER_MAX_CHARS = 50;
+/**
+ * Tier 0(전문): 매치가 정확히 1건이고 전문(Context+Content)이 이 캡 이하일 때만
+ * 요약 대신 전문을 그대로 준다. solutionMax(1500, injection-caps.ts) 보다 낮춰
+ * 세션 누적 버짓에 여유를 남긴다.
+ */
+const FULL_TEXT_MAX_CHARS = 1200;
+/**
+ * 한 턴(UserPromptSubmit) 주입 전체의 최종 안전판. 세션 누적 캡
+ * (context-budget.ts의 solutionSessionMax, 기본 8000)과는 별개 축 — 그건
+ * "세션 전체 합"이고 이건 "이번 한 번의 additionalContext 크기" 상한이다.
+ * 매칭/렌더 로직에 버그가 생겨도 한 턴이 컨텍스트를 과점하지 못하게 막는
+ * 최후 backstop (경쟁 리포트 §5-2 기준값과 정합).
+ */
+const INJECTION_HARD_CAP_CHARS = 4000;
+/** `## Content` 섹션 본문만 추출 (없으면 빈 문자열) */
+function extractContentSection(raw) {
+    const contentMatch = raw.match(/## Content\n([\s\S]*?)(?:\n## |\n---|$)/);
+    return contentMatch ? contentMatch[1] : '';
+}
+/** 코드블록 제거 + 트림 + 빈 줄 제거된 본문 줄 목록 */
+function contentLines(raw) {
+    return extractContentSection(raw)
+        .replace(/```[\s\S]*?```/g, '')
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0);
+}
+function tierHeader(sol) {
+    return `${sol.name} [${sol.type}|${sol.confidence.toFixed(2)}]`;
+}
+/** Tier 2 — 헤더 + 태그 + 핵심 최대 3줄 (최대 SUMMARY_MAX_CHARS) */
+export function buildSummaryTier(sol, raw) {
+    let snippet = contentLines(raw).slice(0, 3).join('\n');
+    if (snippet.length > SUMMARY_MAX_CHARS) {
+        snippet = `${snippet.slice(0, SUMMARY_MAX_CHARS - 3)}...`;
+    }
+    const header = `${tierHeader(sol)}: ${sol.matchedTags.slice(0, 5).join(', ')}`;
+    return snippet ? `${header}\n  ${snippet.replace(/\n/g, '\n  ')}` : header;
+}
+/**
+ * Tier 1 — 이름 + one-liner + compound-read MCP 힌트 (전문은 pull-on-demand).
+ * type/confidence 헤더는 의도적으로 생략 — 인덱스 라인은 포인터일 뿐, 상세는
+ * compound-read로 당겨 읽는다.
+ */
+export function buildIndexTier(sol, raw) {
+    let oneLiner = contentLines(raw)[0] ?? '';
+    if (oneLiner.length > INDEX_ONE_LINER_MAX_CHARS) {
+        oneLiner = `${oneLiner.slice(0, INDEX_ONE_LINER_MAX_CHARS - 3)}...`;
+    }
+    const hint = `compound-read("${sol.name}")`;
+    return oneLiner ? `${sol.name}: ${oneLiner} — ${hint}` : `${sol.name} — ${hint}`;
+}
+/** Tier 0 — 전문(Context+Content) 그대로. 파싱 실패/캡 초과면 null (호출부가 Tier 2로 폴백). */
+export function buildFullTier(sol, raw) {
+    const parsed = parseSolutionV3(raw);
+    if (!parsed)
+        return null;
+    const body = [parsed.context, parsed.content].filter(Boolean).join('\n\n').trim();
+    if (!body || body.length > FULL_TEXT_MAX_CHARS)
+        return null;
+    const header = `${tierHeader(sol)}: ${sol.matchedTags.slice(0, 5).join(', ')}`;
+    return `${header}\n  ${body.replace(/\n/g, '\n  ')}`;
+}
+/**
+ * 매치 목록(relevance desc 정렬 가정)을 Progressive Disclosure 텍스트로 렌더한다.
+ * 순수 함수 — fs 읽기는 caller(main)가 `rawByName`으로 미리 채워 넣는다.
+ *
+ *   - 매치가 정확히 1건 & 전문이 FULL_TEXT_MAX_CHARS 이하 → Tier 0(전문)
+ *   - 그 외 상위 TOP_TIER_COUNT건 → Tier 2(요약)
+ *   - 나머지 → Tier 1(인덱스 라인)
+ */
+export function renderSolutionTiers(sols, rawByName) {
+    const rendered = new Map();
+    const singleFullEligible = sols.length === 1;
+    sols.forEach((sol, rank) => {
+        const raw = rawByName.get(sol.name) ?? '';
+        if (singleFullEligible) {
+            rendered.set(sol.name, buildFullTier(sol, raw) ?? buildSummaryTier(sol, raw));
+            return;
+        }
+        rendered.set(sol.name, rank < TOP_TIER_COUNT ? buildSummaryTier(sol, raw) : buildIndexTier(sol, raw));
+    });
+    return rendered;
+}
 async function main() {
     const _hookStart = Date.now();
     try {
@@ -463,36 +573,21 @@ async function main() {
             if (toInject.length >= Math.min(budget.solutionsPerPrompt, MAX_SOLUTIONS_PER_SESSION - injected.size))
                 break;
         }
-        // Progressive Disclosure Tier 2.5: 핵심 요약 push (이름+태그+본문 핵심 3줄)
-        // 이전 Tier 2(이름+태그만)는 반영률 0% → Claude가 행동 가능한 정보 부족
-        // 토큰 예산: 솔루션당 최대 300자, 3개 제한 → 최대 ~900자
-        const SUMMARY_MAX_CHARS = 300;
-        const summaries = new Map();
-        const candidateEntries = [];
+        // Progressive Disclosure: 매치 랭크에 따라 Tier 0(전문)/2(요약)/1(인덱스)로 나눠 렌더.
+        // rank 순서는 toInject 자체(matchSolutions/applyRoiDemotions가 이미 relevance desc
+        // 정렬해 반환) — 여기서 별도 재정렬하지 않는다.
+        const rawByName = new Map();
         for (const sol of toInject) {
-            let contentSnippet = '';
             try {
-                const raw = fs.readFileSync(sol.path, 'utf-8');
-                const contentMatch = raw.match(/## Content\n([\s\S]*?)(?:\n## |\n---|$)/);
-                if (contentMatch) {
-                    // 코드 블록 제거 후 핵심 텍스트만 추출, 최대 3줄
-                    const lines = contentMatch[1]
-                        .replace(/```[\s\S]*?```/g, '')
-                        .split('\n')
-                        .map(l => l.trim())
-                        .filter(l => l.length > 0);
-                    contentSnippet = lines.slice(0, 3).join('\n');
-                    if (contentSnippet.length > SUMMARY_MAX_CHARS) {
-                        contentSnippet = `${contentSnippet.slice(0, SUMMARY_MAX_CHARS - 3)}...`;
-                    }
-                }
+                rawByName.set(sol.name, fs.readFileSync(sol.path, 'utf-8'));
             }
-            catch { /* fail-open: 파일 읽기 실패 시 이름+태그만 사용 */ }
-            const header = `${sol.name} [${sol.type}|${sol.confidence.toFixed(2)}]: ${sol.matchedTags.slice(0, 5).join(', ')}`;
-            const summary = contentSnippet ? `${header}\n  ${contentSnippet.replace(/\n/g, '\n  ')}` : header;
-            summaries.set(sol.name, summary);
-            candidateEntries.push({ name: sol.name, chars: summary.length });
+            catch { /* fail-open: 파일 읽기 실패 시 이름+태그만으로 렌더 */ }
         }
+        const summaries = renderSolutionTiers(toInject, rawByName);
+        const candidateEntries = toInject.map(sol => ({
+            name: sol.name,
+            chars: (summaries.get(sol.name) ?? sol.name).length,
+        }));
         // H-1 + M-3 fix: lock 안 disjoint 검증으로 새로 추가된 entry만 반환받는다.
         // 다른 hook이 같은 sessionId로 동시에 같은 솔루션을 inject했다면 이 hook의
         // commit에서는 newlyAdded에 포함되지 않아 evidence 중복 카운트가 차단된다.
@@ -593,7 +688,10 @@ async function main() {
         }).join('\n');
         const header = `Matched solutions (apply these patterns to your response):\n`;
         const footer = `\n\nAPPLY the patterns above to your response. If a pattern is directly relevant, follow its guidance. Use compound-read MCP tool for full details if needed.\nWhen using Grep or Bash, always set head_limit or pipe through | head -n to limit output size.`;
-        const fullInjection = header + injections + footer;
+        // 최종 안전판: 위 tier 배분이 어떤 조합이든 이 턴의 additionalContext는
+        // INJECTION_HARD_CAP_CHARS를 넘지 않는다 (context-budget.ts의 세션 누적
+        // 캡과는 별도 축 — 이건 "한 턴" 상한).
+        const fullInjection = truncateContent(header + injections + footer, INJECTION_HARD_CAP_CHARS);
         // 플러그인 시그널 기록 (다른 플러그인이 참고할 수 있도록)
         try {
             writeSignal(sessionId, 'UserPromptSubmit', fullInjection.length);

package/dist/hooks/stop-guard.js

@@ -25,6 +25,7 @@ import { readStdinJSON } from './shared/read-stdin.js';
 import { approve, approveWithWarning, blockStop, failOpenWithTracking } from './shared/hook-response.js';
 import { takeLastExtractionNotice } from '../core/extraction-notice.js';
 import { runMetaGuards } from '../checks/_shared/meta-guard-dispatch.js';
+import { guardModeForModel, readSessionModel } from '../checks/_shared/model-profile.js';
 import { sanitizeForGuard } from '../checks/_shared/text-sanitizer.js';
 import { STATE_DIR } from '../core/paths.js';
 import { sanitizeId } from './shared/sanitize-id.js';
@@ -507,7 +508,9 @@ export async function main() {
         if (process.env.FORGEN_USER_CONFIRMED !== '1') {
             const sessionId = input?.session_id ?? 'unknown';
             const recentTools = loadRecentToolNames(sessionId);
-            const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1 });
+            // W4-3: 세션 모델 기반 완료-가드 모드 (opus-4.8 실측 blocks=0 → advise)
+            const completionGuardMode = guardModeForModel(readSessionModel(sanitizeId(sessionId)));
+            const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1, completionGuardMode });
             for (const r of results) {
                 recordViolation({
                     rule_id: `builtin:${r.shortId}`,
@@ -564,7 +567,7 @@ export async function main() {
         // pre-tool-use 와 일관된 FORGEN_USER_CONFIRMED=1 탈출구 + 영구 비활성화 CLI 노출.
         const reasonWithHint = `[forgen:stop-guard/${hit.id.slice(0, 8)}] ${reason}
 
-(Override this turn: set FORGEN_USER_CONFIRMED=1 (audited). Disable rule permanently: \`forgen suppress-rule ${hit.id}\`. See recent blocks: \`forgen last-block\`.)`;
+(Override this turn: set FORGEN_USER_CONFIRMED=1 (audited). Disable rule permanently: \`forgen suppress-rule ${hit.id}\`. See recent blocks: \`forgen status --blocks\`.)`;
         const count = incrementBlockCount(sessionId, hit.id);
         const threshold = getStuckLoopThreshold();
         if (count > threshold) {

package/dist/hooks/subagent-stop-guard.js

@@ -27,6 +27,7 @@ import { sanitizeId } from './shared/sanitize-id.js';
 import { recordHookTiming } from './shared/hook-timing.js';
 import { STATE_DIR } from '../core/paths.js';
 import { runMetaGuards } from '../checks/_shared/meta-guard-dispatch.js';
+import { guardModeForModel, readSessionModel } from '../checks/_shared/model-profile.js';
 import { recordViolation } from '../engine/lifecycle/signals.js';
 import { incrementBlockCount, resetBlockCount, getStuckLoopThreshold, logDriftEvent, } from './stop-guard.js';
 const HOOK_NAME = 'subagent-stop-guard';
@@ -108,7 +109,9 @@ export async function main() {
         const sessionId = input?.session_id ?? 'unknown';
         const agentId = input?.agent_id ?? input?.agentId ?? 'unknown';
         const recentTools = loadAgentRecentTools(sessionId, agentId);
-        const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1 });
+        // W4-3: 세션 모델 기반 완료-가드 모드 (opus-4.8 실측 blocks=0 → advise)
+        const completionGuardMode = guardModeForModel(readSessionModel(sanitizeId(sessionId)));
+        const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1, completionGuardMode });
         // 2c: stuck-loop 카운터를 (sessionId, agentId) 로 분리해 동시 subagent 간 충돌 방지.
         const counterKey = `${sessionId}:${agentId}`;
         for (const r of results) {

package/dist/host/capabilities-claude.js

@@ -6,6 +6,7 @@
  */
 export const claudeCapabilities = {
     hostId: 'claude',
+    verificationLevel: 'runtime', // 레퍼런스 host — forgen 이 실제로 강제/실행.
     intents: {
         'block-completion': {
             status: 'supported',

package/dist/host/capabilities-codex.js

@@ -9,6 +9,7 @@
  */
 export const codexCapabilities = {
     hostId: 'codex',
+    verificationLevel: 'source', // hook schema 소스 검증 + forgen 배선 완료.
     intents: {
         'block-completion': {
             status: 'supported',

package/dist/host/capabilities-opencode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OpenCode HostCapabilities — Multi-Harness Adapter Plan P1
+ * (`reports/harness-probe/adapter-plan-2026-07-20.md` §2.2 / §3.1).
+ *
+ * ⚠️ 검증 수준(정직): verificationLevel='docs' 유지. OpenCode plugin 문서 + context7
+ * 실소스 대조(`/anomalyco/opencode`: tool.execute.before(input.tool, output.args), throw=block
+ * 확인). codex 의 로컬-schema source-level 과는 다른 축.
+ *
+ * 2026-07-22 **런타임 부분 검증(opencode v1.1.8, 격리 XDG)**: `forgen install opencode` 배포 후
+ *   - plugin(`plugins/forgen.ts`) **로드 성공**(service=plugin loading plugin, 에러 없음),
+ *   - MCP(`mcp.forgen-compound`) **등록 + 9 tools** 로드 성공(toolCount=9).
+ *   미검증: tool.execute.before 발화(guard block) end-to-end 는 model API 필요(격리 세션에서
+ *   401 Missing API key 로 model 단계 미도달) → verificationLevel='docs' 유지가 정직.
+ *   plugin-load + MCP 는 runtime-confirmed, guard-firing 은 model-backed 세션 테스트 대기.
+ *
+ * OpenCode 통합 형태는 Claude/Codex 와 다르다: subprocess-stdin hook 이 아니라
+ * **in-process TypeScript plugin**(`.opencode/plugins/`, 25+ 이벤트, tool.execute.before
+ * throw-to-block). 이 형태 차이 때문에 P1 은 plugin 슬림이 최대 신규 델타(plan §5 blocker 1).
+ *
+ * 근거 소스:
+ *   - OpenCode plugins docs: https://opencode.ai/docs/plugins/
+ *   - plan §2.2 (tool.execute.before throw, session.idle, experimental.session.compacting,
+ *     tui.prompt.append, opencode.jsonc MCP, message.updated/session.* event stream)
+ */
+import type { HostCapabilities } from '../core/trust-layer-intent.js';
+export declare const opencodeCapabilities: HostCapabilities;

package/dist/host/capabilities-opencode.js

@@ -0,0 +1,78 @@
+/**
+ * OpenCode HostCapabilities — Multi-Harness Adapter Plan P1
+ * (`reports/harness-probe/adapter-plan-2026-07-20.md` §2.2 / §3.1).
+ *
+ * ⚠️ 검증 수준(정직): verificationLevel='docs' 유지. OpenCode plugin 문서 + context7
+ * 실소스 대조(`/anomalyco/opencode`: tool.execute.before(input.tool, output.args), throw=block
+ * 확인). codex 의 로컬-schema source-level 과는 다른 축.
+ *
+ * 2026-07-22 **런타임 부분 검증(opencode v1.1.8, 격리 XDG)**: `forgen install opencode` 배포 후
+ *   - plugin(`plugins/forgen.ts`) **로드 성공**(service=plugin loading plugin, 에러 없음),
+ *   - MCP(`mcp.forgen-compound`) **등록 + 9 tools** 로드 성공(toolCount=9).
+ *   미검증: tool.execute.before 발화(guard block) end-to-end 는 model API 필요(격리 세션에서
+ *   401 Missing API key 로 model 단계 미도달) → verificationLevel='docs' 유지가 정직.
+ *   plugin-load + MCP 는 runtime-confirmed, guard-firing 은 model-backed 세션 테스트 대기.
+ *
+ * OpenCode 통합 형태는 Claude/Codex 와 다르다: subprocess-stdin hook 이 아니라
+ * **in-process TypeScript plugin**(`.opencode/plugins/`, 25+ 이벤트, tool.execute.before
+ * throw-to-block). 이 형태 차이 때문에 P1 은 plugin 슬림이 최대 신규 델타(plan §5 blocker 1).
+ *
+ * 근거 소스:
+ *   - OpenCode plugins docs: https://opencode.ai/docs/plugins/
+ *   - plan §2.2 (tool.execute.before throw, session.idle, experimental.session.compacting,
+ *     tui.prompt.append, opencode.jsonc MCP, message.updated/session.* event stream)
+ */
+export const opencodeCapabilities = {
+    hostId: 'opencode',
+    // docs-level: OpenCode 문서 기반 선언, forgen 배선 미완(plugin 슬림 전). 아래 status 의
+    // supported 는 "플랫폼 가능"이지 "forgen 강제"가 아니다 — intentEnforced 로 게이트할 것.
+    verificationLevel: 'docs',
+    intents: {
+        'block-completion': {
+            // session.idle 는 발화하나 "완료 강제 차단/재-turn" 계약이 문서에 없다.
+            status: 'unsupported',
+            expression: 'session.idle 이벤트는 관측 가능하나 force-continue 표면 부재 → advise-only',
+            mitigation: 'ADR-010 F1(frontier blocks=0)과 동일한 advise-mode: tui.toast.show 로 사용자에게 표면화하되 하드 차단은 주장하지 않는다. (model,harness)→policy 축으로 advise 처리.',
+            source: 'plan §2.2/§3.1 — OpenCode docs 에 완료 방지 API 미문서화. Cursor 와 동일 한계.',
+        },
+        'block-tool-use': {
+            // tool.execute.before 에서 throw 하면 *모든* tool 차단 (Cursor 의 shell/MCP/read 한정보다 강함).
+            status: 'supported',
+            expression: 'plugin `tool.execute.before` 훅에서 throw → 해당 tool 실행 차단(전 tool 대상)',
+            source: 'https://opencode.ai/docs/plugins/ — docs 예시가 .env read 를 tool.execute.before throw 로 차단. plan §2.2.',
+        },
+        'inject-context': {
+            // experimental.session.compacting(output.context/prompt) + tui.prompt.append/session.created.
+            status: 'partial',
+            expression: 'experimental.session.compacting 로 output.context/prompt 수정 + tui.prompt.append/session.created 로 주입',
+            mitigation: 'experimental 표면이라 안정성 미보장 — 안정 계약 확정 전까지 정적 룰(AGENTS.md/.opencode) 폴백을 1차로 유지하고 동적 주입은 best-effort.',
+            source: 'plan §2.2 — experimental.session.compacting / tui.prompt.append (less-stable surface).',
+        },
+        'observe-only': {
+            // 이벤트 스트림(message.updated/session.*) → observer log. host 무관 stdout.
+            status: 'supported',
+            expression: 'message.updated/session.* 이벤트 스트림 → observer log (denyOrObserve 는 host 무관 stdout)',
+            source: 'plan §2.2 event stream; forgen denyOrObserve 는 stdout JSON 만 다뤄 host 무관.',
+        },
+        'secret-filter': {
+            // tool.execute.before(pre-block) + tool.execute.after(post-redact). pre 가드가 1차.
+            status: 'supported',
+            expression: 'tool.execute.before 로 자격증명 tool 입력 차단(pre) + tool.execute.after 로 결과 redact(post)',
+            mitigation: 'Claude 와 동일하게 PreToolUse 등가(tool.execute.before) 가드가 1차 방어. post-redact 는 after 훅으로 보강.',
+            source: 'plan §3.1 — OpenCode 는 pre+post 둘 다 표면 보유(Codex 의 post-only partial 보다 강함).',
+        },
+        'forge-loop-state-inject': {
+            // inject-context 와 동일 표면(experimental) — ≤1KB forge-loop-state.
+            status: 'partial',
+            expression: '<forge-loop-state> ≤1KB 를 tui.prompt.append/session.created 로 주입(experimental 표면 공유)',
+            mitigation: 'inject-context 와 동일한 experimental 한계 — 안정 계약 전까지 best-effort.',
+            source: 'plan §2.2/§3.1 — inject-context 와 같은 표면 재사용.',
+        },
+        'self-evidence-record': {
+            // 이벤트 스트림 캡처 → ~/.forgen/state/*.json, host:"opencode" 태그.
+            status: 'supported',
+            expression: 'session.*/message.updated 캡처 → ~/.forgen/state/*.json (host 무관). evidence 에 host:"opencode" 태그.',
+            source: 'plan §2.2 event stream — file-transcript polling 보다 richer. spec §4.2 host-tagged evidence.',
+        },
+    },
+};

package/dist/host/capabilities-registry.d.ts

@@ -9,3 +9,10 @@ import { type HostCapabilities, type HostId, type TrustLayerIntent } from '../co
 export declare function getHostCapabilities(host: HostId): HostCapabilities;
 export declare function listRegisteredHosts(): readonly HostId[];
 export declare function intentSupported(host: HostId, intent: TrustLayerIntent): boolean;
+/**
+ * "forgen 이 이 host 에서 이 의도를 *실제로 강제/실행* 하는가" (W3-3 리뷰 SEV-3 #1).
+ * intentSupported 와 달리 verificationLevel 을 게이트한다 — 'docs'(플랫폼-가능하나 미배선,
+ * 예: opencode P1)는 supported 여도 false. 프로그램 소비자가 "선언"과 "실배선"을 혼동하지
+ * 않도록 하는 정직 게이트.
+ */
+export declare function intentEnforced(host: HostId, intent: TrustLayerIntent): boolean;

package/dist/host/capabilities-registry.js

@@ -8,9 +8,11 @@
 import { assertCapabilitiesComplete, } from '../core/trust-layer-intent.js';
 import { claudeCapabilities } from './capabilities-claude.js';
 import { codexCapabilities } from './capabilities-codex.js';
+import { opencodeCapabilities } from './capabilities-opencode.js';
 const REGISTRY = new Map([
     [claudeCapabilities.hostId, claudeCapabilities],
     [codexCapabilities.hostId, codexCapabilities],
+    [opencodeCapabilities.hostId, opencodeCapabilities],
 ]);
 // 모듈 로드 시점 자기 검증 — 하나라도 미선언이면 즉시 throw.
 for (const caps of REGISTRY.values()) {
@@ -28,3 +30,15 @@ export function listRegisteredHosts() {
 export function intentSupported(host, intent) {
     return getHostCapabilities(host).intents[intent].status === 'supported';
 }
+/**
+ * "forgen 이 이 host 에서 이 의도를 *실제로 강제/실행* 하는가" (W3-3 리뷰 SEV-3 #1).
+ * intentSupported 와 달리 verificationLevel 을 게이트한다 — 'docs'(플랫폼-가능하나 미배선,
+ * 예: opencode P1)는 supported 여도 false. 프로그램 소비자가 "선언"과 "실배선"을 혼동하지
+ * 않도록 하는 정직 게이트.
+ */
+export function intentEnforced(host, intent) {
+    const caps = getHostCapabilities(host);
+    if (caps.verificationLevel === 'docs')
+        return false;
+    return caps.intents[intent].status === 'supported';
+}

package/dist/host/exec-host.d.ts

@@ -9,6 +9,7 @@
  * 호환성: 기존 'claude -p prompt --model haiku' 호출은 default_host 가 'claude' 인
  * 경우 동일 동작. Codex 메인 사용자는 자동으로 codex exec --json 호출.
  */
+import type { HostId } from '../core/trust-layer-intent.js';
 export interface ExecHostOptions {
     /** prompt — `-p`/`exec` 의 본문 */
     prompt: string;
@@ -19,7 +20,7 @@ export interface ExecHostOptions {
     /** working directory */
     cwd?: string;
     /** explicit host override (default: profile.default_host). */
-    host?: 'claude' | 'codex';
+    host?: HostId;
     /** ENV vars 추가 (기존 process.env 위에 머지) */
     env?: NodeJS.ProcessEnv;
 }
@@ -30,10 +31,10 @@ export interface ExecHostOptions {
  *     30s default 가 false-positive ETIMEDOUT 발생. 90s 마진 필요.
  *   - 명시 timeout 옵션은 그대로 우선.
  */
-export declare const DEFAULT_TIMEOUT_BY_HOST: Record<'claude' | 'codex', number>;
+export declare const DEFAULT_TIMEOUT_BY_HOST: Record<HostId, number>;
 export interface ExecHostResult {
     message: string;
-    host: 'claude' | 'codex';
+    host: HostId;
     /** 토큰 사용량 (codex 만 노출. claude 는 null). */
     usage: {
         input_tokens?: number;

package/dist/host/exec-host.js

@@ -22,6 +22,8 @@ import { parseCodexJsonlOutput } from './codex-output-parser.js';
 export const DEFAULT_TIMEOUT_BY_HOST = {
     claude: 30_000,
     codex: 90_000,
+    // opencode headless CLI: reasoning-mode 응답이 codex 처럼 길 수 있어 넉넉히(P1 실측 후 조정).
+    opencode: 90_000,
 };
 /**
  * 실 host CLI 를 호출하여 prompt 응답 받기.

package/dist/host/host-binding.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HostBinding — Multi-Harness Adapter Plan P0 (`reports/harness-probe/adapter-plan-2026-07-20.md` §4.1)
+ *
+ * `prepareHarness` 의 host if-ladder (`harness.ts:447-479`) 를 formalize 한 계약.
+ * 각 host 는 capabilities 선언(`capabilities-registry.ts`) + projection 함수(`projection.ts`) +
+ * 세션 준비 단계(hook-surface wiring, 구 if-ladder 분기)를 하나의 등록 단위로 묶는다.
+ *
+ * `Record<HostId, HostBinding>` 완전성 요구로, 새 host 를 `HostId` 에 추가하면 registry
+ * 엔트리 누락이 컴파일 타임에 걸린다 (§4.2 P1 OpenCode 확장의 전제 조건).
+ */
+import type { HostCapabilities, HostId } from '../core/trust-layer-intent.js';
+import type { ProjectToClaudeEvent } from './projection.js';
+import type { V1BootstrapResult } from '../core/v1-bootstrap.js';
+/** `prepareHarness` 가 host-specific 세션 준비 단계에 넘기는 컨텍스트. */
+export interface HarnessSessionContext {
+    readonly cwd: string;
+    readonly pkgRoot: string;
+    readonly env: Record<string, string>;
+    readonly v1Result: V1BootstrapResult;
+}
+export interface HostBinding {
+    readonly id: HostId;
+    readonly capabilities: HostCapabilities;
+    readonly projection: ProjectToClaudeEvent;
+    /** harness.ts 의 host-specific artifact 준비 단계 (구 if-ladder 분기 대체). */
+    prepareSession(ctx: HarnessSessionContext): Promise<void>;
+}

package/dist/host/host-binding.js

@@ -0,0 +1,11 @@
+/**
+ * HostBinding — Multi-Harness Adapter Plan P0 (`reports/harness-probe/adapter-plan-2026-07-20.md` §4.1)
+ *
+ * `prepareHarness` 의 host if-ladder (`harness.ts:447-479`) 를 formalize 한 계약.
+ * 각 host 는 capabilities 선언(`capabilities-registry.ts`) + projection 함수(`projection.ts`) +
+ * 세션 준비 단계(hook-surface wiring, 구 if-ladder 분기)를 하나의 등록 단위로 묶는다.
+ *
+ * `Record<HostId, HostBinding>` 완전성 요구로, 새 host 를 `HostId` 에 추가하면 registry
+ * 엔트리 누락이 컴파일 타임에 걸린다 (§4.2 P1 OpenCode 확장의 전제 조건).
+ */
+export {};

package/dist/host/host-runtime.js

@@ -41,9 +41,27 @@ const codexRuntime = {
     hookInjectionStrategy: 'generate',
     dangerousSkipFlag: '--dangerously-bypass-approvals-and-sandbox',
 };
+/**
+ * OpenCode runtime — P1 파운데이션 스텁. OpenCode 는 subprocess-hook 이 아니라 in-process
+ * plugin 형태라(plan §2.2), hook wrapping 은 plugin 슬림(`install-opencode` 미구현)이 담당한다.
+ * launcher(headless `opencode` CLI)와 라벨만 실값; wrapHookCommand 는 슬림 착지 전까지 fail-loud.
+ */
+const opencodeRuntime = {
+    id: 'opencode',
+    displayName: 'OpenCode',
+    launcher: 'opencode',
+    missingInstallMessage: 'OpenCode is not installed.',
+    wrapHookCommand() {
+        throw new Error('[forgen] OpenCode hook wrapping은 in-process plugin 슬림(install-opencode)이 담당합니다 — P1 미구현.');
+    },
+    // in-process plugin 이라 subprocess hook 생성 전략과 무관. 슬림 착지 시 재정의.
+    hookInjectionStrategy: 'generate',
+    dangerousSkipFlag: '',
+};
 const RUNTIMES = {
     claude: claudeRuntime,
     codex: codexRuntime,
+    opencode: opencodeRuntime,
 };
 export function getHostRuntime(runtime) {
     const r = RUNTIMES[runtime];

package/dist/host/install-codex.d.ts

@@ -46,3 +46,11 @@ export interface CodexInstallResult {
     devGuideSkillsRemoved: number;
 }
 export declare function planCodexInstall(opts: CodexInstallOptions): CodexInstallResult;
+export declare function resolveAgentsMdPath(_pkgRoot: string): string;
+export declare function upsertForgenRulesInAgentsMd(opts: {
+    agentsMdPath: string;
+    pkgRoot: string;
+    dryRun: boolean;
+}): {
+    injected: boolean;
+};

package/dist/host/install-codex.js

@@ -273,7 +273,7 @@ function installCodexSkills(opts) {
     return { installed: count };
 }
 // ── P3-3: AGENTS.md inject ────────────────────────────────────────────
-function resolveAgentsMdPath(_pkgRoot) {
+export function resolveAgentsMdPath(_pkgRoot) {
     // Phase 3 critic fix: pkgRoot 기반 walk-up 은 `npm install -g` 시 시스템 디렉토리
     // (예: /usr/local/lib/node_modules/forgen) 에 fallback AGENTS.md 작성 위험.
     // *cwd 기반* 으로 변경 — 사용자 작업 디렉토리의 git root, 없으면 cwd 자체.
@@ -313,7 +313,7 @@ function buildForgenRulesBlock(pkgRoot) {
     ];
     return lines.join('\n');
 }
-function upsertForgenRulesInAgentsMd(opts) {
+export function upsertForgenRulesInAgentsMd(opts) {
     const { agentsMdPath, pkgRoot, dryRun } = opts;
     const block = buildForgenRulesBlock(pkgRoot);
     let current = '';

package/dist/host/install-opencode.d.ts

@@ -0,0 +1,38 @@
+/**
+ * install-opencode — forgen 을 OpenCode host 에 설치 (W3-3 P1).
+ *
+ * OpenCode 는 in-process TS plugin + opencode.json(c) MCP + AGENTS.md 를 쓴다:
+ *   1. plugin: `~/.config/opencode/plugins/forgen.ts` (assets/opencode/forgen.ts 배포).
+ *      GUARD_CMD 는 절대 forgen CLI 경로로 치환(런타임 PATH 비의존 — 리뷰 MED4).
+ *   2. MCP: 기존 config 파일(opencode.jsonc 우선, 없으면 opencode.json)에 mcp.forgen-compound
+ *      surgical 병합. **JSONC 파서(jsonc-parser)로 주석/trailing-comma 보존**, 쓰기 전 백업
+ *      (리뷰 HIGH: JSON.parse 가 공식 JSONC 를 clobber 하던 데이터 손실 수정).
+ *   3. AGENTS.md: cwd 의 forgen rules block (Codex 헬퍼 재사용).
+ */
+export interface OpencodeInstallOptions {
+    pkgRoot: string;
+    dryRun?: boolean;
+    registerMcp?: boolean;
+    /** ~/.config/opencode override (격리 테스트용). */
+    opencodeConfigDir?: string;
+    /** AGENTS.md 위치 override (격리 테스트용). */
+    agentsMdPath?: string;
+}
+export interface OpencodeInstallResult {
+    configDir: string;
+    pluginPath: string;
+    pluginInstalled: boolean;
+    /** 사용자 소유(비-managed) plugin 을 백업했으면 그 경로. */
+    pluginBackupPath?: string;
+    mcpRegistered: boolean;
+    mcpAlreadyPresent: boolean;
+    /** MCP 대상 config 파일(.jsonc 우선). */
+    mcpConfigPath: string;
+    /** 파싱 불가 config 라 MCP 를 건드리지 않고 abort 했으면 true(데이터 손실 방지). */
+    mcpSkippedUnparseable: boolean;
+    /** config 백업 경로(수정 전 .bak). */
+    mcpBackupPath?: string;
+    agentsMdInjected: boolean;
+}
+export declare function resolveOpencodeConfigDir(opts: OpencodeInstallOptions): string;
+export declare function planOpencodeInstall(opts: OpencodeInstallOptions): OpencodeInstallResult;