elanous 0.2.34 → 0.2.36

package/src/harness/launch-utterance-ledger.ts

@@ -0,0 +1,208 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, writeSync } from 'node:fs';
+import { join, parse, resolve } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { debug } from '../debug/log.js';
+
+/** Product ledger of the raw first text a launch entrance received (say · hand · ask-file).
+ *  Auxiliary evidence: preparing or appending never refuses a launch — failures are observed. */
+export interface LaunchUtteranceStart {
+  readonly event: 'start';
+  readonly launchId: string;
+  readonly source: 'say' | 'hand' | 'ask-file';
+  readonly utterance: string;
+  /** sha256 of the UTF-8 bytes of `utterance` (or of the raw bytes when given). */
+  readonly sha256: string;
+  /** Present only when the raw source bytes are not lossless UTF-8 (ask-file). */
+  readonly utteranceBase64?: string;
+  /** Present for `say`: the exact argv words the process received. */
+  readonly argv?: readonly string[];
+  /** The entrance was asked for a plan only (`--dry-run`) — the text was received, nothing launched. */
+  readonly dryRun?: true;
+  readonly at: string;
+}
+
+export interface LaunchUtteranceInput {
+  readonly source: LaunchUtteranceStart['source'];
+  readonly utterance: string;
+  readonly launchId: string;
+  readonly rawBytes?: Uint8Array;
+  readonly argv?: readonly string[];
+  readonly dryRun?: boolean;
+}
+
+const LAUNCH_ID = /^tl-[0-9a-f]{12}$/;
+const DATE_FILE = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+const DAY_MS = 86_400_000;
+
+/** Env contract of the one explicit hand→say pair (set by the hand launcher, consumed once by say). */
+export const HAND_LAUNCH_ID_ENV = 'ELANOUS_HAND_LAUNCH_ID';
+export const HAND_LAUNCH_SHA256_ENV = 'ELANOUS_HAND_LAUNCH_SHA256';
+export const HAND_LAUNCH_RUN_ENV = 'ELANOUS_HAND_LAUNCH_RUN';
+/** base64 of the hand's exact original text (untrimmed), so the paired child can re-record it byte-exact. */
+export const HAND_LAUNCH_ORIGINAL_ENV = 'ELANOUS_HAND_LAUNCH_ORIGINAL_B64';
+const MAX_ORIGINAL_ENV_BYTES = 64 * 1024;
+
+/** Same `tl-<12 hex>` shape the hand card contract already carries; minted fresh in every process. */
+export function newLaunchUtteranceId(): string { return `tl-${randomBytes(6).toString('hex')}`; }
+export function isLaunchUtteranceId(value: unknown): value is string { return typeof value === 'string' && LAUNCH_ID.test(value); }
+export function utteranceSha256(value: string | Uint8Array): string { return createHash('sha256').update(value).digest('hex'); }
+
+/** Env a hand launcher passes to its say child so that pair — and only that pair — shares the ID.
+ *  `sentence` is the exact argv word the say child receives; `original` is the hand's untrimmed text. */
+export function handLaunchPairEnv(launchId: string, sentence: string, runId: string, original?: string): Record<string, string> {
+  const originalB64 = original === undefined ? undefined : Buffer.from(original, 'utf8').toString('base64');
+  return {
+    [HAND_LAUNCH_ID_ENV]: launchId, [HAND_LAUNCH_SHA256_ENV]: utteranceSha256(sentence), [HAND_LAUNCH_RUN_ENV]: runId,
+    ...(originalB64 !== undefined && originalB64.length <= MAX_ORIGINAL_ENV_BYTES ? { [HAND_LAUNCH_ORIGINAL_ENV]: originalB64 } : {}),
+  };
+}
+
+/** Hand launcher seam: only a `harness say <sentence>` launch with a launchId ⊕ runId gets the pair env
+ *  (ID ⊕ sentence sha ⊕ runId ⊕ exact original). Any other launch context passes through unchanged. */
+export function withHandLaunchPairContext<C extends { launchId?: string; runId?: string; env: Record<string, string>; launchUtterance?: string }>(
+  args: readonly string[], context: C,
+): C {
+  const sayAt = args.indexOf('say');
+  const sentence = args.at(-1);
+  if (!context.launchId || !context.runId || sayAt < 1 || args[sayAt - 1] !== 'harness' || sentence === undefined || sayAt === args.length - 1) return context;
+  return { ...context, env: { ...context.env, ...handLaunchPairEnv(context.launchId, sentence, context.runId, context.launchUtterance) } };
+}
+
+/** Resolve the say launchId: inherit only when the env pair matches this exact sentence and run, then
+ *  remove the pair from `env` so no descendant or later say in this process can reuse the ID.
+ *  When paired, `utterance` is the hand's exact original text (falls back to the sentence). */
+export function consumeHandLaunchId(sentence: string, env: NodeJS.ProcessEnv = process.env, runIdEnv = 'ELANOUS_RUN_ID'): {
+  launchId: string; inherited: boolean; utterance: string;
+} {
+  const inherited = env[HAND_LAUNCH_ID_ENV];
+  const sha = env[HAND_LAUNCH_SHA256_ENV];
+  const run = env[HAND_LAUNCH_RUN_ENV];
+  const originalB64 = env[HAND_LAUNCH_ORIGINAL_ENV];
+  for (const key of [HAND_LAUNCH_ID_ENV, HAND_LAUNCH_SHA256_ENV, HAND_LAUNCH_RUN_ENV, HAND_LAUNCH_ORIGINAL_ENV]) delete env[key];
+  const paired = isLaunchUtteranceId(inherited) && sha === utteranceSha256(sentence)
+    && typeof run === 'string' && run.length > 0 && env[runIdEnv] === run;
+  if (inherited !== undefined && !paired) {
+    try { debug.log('harness.launch-utterance', 'inherit-refused', { hasSha: sha !== undefined, hasRun: run !== undefined }); } catch { /* fail-soft */ }
+  }
+  if (!paired) return { launchId: newLaunchUtteranceId(), inherited: false, utterance: sentence };
+  const original = originalB64 === undefined ? undefined : Buffer.from(originalB64, 'base64').toString('utf8');
+  const utterance = original !== undefined && original.trim() === sentence.trim() ? original : sentence;
+  return { launchId: inherited, inherited: true, utterance };
+}
+
+/** Symlink policy over every component of `path`, parents included: a symlink owned by the system
+ *  (uid 0 — e.g. macOS `/var` · `/tmp`) is an OS alias and allowed; any other symlink is refused, so a
+ *  user-made link can never redirect one instance's ledger into another instance. */
+export function assertLedgerPathPolicy(path: string): void {
+  if (!path.trim()) throw new Error('ledger path must not be empty');
+  const absolute = resolve(path);
+  let part = parse(absolute).root;
+  for (const segment of absolute.slice(part.length).split('/').filter(Boolean)) {
+    part = join(part, segment);
+    let stat;
+    try { stat = lstatSync(part); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+      throw error;
+    }
+    if (stat.isSymbolicLink() && stat.uid !== 0) throw new Error(`ledger symlink refused: ${part}`);
+  }
+}
+
+export function launchUtteranceDir(root: string = effectiveInstanceRoot()): string {
+  return join(resolve(root), 'launch-utterances');
+}
+
+function observeFailure(operation: 'prepare' | 'append' | 'query', error: unknown, extra: Record<string, unknown> = {}): void {
+  const reason = error instanceof Error ? error.message : String(error);
+  try { debug.log('harness.launch-utterance', `${operation}-failed`, { operation, reason, ...extra }, { level: 'warn' }); } catch { /* logging must not block launch */ }
+  try { console.error(`[launch-utterance] ${operation} failed: ${reason}`); } catch { /* fail-soft */ }
+}
+
+function buildRow(input: LaunchUtteranceInput, now: Date): LaunchUtteranceStart {
+  const raw = input.rawBytes;
+  const lossy = raw !== undefined && !Buffer.from(input.utterance, 'utf8').equals(Buffer.from(raw));
+  return {
+    event: 'start',
+    launchId: input.launchId,
+    source: input.source,
+    utterance: input.utterance,
+    sha256: utteranceSha256(raw ?? input.utterance),
+    ...(lossy ? { utteranceBase64: Buffer.from(raw).toString('base64') } : {}),
+    ...(input.argv ? { argv: [...input.argv] } : {}),
+    ...(input.dryRun === true ? { dryRun: true as const } : {}),
+    at: now.toISOString(),
+  };
+}
+
+/** Append one start row to this instance's date file. Returns whether it landed; never throws. */
+export function recordLaunchUtterance(
+  input: LaunchUtteranceInput,
+  root: string = effectiveInstanceRoot(),
+  now: Date = new Date(),
+): boolean {
+  let dir: string;
+  let row: string;
+  try {
+    if (!isLaunchUtteranceId(input.launchId)) throw new Error(`invalid launchId: ${String(input.launchId)}`);
+    dir = launchUtteranceDir(root);
+    assertLedgerPathPolicy(dir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    assertLedgerPathPolicy(dir);
+    if (!lstatSync(dir).isDirectory()) throw new Error(`ledger dir is not a directory: ${dir}`);
+    row = `${JSON.stringify(buildRow(input, now))}\n`;
+  } catch (error) { observeFailure('prepare', error, { source: input.source, launchId: input.launchId }); return false; }
+  try {
+    const file = join(dir, `${now.toISOString().slice(0, 10)}.jsonl`);
+    const fd = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    try {
+      if (!fstatSync(fd).isFile()) throw new Error(`ledger file is not a regular file: ${file}`);
+      writeSync(fd, row);
+    } finally { closeSync(fd); }
+    try { debug.log('harness.launch-utterance', 'recorded', { source: input.source, launchId: input.launchId }); } catch { /* fail-soft */ }
+    return true;
+  } catch (error) { observeFailure('append', error, { source: input.source, launchId: input.launchId }); return false; }
+}
+
+function readNoFollow(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    if (!fstatSync(fd).isFile()) throw new Error(`ledger file is not a regular file: ${file}`);
+    return readFileSync(fd, 'utf8');
+  } finally { closeSync(fd); }
+}
+
+/** Reads only this instance's date files that overlap [now - sinceMs, now], and rows inside that window. */
+export function queryLaunchUtterances(options: { root?: string; sinceMs?: number; now?: Date } = {}): LaunchUtteranceStart[] {
+  const now = options.now ?? new Date();
+  const sinceMs = options.sinceMs ?? DAY_MS;
+  if (!Number.isFinite(sinceMs) || sinceMs < 0 || sinceMs > 31 * DAY_MS) throw new Error('invalid ledger query window');
+  const until = now.getTime();
+  const from = until - sinceMs;
+  const dir = launchUtteranceDir(options.root);
+  let names: string[];
+  try {
+    assertLedgerPathPolicy(dir);
+    if (!lstatSync(dir).isDirectory()) throw new Error(`ledger dir is not a directory: ${dir}`);
+    names = readdirSync(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') observeFailure('query', error);
+    return [];
+  }
+  const rows: LaunchUtteranceStart[] = [];
+  for (const name of names.filter((n) => DATE_FILE.test(n)).sort()) {
+    const day = Date.parse(`${name.slice(0, 10)}T00:00:00.000Z`);
+    if (!Number.isFinite(day) || day > until || day + DAY_MS <= from) continue;
+    let text: string;
+    try { text = readNoFollow(join(dir, name)); } catch (error) { observeFailure('query', error, { file: name }); continue; }
+    for (const line of text.split('\n')) {
+      if (!line) continue;
+      try {
+        const row = JSON.parse(line) as LaunchUtteranceStart;
+        const at = Date.parse(row.at);
+        if (row.event === 'start' && typeof row.utterance === 'string' && Number.isFinite(at) && at >= from && at <= until) rows.push(row);
+      } catch { /* skip torn line */ }
+    }
+  }
+  return rows;
+}

package/src/harness/pod-control-send.ts

@@ -2,6 +2,14 @@ import { encodeControlMemoFrame, type ControlMemoPayload } from './control-inbox
 import type { PodFragmentRecord } from './self-send-target.js';
 import { defaultKubectl, type Kubectl } from '../task-orchestrator/surfaces/self-implement-pod.js';
 
+const POD_CONTROL_KUBECTL_TIMEOUT_MS = 120_000;
+
+export function parsePodReadWait(value: string | number): number {
+  const parsed = typeof value === 'string' && !value.trim() ? Number.NaN : Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 60) throw new Error('self send --read-wait는 0~60초의 유한한 값이어야 합니다');
+  return Math.floor(parsed);
+}
+
 const PUBLISH = `set -eu
 inbox="$1"
 kind="$2"
@@ -9,9 +17,24 @@ IFS= read -r line
 mkdir -p "\${inbox}.ready"
 if [ "$kind" = memo ]; then
   temp=$(mktemp "\${inbox}.ready/.write-XXXXXXXX")
-  trap 'rm -f "$temp"' EXIT
+  record=''
+  cleanup_memo() {
+    rm -f "$temp"
+    if [ -n "$record" ]; then rm -f "$record.ack-request" "$record.ack"; fi
+  }
+  trap 'cleanup_memo' EXIT
+  trap 'exit 129' HUP
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
   printf 'memo:%s\\n' "$line" > "$temp"
-  mv "$temp" "\${inbox}.ready/record-$(printf '%016x' "$(date +%s%3N)")-$(cat /proc/sys/kernel/random/uuid)"
+  record="\${inbox}.ready/record-$(printf '%016x' "$(date +%s%3N)")-$(cat /proc/sys/kernel/random/uuid)"
+  : > "$record.ack-request"
+  mv "$temp" "$record"
+  printf 'ELANOUS_POD_MEMO_PUBLISHED %s\\n' "\${record##*/}"
+  count=0
+  while [ ! -e "$record.ack" ] && [ "$count" -lt "$3" ]; do sleep 1; count=$((count + 1)); done
+  if [ -e "$record.ack" ]; then printf 'ELANOUS_POD_MEMO_READ %s\\n' "\${record##*/}"
+  else printf 'ELANOUS_POD_MEMO_UNVERIFIED %s\\n' "\${record##*/}"; fi
 else
   temp=$(mktemp "\${inbox}.ready/.write-XXXXXXXX")
   trap 'rm -f "$temp"' EXIT
@@ -25,13 +48,18 @@ else
 fi`;
 
 /** Publish a control-inbox record inside the child container, not on the host. */
