elanous 0.2.34 → 0.2.36

package/src/loops/msg-wake.ts

@@ -5,7 +5,8 @@
 //   sse        — 아무것도 안 한다(구독자가 이미 듣는다)
 //   cron       — 다음 틱에 읽는다 · `wake-deferred` 로그만
 //   pty-inject — elanous TUI(pty 별명 = 자리 소문자)가 턴 idle 일 때만 한 줄 주입
-//   herdr      — 자리 폴더 `herdr.pane` 의 pane 이 agent_status=idle 일 때만 한 줄 주입
+//   herdr      — 자리 폴더 `herdr.pane` 의 pane 이 idle(·done) 일 때만 한 줄 주입 — `eln herdr prompt` 와 같은 생산 함수
+//                (`herdrPrompt` · `agent get` 상태 확인 → bracketed `pane run` 한 번). working/blocked 는 넣지 않고 busy.
 //   none       — stderr 경고 한 줄 · 해석 실패는 «모름»으로 남긴다(«없다»로 위장 금지)
 // ⛔ 우편은 입력칸에 넣지 않는다(대표 10-15 01:20) — 기본은 입력칸 주입 0. 10-15 01:10 사고: 대표 가 치던 문장에
 //    깨움 한 줄 ⊕ Enter 가 섞여 제출됐다(«에이전트 idle ≠ 사람이 안 친다»). 자리 폴더에서 푼 대상(pty 별명·
@@ -20,7 +21,6 @@
 //    상한(시도 3 · 2시간) → `gave-up`. 관측 = `loops.msg-wake` deferred | redelivered | gave-up.
 //    재두드림 «전»에 그 주소 미읽음을 잰다 — 0 이면 두드리지 않고 줄을 지운다(`dropped-read` · H4-FOLLOW ③).
 
