elanous 0.2.35 → 0.2.37

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

@@ -11,12 +11,14 @@ import { getUserConfig, ORCHESTRATOR_DEFAULTS, resolveConfiguredAgentRoleLlm, ty
 import { rubricPriority } from '../../release-loop/rubric.js';
 import { debug } from '../../debug/log.js';
 import { emitLoopHeartbeat } from '../neighbor-runtime.js';
+import { ConsensusEngine } from '../consensus.js';
 import { listSelfDevRuns, runSummaryLine, selfDevRunsDir } from '../../self-dev/run-store.js';
 import { planAction, runSeatLoopOnce, type SeatDeps, type SeatItem } from '../../seat-loop/seat-loop.js';
 import { addHarnessQueue, harnessQueueOutcome, setQueuedPoolHint } from '../../harness/harness-queue.js';
 import { placeOnGrid, type GridHost } from './grid-place.js';
 import { checkPodPool, parsePodPool, resolvePodPoolSpec } from '../../task-orchestrator/surfaces/pod-pool.js';
 import { leaseKubectl } from '../../task-orchestrator/surfaces/pod-lease.js';
+import { defaultAnomalyCluster, extractContainerExit, type AnomalyCluster } from './anomaly-cluster.js';
 import { isLaunchEligible, isTrafficLaunch, recordDispatchCycle, seatOfTree, type TrafficProcess } from './traffic.js';
 import { defaultListHarnessProcesses } from '../../harness/harness-cli-command.js';
 import * as testGuard from '../../instance/test-write-guard.js';
@@ -24,6 +26,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';
 
@@ -31,7 +34,7 @@ export type Window = '08' | '12' | '18';
 export type Node = 'intake' | 'split' | 'place' | 'delegate' | 'launch' | 'reconcile' | 'report';
 export type Mode = 'off' | 'shadow' | 'live';
 const SEAT_LOOP_IDS: Readonly<Record<string, string>> = { OP: 'op-seat', MK: 'cmo-seat', TC: 'tc-seat', UX: 'ux-seat' };
-export interface Cell { id: string; title: string; kind?: string; seat?: string; host?: string; gridHost?: boolean; version?: string; cardId: string; origin: 'candidate' | 'flow1a'; priority?: 'P0' | 'P1' | 'P2' | 'P3' | 'P4'; predecessors?: string[] }
+export interface Cell { id: string; title: string; kind?: string; seat?: string; host?: string; gridHost?: boolean; version?: string; cardId: string; origin: 'candidate' | 'flow1a'; priority?: 'P0' | 'P1' | 'P2' | 'P3' | 'P4'; predecessors?: string[]; consensusProposalId?: string }
 export interface TickState {
   runId: string; window: Window; mode: Mode; day: string;
   cards: TaskCard[]; skippedCards: Array<{ id: string; reason: string }>; cells: Cell[]; placed: number; unplaced?: number; delegated: number; wouldDelegate: number; rebalanced?: number; rebalanceBlocked?: Array<{ id: string; reason: string }>;
@@ -57,7 +60,7 @@ export interface TickState {
   missing: string[];
 }
 /** FLOW1a contract: with `{ shadow: true }` the splitter only proposes cells and writes nothing (cards, ledgers, LLM side effects excepted). */
-export type SplitAdapter = (card: TaskCard, opts?: { shadow?: boolean }) => Promise<Array<{ id: string; title: string; kind?: string; seat?: string; host?: string }>> | Array<{ id: string; title: string; kind?: string; seat?: string; host?: string }>;
+export type SplitAdapter = (card: TaskCard, opts?: { shadow?: boolean }) => Promise<Array<{ id: string; title: string; kind?: string; seat?: string; host?: string; consensusProposalId?: string }>> | Array<{ id: string; title: string; kind?: string; seat?: string; host?: string; consensusProposalId?: string }>;
 /** RELPLAN1 `placeCell(input: PlacementCell)` — owner·priority·predecessors are required; the result carries no seat. */
 export type PlacementInput = { id: string; title: string; owner: string; priority: 'P0' | 'P1' | 'P2'; predecessors: string[] };
 export type PlaceAdapter = (cell: PlacementInput, deps?: { dryRun?: boolean; now?: Date }) => Promise<{ version?: string } | null> | { version?: string } | null;
@@ -72,6 +75,8 @@ export interface TickDeps {
   gridHosts?: readonly GridHost[];
   seatTurn?: (seat: string, root: string, host?: string, options?: Pick<SeatDeps, 'enqueue'>) => Promise<{ status: string; queueId?: string; runId?: string; item?: { source: string; id: string } }>;
   queueOutcome?: (queueId: string, root: string) => 'pending' | 'unknown' | 'retryable' | 'succeeded';
+  /** ANOMALY-CLUSTER — grouping state shared with the dispatcher relaunch gate; defaults to the process-wide instance. */
+  anomalyCluster?: AnomalyCluster;
   /** Snapshot of running harness processes for launch-cap decisions; an unreadable snapshot blocks launches. */
   launchProcesses?: () => { status: 'ok'; records: readonly TrafficProcess[] } | { status: 'incomplete' };
   /** 발사 전 대기열 항목의 풀 힌트 갱신(주입 안 하면 harness-queue `setQueuedPoolHint`). */
@@ -90,6 +95,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. */
@@ -450,6 +457,22 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
   const root = deps.root ?? effectiveInstanceRoot();
   const runId = deps.runId ?? graphRunId() ?? `${kstDay(now)}-${window}`;
   const path = stateFile(root, runId);
+  const consensus = new ConsensusEngine({ stateDir: root });
+  const consensusAllows = (cell: Cell): boolean => {
+    if (cell.kind !== 'cross-branch-change' && !cell.consensusProposalId) return true;
+    const workKey = `orch:${cell.cardId}:${cell.id}`;
+    try {
+      if (cell.kind === 'cross-branch-change') {
+        const proposal = consensus.proposalForWork(workKey);
+        if (!proposal || (cell.consensusProposalId && cell.consensusProposalId !== proposal.id)) return false;
+        cell.consensusProposalId = proposal.id;
+      }
+      return !!cell.consensusProposalId && consensus.canExecute(cell.consensusProposalId);
+    } catch (error) {
+      debug.log('loop.orchestrator', 'consensus-gate-failed', { id: cell.consensusProposalId, workKey, error: String(error) }, { level: 'warn' });
+      return false;
+    }
+  };
   const orchestratorConfig = getUserConfig().loops?.orchestrator;
   const configured = deps.mode ?? orchestratorConfig?.mode;
   const mode: Mode = configured === 'off' || configured === 'live' ? configured : 'shadow';
@@ -498,7 +521,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);
@@ -525,9 +549,12 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
         const cells = ruleOnly ? [{ id: card.id, title: card.title }] : split ? await split(card, { shadow: mode === 'shadow' }) : [{ id: card.id, title: card.title }];
         for (const cell of cells) {
           if (!cell.id?.trim() || !cell.title?.trim()) throw new Error('invalid split cell');
+          const workKey = `orch:${card.id}:${cell.id}`;
+          const proposalId = cell.consensusProposalId ?? (cell.kind === 'cross-branch-change' ? consensus.proposalForWork(workKey)?.id : undefined);
           state.cells.push({ cardId: card.id, id: cell.id, title: cell.title, origin: split ? 'flow1a' : 'candidate',
             ...(ruleOnly ? { priority: rubricPriority(card.sections.map(section => section.content).join('\n')) } : {}),
-            ...(cell.kind !== undefined ? { kind: cell.kind } : {}), ...(cell.seat ? { seat: cell.seat } : {}), ...(cell.host !== undefined ? { host: cell.host } : {}) });
+            ...(cell.kind !== undefined ? { kind: cell.kind } : {}), ...(cell.seat ? { seat: cell.seat } : {}), ...(cell.host !== undefined ? { host: cell.host } : {}),
+            ...(proposalId ? { consensusProposalId: proposalId } : {}) });
         }
         observe('exchange', `split:${card.id}`, cells.length);
         if (split && cells.length && mode === 'live') {
@@ -563,6 +590,7 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
         }
         if (available && (mode === 'live' || !deps.placeCell)) for (const cell of state.cells) {
           if (cell.origin !== 'flow1a' || !cell.seat || !SEAT_LOOP_IDS[cell.seat]) continue;
+          if (!consensusAllows(cell)) { observe('consensus-blocked', cell.consensusProposalId, 1); continue; }
           // RELPLAN's dryRun calculates the same release without writing a checklist in shadow.
           try {
             const priority = cell.priority === 'P3' || cell.priority === 'P4' ? 'P2' : cell.priority ?? 'P2';
@@ -641,6 +669,7 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
       };
       for (const cell of state.cells) {
         if (cell.origin !== 'flow1a' || !cell.seat) continue;
+        if (!consensusAllows(cell)) { observe('consensus-blocked', cell.consensusProposalId, 1); continue; }
         const targetLoopId = SEAT_LOOP_IDS[cell.seat];
         if (!targetLoopId) continue;
         const key = `orch:${cell.cardId}:${cell.id}`;
@@ -670,6 +699,17 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
           // shadow 표본은 따로 센다 — 자리 경로로 아직 안 간 칸(shadow 틱·배치 전)이 나중에 live 로 바뀌면 그때 뜬다.
           // ⚠️ 이미 자리 저널에 들어간 칸은 live 로 바꿔도 다시 안 넘긴다(keys.has 에서 끝) — 한 칸의 발사 주체는 하나다(의도).
           const handKey = handLive ? key : `shadow:${key}`;
+          // ANOMALY-CLUSTER: the goal·host pair is the hold key (never part of the failure signature). While a
+          // signature with 3+ runs is un-judged, its relaunch is held and the cell is carried to the next tick.
+          const anomalyGoal = cell.cardId;
+          const anomalyHost = cell.seat;
+          const anomaly = deps.anomalyCluster ?? defaultAnomalyCluster();
+          const hold = anomaly.hold(anomalyGoal, anomalyHost);
+          if (hold.hold) {
+            (state.deferredCells ??= []).push(cell);
+            observe('anomaly-cluster-hold', `${key}:${hold.reason}`, 1, 'task-agent');
+            continue;
+          }
           mkdirSync(dirname(ledger), { recursive: true });
           mkdirSync(dirname(path), { recursive: true });
           // Claim under the seat-journal lock — the same lock the seat append takes, so a live claim and a seat row never both land.
@@ -689,9 +729,18 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
               withFileLockSync(`${path}.lock`, () => appendFileSync(ledger, `${JSON.stringify({ key: handKey, cell: cell.id, cardId: result.card.id, mode: result.mode, launched: result.launched, status: 'handed', runId, at: now.toISOString() })}\n`));
               (state.handed ??= []).push({ key, cell: cell.id, cardId: result.card.id, mode: result.mode, launched: result.launched });
               observe('hand-to-task-agent', `${key}:${result.card.id}:${result.mode}${result.launched ? ':launched' : ''}`, 1, 'task-agent');
+              // A hand that went through is the cause verdict for this goal·host — clear a pending hold.
+              if (anomaly.isHeld(anomalyGoal, anomalyHost)) anomaly.release(anomalyGoal, anomalyHost, '원인 판정: hand-to-task-agent 성공');
               // A live hand is an assignment: it counts toward maxDelegatePerTick like a seat row (COORD-HA ②).
               if (handLive) { keys.add(key); state.delegatedKeys?.push(key); continue; }
             } catch (error) {
+              // ANOMALY-CLUSTER record point: signature from kind·container exit·stage·reason tail of lastLines.
+              const failureLines = [String(error)];
+              anomaly.record({
+                goal: anomalyGoal, host: anomalyHost, runId,
+                kind: 'hand-to-task-agent-failed', containerExit: extractContainerExit(failureLines[0]!),
+                stage: 'delegate', lastLines: failureLines, at: now.toISOString(),
+              });
               observe('hand-to-task-agent-failed', `${key}:${String(error).slice(0, 160)}`, 1, 'task-agent');
               // A failed live hand stays claimed (no relaunch loop) and does not fall back to the seat path — one launcher per cell.
               if (handLive) { keys.add(key); continue; }
@@ -750,7 +799,7 @@ export async function runOrchestratorNode(node: Node, deps: TickDeps = {}): Prom
       // shadow 는 저널을 읽지 않는다 — 깨진 live 저널이 관측 전용 틱을 넘어뜨리지 않게.
       const latestRequests = new Map(mode === 'live' && state.degradation?.level !== 2 ? readRequests(root).map(row => [row.key, row]) : []);
       const eligible = state.cells.filter(cell => state.degradation?.level !== 2 && cell.origin === 'flow1a' && cell.seat && SEAT_LOOP_IDS[cell.seat]
-        && validVersion(cell.version) && (mode === 'shadow' || latestRequests.get(`orch:${cell.cardId}:${cell.id}`)?.status === 'queued')
+        && consensusAllows(cell) && validVersion(cell.version) && (mode === 'shadow' || latestRequests.get(`orch:${cell.cardId}:${cell.id}`)?.status === 'queued')
         && (orchestratorConfig?.maxDelegatePerTick === undefined || state.delegatedKeys?.includes(`orch:${cell.cardId}:${cell.id}`)
           || (mode === 'live' && latestRequests.has(`orch:${cell.cardId}:${cell.id}`))));
       const seats = [...new Set(eligible.map(cell => cell.seat!))];