-export function sendPodControl(record: PodFragmentRecord, message: { stop: true } | { memo: ControlMemoPayload }, kubectl: Kubectl = defaultKubectl): void {
+export function sendPodControl(record: PodFragmentRecord, message: { stop: true } | { memo: ControlMemoPayload }, kubectl: Kubectl = defaultKubectl,
+  readWaitSeconds = 0): { memoRecord?: string; read?: boolean } {
   const stop = 'stop' in message;
   const input = stop ? 'stop\n' : `${encodeControlMemoFrame(message.memo)}\n`;
   const result = kubectl([
     ...(record.context ? ['--context', record.context] : []), '-n', record.namespace,
     'exec', '-i', `job/${record.job}`, '-c', 'child', '--',
-    'sh', '-c', PUBLISH, 'pod-control', record.inboxDir, stop ? 'stop' : 'memo',
-  ], input);
+    'sh', '-c', PUBLISH, 'pod-control', record.inboxDir, stop ? 'stop' : 'memo', String(parsePodReadWait(readWaitSeconds)),
+  ], input, POD_CONTROL_KUBECTL_TIMEOUT_MS);
   if (result.status !== 0) throw new Error(`Pod ${record.job} control send 실패: ${result.stderr.trim() || 'kubectl exec failed'}`);