-import { spawn } from 'node:child_process';
 import { Database } from 'bun:sqlite';
 import { randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs';
@@ -30,6 +30,7 @@ import { dirname, join } from 'node:path';
 import { debug } from '../debug/log.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
 import { readUnreadCount } from '../msg/msg-store.js';
+import { herdrPrompt, type HerdrCliRunner } from '../pty-shell/herdr-prompt.js';
 import { listPtyManifestRows } from '../pty-shell/pty-manifest.js';
 import { messageRouteFor, type MessageWake } from './msg-address.js';
 
@@ -75,8 +76,8 @@ export interface WakeDeps {
   hasOptIn?: (path: string) => boolean;
   /** Loads the pty writer (the CLI module is heavy, so it is imported only when a pty wake is due). */
   ptyInjector?: () => Promise<(ptyId: string, line: string) => Promise<void>>;
-  herdrStatus?: (paneId: string, signal: AbortSignal) => Promise<string>;
-  herdrInject?: (paneId: string, line: string, signal: AbortSignal) => Promise<void>;
+  /** The herdr CLI runner `herdrPrompt` drives (`agent get` · `pane run`). Default: the real `herdr` (HERDR_BIN_PATH · PATH). */
+  herdrRun?: HerdrCliRunner;
   warn?: (line: string) => void;
   /** Unread count for an address before a deferred re-knock (H4-FOLLOW ③). null = «모름» (never drops). Default: the msg ledger. */
   readUnread?: (address: string) => number | null;
@@ -178,29 +179,6 @@ function releaseClaim(claim: WakeClaim): void {
   } catch { /* a stale claim only delays the next wake by one window */ }
 }
 
-function run(cmd: string, args: string[], timeoutMs: number, signal: AbortSignal): Promise<string> {
-  return new Promise((resolve, reject) => {
-    if (signal.aborted) { reject(new Error(`${cmd} aborted`)); return; }
-    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], signal });
-    let out = '';
-    const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error(`${cmd} timeout`)); }, timeoutMs);
-    child.stdout.on('data', chunk => { out += String(chunk); });
-    child.on('error', error => { clearTimeout(timer); reject(error); });
-    child.on('close', code => { clearTimeout(timer); code === 0 ? resolve(out) : reject(new Error(`${cmd} exit ${code}`)); });
-  });
-}
-
-async function defaultHerdrStatus(paneId: string, signal: AbortSignal): Promise<string> {
-  const parsed = JSON.parse(await run('herdr', ['pane', 'get', paneId], WAKE_TIMEOUT_MS, signal)) as { result?: { pane?: { agent_status?: unknown } } };
-  const status = parsed.result?.pane?.agent_status;
-  return typeof status === 'string' ? status : 'unknown';
-}
-
-async function defaultHerdrInject(paneId: string, line: string, signal: AbortSignal): Promise<void> {
-  // `pane run` = send-text ⊕ Enter 한 번에.
-  await run('herdr', ['pane', 'run', paneId, line], WAKE_TIMEOUT_MS, signal);
-}
-
 async function defaultPtyInjector(): Promise<(ptyId: string, line: string) => Promise<void>> {
   const { runPtyText } = await import('../cli/pty-takeover-cli.js');
   return async (ptyId, line) => {
@@ -261,17 +239,35 @@ export async function wakeRecipient(address: string, msgId: number, message: { f
         injecting = true;
         await inject(resolution.target!, line);
       } else {
-        const status = await (deps.herdrStatus ?? defaultHerdrStatus)(resolution.target!, controller.signal);
-        if (status !== 'idle') return done('busy', `agent_status=${status}`);
-        // 조회 사이 자리의 pane 이 바뀌었으면 옛 pane 에 넣지 않는다 — 주소→대상을 다시 푼다.
-        const again = resolveWake(address, deps);
-        // opt-in 은 주입 직전에 «먼저» 다시 본다 — 기다리는 사이 `wake-inject` 를 지웠으면(대상이 바뀌었어도) 주입 0.
-        if (!seatOptedIn(address, deps)) { resolution = { ...resolution, optIn: false }; return done('skipped', 'human-pane-no-opt-in'); }
-        if (again.wake !== 'herdr' || again.target !== resolution.target) return done('busy', `target-moved:${again.target ?? again.wake}`);
-        // ⛔ 마감은 «주입 바로 앞»에서 — 재해석이 늦어 넘겼어도 새 주입 0.
-        if (expired()) return done('timeout');
-        injecting = true;
-        await (deps.herdrInject ?? defaultHerdrInject)(resolution.target!, line, controller.signal);
+        // `eln herdr prompt` 와 같은 생산 함수 — 상태 확인(idle·done 만) → 제출 앞 관문 → bracketed `pane run` 한 번.
+        // 라벨은 묻지 않는다(anyAgent): 자리 폴더가 이미 대상을 정했고, claude/codex pane 도 예전처럼 깨운다.
+        const target = resolution.target!;
+        const prompted = await herdrPrompt({ target, text: line, anyAgent: true, paneFallback: true, timeoutMs: Math.max(1, deadline - Date.now()) }, {
+          ...(deps.herdrRun ? { run: deps.herdrRun } : {}),
+          beforeSubmit: () => {
+            // opt-in 은 주입 직전에 «먼저» 다시 본다 — 기다리는 사이 `wake-inject` 를 지웠으면(대상이 바뀌었어도) 주입 0.
+            if (!seatOptedIn(address, deps)) { resolution = { ...resolution, optIn: false }; return 'human-pane-no-opt-in'; }
+            // 조회 사이 자리의 pane 이 바뀌었으면 옛 pane 에 넣지 않는다 — 주소→대상을 다시 푼다.
+            const again = resolveWake(address, deps);
+            if (again.wake !== 'herdr' || again.target !== target) return `target-moved:${again.target ?? again.wake}`;
+            // ⛔ 마감은 «주입 바로 앞»에서 — 재해석이 늦어 넘겼어도 새 주입 0.
+            if (expired()) return 'timeout';
+            injecting = true;
+            return undefined;
+          },
+        });
+        if (!prompted.accepted) injecting = false;
+        const reason = prompted.reason;
+        const result: WakeResult = reason === 'submitted' ? 'injected'
+          : reason === 'human-pane-no-opt-in' ? 'skipped'
+            : reason === 'timeout' ? 'timeout'
+              : reason.startsWith('target-moved:') || reason === 'agent_working' || reason === 'agent_blocked' || reason === 'agent_unknown' ? 'busy'
+                : 'failed';
+        const outReason = result === 'busy' && !reason.startsWith('target-moved:') ? `agent_status=${prompted.status ?? 'unknown'}`
+          : result === 'injected' || result === 'timeout' ? undefined : reason;
+        logPending('herdr-prompt', { seat: address.trim().toUpperCase(), msgId, target, result, accepted: prompted.accepted, reason,
+          ...(prompted.status ? { status: prompted.status } : {}), ...(prompted.agent ? { agent: prompted.agent } : {}), ms: prompted.ms });
+        if (result !== 'injected') return done(result, outReason);
       }
       return done('injected');
     } catch (error) {
@@ -309,7 +305,7 @@ export async function wakeRecipient(address: string, msgId: number, message: { f
 
 interface PendingWakeRow { address: string; first_msg_id: number; last_msg_id: number; last_from: string; count: number; since: number; attempts: number; reason: string }
 
-export type PendingWakeEvent = 'deferred' | 'redelivered' | 'gave-up' | 'dropped-read' | 'skip';
+export type PendingWakeEvent = 'deferred' | 'redelivered' | 'gave-up' | 'dropped-read' | 'skip' | 'herdr-prompt';
 
 function logPending(event: PendingWakeEvent, data: Record<string, unknown>): void {
   try { debug.log('loops.msg-wake', event, data); } catch { /* observability is fail-open */ }

package/src/loops/orchestrator/inbox.ts

@@ -3,6 +3,7 @@ import { classifySeatTrafficProposal } from '../../seat-loop/traffic-signal.js';
 import { debug } from '../../debug/log.js';
 import { LOOP_MESSAGE_ROUTES } from '../msg-address.js';
 import { replyWithAgent, type AgentReplyInput } from '../agent-reply.js';
+import { knowhowAdvice, type KnowhowAdvice, type KnowhowOptions } from './knowhow-pack.js';
 import type { RoleLlmSpec } from '../../user-config.js';
 import type { LLMProvider } from '../../llm.js';
 
@@ -28,18 +29,59 @@ function trafficProposal(request: Message): 'hold' | 'UNHOLD' | null {
     ? null : classifySeatTrafficProposal(request.body);
 }
 
-/** This loop suggests traffic moves; it never changes traffic.json. */
-export function coordinatorReply(request: Message): string {
+export interface CoordinatorInboxOptions {
+  /** `false` disables the resident knowhow pack (traffic rule only). */
+  knowhow?: KnowhowOptions | false;
+}
+
+const NO_LOCK_LINE = '실제 잠금 변경은 수행하지 않았습니다.';
+
+function flatten(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/** Propose a resident K item: cite the pack, the item id and the measurement it was judged by. */
+function knowhowProposal(advice: KnowhowAdvice): { proposal: string; evidence: string } {
+  const cite = `${advice.packVersion} 팩 ${advice.packHash} · ${advice.item.id} «${advice.item.title}»`;
+  const measurement = `재는 명령: \`${advice.item.command}\` → ${advice.detail}`;
+  if (advice.freshness === 'stale') {
+    return {
+      proposal: `모름 — 노하우 낡음 의심 (${advice.item.id})`,
+      evidence: `${cite} · ${measurement} — 기대와 어긋나 처방을 제안하지 않습니다. OP 가 항목을 갱신해야 합니다.`,
+    };
+  }
+  const freshness = advice.freshness === 'confirmed' ? '기대 일치'
+    : advice.freshness === 'unverifiable' ? '기대 문면 — 사람 확인' : '재지 못함 — 사람 확인';
+  return {
+    proposal: `${advice.item.id} — ${flatten(advice.item.prescription, 240)}`,
+    evidence: `${cite} · ${measurement} (${freshness}) — 제안만 하고 어떤 쓰기도 하지 않습니다.`,
+  };
+}
+
+/** This loop suggests traffic moves and quotes knowhow; it never changes traffic.json or the ledgers. */
+export function coordinatorReply(request: Message, knowhow: KnowhowOptions | false = {}): string {
   const traffic = trafficProposal(request);
-  const proposal = traffic === 'hold' ? 'hold 제안' : traffic === 'UNHOLD' ? 'UNHOLD 제안' : '모름 — OP/자리 판단 필요';
-  const evidence = traffic === 'hold' ? '자리 메시지에 «손 구현 착수»가 있습니다.'
-    : traffic === 'UNHOLD' ? '자리 메시지에 «첫 줄 확정»이 있습니다.'
-      : '착수·첫 줄 확정을 확정 진술로 확인하지 못했습니다. 칸·traffic 근거를 사람이 확인해야 합니다.';
-  return `re #${request.id}\n제안: ${proposal}\n근거: ${evidence}\n실제 잠금 변경은 수행하지 않았습니다.`;
+  if (traffic !== null) {
+    const proposal = traffic === 'hold' ? 'hold 제안' : 'UNHOLD 제안';
+    const evidence = traffic === 'hold' ? '자리 메시지에 «손 구현 착수»가 있습니다.'
+      : '자리 메시지에 «첫 줄 확정»이 있습니다.';
+    return `re #${request.id}\n제안: ${proposal}\n근거: ${evidence}\n${NO_LOCK_LINE}`;
+  }
+  const advice = knowhow === false ? null : knowhowAdvice(request.body, knowhow);
+  if (advice) {
+    const { proposal, evidence } = knowhowProposal(advice);
+    return `re #${request.id}\n제안: ${proposal}\n근거: ${evidence}\n${NO_LOCK_LINE}`;
+  }
+  const candidate = flatten(request.body, 200);
+  debug.log('loop.coordinator-knowhow', 'candidate', { requestId: request.id, from: request.from, question: candidate });
+  return `re #${request.id}\n제안: 모름 — OP/자리 판단 필요\n근거: 착수·첫 줄 확정을 확정 진술로 확인하지 못했고, `
+    + `맞는 K-OP 노하우 항목도 없습니다. 칸·traffic 근거를 사람이 확인해야 합니다.\n`
+    + `노하우 후보: ${candidate} — 새 K-OP 항목의 입력으로 쓸 수 있습니다.\n${NO_LOCK_LINE}`;
 }
 
 /** Single reply writer: prefer the durable thread link, while recognizing pre-migration body markers. */
-function writeCoordinatorReply(store: MsgStore, request: Message): { id: number; posted: boolean } {
+function writeCoordinatorReply(store: MsgStore, request: Message, replyText: string): { id: number; posted: boolean } {
   const marker = `re #${request.id}`;
   const linked = store.db.query(`SELECT id FROM msg_messages WHERE sender = ? AND recipient = ?
     AND reply_to = ? AND kind = 'reply' ORDER BY id LIMIT 1`).get(RECIPIENT, request.from, request.id) as { id: number } | null;
@@ -49,12 +91,14 @@ function writeCoordinatorReply(store: MsgStore, request: Message): { id: number;
     .get(RECIPIENT, request.from, marker, marker.length + 1, `${marker}\n`) as { id: number } | null;
   if (legacy) return { id: legacy.id, posted: false };
   const reply = store.post({ from: RECIPIENT, to: request.from,
-    body: coordinatorReply(request).slice(marker.length + 1), kind: 'reply', replyTo: request.id });
+    body: replyText.slice(marker.length + 1), kind: 'reply', replyTo: request.id });
   return { id: reply.id, posted: true };
 }
 
 /** One transaction ties a reply to its acknowledgement. A retry finds the durable receipt. */
-export function runCoordinatorInbox(inputStore?: MsgStore, limit = 100, path?: string): CoordinatorInboxResult {
+export function runCoordinatorInbox(inputStore?: MsgStore, limit = 100, path?: string,
+  options: CoordinatorInboxOptions = {}): CoordinatorInboxResult {
+  const knowhow = options.knowhow ?? {};
   const store = inputStore ?? openMsgStore(path);
   const ownStore = inputStore === undefined;
   let replied = 0;
@@ -70,10 +114,14 @@ export function runCoordinatorInbox(inputStore?: MsgStore, limit = 100, path?: s
         continue;
       }
       const key = `coord-inbox:${request.id}:${request.from}`;
+      // Measurement runs outside the write transaction: a pack command never holds the ledger lock.
+      const known = store.db.query('SELECT message_id FROM msg_provenance WHERE provenance_key = ?')
+        .get(key) as { message_id: number } | null;
+      const replyText = known ? '' : coordinatorReply(request, knowhow);
       const result = store.db.transaction(() => {
         const existing = store.db.query('SELECT message_id FROM msg_provenance WHERE provenance_key = ?')
           .get(key) as { message_id: number } | null;
-        const reply = existing ? { id: existing.message_id, posted: false } : writeCoordinatorReply(store, request);
+        const reply = existing ? { id: existing.message_id, posted: false } : writeCoordinatorReply(store, request, replyText);
         if (!existing) store.db.query('INSERT INTO msg_provenance(provenance_key, message_id) VALUES (?, ?)').run(key, reply.id);
         store.ack(RECIPIENT, request.id);
         return { posted: reply.posted };

package/src/loops/orchestrator/knowhow-pack.ts

@@ -0,0 +1,364 @@
+/**
+ * K3 knowledge pack — the coordinator reads OP knowhow from `내부 문서 `KNOWHOW``
+ * on every tick, so a doc landing alone (no code deploy) refreshes what is resident.
+ *
+ * A pack holds only items whose `상태:` is `active` **and** that carry a `재는 명령:`;
+ * every item is ordered by id and the pack carries a content hash so a reply can cite
+ * exactly which pack it read.
+ *
+ * The inbox may then *propose* an item's 처방 — it never writes, and it never changes a lock.
+ * A measurement command is executed only when it passes the read-only allowlist; when its
+ * output contradicts the item's `기대`, the advice is stale and the inbox answers 모름.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { debug } from '../../debug/log.js';
+
+export const KNOWHOW_PACK_VERSION = 'K3';
+export const KNOWHOW_DOC_RELATIVE_PATH = 'docs/roles/OP/KNOWHOW.md';
+
+export interface KnowhowItem {
+  id: string;
+  title: string;
+  status: string;
+  situation: string;
+  signal: string;
+  prescription: string;
+  command: string;
+  expectation: string;
+  validWhen: string;
+  source: string;
+}
+
+export interface KnowhowPack {
+  version: string;
+  hash: string;
+  docPath: string;
+  items: KnowhowItem[];
+}
+
+export interface KnowhowCommandRun {
+  status: number;
+  output: string;
+  /** Set when the runner refused to execute (placeholder, timeout, spawn failure). */
+  skipped?: string;
+}
+
+export type KnowhowCommandRunner = (command: string) => KnowhowCommandRun;
+
+export interface KnowhowOptions {
+  /** Explicit doc path; otherwise `ELANOUS_KNOWHOW_DOC`, otherwise the repository copy. */
+  docPath?: string;
+  /** Working directory for measurement commands. */
+  cwd?: string;
+  /** Measurement seam: replaced by tests, defaults to the guarded read-only runner. */
+  runCommand?: KnowhowCommandRunner;
+}
+
+export type KnowhowFreshness = 'confirmed' | 'stale' | 'unmeasured' | 'unverifiable';
+
+export interface KnowhowMatch {
+  item: KnowhowItem;
+  score: number;
+  matchedTokens: string[];
+}
+
+export interface KnowhowAdvice extends KnowhowMatch {
+  packVersion: string;
+  packHash: string;
+  freshness: KnowhowFreshness;
+  detail: string;
+}
+
+/** Label → item field. Labels keep their parenthetical form when the doc uses one. */
+const FIELD_LABELS: Array<[RegExp, keyof KnowhowItem]> = [
+  [/^상황$/i, 'situation'],
+  [/^신호(?:\(관측\))?$/i, 'signal'],
+  [/^처방(?:\(힐링\))?$/i, 'prescription'],
+  [/^재는 명령$/i, 'command'],
+  [/^기대$/i, 'expectation'],
+  [/^유효 조건$/i, 'validWhen'],
+  [/^출처$/i, 'source'],
+];
+
+function stripTicks(value: string): string {
+  const trimmed = value.trim();
+  const match = /^`([\s\S]*)`$/.exec(trimmed);
+  return match ? match[1]!.trim() : trimmed;
+}
+
+function labeledLine(section: string, field: keyof KnowhowItem): string {
+  for (const line of section.split('\n')) {
+    const entry = /^-\s+([^:]{1,24}):\s*(.+)$/.exec(line.trim());
+    if (!entry) continue;
+    const label = entry[1]!.trim();
+    if (FIELD_LABELS.some(([pattern, name]) => name === field && pattern.test(label))) return stripTicks(entry[2]!);
+  }
+  return '';
+}
+
+/** Split the markdown inventory into K items. Unknown labels are ignored, not fatal. */
+export function parseKnowhowDoc(text: string): KnowhowItem[] {
+  const sections = text.split(/^## /m).slice(1);
+  const items: KnowhowItem[] = [];
+  for (const section of sections) {
+    const heading = /^(K-OP-(?:[A-Z]{1,4}-)?\d+)\s+(.*)$/.exec(section.split('\n', 1)[0] ?? '');
+    if (!heading) continue;
+    const item: KnowhowItem = {
+      id: heading[1]!, title: heading[2]!.trim(), status: '', situation: labeledLine(section, 'situation'),
+      signal: labeledLine(section, 'signal'), prescription: labeledLine(section, 'prescription'),
+      command: labeledLine(section, 'command'), expectation: labeledLine(section, 'expectation'),
+      validWhen: labeledLine(section, 'validWhen'), source: labeledLine(section, 'source'),
+    };
+    const status = /상태:\s*([A-Za-z][A-Za-z-]*)/.exec(item.source);
+    if (status) item.status = status[1]!;
+    if (item.status !== 'active') continue;
+    if (!item.command || /^\(없음/.test(item.command)) continue;
+    items.push(item);
+  }
+  return items.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function buildKnowhowPack(items: KnowhowItem[], docPath: string): KnowhowPack {
+  const body = items.map(item => [item.id, item.title, item.situation, item.signal, item.prescription,
+    item.command, item.expectation].join('\n')).join('\n---\n');
+  const hash = createHash('sha256').update(`${KNOWHOW_PACK_VERSION}\n${body}`).digest('hex').slice(0, 16);
+  return { version: KNOWHOW_PACK_VERSION, hash, docPath, items };
+}
+
+/** Marker text for a command that still carries `<...>` placeholders from the doc. */
+const PLACEHOLDER_SOURCE = '<[^<>\\n]{1,60}>';
+const PLACEHOLDER = new RegExp(PLACEHOLDER_SOURCE, 'g');
+
+function repositoryRoot(): string | null {
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 8; depth++) {
+    if (existsSync(join(current, KNOWHOW_DOC_RELATIVE_PATH))) return current;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+export function resolveKnowhowDocPath(explicit?: string): string | null {
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const fromEnv = process.env.ELANOUS_KNOWHOW_DOC;
+  if (fromEnv) return existsSync(fromEnv) ? fromEnv : null;
+  if (existsSync(join(process.cwd(), KNOWHOW_DOC_RELATIVE_PATH))) return join(process.cwd(), KNOWHOW_DOC_RELATIVE_PATH);
+  const root = repositoryRoot();
+  return root ? join(root, KNOWHOW_DOC_RELATIVE_PATH) : null;
+}
+
+const packCache = new Map<string, { stamp: string; pack: KnowhowPack }>();
+
+/** Resident pack for one tick: re-read whenever the doc's mtime/size changes. */
+export function loadKnowhowPack(docPath: string): KnowhowPack | null {
+  if (!existsSync(docPath)) return null;
+  let stamp: string;
+  try {
+    const info = statSync(docPath);
+    stamp = `${info.mtimeMs}:${info.size}`;
+  } catch { return null; }
+  const cached = packCache.get(docPath);
+  if (cached && cached.stamp === stamp) return cached.pack;
+  const pack = buildKnowhowPack(parseKnowhowDoc(readFileSync(docPath, 'utf8')), docPath);
+  packCache.set(docPath, { stamp, pack });
+  debug.log('loop.knowhow-pack', 'load', { version: pack.version, hash: pack.hash,
+    items: pack.items.length, docPath });
+  return pack;
+}
+
+const STOPWORDS = new Set(['그리고', '그러나', '하지만', '그러면', '어떻게', '무엇', '뭐가', '뭘', '이거', '그거',
+  '저거', '지금', '오늘', '내일', '확인', '요청', '질문', '경우', '때문', '때는', '먼저', '다시', '대한', '위해',
+  '에서', '으로', '하는', '하지', '한다', '있다', '없다', '같다', '되는', '되나', '됐다', '있나', '인가', '무슨',
+  '어느', '이런', '그런', '저런', '좀', '더', '또는', '그게', '이게', '저게', '합니까', '인지', '하는데',
+  '보다', '라며', '해도', '하면', '해서', '부터', '까지', '아직', '이미', '모두', '이후', '이전', '동안',
+  'the', 'and', 'for', 'you', 'can', 'this', 'that', 'what', 'which', 'how', 'why', 'when', 'with', 'from',
+  'are', 'was', 'were', 'has', 'have', 'had', 'not', 'but', 'all', 'any', 'our', 'your', 'its', 'it', 'is',
+  'of', 'to', 'in', 'on', 'do', 'does', 'did', 'please', 'anyone']);
+
+const KOREAN_SUFFIXES = ['에서부터', '으로부터', '에서는', '으로는', '이었습니다', '했습니다', '됩니다', '됐습니다',
+  '합니까', '했나요', '되나요', '인가요', '에서', '으로', '부터', '까지', '했나', '됐나', '되나', '했지', '하지',
+  '됐다', '한다', '된다', '이다', '있다', '없다', '었던', '였던', '라는', '이라', '거나', '면서', '지만',
+  '에게', '한테', '보다', '처럼', '만큼', '라고', '하고', '해도', '하면', '인데', '나요', '가요', '세요',
+  '은', '는', '을', '를', '이', '가', '의', '에', '와', '과', '로', '도', '만', '라', '며', '서', '나', '고', '면'];
+
+function normalizeToken(raw: string): string {
+  let token = raw.toLowerCase();
+  for (const suffix of KOREAN_SUFFIXES) {
+    if (token.length > suffix.length + 1 && token.endsWith(suffix)) {
+      token = token.slice(0, -suffix.length);
+      break;
+    }
+  }
+  return token;
+}
+
+function tokenize(text: string): string[] {
+  const tokens: string[] = [];
+  for (const raw of text.toLowerCase().split(/[^0-9a-z가-힣-]+/)) {
+    const token = normalizeToken(raw);
+    if (token.length < 2 || STOPWORDS.has(raw) || STOPWORDS.has(token)) continue;
+    if (/^\d+$/.test(token)) continue;
+    tokens.push(token);
+  }
+  return tokens;
+}
+
+function tokensMatch(a: string, b: string): boolean {
+  if (a === b) return true;
+  if (a.length >= 3 && b.length >= 3 && (a.startsWith(b) || b.startsWith(a))) return true;
+  return false;
+}
+
+const MIN_MATCH_SCORE = 2.2;
+const MIN_MATCH_TOKENS = 2;
+
+/**
+ * Match a question against the pack item text (title ⊕ 상황 ⊕ 신호) using inverse document
+ * frequency, so a word shared by most items ("착지", "PR") cannot carry a match alone.
+ */
+export function matchKnowhowItem(pack: KnowhowPack, question: string, minScore = MIN_MATCH_SCORE): KnowhowMatch | null {
+  const questionTokens = [...new Set(tokenize(question))];
+  if (questionTokens.length === 0 || pack.items.length === 0) return null;
+  const itemTokens = pack.items.map(item => [...new Set(tokenize(`${item.title} ${item.situation} ${item.signal}`))]);
+  const total = pack.items.length;
+  const scored = pack.items.map((item, index) => {
+    const matched: string[] = [];
+    let score = 0;
+    for (const token of questionTokens) {
+      const hits = itemTokens.filter(tokens => tokens.some(candidate => tokensMatch(token, candidate))).length;
+      if (hits === 0 || !itemTokens[index]!.some(candidate => tokensMatch(token, candidate))) continue;
+      matched.push(token);
+      score += Math.log((total + 1) / (hits + 0.5));
+    }
+    return { item, score: Number(score.toFixed(3)), matchedTokens: matched };
+  }).sort((a, b) => b.score - a.score || a.item.id.localeCompare(b.item.id));
+  const best = scored[0];
+  if (!best || best.matchedTokens.length < MIN_MATCH_TOKENS || best.score < minScore) return null;
+  return best;
+}
+
+const READ_ONLY_BINARIES = new Set(['rg', 'grep', 'cat', 'head', 'tail', 'wc', 'ls', 'jq', 'awk', 'find',
+  'sort', 'uniq', 'cut', 'echo', 'pwd', 'stat', 'file', 'date', 'printf', 'true', 'test']);
+const GIT_READ_ONLY_SUBCOMMANDS = new Set(['status', 'log', 'show', 'diff', 'rev-parse', 'rev-list',
+  'ls-files', 'ls-tree', 'worktree', 'shortlog', 'blame', 'describe', 'branch', 'tag', 'remote', 'config', 'cat-file']);
+const GIT_WRITE_ARGS = new Set(['-d', '-D', '-m', '-M', '--delete', '--move', '--force', '--set', '--unset',
+  '--add', '--edit', '--prune', 'add', 'commit', 'push', 'merge', 'reset', 'checkout', 'switch', 'clean',
+  'rm', 'mv', 'apply', 'stash', 'gc', 'update-ref', 'submodule', 'rebase', 'cherry-pick', 'revert']);
+const ELANOUSH_READ_ONLY: Record<string, string[] | null> = {
+  logs: null, 'tasks:show': null, 'tasks:list': null,
+  release: ['checklist'], decisions: ['list'], msg: ['list'], memory: ['list'],
+};
+
+export type ReadOnlyVerdict = { ok: true } | { ok: false; reason: string };
+
+/** Allowlist guard: only commands that cannot mutate the repository or the ledgers run. */
+export function isReadOnlyCommand(command: string): ReadOnlyVerdict {
+  const stripped = command.replace(PLACEHOLDER, ' ');
+  if (!stripped.trim()) return { ok: false, reason: 'empty command' };
+  if (/[<>`$]|[;\n]/.test(stripped)) return { ok: false, reason: 'shell redirect, substitution or sequence' };
+  const segments = stripped.split(/\s*(?:&&|\|\||\||&)\s*/).map(part => part.trim()).filter(Boolean);
+  if (segments.length === 0) return { ok: false, reason: 'empty command' };
+  for (const segment of segments) {
+    const words = segment.split(/\s+/);
+    const binary = words[0]!.replace(/^.*\//, '');
+    const args = words.slice(1);
+    if (binary === 'git') {
+      const sub = args.find(word => !word.startsWith('-'));
+      if (!sub) return { ok: false, reason: 'git without subcommand' };
+      if (!GIT_READ_ONLY_SUBCOMMANDS.has(sub)) return { ok: false, reason: `git ${sub} is not read-only` };
+      if (args.some(word => GIT_WRITE_ARGS.has(word))) return { ok: false, reason: `git ${sub} write flag` };
+      continue;
+    }
+    if (binary === 'eln' || binary === 'elanous') {
+      const verbs = args.filter(word => !word.startsWith('-'));
+      const [first, second, third] = verbs;
+      // `eln tasks show` and `eln release checklist status` name the verb in two words.
+      if (first && second && `${first}:${second}` in ELANOUSH_READ_ONLY) {
+        const allowed = ELANOUSH_READ_ONLY[`${first}:${second}`];
+        if (allowed && (!third || !allowed.includes(third))) {
+          return { ok: false, reason: `${binary} ${first} ${second} ${third ?? ''} is not read-only` };
+        }
+        continue;
+      }
+      if (!first || !(first in ELANOUSH_READ_ONLY)) return { ok: false, reason: `${binary} ${first ?? ''} is not read-only` };
+      const allowed = ELANOUSH_READ_ONLY[first];
+      if (allowed && (!second || !allowed.includes(second))) return { ok: false, reason: `${binary} ${first} ${second ?? ''} is not read-only` };
+      continue;
+    }
+    if (!READ_ONLY_BINARIES.has(binary)) return { ok: false, reason: `${binary} is not on the read-only allowlist` };
+  }
+  return { ok: true };
+}
+
+export type ExpectationVerdict = 'confirmed' | 'stale' | 'unverifiable';
+
+/**
+ * Compare a measurement output against the item's 기대. Only machine-checkable wordings
+ * are judged: `N 줄/건/개` (exact count) and `≥N` / `N 이상` (lower bound).
+ */
+export function evaluateExpectation(expectation: string, output: string): { verdict: ExpectationVerdict; detail: string } {
+  const lines = output.split('\n').map(line => line.trim()).filter(line => line.length > 0);
+  const counted = /(\d+)\s*(줄|행|건|개|line)/.exec(expectation);
+  if (counted) {
+    const expected = Number(counted[1]);
+    const ok = lines.length === expected;
+    return { verdict: ok ? 'confirmed' : 'stale', detail: `기대 ${expected}${counted[2]} · 실제 ${lines.length}줄` };
+  }
+  const lower = /(?:[≥>=]\s*(\d+))|(?:(\d+)\s*이상)/.exec(expectation);
+  if (lower) {
+    const expected = Number(lower[1] ?? lower[2]);
+    const numbers = (output.match(/\d+/g) ?? []).map(Number);
+    const ok = numbers.length > 0 && numbers.every(value => value >= expected);
+    return { verdict: ok ? 'confirmed' : 'stale',
+      detail: `기대 ≥${expected} · 실제 ${numbers.length > 0 ? numbers.join(',') : '(수 없음)'}` };
+  }
+  if (!lines.length) return { verdict: 'stale', detail: '기대 비교 불가 · 재는 명령 출력이 비었다' };
+  return { verdict: 'unverifiable', detail: `기대 문면: ${expectation.slice(0, 120)} — 자동 비교 규칙 없음` };
+}
+
+/** Default runner: guarded, bounded, and never shells a doc placeholder. */
+export function readOnlyRunner(cwd: string): KnowhowCommandRunner {
+  return (command: string): KnowhowCommandRun => {
+    const verdict = isReadOnlyCommand(command);
+    if (!verdict.ok) return { status: -1, output: '', skipped: verdict.reason };
+    if (new RegExp(PLACEHOLDER_SOURCE).test(command)) return { status: -1, output: '', skipped: 'placeholder 미치환' };
+    const run = spawnSync('bash', ['-c', command], { cwd, encoding: 'utf8', timeout: 15_000, maxBuffer: 1 << 20 });
+    if (run.error) return { status: -1, output: '', skipped: run.error.message.slice(0, 120) };
+    return { status: run.status ?? -1, output: `${run.stdout ?? ''}${run.stderr ?? ''}` };
+  };
+}
+
+export function measureKnowhowItem(
+  item: KnowhowItem, run: KnowhowCommandRunner,
+): { freshness: KnowhowFreshness; detail: string } {
+  const verdict = isReadOnlyCommand(item.command);
+  if (!verdict.ok) return { freshness: 'unmeasured', detail: `재지 못함 — ${verdict.reason} (읽기 전용 허용 목록 밖)` };
+  const result = run(item.command);
+  if (result.skipped) return { freshness: 'unmeasured', detail: `재지 못함 — ${result.skipped}` };
+  if (result.status !== 0) return { freshness: 'unmeasured', detail: `재지 못함 — rc=${result.status}` };
+  const judged = evaluateExpectation(item.expectation, result.output);
+  return { freshness: judged.verdict, detail: judged.detail };
+}
+
+/** The advice the inbox may propose: item ⊕ pack identity ⊕ freshness of its measurement. */
+export function knowhowAdvice(question: string, options: KnowhowOptions = {}): KnowhowAdvice | null {
+  const docPath = resolveKnowhowDocPath(options.docPath);
+  if (!docPath) return null;
+  const pack = loadKnowhowPack(docPath);
+  if (!pack) return null;
+  const match = matchKnowhowItem(pack, question);
+  if (!match) return null;
+  const run = options.runCommand ?? readOnlyRunner(options.cwd ?? process.cwd());
+  const measured = measureKnowhowItem(match.item, run);
+  const advice: KnowhowAdvice = { ...match, packVersion: pack.version, packHash: pack.hash,
+    freshness: measured.freshness, detail: measured.detail };
+  debug.log('loop.knowhow-pack', 'advice', { id: match.item.id, score: match.score,
+    freshness: advice.freshness, packHash: pack.hash });
+  return advice;
+}

package/src/loops/orchestrator/tick.ts

@@ -24,6 +24,7 @@ import { seatCapDetails } from '../budget.js';
 export { isLaunchEligible } from './traffic.js';
 import { readTaskAgentState, TASK_SEATS, type HandTaskOptions, type TaskCard as TaskAgentCard, type HandTaskResult, type TaskLauncher, type TaskSeat } from '../../task-agent/task-hand.js';
 import { runCoordinatorAgentInbox, runCoordinatorInbox, type CoordinatorInboxResult } from './inbox.js';
+import type { KnowhowOptions } from './knowhow-pack.js';
 import { loadAgentRolePack, type AgentReplyInput } from '../agent-reply.js';
 import type { LLMProvider } from '../../llm.js';
 
@@ -90,6 +91,8 @@ export interface TickDeps {
   /** Production still uses the restricted turn; tests can supply a deterministic turn. */
   coordinatorAgentRun?: AgentReplyInput['runAgent'];
   coordinatorAgentProvider?: LLMProvider;
+  /** Resident knowhow pack seam; the real intake reads 내부 문서 `KNOWHOW` every tick. */
+  coordinatorKnowhow?: KnowhowOptions | false;
 }
 
 /** ORCH-TA-HAND ledger — one row per handed `orch:<card>:<cell>` key so a cell is handed once across ticks and processes. */
@@ -498,7 +501,8 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
         ? runCoordinatorAgentInbox({ role, pack: loadAgentRolePack('coordinator'), path: inboxPath, root,
             ...(deps.coordinatorAgentRun ? { runAgent: deps.coordinatorAgentRun } : {}),
             ...(deps.coordinatorAgentProvider ? { provider: deps.coordinatorAgentProvider } : {}) })
-        : runCoordinatorInbox(undefined, 100, inboxPath);
+        : runCoordinatorInbox(undefined, 100, inboxPath,
+          deps.coordinatorKnowhow === undefined ? {} : { knowhow: deps.coordinatorKnowhow });
     }))();
     if (inbox.replied || inbox.acknowledged) {
       observe('exchange', 'coordinator-inbox-replied', inbox.replied);

package/src/maturity/feature-maturity.ts

@@ -62,7 +62,7 @@ export const FEATURE_MATURITY = {
     preview: 'beta', pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta', image: 'beta', 'agent-env': 'beta',
     where: 'stable', bench: 'beta', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
     pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
-    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', freeze: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', freeze: 'beta', herdr: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
     control: 'beta', resources: 'beta', hooks: 'beta', setup: 'stable', start: 'stable',
     grounding: 'beta', graph: 'beta', loop: 'stable', resource: 'beta', card: 'stable', 'launch-head': 'beta',
     a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',