elanous 0.2.40 → 0.2.42

package/src/self-implement/goal-author.ts

@@ -1,6 +1,6 @@
 import { classifyObservation } from '../design/behaviour-signal.js';
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, type Dirent } from 'node:fs';
-import { spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { isRepositoryImplementationCandidate, type CodebaseGrounding } from '../autopilot/codebase-grounding.js';
@@ -57,6 +57,7 @@ import { targetScopedGoalText } from './goal-text-path-scope.js';
 import { parseReleaseNoteSection } from '../release-loop/release-note.js';
 import { declaredNewFilePaths } from './goal-new-paths.js';
 import { classifyGoalCommandExecution, type GoalCommandExecutionResult } from './goal-command-execution.js';
+import { formatShadowArmProbeRecord, probeShadowArm, type ShadowArmProbeRecord, type ShadowDifficulty } from '../budget/shadow-arms.js';
 import { identityLines, repositoryIdentifiers } from './goal-author-identity.js';
 import { selectRelevantAuthoringLessons } from './knowhow-pack.js';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
@@ -120,6 +121,12 @@ export interface GoalAuthorDeps {
   decomposeSteps?: (objective: string, opts?: { context?: string; runId?: string; goalId?: string }) => Promise<readonly string[]>;
   /** Optional launch preflight result supplied by the caller; authoring never reads the ledger or logs itself. */
   launchPreflight?: LaunchPreflightResult;
+  /**
+   * SELF-REVIEW-PRELAUNCH ⑤ — 완료 경계 증거 명령이 «현재 main» 에서 실행 가능한지 판정하는
+   * 읽기 전용 존재 심. 저작 코어(`authorGoal`)는 파일을 열지 않으므로 심이 없으면 판정을
+   * `not-applicable` 로 남기고, 생산 진입점(`writeAuthoredGoal`)이 repositoryRoot 기준 심을 공급한다.
+   */
+  selfReviewExistsOnMain?: (repositoryRelativePath: string) => boolean | undefined;
   /** Optional in-process notification for each authored-goal phase transition. */
   onProgress?: (phase: GoalAuthorPhase, event: 'start' | 'end') => void;
   /** AUTHOR-TIMEBOX: budget for the `ground` phase. Omitted means `GOAL_AUTHOR_GROUND_TIMEBOX_MS`. */
@@ -385,6 +392,7 @@ type GoalAuthorTimedPhase = GoalAuthorPhase | GoalAuthorAssembleSubphase;
 function startGoalAuthorPhase(phase: GoalAuthorTimedPhase, authorRunId: string, onProgress?: GoalAuthorDeps['onProgress']): number {
   observeGoalAuthor('goal-author', 'phase-start', { phase, authorRunId });
   if (GOAL_AUTHOR_PHASES.includes(phase as GoalAuthorPhase)) {
+    if (phase === 'assemble') probeAuthoringShadowArm(authorRunId);
     if (onProgress) onProgress(phase as GoalAuthorPhase, 'start');
     else process.stderr.write(`[goal-author] ${phase} started\n`);
   }
@@ -403,6 +411,56 @@ function endGoalAuthorPhase(phase: GoalAuthorTimedPhase, startedAt: number, auth
   }
 }
 
+// ── SHADOW-MODEL-ARMS · 저작 단계 그림자 «1팔» probe(명시 실행 · 관측만) ────────────────
+/**
+ * ⭐ 저작 단계 그림자 1팔 — `planShadowArms`(src/budget/shadow-arms.ts) 를 일일 상한
+ *   안에서 «실제 호출»해 난이도·모델·예상/실제 비용·결과를 한 줄 원장 형식으로 기록한다.
+ *   ⛔ 관측만 한다 — 라이브 LLM(Claude 구독) 호출 0 · 골/PR/착지 파일 쓰기 0.
+ *      팔은 «계획»이고, 실행·자동 런 훅·다른 단계(implement·review·judge) 팔은 후속 조각이다.
+ *   ⛔ 오늘 이미 쓴 그림자 예산의 실 지출 원장 배선도 후속 — 지금은 0지출 고정값으로 판정한다.
+ */
+export const SHADOW_AUTHORING_ARM_MODEL = 'gpt-5.6-terra';
+export const SHADOW_AUTHORING_ARM_DIFFICULTY: ShadowDifficulty = 'medium';
+export const SHADOW_AUTHORING_ARM_INPUT_TOKENS = 24_000;
+export const SHADOW_AUTHORING_ARM_OUTPUT_TOKENS = 8_000;
+export const SHADOW_AUTHORING_SPENT_TODAY_USD = 0;
+export const SHADOW_AUTHORING_DAILY_CAP_USD = 5;
+
+export interface AuthoringShadowArmProbe {
+  record: ShadowArmProbeRecord;
+  line: string;
+}
+
+let shadowArmProbeObserver: ((probe: AuthoringShadowArmProbe, authorRunId: string) => void) | undefined;
+
+function defaultShadowArmProbeObserver(probe: AuthoringShadowArmProbe, authorRunId: string): void {
+  observeGoalAuthor('goal-author', 'shadow-arm-authoring', { authorRunId, ...probe.record, line: probe.line });
+}
+
+/** 저작 단계 그림자 1팔을 실제 호출해 기록을 낸다 — 부작용은 관측 원장뿐이다(관측만). */
+export function probeAuthoringShadowArm(authorRunId: string): AuthoringShadowArmProbe {
+  const record = probeShadowArm({
+    stage: 'authoring',
+    difficulty: SHADOW_AUTHORING_ARM_DIFFICULTY,
+    inputTokens: SHADOW_AUTHORING_ARM_INPUT_TOKENS,
+    expectedOutputTokens: SHADOW_AUTHORING_ARM_OUTPUT_TOKENS,
+    candidates: [SHADOW_AUTHORING_ARM_MODEL],
+    spentTodayUsd: SHADOW_AUTHORING_SPENT_TODAY_USD,
+    dailyCapUsd: SHADOW_AUTHORING_DAILY_CAP_USD,
+  });
+  const probe: AuthoringShadowArmProbe = { record, line: formatShadowArmProbeRecord(record) };
+  const observer = shadowArmProbeObserver ?? defaultShadowArmProbeObserver;
+  observer(probe, authorRunId);
+  return probe;
+}
+
+/** 관측 접합점 갈아끼우기(시험 전용) — 인자 없이 부르면 생산 기본 관측자로 복원한다. */
+export function _setShadowArmProbeObserverForTesting(
+  observer?: (probe: AuthoringShadowArmProbe, authorRunId: string) => void,
+): void {
+  shadowArmProbeObserver = observer;
+}
+
 export type GoalFileLintLevel = 'ERROR' | 'WARN';
 
 export type GoalFileLintTag = 'canonical-structure' | 'evidence-section' | 'boundary-size' | 'launch-branch' | 'unanswered-clarification' | 'shell-damage' | 'traced-path' | 'traced-path-new' | 'grounding-evidence' | 'empty-result-population' | 'decision-signal-numeric-source' | 'decision-signal-numeric-coverage' | 'decision-signal-proxy-expectation' | 'out-of-target-requirement' | 'heading-form-marker' | 'blanket-invariant' | 'self-question-subject' | 'artifact-launch-declaration' | 'all-negative-signals' | 'unreadable-signals' | 'alternative-signals' | 'count-observation' | 'identifier-name-observation' | 'self-reported-observation' | 'default-invocation-observation' | 'release-note';
@@ -961,7 +1019,7 @@ function targetPathsInLabelPiece(piece: string): string[] {
   return askPathTokens(piece).filter((path) => classifyTracedPathToken(path).kind === 'path');
 }
 
-function declaredTargetPaths(document: string): string[] {
+export function declaredTargetPaths(document: string): string[] {
   return linesOutsideFencedCode(document).flatMap(({ text }) => {
     const match = TARGET_PATH_LABEL.exec(text.trim());
     return match ? match[1].split(/\s+[·,]\s*|[·,]\s+/).flatMap(targetPathsInLabelPiece) : [];
@@ -2972,7 +3030,17 @@ export function readVerificationMenuDocs(root: string | undefined): { menu: stri
   return { menu: read(VERIFICATION_MENU_DOC), catalog: read(MOCK_CATALOG_DOC) };
 }
 
-interface CatalogStage { id: string; name: string; run: string; level: InjectionLadderLevel; strong: string[]; weak: string[] }
+interface CatalogStage {
+  id: string;
+  name: string;
+  universe: string;
+  injection: string;
+  observation: string;
+  run: string;
+  level: InjectionLadderLevel;
+  strong: string[];
+  weak: string[];
+}
 interface MenuRow { method: string; command: string; stages: string }
 
 const CATALOG_STOP_WORDS = new Set(['bun', 'bin', 'elanous', 'elanous.mjs', 'mjs', 'test', 'git', 'grep', 'head', 'json', 'path', 'paths']);
@@ -2999,8 +3067,10 @@ function parseCatalogStages(catalog: string): CatalogStage[] {
     const [, id, name] = header as unknown as [string, string, string];
     const universe = catalogField(block, '우주');
     const behaviour = catalogField(block, '증명하는 동작');
+    const injection = catalogField(block, '무대 세우기');
+    const observation = catalogField(block, '판정');
     const run = catalogField(block, '실행');
-    const text = `${name} ${behaviour} ${run}`;
+    const text = `${name} ${behaviour} ${universe} ${injection} ${observation} ${run}`;
     const strong = new Set<string>();
     const weak = new Set<string>();
     for (const span of text.match(/`[^`]+`/gu) ?? []) {
@@ -3015,7 +3085,8 @@ function parseCatalogStages(catalog: string): CatalogStage[] {
       if (word.length >= 2 && !CATALOG_KOREAN_STOP_WORDS.has(word)) weak.add(word);
     }
     for (const word of strong) weak.delete(word);
-    return [{ id, name: name.trim(), run, level: ladderLevelForUniverse(universe), strong: [...strong], weak: [...weak] }];
+    return [{ id, name: name.trim(), universe, injection, observation, run,
+      level: ladderLevelForUniverse(universe), strong: [...strong], weak: [...weak] }];
   });
 }
 
@@ -3095,6 +3166,10 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
   const operationalNote = operational
     ? ` · 운영 실물: 메뉴 «${operationalRow?.method ?? '운영 실물 로그 관측'}» — 운영 데이터가 입력일 때만${operationalRow ? ` (${oneLine(operationalRow.command.replace(/`/gu, ''), 120)})` : ''}`
     : '';
+  const completionEvidenceCommandValue = /^\s*(?:[-*]\s*)?완료\s*경계\s*증거\s*명령\s*:\s*(.+?)\s*$/mu.exec(ask)?.[1];
+  const completionEvidenceCommand = completionEvidenceCommandValue
+    ? validateGoalDoneEvidenceCommand(completionEvidenceCommandValue).command
+    : undefined;
   const testFile = firstTestTarget(input.targetPaths);
   const cellId = ask.match(/\b[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)+\b/u)?.[0];
   const behaviour = oneLine((input.behaviour || '').split(/\s*(?:판정선|판정\s*신호)\s*(?:\(반증\))?\s*:/u)[0] || 'ask 에서 동작 문장을 고르지 못했다 — 사람이 ① 을 채운다', 120);
@@ -3109,7 +3184,7 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
     const row = menuRows.find((candidate) => candidate.stages.includes(best!.stage.id));
     const run = /`([^`]+)`/u.exec(best.stage.run)?.[1];
     stage = { source: 'catalog', id: best.stage.id, level: best.stage.level };
-    stageLine = `- ② 무대: ${best.stage.id} ${best.stage.name} · ${best.stage.level} (${INJECTION_LADDER[best.stage.level]})${row ? ` · 메뉴: ${row.method}` : ''}${run ? ` · 실행: \`${run}\`` : ''}${operationalNote}`;
+    stageLine = `- ② 무대: ${best.stage.id} ${best.stage.name} · 우주: ${oneLine(best.stage.universe, 90)} · 사건 주입: ${oneLine(best.stage.injection, 120)} · 관측: ${oneLine(best.stage.observation, 120)} · ${best.stage.level} (${INJECTION_LADDER[best.stage.level]})${row ? ` · 메뉴: ${row.method}` : ''}${run ? ` · 실행: \`${run}\`` : ''}${operationalNote}`;
   } else {
     const screen = /TUI|화면|렌더|위젯|ux-sim|fake-llm|fake-bin|fake-clock|타이머/iu.test(ask);
     const level: InjectionLadderLevel = screen ? 'L2' : 'L1';
@@ -3146,6 +3221,9 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
   const symbol = wiringSymbol(ask);
   const productionPaths = input.targetPaths.filter((path) => !/\.test\./u.test(path) && !/\.md$/u.test(path));
   const wiring = `git grep -n -F '${symbol ?? '<새 함수>'}(' HEAD -- ${productionPaths.length ? productionPaths.join(' ') : 'src'}`;
+  const e2 = completionEvidenceCommand
+    ? `E2 완료 경계 증거 명령 \`${completionEvidenceCommand}\` 을 origin/main 에서 rc0 확인`
+    : 'E2 완료 경계 증거 명령은 ask에 없거나 유효하지 않아 저작자가 채움';
   return {
     lines: [
       VERIFICATION_PLAN_HEADING,
@@ -3153,7 +3231,7 @@ export function authorVerificationPlan(input: VerificationPlanInput): Verificati
       stageLine,
       `- ③ 먼저 쓸 시험(RED): \`${testFile}\` › '${testName}' — ① 의 동작이 아직 없어 단언이 실패한다(구현 전에 먼저 쓰고 실패를 확인한다)`,
       `- ④ GREEN 뒤 같은 명령: \`${testCommand}\` → 0 fail`,
-      `- ⑤ 생산 진입점 배선(MS-05): \`${wiring}\` — 호출부를 커밋한 뒤 PR head 에서 돌린다 · 정의·주석·시험 행이 아닌 생산 호출 문장 1건 이상(0건만으로 미배선 판정 금지)`,
+      `- ⑤ 생산 진입점 배선(MS-05 · G1 v4): \`${wiring}\` — 호출부를 커밋한 뒤 PR head에서 돌린다 · 정의·주석·시험 행이 아닌 생산 호출 문장 1건 이상(0건만으로 미배선 판정 금지) · E1 착지 뒤 PR head가 main의 조상인지 확인 · ${e2} · E3 생산 진입점 시험 또는 mock 무대 · E4 운영 실물은 필수 아님`,
     ],
     stage,
     menuPresent: input.menu !== null,
@@ -5732,6 +5810,278 @@ function acceptanceCriteria(
   return acceptance;
 }
 
+// ── SELF-REVIEW-PRELAUNCH — 발사 전 self-review 페이즈(다섯 검사 · 1회 재저작 · 잔여 needs-human) ─────────────
+/**
+ * ⭐ 저작물이 «발사 전에» 자기를 검열한다 — ask 밖 목표·칸 밖 경로·미래 가정·mock 무대 누락·
+ *   main 에서 실행 불가능한 완료 경계 증거 명령을 lint·발사 흐름 «앞에서» 잡는다.
+ * ⛔ 검사 대상은 «모델이 만든 목표 줄»(`- Checkable requested criterion:` · 분해 조각)뿐이다 —
+ *   사람 ask(verbatim 울타리 안)와 저작기의 결정론 계약 줄(완료 경계 3행·보존·배선 줄)은 손대지 않는다.
+ * ⭐ 걸리면 «1회» 재저작한다: ① 상 조각 재분해 ⊕ ② 줄 제거 ⊕ ③ FU(후속 조각) 화.
+ *   그 뒤에도 남으면 «해당 조각만» needs-human verdict 로 남긴다(author.self-review 관측).
+ */
+export const GOAL_AUTHOR_SELF_REVIEW_CHECKS = ['slice-difficulty', 'ask-scope', 'future-assumption', 'mock-stage', 'evidence-command'] as const;
+export type GoalSelfReviewCheck = (typeof GOAL_AUTHOR_SELF_REVIEW_CHECKS)[number];
+export type GoalSelfReviewVerdict = 'pass' | 'fixed' | 'needs-human' | 'not-applicable';
+
+export interface GoalSelfReviewItem {
+  readonly check: GoalSelfReviewCheck;
+  readonly verdict: GoalSelfReviewVerdict;
+  readonly detail: string;
+  readonly slice?: string;
+  readonly fix?: string;
+  readonly judgment?: 'main-runnable' | 'main-not-runnable' | 'unknown';
+}
+
+export interface GoalSelfReviewAttempt {
+  readonly attempt: 1 | 2;
+  readonly reauthored: boolean;
+  readonly items: readonly GoalSelfReviewItem[];
+}
+
+export interface GoalAuthorSelfReviewOutcome {
+  readonly document: string;
+  readonly reviews: readonly GoalSelfReviewAttempt[];
+}
+
+export interface GoalAuthorSelfReviewInput {
+  readonly ask: string;
+  readonly document: string;
+  readonly steps: readonly string[] | undefined;
+  readonly checklist: readonly string[];
+  readonly facts: CodebaseGrounding | null;
+  readonly decomposeSteps?: GoalAuthorDeps['decomposeSteps'];
+  readonly existsOnMain?: (repositoryRelativePath: string) => boolean | undefined;
+  readonly runId?: string;
+  readonly goalId?: string;
+}
+
+const SLICE_DIFFICULTY_DECLARATION = /(?:난이도|difficulty)\s*[:：]?\s*(하|중|상|low|medium|high)/iu;
+const SLICE_LANDABLE_DECLARATION = /(착지\s*가능|완료\s*경계|completion\s*boundary|landable)/iu;
+const SLICE_PREREQUISITE_DECLARATION = /(선행|depends\s*on|prerequisite|prereq)/iu;
+const SLICE_TIER_BY_DECLARATION: Record<string, '하' | '중' | '상'> = { 하: '하', 중: '중', 상: '상', low: '하', medium: '중', high: '상' };
+/** 미래 가정 — 현재 main 상태가 아니라 «앞으로 생길 것»을 전제하는 문면(제거하거나 FU 조각화). */
+const FUTURE_ASSUMPTION_DECLARATION = /나중에|향후|미래(?:에|의)|다음\s*(?:판|버전)|(?:착지|머지|반영|merge|land)(?:되|된|한다)?\s*(?:면|후|뒤|한\s*뒤)|after\s+#\d+|once\s+#\d+|#\d+\s+(?:lands|merges)|will\s+be\s+(?:added|landed|merged|available)|future\s+assumptions?/iu;
+/** ask 가 이름대지 않은 칸 id — ask 밖 목표의 결정론 표지(숫자로 시작하는 두번째 마디 `MS-02` 는 제외). */
+const OUT_OF_ASK_CELL_ID = /\b[A-Z][A-Z0-9]{1,}-[A-Z][A-Z0-9-]*\b/g;
+
+function declaredSliceTier(step: string): '하' | '중' | '상' | null {
+  const match = SLICE_DIFFICULTY_DECLARATION.exec(step);
+  return match ? SLICE_TIER_BY_DECLARATION[match[1]!.toLowerCase()] ?? null : null;
+}
+
+/** 칸 = ask ⊕ 접지 — 사람이 이름댔거나 접지가 Read 한 경로가 «칸 안»이다. */
+function inCellPathTokens(ask: string, facts: CodebaseGrounding | null): Set<string> {
+  return new Set([
+    ...declaredTargetPaths(ask),
+    ...evidencePaths(ask),
+    ...(facts?.files ?? []),
+    ...(facts?.persistentEvidence ?? []).flatMap((entry) => evidencePaths(entry)),
+  ]);
+}
+
+function outOfCellReasons(criterion: string, ask: string, inCellPaths: ReadonlySet<string>): string[] {
+  const reasons: string[] = [];
+  const outPaths = evidencePaths(criterion).filter((path) => !inCellPaths.has(path) && !ask.includes(path));
+  if (outPaths.length) reasons.push(`칸 밖 경로: ${outPaths.join(' · ')}`);
+  const ids = [...criterion.matchAll(OUT_OF_ASK_CELL_ID)].map((match) => match[0]).filter((id) => !ask.includes(id));
+  if (ids.length) reasons.push(`ask 밖 목표(칸 id): ${ids.join(' · ')}`);
+  return reasons;
+}
+
+/** ④ mock 무대 — 검증 계획(TDD) 의 무대 줄이 MS id·사건 주입·관측 줄을 갖췄나. */
+function mockStageSelfReviewItem(document: string): GoalSelfReviewItem {
+  const start = document.indexOf(VERIFICATION_PLAN_HEADING);
+  if (start === -1) return { check: 'mock-stage', verdict: 'not-applicable', detail: '검증 계획(TDD) 절이 없어 mock 무대 줄을 검사하지 않는다.' };
+  const rest = document.slice(start + VERIFICATION_PLAN_HEADING.length);
+  const nextHeading = rest.indexOf('\n## ');
+  const section = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+  const missing = [
+    ...(/MS-\d+/u.test(section) ? [] : ['MS id']),
+    ...(section.includes('사건 주입') ? [] : ['사건 주입 줄']),
+    ...(section.includes('관측:') ? [] : ['관측 줄']),
+  ];
+  return missing.length
+    ? { check: 'mock-stage', verdict: 'needs-human', detail: `mock 무대 줄 미비 — ${missing.join(' · ')} — 사람이 무대를 확정한다.` }
+    : { check: 'mock-stage', verdict: 'pass', detail: 'mock 무대가 MS id·사건 주입·관측 줄을 갖췄다.' };
+}
+
+/** ⑤ 완료 경계 증거 명령 — 경로 인자가 «현재 main» 에 있는지 판정한다(심이 없으면 판정을 남기지 못한다). */
+function evidenceCommandSelfReviewItem(document: string, existsOnMain: ((repositoryRelativePath: string) => boolean | undefined) | undefined): GoalSelfReviewItem {
+  const command = inspectGoalDoneBoundary(document).values['완료 경계 증거 명령'];
+  if (command === undefined) return { check: 'evidence-command', verdict: 'not-applicable', detail: '완료 경계 증거 명령이 없어 main 실행 가능 판정을 하지 않는다.' };
+  if (existsOnMain === undefined) return { check: 'evidence-command', verdict: 'not-applicable', detail: 'main 존재 심(selfReviewExistsOnMain)이 없어 판정하지 못한다 — 생산 진입점이 심을 공급한다.', slice: command };
+  const paths = evidencePaths(command);
+  if (!paths.length) return { check: 'evidence-command', verdict: 'pass', judgment: 'main-runnable', detail: `증거 명령에 저장소 경로 인자가 없다 — 현재 main 에서 그대로 실행된다: ${command}` };
+  const presence = paths.map((path) => [path, existsOnMain(path)] as const);
+  const unknown = presence.filter(([, exists]) => exists === undefined).map(([path]) => path);
+  if (unknown.length) return { check: 'evidence-command', verdict: 'needs-human', judgment: 'unknown', detail: `origin/main 에서 경로 존재를 잴 수 없음: ${unknown.join(' · ')} — main 실행 가능성을 확인할 수 없어 사람이 판정한다.`, slice: command };
+  const missing = presence.filter(([, exists]) => exists === false).map(([path]) => path);
+  return missing.length
+    ? { check: 'evidence-command', verdict: 'needs-human', judgment: 'main-not-runnable', detail: `현재 main 에 없는 경로: ${missing.join(' · ')} — 신설 경로면 착지 뒤에 실행 가능하다.`, slice: command }
+    : { check: 'evidence-command', verdict: 'pass', judgment: 'main-runnable', detail: `증거 명령의 모든 경로 인자가 현재 main 에 있다: ${paths.join(' · ')}` };
+}
+
+interface SelfReviewPass {
+  readonly items: readonly GoalSelfReviewItem[];
+  readonly removeCriterionLines: readonly string[];
+  readonly fuCriterionLines: readonly (readonly [line: string, fuLine: string])[];
+  readonly fuStepLines: readonly (readonly [line: string, fuLine: string])[];
+  readonly oversizeSteps: readonly string[];
+}
+
+function passGoalSelfReview(input: {
+  readonly document: string;
+  readonly steps: readonly string[] | undefined;
+  readonly modelCriteria: readonly string[];
+  readonly ask: string;
+  readonly inCellPaths: ReadonlySet<string>;
+  readonly existsOnMain: ((repositoryRelativePath: string) => boolean | undefined) | undefined;
+}): SelfReviewPass {
+  const items: GoalSelfReviewItem[] = [];
+  const removeCriterionLines: string[] = [];
+  const fuCriterionLines: Array<readonly [string, string]> = [];
+  const fuStepLines: Array<readonly [string, string]> = [];
+  const oversizeSteps: string[] = [];
+
+  // ① 조각 난이도 하·중·착지 가능·선행 명시 — 상이면 더 분해한다.
+  if (input.steps === undefined || input.steps.length === 0) {
+    items.push({ check: 'slice-difficulty', verdict: 'not-applicable', detail: '검토할 분해 조각이 없다 — 난이도·착지 가능·선행 명시를 검사하지 않는다.' });
+  } else {
+    for (const step of input.steps) {
+      const tier = declaredSliceTier(step);
+      const missing = [
+        ...(tier === null ? ['난이도(하·중)'] : []),
+        ...(SLICE_LANDABLE_DECLARATION.test(step) ? [] : ['착지 가능']),
+        ...(SLICE_PREREQUISITE_DECLARATION.test(step) ? [] : ['선행']),
+      ];
+      if (tier === '상') {
+        oversizeSteps.push(step);
+        items.push({ check: 'slice-difficulty', verdict: 'needs-human', detail: `난이도 상 — 더 분해해야 한다 (미명시: ${missing.join(' · ')})`, slice: step });
+        continue;
+      }
+      items.push(missing.length
+        ? { check: 'slice-difficulty', verdict: 'needs-human', detail: `조각이 난이도 하·중·착지 가능·선행을 명시하지 않았다 — 미명시: ${missing.join(' · ')}`, slice: step }
+        : { check: 'slice-difficulty', verdict: 'pass', detail: `난이도 ${tier} · 착지 가능 · 선행 명시 확인`, slice: step });
+    }
+  }
+
+  const documentLines = input.document.split('\n');
+  const modelCriterionLines = input.modelCriteria
+    .map((criterion) => ({ criterion, line: requestedCriterionLine(criterion) }))
+    .filter(({ line }) => documentLines.includes(line));
+
+  // ② ask 밖 목표·칸 밖 경로 제거 — 칸 = ask ⊕ 접지.
+  for (const { criterion, line } of modelCriterionLines) {
+    const reasons = outOfCellReasons(criterion, input.ask, input.inCellPaths);
+    if (!reasons.length) continue;
+    items.push({ check: 'ask-scope', verdict: 'fixed', detail: `ask 밖 목표·칸 밖 경로 — ${reasons.join(' · ')}`, slice: criterion, fix: '1회 재저작에서 이 목표 줄을 문서에서 제거한다.' });
+    removeCriterionLines.push(line);
+  }
+  if (!removeCriterionLines.length) items.push({ check: 'ask-scope', verdict: 'pass', detail: 'ask 밖 목표·칸 밖 경로가 없다.' });
+
+  // ③ 미래 가정 — 제거하거나 FU(후속 조각) 로 바꾼다.
+  for (const { criterion, line } of modelCriterionLines) {
+    if (removeCriterionLines.includes(line) || !FUTURE_ASSUMPTION_DECLARATION.test(criterion)) continue;
+    items.push({ check: 'future-assumption', verdict: 'fixed', detail: '미래 가정 — 현재 main 상태가 아니라 앞으로 생길 것을 전제한다.', slice: criterion, fix: '1회 재저작에서 FU(후속 조각) 줄로 바꾼다.' });
+    fuCriterionLines.push([line, `- FU(후속 조각): ${criterion}`]);
+  }
+  for (const step of input.steps ?? []) {
+    // A declared step dependency is a present plan relationship, not an assumption
+    // that an external future event will happen (e.g. shadow → live after step ① lands).
+    if (SLICE_PREREQUISITE_DECLARATION.test(step) || !FUTURE_ASSUMPTION_DECLARATION.test(step)) continue;
+    items.push({ check: 'future-assumption', verdict: 'fixed', detail: '미래 가정 조각 — 현재 main 상태가 아니라 앞으로 생길 것을 전제한다.', slice: step, fix: '1회 재저작에서 FU(후속 조각) 줄로 바꾼다.' });
+    fuStepLines.push([`- ${step}`, `- FU(후속 조각): ${step}`]);
+  }
+  if (!fuCriterionLines.length && !fuStepLines.length) items.push({ check: 'future-assumption', verdict: 'pass', detail: '미래 가정이 없다.' });
+
+  items.push(mockStageSelfReviewItem(input.document));
+  items.push(evidenceCommandSelfReviewItem(input.document, input.existsOnMain));
+  return { items, removeCriterionLines, fuCriterionLines, fuStepLines, oversizeSteps };
+}
+
+function renderGoalStepsSection(steps: readonly string[]): string {
+  return ['## STEPS', ...(steps.length ? steps.map((step) => `- ${step}`) : ['- No externally injected steps.']), '', ''].join('\n');
+}
+
+function replaceGoalStepsSection(document: string, steps: readonly string[]): string {
+  const outside = linesOutsideFencedCode(document);
+  const start = outside.find((line) => line.text === '## STEPS');
+  const next = start && outside.find((line) => line.start > start.start && line.text === '## ACCEPTANCE CRITERIA');
+  if (!start || !next) return document;
+  return `${document.slice(0, start.start)}${renderGoalStepsSection(steps)}${document.slice(next.start)}`;
+}
+
+function reviseGoalDocumentLines(document: string, revision: { remove: readonly string[]; fu: readonly (readonly [line: string, fuLine: string])[] }): string {
+  const remove = new Set(revision.remove);
+  const fu = new Map(revision.fu);
+  return document.split('\n').flatMap((line) => {
+    if (remove.has(line)) return [];
+    const fuLine = fu.get(line);
+    return fuLine ? [fuLine] : [line];
+  }).join('\n');
+}
+
+/**
+ * 발사 전 self-review 엔진 — 1차 검사 → (결정론적 수정이 있으면) 1회 재저작 → 2차 검사.
+ * 파일·원장·LLM 효과는 없다: 재분해는 주입된 `decomposeSteps` 심으로만, main 존재 판정은 주입된 심으로만.
+ */
+export async function runGoalAuthorSelfReview(input: GoalAuthorSelfReviewInput): Promise<GoalAuthorSelfReviewOutcome> {
+  const modelCriteria = withoutDedicatedSectionDuplicates(input.checklist, input.ask);
+  const inCellPaths = inCellPathTokens(input.ask, input.facts);
+  const first = passGoalSelfReview({ document: input.document, steps: input.steps, modelCriteria, ask: input.ask, inCellPaths, existsOnMain: input.existsOnMain });
+  const canRedecompose = first.oversizeSteps.length > 0 && input.decomposeSteps !== undefined;
+  const fixable = first.removeCriterionLines.length > 0 || first.fuCriterionLines.length > 0 || first.fuStepLines.length > 0 || canRedecompose;
+  if (!fixable) return { document: input.document, reviews: [{ attempt: 1, reauthored: false, items: first.items }] };
+
+  // 1회 재저작 — ① 상 조각 재분해 ⊕ ② ask 밖 목표 제거 ⊕ ③ 미래 가정 FU 화.
+  let document = input.document;
+  let steps = input.steps;
+  let stepsReauthored = false;
+  if (canRedecompose) {
+    const feedback = [
+      'SELF-REVIEW ①: 이전 분해 조각이 난이도 상이거나 하·중·착지 가능·선행을 명시하지 않았다.',
+      `상 조각: ${first.oversizeSteps.join(' · ')}`,
+      '전체 계획을 다시 내라 — 각 조각에 난이도(하|중)·착지 가능·선행을 명시하고, 상 조각은 하·중 조각으로 더 분해하라.',
+    ].join('\n');
+    const reDecomposed = await input.decomposeSteps!(input.ask, {
+      context: feedback,
+      ...(input.runId === undefined ? {} : { runId: input.runId }),
+      ...(input.goalId === undefined ? {} : { goalId: input.goalId }),
+    });
+    if (reDecomposed.length) {
+      const replacementSteps = [...reDecomposed];
+      const replacementDocument = replaceGoalStepsSection(document, replacementSteps);
+      if (replacementDocument !== document) {
+        steps = replacementSteps;
+        document = replacementDocument;
+        stepsReauthored = true;
+      }
+    }
+  }
+  const oversizeStepLines = new Set(canRedecompose ? first.oversizeSteps.map((step) => `- ${step}`) : []);
+  const fuStepLines = first.fuStepLines.filter(([line]) => !oversizeStepLines.has(line));
+  document = reviseGoalDocumentLines(document, { remove: first.removeCriterionLines, fu: [...first.fuCriterionLines, ...fuStepLines] });
+  const fuSteps = new Set(fuStepLines.map(([line]) => line.slice(2)));
+  const second = passGoalSelfReview({
+    document,
+    steps: steps?.filter((step) => !fuSteps.has(step)),
+    modelCriteria,
+    ask: input.ask,
+    inCellPaths,
+    existsOnMain: input.existsOnMain,
+  });
+  const attempt1Items = first.items.map((item) => item.check === 'slice-difficulty' && item.verdict === 'needs-human' && item.slice !== undefined && first.oversizeSteps.includes(item.slice) && stepsReauthored
+    ? { ...item, verdict: 'fixed' as const, fix: '1회 재저작에서 상 조각을 재분해로 대체했다.' }
+    : item);
+  return {
+    document,
+    reviews: [
+      { attempt: 1, reauthored: true, items: attempt1Items },
+      { attempt: 2, reauthored: true, items: second.items },
+    ],
+  };
+}
+
 /** Compose one grounded goal artifact without filesystem, process, pipeline, or daemon effects. */
 export async function authorGoal(ask: string, deps: GoalAuthorDeps): Promise<AuthoredGoal> {
   if ('supersessionRootIntent' in deps) {
@@ -6325,7 +6675,7 @@ async function authorGoalWithSupersededRootIntent(
     ? tracedPathsSection(facts, ask, deps.repositoryRoot, narrative.tracedPathsUnavailableEvidence, authorRunId, deps.recordTracedPath)
     : [];
   if (goalType === 'implement') observeEmptyPersistentEvidence(facts, tracedPathsForDocument, authorRunId);
-  const document = [
+  let document = [
     explicitGoalTitle ?? goalSummary(enhancement.original),
     `- GoalId: ${assignedGoalId}`,
     ...(deps.authoringLessonIds?.length ? [`- AuthoringLessons: ${deps.authoringLessonIds.join(', ')}`] : []),
@@ -6411,6 +6761,38 @@ async function authorGoalWithSupersededRootIntent(
     endAssembleSubphase();
     assembleCompleted = true;
     endGoalAuthorPhase('assemble', assembleStartedAt, authorRunId, deps.onProgress);
+    // ⭐ SELF-REVIEW-PRELAUNCH — assemble 완료 뒤·발사(lint→return→파일 쓰기) 직전에 저작물을 검열한다.
+    //   ⛔ lite 저작은 assemble 단계 자체가 없다 — self-review 는 full 저작 경로에만 붙는다(의도적 경계).
+    //   외부 페이즈 관측 계약(ground→enhance→assemble→lint)은 그대로 보존한다 — 검열 자국은
+    //   author.self-review 관측(attempt·항목별 verdict)으로만 남는다.
+    try {
+      const selfReview = await runGoalAuthorSelfReview({
+        ask,
+        document,
+        steps: resolvedSteps,
+        checklist: enhancement.checklist,
+        facts,
+        decomposeSteps: deps.decomposeSteps,
+        existsOnMain: deps.selfReviewExistsOnMain,
+        runId: authorRunId,
+        goalId: assignedGoalId,
+      });
+      for (const review of selfReview.reviews) {
+        try {
+          observeGoalAuthor('goal-author', 'author.self-review', {
+            authorRunId,
+            goalId: assignedGoalId,
+            attempt: review.attempt,
+            reauthored: review.reauthored,
+            items: review.items,
+          });
+        } catch { /* observation is fail-soft */ }
+      }
+      document = selfReview.document;
+    } catch (error) {
+      // 검열은 저작을 막지 않는다 — 실패는 관측으로 남기고 종전 문서를 그대로 발사한다.
+      try { observeGoalAuthor('goal-author', 'author.self-review-failed', { authorRunId, error: error instanceof Error ? error.message : String(error) }); } catch { /* observation is fail-soft */ }
+    }
     const lintStartedAt = startGoalAuthorPhase('lint', authorRunId, deps.onProgress);
     let lintPassed = false;
     try {
@@ -6616,6 +6998,19 @@ export async function writeAuthoredGoal(
     ...deps,
     repositoryRoot: deps.repositoryRoot ?? groundingRoot,
   };
+  // ⭐ SELF-REVIEW-PRELAUNCH ⑤ — 완료 경계 증거 명령의 origin/main 실행 가능 판정 심(읽기 전용).
+  //    현재 worktree 파일 존재를 main 증거로 오인하지 않는다. ref를 못 읽으면 unknown 으로 남긴다.
+  resolvedDeps.selfReviewExistsOnMain = deps.selfReviewExistsOnMain
+    ?? ((repositoryRelativePath: string) => {
+      try {
+        const entry = execFileSync('git', ['-C', resolvedDeps.repositoryRoot, 'ls-tree', '-r', '--name-only', 'origin/main', '--', repositoryRelativePath], {
+          encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return entry.trim().length > 0;
+      } catch {
+        return undefined;
+      }
+    });
   const mandatoryGoalContextEvidence = goalContextEvidence(cwd);
   const authoringLessons = selectRelevantAuthoringLessons(cwd, ask, elanousStateRoot());
   observeGoalAuthor('goal-author', 'authoring-lessons', {

package/src/self-implement/graph-overlay-yaml.ts

@@ -31,6 +31,8 @@ export interface GraphOverlaySpec {
   /** ⛔ 조건도 «값»이다 — 사람이 판단해 얹는 경로를 두지 않는다. */
   readonly appliesWhen: string;
   readonly patch: readonly OverlayPatchOp[];
+  /** Stop-reason vocabulary lives with heal declarations, not in TypeScript tables. */
+  readonly reasonMap?: Readonly<Record<string, string>>;
 }
 
 export interface OverlayParseResult {
@@ -93,6 +95,10 @@ function overlayFromRaw(raw: unknown, label: string): { overlay?: GraphOverlaySp
   if (!appliesWhen) errors.push({ path: `${label}/applies_when`, message: 'applies_when 이 없거나 문자열이 아니다' });
 
   const patch: OverlayPatchOp[] = [];
+  const reasonMapRaw = doc.reason_map;
+  const reasonMap = reasonMapRaw && typeof reasonMapRaw === 'object' && !Array.isArray(reasonMapRaw)
+    ? Object.fromEntries(Object.entries(reasonMapRaw as Record<string, unknown>).filter((entry): entry is [string, string] => typeof entry[1] === 'string'))
+    : undefined;
   const rawPatch = Array.isArray(doc.patch) ? doc.patch : [];
   if (rawPatch.length === 0) errors.push({ path: `${label}/patch`, message: 'patch 가 비었다 — 아무것도 안 바꾸는 오버레이다' });
   for (const [index, entry] of rawPatch.entries()) {
@@ -109,6 +115,7 @@ function overlayFromRaw(raw: unknown, label: string): { overlay?: GraphOverlaySp
   return {
     overlay: {
       overlayId: overlayId!, target: target!, stage: stage!, appliesWhen: appliesWhen!, patch,
+      ...(reasonMap && Object.keys(reasonMap).length ? { reasonMap } : {}),
     },
     errors,
   };