+  if (stop) return {};
+  const published = /^ELANOUS_POD_MEMO_PUBLISHED (record-[0-9a-f-]+)$/m.exec(result.stdout)?.[1];
+  if (!published) return {};
+  return { memoRecord: published, read: result.stdout.includes(`ELANOUS_POD_MEMO_READ ${published}`) };
 }

package/src/harness/self-send-remote.ts

@@ -0,0 +1,69 @@
+import { readTaskAgentState, shellQuote, taskAgentStatePath, type TaskCard } from '../task-agent/task-hand.js';
+import { defaultSshRunner, remoteLedgerMirrorDir, type SshRunner } from '../task-agent/parent-host.js';
+import { loadRunLedger } from '../self-implement/run-ledger.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { normalizeRunId } from './harness-space.js';
+import { parsePodReadWait } from './pod-control-send.js';
+import { SELF_SEND_LOCAL_ONLY_ENV } from './self-send-routing-guard.js';
+
+export interface RemotePodRunCard extends Pick<TaskCard, 'id' | 'runId' | 'runChildId' | 'parentHost'>, Partial<Pick<TaskCard, 'status'>> {}
+
+export class RemotePodOwnershipAmbiguousError extends Error {
+  override name = 'RemotePodOwnershipAmbiguousError';
+}
+
+export function remotePodControlForOptions(opts: { stop?: boolean; memo?: string; readWait?: string }): { stop: true } | { memo: string; readWait: string } {
+  if (Boolean(opts.stop) === (opts.memo !== undefined)) throw new Error('self send에는 --stop 또는 --memo 한 가지만 필요합니다');
+  if (opts.stop) return { stop: true };
+  if (!opts.memo || /[\r\n]/.test(opts.memo)) throw new Error('control inbox memo must be a non-empty single line');
+  return { memo: opts.memo, readWait: String(parsePodReadWait(opts.readWait ?? '10')) };
+}
+
+/** Resolve only an exact card parent or a child recorded under that parent. */
+export function remotePodCardForRun(runId: string, cards: readonly RemotePodRunCard[],
+  children: (card: RemotePodRunCard) => readonly string[]): RemotePodRunCard | null {
+  if (runId !== normalizeRunId(runId)) return null;
+  const active = cards.filter((card) => card.parentHost?.host && card.runId
+    && (card.status === undefined || card.status === 'launched'));
+  const direct = active.filter((card) => card.parentHost?.host && card.runId
+    && (card.runId === runId || card.runChildId === runId));
+  const mirrored = active.filter((card) => children(card).includes(runId));
+  const matches = [...new Map([...direct, ...mirrored].map((card) => [card.id, card])).values()];
+  if (matches.length > 1) throw new RemotePodOwnershipAmbiguousError(`self send 원격 런 소유 카드가 여러 개입니다: ${runId} (${matches.map((card) => card.id).join(', ')})`);
+  return matches[0] ?? null;
+}
+
+/** A missing child mirror is a possible explanation, never proof of ownership. */
+export function remoteChildOwnershipUnconfirmed(card: RemotePodRunCard | null, cards: readonly RemotePodRunCard[]): boolean {
+  return !card && cards.filter((candidate) => candidate.parentHost?.host && candidate.runId && !candidate.runChildId
+    && (candidate.status === undefined || candidate.status === 'launched')).length === 1;
+}
+
+export function findRemotePodCardForRun(runId: string): { card: RemotePodRunCard | null; remoteChildUnconfirmed: boolean } {
+  const cards = Object.values(readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(taskAgentStatePath()).tasks ?? {});
+  const card = remotePodCardForRun(runId, cards, (card) => {
+    if (!card.runId || !card.parentHost?.host) return [];
+    const ledger = loadRunLedger(card.runId, remoteLedgerMirrorDir(effectiveInstanceRoot(), card.parentHost.host)) ?? [];
+    return ledger.filter((entry) => entry.event === 'pod-child-run')
+      .map((entry) => entry.data.childRunId).filter((value): value is string => typeof value === 'string');
+  });
+  return { card, remoteChildUnconfirmed: remoteChildOwnershipUnconfirmed(card, cards) };
+}
+
+export function sendRemotePodRun(card: RemotePodRunCard, runId: string, control: { memo: string; readWait: string } | { stop: true },
+  ssh: SshRunner = defaultSshRunner): { stdout: string; stderr: string } {
+  const host = card.parentHost?.host;
+  if (!host || !/^[A-Za-z0-9][A-Za-z0-9._@-]{0,127}$/.test(host) || runId !== normalizeRunId(runId))
+    throw new Error(`self send 원격 런 대상이 유효하지 않습니다: ${runId}`);
+  const binary = '$HOME/.local/share/elanous/bin/elanous';
+  const configDir = card.parentHost?.configDir ? shellQuote(card.parentHost.configDir) : '$HOME/.elanous';
+  const args = control.stop ? '--stop' : `--memo ${shellQuote(control.memo)} --read-wait ${shellQuote(control.readWait)}`;
+  const script = `${SELF_SEND_LOCAL_ONLY_ENV}=1 ${binary} --config-dir ${configDir} self send --run ${shellQuote(runId)} ${args}`;
+  const wait = 'memo' in control ? Number(control.readWait) : 0;
+  // The remote kubectl call has a 120s ceiling; SSH must outlive it and CLI startup.
+  const result = ssh(host, script, Math.max(150_000, (Number.isFinite(wait) ? Math.max(0, wait) : 0) * 1_000 + 90_000));
+  if (result.status !== 0) throw new Error(`self send 원격 Pod 전달 실패 (${host}, ${runId}, rc=${result.status ?? 'unknown'}): ${result.stderr.trim() || result.stdout.trim() || '원격 응답 없음'}`);
+  const podReceipt = control.stop ? 'Pod 조각에 soft stop 기록:' : 'Pod 조각에 감독 메모 기록:';
+  if (!result.stdout.includes(podReceipt)) throw new Error(`self send 원격 Pod 전달 미확인 (${host}, ${runId}): ${result.stdout.trim() || '원격 Pod 영수증 없음'}`);
+  return { stdout: result.stdout, stderr: result.stderr };
+}

package/src/harness/self-send-routing-guard.ts

@@ -0,0 +1,6 @@
+export const SELF_SEND_LOCAL_ONLY_ENV = 'ELANOUS_SELF_SEND_LOCAL_ONLY';
+
+/** A remote child must resolve its own Pod fragment without starting another SSH hop. */
+export function mayLookupRemotePodRun(env: NodeJS.ProcessEnv): boolean {
+  return env[SELF_SEND_LOCAL_ONLY_ENV] !== '1';
+}

package/src/harness/self-send-target.ts

@@ -69,14 +69,15 @@ export function finishPodFragment(spaceId: string, env?: NodeJS.ProcessEnv): voi
   }
 }
 
-export function dispatchPodSelfSend(spaceId: string, message: { stop: true } | { memo: ControlMemoPayload }, kubectl?: Kubectl, env?: NodeJS.ProcessEnv): { job: string } | null {
+export function dispatchPodSelfSend(spaceId: string, message: { stop: true } | { memo: ControlMemoPayload }, kubectl?: Kubectl, env?: NodeJS.ProcessEnv,
+  readWaitSeconds = 0): { job: string; memoRecord?: string; read?: boolean } | null {
   const record = readPodFragment(spaceId, env);
   if (!record) {
     if (podFragmentFinished(spaceId, env)) throw new Error(`self send 대상 조각이 이미 끝났다: ${spaceId}`);
     return null;
   }
-  sendPodControl(record, message, kubectl);
-  return { job: record.job };
+  const receipt = sendPodControl(record, message, kubectl, readWaitSeconds);
+  return { job: record.job, ...receipt };
 }
 
 export type SelfSendTargetResolution =

package/src/impl-discipline/detector.ts

@@ -1,6 +1,6 @@
 // Phase detector for implementation discipline.
 //
-// Given the current turn's user text, classify into one of three
+// Given the current turn's user text, classify into one of four
 // phases. The system-prompt builder reads this result to decide
 // which discipline guidance (if any) to inject as a system message.
 //
@@ -8,15 +8,16 @@
 //   plan-loaded         — PLAN-*.md / HANDOFF-*.md / SPEC-*.md file-ref
 //                         OR Korean/English doc keyword (핸드오프, 플랜
 //                         문서, handoff, plan doc, 스펙 문서).
+//   design-first        — implementation request contains an explicit new
+//                         project, empty repository, or from-scratch signal.
 //   implementation-ready — starts with an implementation verb
 //                         (구현/implement/build/포팅/port/만들어) AND
 //                         NOT paired with an exploration verb
 //                         (설명/분석/리뷰).
 //   idle                — everything else.
 //
-// plan-loaded wins over implementation-ready when both would fire —
-// when a plan doc is in play, the LLM must read-and-confirm before
-// diving into edits, even if the user also said "구현해".
+// An explicit new-project request wins over plan-loaded; otherwise the
+// existing plan-loaded and implementation-ready precedence is unchanged.
 
 import type { DetectInput, ImplPhase } from './types.js';
 
@@ -38,6 +39,11 @@ const DOC_KEYWORDS = [
 ];
 
 const IMPL_VERB_RE = /(^|[\s\u3000])(구현|implement|build|포팅|port|만들어)/i;
+const PROJECT_IMPL_VERB_RE = /(^|[\s\u3000])(구현|implement|build|포팅|port|개발|develop|생성|create|만들어)/i;
+const NEW_PROJECT_SIGNAL_RE = /(?:새(?:로운)?\s*(?:저장소|프로젝트)|빈\s*저장소|(?:new|empty)\s+(?:repository|repo|project)\b)/i;
+const FROM_SCRATCH_RE = /(?:\bfrom\s+scratch\b|처음부터)/i;
+const PROJECT_TARGET_RE = /(?:\b(?:project|app|service)\b|프로젝트|앱|서비스|웹앱)/i;
+const FUNCTION_TARGET_RE = /(?:함수|function|method)/i;
 
 // Exploration verbs that, when co-occurring with an implementation
 // verb, downgrade the turn to idle. "이 함수 구현 방식 분석해줘"
@@ -58,6 +64,12 @@ export function detectImplPhase(input: DetectInput): ImplPhase {
   if (!trimmed) return 'idle';
   const lower = trimmed.toLowerCase();
 
+  const explicitProjectScope = NEW_PROJECT_SIGNAL_RE.test(trimmed)
+    || (FROM_SCRATCH_RE.test(trimmed) && PROJECT_TARGET_RE.test(trimmed) && !FUNCTION_TARGET_RE.test(trimmed));
+  if (explicitProjectScope && PROJECT_IMPL_VERB_RE.test(trimmed)) {
+    return 'design-first';
+  }
+
   if (FILE_REF_RE.test(trimmed) || hasDocKeyword(lower)) {
     return 'plan-loaded';
   }

package/src/impl-discipline/system-prompt.ts

@@ -23,6 +23,15 @@ const PLAN_LOADED_PROMPT = `# 플랜/핸드오프 문서 참조 감지
 5. "should I proceed?" 같은 열린 질문 금지 — 확정된 선택지(2~4개) 로 묻거나 plan 을 제출.
 6. 사용자 확인이 명확히 있을 때만 Edit/Write 로 진입.`;
 
+const DESIGN_FIRST_PROMPT = `# 새 프로젝트 구현 요청 — RFC 먼저
+
+사용자가 새 저장소나 새 프로젝트의 구현을 요청했습니다. 앱 코드·프로젝트 설정을 쓰거나 시험을 실행하기 전에 저장소 루트에 RFC.md 초안을 작성하고 명시적 승인을 요청하세요.
+
+1. 요청에 PLAN/HANDOFF/SPEC 문서가 있으면 먼저 읽고 RFC 초안에 목표·범위·비목표·설계·수용 기준을 반영하세요.
+2. RFC 초안과 결정이 필요한 항목을 제시하고 승인을 요청하세요.
+3. 승인 전에는 애플리케이션 코드·설정을 만들거나 시험을 실행하지 마세요.
+4. 승인 뒤 RFC와 대조해 구현을 시작하세요.`;
+
 const IMPLEMENTATION_READY_PROMPT = `# 명시적 구현 요청 감지
 
 사용자가 구현을 요청했습니다. **구현 요청 자체가 실행 승인입니다.** 계획을 설명한 뒤 멈추지 말고, 이번 턴 안에서 실제 코드 편집(Edit/Write)까지 진행하세요.
@@ -79,6 +88,7 @@ function promptWithNativeStructure(phase: ImplPhase, enabledTools: readonly Nati
   const { listNativeToolDisplayNamesByKind } = require('../native-tool-catalog.js') as typeof import('../native-tool-catalog.js');
   const namesByKind = listNativeToolDisplayNamesByKind(enabledTools);
   switch (phase) {
+    case 'design-first': return DESIGN_FIRST_PROMPT;
     case 'plan-loaded': {
       let prompt = PLAN_LOADED_PROMPT;
       prompt = replaceDirective(prompt, '1. 먼저 Read 로 문서 전체를 읽으세요 (offset/limit 없이).', namesByKind, ['read']);
@@ -111,6 +121,7 @@ export function promptForPhase(phase: ImplPhase, options: ImplDisciplinePromptOp
   }
   switch (phase) {
     case 'plan-loaded': return PLAN_LOADED_PROMPT;
+    case 'design-first': return DESIGN_FIRST_PROMPT;
     case 'implementation-ready': return IMPLEMENTATION_READY_PROMPT;
     case 'idle': return '';
   }

package/src/impl-discipline/types.ts

@@ -1,11 +1,11 @@
 // Implementation-discipline phase types.
 //
-// The detector maps a user turn to one of three phases; the
+// The detector maps a user turn to one of four phases; the
 // system-prompt builder emits different guidance per phase. State is
 // derived per-turn (stateless) so a wrong classification self-heals
 // on the next turn.
 
-export type ImplPhase = 'idle' | 'plan-loaded' | 'implementation-ready';
+export type ImplPhase = 'idle' | 'plan-loaded' | 'design-first' | 'implementation-ready';
 
 export interface DetectInput {
   /** Raw user text for the current turn. */