oh-my-codex 0.18.7 → 0.18.9

package/plugins/oh-my-codex/hooks/codex-native-hook.mjs

@@ -1,10 +1,162 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const hookDir = dirname(fileURLToPath(import.meta.url));
+// sync-plugin-mirror verifies this stable marker; runtime behavior is tested separately.
+const OMX_PLUGIN_HOOK_LAUNCHER_CONTRACT_MARKER = 'omx-plugin-hook-launcher:v1';
+const MAX_WRAPPER_STDIN_BYTES = 1024 * 1024;
+const RAW_EVENT_SCAN_BYTES = 64 * 1024;
+const CODEX_HOOK_EVENT_NAMES = new Set([
+  'SessionStart',
+  'PreToolUse',
+  'PostToolUse',
+  'UserPromptSubmit',
+  'PreCompact',
+  'PostCompact',
+  'Stop',
+]);
+
+function skipJsonWhitespace(raw, index) {
+  while (index < raw.length && /\s/.test(raw[index] ?? '')) index += 1;
+  return index;
+}
+
+function readJsonStringLiteral(raw, quoteIndex) {
+  if (raw[quoteIndex] !== '"') return null;
+  let value = '';
+  for (let index = quoteIndex + 1; index < raw.length; index += 1) {
+    const char = raw[index];
+    if (char === '"') return { value, endIndex: index + 1 };
+    if (char !== '\\') {
+      value += char;
+      continue;
+    }
+
+    index += 1;
+    if (index >= raw.length) return null;
+    const escaped = raw[index];
+    switch (escaped) {
+      case '"':
+      case '\\':
+      case '/':
+        value += escaped;
+        break;
+      case 'b':
+        value += '\b';
+        break;
+      case 'f':
+        value += '\f';
+        break;
+      case 'n':
+        value += '\n';
+        break;
+      case 'r':
+        value += '\r';
+        break;
+      case 't':
+        value += '\t';
+        break;
+      case 'u': {
+        const hex = raw.slice(index + 1, index + 5);
+        if (!/^[0-9a-fA-F]{4}$/.test(hex)) return null;
+        value += String.fromCharCode(Number.parseInt(hex, 16));
+        index += 4;
+        break;
+      }
+      default:
+        return null;
+    }
+  }
+  return null;
+}
+
+function extractTopLevelStringField(rawInput, fieldNames) {
+  const raw = rawInput.slice(0, RAW_EVENT_SCAN_BYTES);
+  const wanted = new Set(fieldNames);
+  let depth = 0;
+  let index = 0;
+
+  while (index < raw.length) {
+    const char = raw[index];
+    if (char === '"') {
+      const key = readJsonStringLiteral(raw, index);
+      if (!key) return null;
+      index = key.endIndex;
+      const afterKey = skipJsonWhitespace(raw, index);
+      if (depth === 1 && raw[afterKey] === ':' && wanted.has(key.value)) {
+        const valueStart = skipJsonWhitespace(raw, afterKey + 1);
+        const value = readJsonStringLiteral(raw, valueStart);
+        return value?.value ?? null;
+      }
+      continue;
+    }
+    if (char === '{') depth += 1;
+    else if (char === '}') depth = Math.max(0, depth - 1);
+    index += 1;
+  }
+
+  return null;
+}
+
+function extractTopLevelHookEventName(rawInput) {
+  const eventName = extractTopLevelStringField(rawInput, ['hook_event_name', 'hookEventName', 'event', 'name']);
+  return CODEX_HOOK_EVENT_NAMES.has(eventName) ? eventName : null;
+}
+
+function detectStopHookInput(input) {
+  const text = input.toString('utf8');
+  try {
+    const parsed = JSON.parse(text);
+    const eventName = parsed?.hook_event_name ?? parsed?.hookEventName ?? parsed?.event ?? parsed?.name;
+    return eventName === 'Stop';
+  } catch {
+    return extractTopLevelHookEventName(text) === 'Stop';
+  }
+}
+
+async function readBoundedStdin() {
+  const chunks = [];
+  let totalBytes = 0;
+  for await (const rawChunk of process.stdin) {
+    const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+    totalBytes += chunk.length;
+    if (totalBytes > MAX_WRAPPER_STDIN_BYTES) {
+      const remaining = MAX_WRAPPER_STDIN_BYTES - Buffer.concat(chunks).length;
+      if (remaining > 0) chunks.push(chunk.subarray(0, remaining));
+      return { input: Buffer.concat(chunks), oversized: true, totalBytes };
+    }
+    chunks.push(chunk);
+  }
+  return { input: Buffer.concat(chunks), oversized: false, totalBytes };
+}
+
+function stopFallbackOutput(stopReason, detail) {
+  const reason = 'OMX plugin Stop hook launcher failed before valid native Stop JSON could be produced. Continue once, preserve runtime state, inspect hook launcher diagnostics, and retry.';
+  return {
+    decision: 'block',
+    reason,
+    stopReason,
+    systemMessage: detail ? `${reason} Failure: ${detail}` : reason,
+  };
+}
+
+function writeStopFallback(stopReason, detail) {
+  process.stdout.write(`${JSON.stringify(stopFallbackOutput(stopReason, detail))}\n`);
+  process.exitCode = 0;
+}
+
+function failLauncher(error, isStop, stopReason = 'plugin_stop_hook_launcher_failure') {
+  const detail = error instanceof Error ? error.message : String(error);
+  console.error(`[oh-my-codex] ${detail}`);
+  if (isStop) {
+    writeStopFallback(stopReason, detail);
+    return;
+  }
+  process.exitCode = 1;
+}
 
 function readPinnedLauncher() {
   const launcherPath = join(hookDir, 'omx-command.json');
@@ -20,8 +172,7 @@ function readPinnedLauncher() {
     return { command: raw.command, argsPrefix };
   } catch (error) {
     if (error?.code === 'ENOENT') return null;
-    console.error(`[oh-my-codex] invalid plugin hook launcher ${launcherPath}: ${error.message}`);
-    process.exit(1);
+    throw new Error(`invalid plugin hook launcher ${launcherPath}: ${error.message}`);
   }
 }
 
@@ -32,25 +183,187 @@ function readConfiguredLauncher() {
   return readPinnedLauncher() ?? { command: 'omx', argsPrefix: [] };
 }
 
-const { command, argsPrefix } = readConfiguredLauncher();
-const child = spawn(command, [...argsPrefix, 'codex-native-hook'], {
-  stdio: ['pipe', 'pipe', 'pipe'],
-  env: process.env,
-  shell: process.platform === 'win32',
-});
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
 
-process.stdin.pipe(child.stdin);
-child.stdout.pipe(process.stdout);
-child.stderr.pipe(process.stderr);
-child.on('error', (error) => {
-  console.error(`[oh-my-codex] failed to launch ${command} codex-native-hook: ${error.message}`);
-  process.exitCode = 1;
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    console.error(`[oh-my-codex] codex-native-hook terminated by ${signal}`);
+function isTerminalOutcome(value) {
+  return ['finish', 'finished', 'complete', 'completed', 'done', 'blocked', 'blocked-on-user', 'blocked_on_user', 'failed', 'fail', 'error', 'cancelled', 'canceled', 'cancel', 'aborted', 'abort', 'userinterlude', 'user-interlude', 'interrupted', 'interrupt', 'askuserquestion', 'ask-user-question', 'askuser', 'question'].includes(String(value ?? '').trim().toLowerCase());
+}
+
+function isTerminalRunStateForMode(state, mode) {
+  if (!state) return false;
+  const runMode = String(state.mode ?? '').trim();
+  if (runMode && runMode !== mode) return false;
+  return isTerminalOutcome(state.outcome)
+    || isTerminalOutcome(state.run_outcome)
+    || isTerminalOutcome(state.lifecycle_outcome)
+    || isTerminalOutcome(state.terminal_outcome);
+}
+
+function canonicalPath(path) {
+  const absolute = resolve(path);
+  if (!existsSync(absolute)) return absolute;
+  try {
+    return typeof realpathSync.native === 'function' ? realpathSync.native(absolute) : realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+function sameFilePath(leftPath, rightPath) {
+  return canonicalPath(leftPath) === canonicalPath(rightPath);
+}
+
+function isSessionStateAuthoritativeForCwd(state, cwd) {
+  if (!isSafeSessionId(state?.session_id)) return false;
+  const sessionCwd = typeof state.cwd === 'string' ? state.cwd.trim() : '';
+  return !sessionCwd || sameFilePath(sessionCwd, cwd);
+}
+
+function listAuthoritativeStateBaseDirs(cwd) {
+  if (process.env.OMX_TEAM_STATE_ROOT?.trim()) return [process.env.OMX_TEAM_STATE_ROOT.trim()];
+  if (process.env.OMX_ROOT?.trim()) return [join(process.env.OMX_ROOT.trim(), '.omx', 'state')];
+  if (process.env.OMX_STATE_ROOT?.trim()) return [join(process.env.OMX_STATE_ROOT.trim(), '.omx', 'state')];
+  return [join(cwd, '.omx', 'state')];
+}
+
+function isSafeSessionId(sessionId) {
+  return typeof sessionId === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(sessionId.trim());
+}
+
+function readCurrentSessionId(stateBaseDirs, cwd) {
+  for (const stateDir of stateBaseDirs) {
+    const session = readJsonFile(join(stateDir, 'session.json'));
+    if (isSessionStateAuthoritativeForCwd(session, cwd)) return session.session_id.trim();
+  }
+  const envSessionId = process.env.OMX_SESSION_ID || process.env.CODEX_SESSION_ID;
+  return isSafeSessionId(envSessionId) ? envSessionId.trim() : null;
+}
+
+function shouldContinueAutopilotState(state) {
+  if (state?.active !== true) return false;
+  return !(isTerminalOutcome(state.current_phase)
+    || isTerminalOutcome(state.run_outcome)
+    || isTerminalOutcome(state.lifecycle_outcome)
+    || isTerminalOutcome(state.terminal_outcome)
+    || isTerminalOutcome(state.outcome)
+    || (typeof state.completed_at === 'string' && state.completed_at.trim() !== ''));
+}
+
+function hasActiveAutopilotStateForOversizedStop(input) {
+  const text = input.toString('utf8');
+  const cwd = extractTopLevelStringField(text, ['cwd']) || process.cwd();
+  const stateBaseDirs = listAuthoritativeStateBaseDirs(cwd);
+  const sessionId = readCurrentSessionId(stateBaseDirs, cwd);
+  if (!isSafeSessionId(sessionId)) return false;
+
+  const sessionDir = join(stateBaseDirs[0], 'sessions', sessionId.trim());
+  const terminalRunState = readJsonFile(join(sessionDir, 'run-state.json'));
+  if (isTerminalRunStateForMode(terminalRunState, 'autopilot')) return false;
+
+  const sessionState = readJsonFile(join(sessionDir, 'autopilot-state.json'));
+  return shouldContinueAutopilotState(sessionState);
+}
+
+function writeJsonNoop() {
+  process.stdout.write(`${JSON.stringify({})}\n`);
+  process.exitCode = 0;
+}
+
+async function main() {
+  const { input, oversized, totalBytes } = await readBoundedStdin();
+  const isStop = detectStopHookInput(input);
+
+  if (oversized) {
+    const message = `plugin hook stdin exceeded ${MAX_WRAPPER_STDIN_BYTES} bytes before launcher delegation; totalBytes>${totalBytes}`;
+    if (isStop) {
+      if (hasActiveAutopilotStateForOversizedStop(input)) {
+        console.error(`[oh-my-codex] ${message}`);
+        writeStopFallback('plugin_stop_hook_stdin_oversized_active_workflow', message);
+        return;
+      }
+      writeJsonNoop();
+      return;
+    }
+    console.error(`[oh-my-codex] ${message}`);
     process.exitCode = 1;
     return;
   }
-  process.exitCode = code ?? 0;
+
+  let launcher;
+  try {
+    launcher = readConfiguredLauncher();
+  } catch (error) {
+    failLauncher(error, isStop);
+    return;
+  }
+
+  const { command, argsPrefix } = launcher;
+  const child = spawn(command, [...argsPrefix, 'codex-native-hook'], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: process.env,
+    shell: process.platform === 'win32',
+  });
+
+  let stdoutBytes = 0;
+  let childSpawnError = null;
+  let childStdinError = null;
+
+  child.stdout.on('data', (chunk) => {
+    stdoutBytes += Buffer.byteLength(chunk);
+    process.stdout.write(chunk);
+  });
+  child.stderr.pipe(process.stderr);
+  child.stdin.on('error', (error) => {
+    childStdinError = error;
+  });
+  child.on('error', (error) => {
+    childSpawnError = error;
+  });
+  child.on('close', (code, signal) => {
+    if (isStop && stdoutBytes === 0) {
+      if (childSpawnError) {
+        writeStopFallback('plugin_stop_hook_launcher_spawn_error', `failed to launch ${command} codex-native-hook: ${childSpawnError.message}`);
+        return;
+      }
+      if (signal) {
+        writeStopFallback('plugin_stop_hook_launcher_signal', `codex-native-hook terminated by ${signal}`);
+        return;
+      }
+      if (code && code !== 0) {
+        if (childStdinError) {
+          writeStopFallback('plugin_stop_hook_launcher_stdin_error', `codex-native-hook stdin failed: ${childStdinError.message}`);
+          return;
+        }
+        writeStopFallback('plugin_stop_hook_launcher_exit', `codex-native-hook exited with code ${code}`);
+        return;
+      }
+      writeStopFallback('plugin_stop_hook_launcher_empty_stdout', 'codex-native-hook exited successfully without producing Stop hook JSON');
+      return;
+    }
+
+    if (childSpawnError) {
+      console.error(`[oh-my-codex] failed to launch ${command} codex-native-hook: ${childSpawnError.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (signal) {
+      console.error(`[oh-my-codex] codex-native-hook terminated by ${signal}`);
+      process.exitCode = 1;
+      return;
+    }
+    process.exitCode = code ?? 0;
+  });
+
+  child.stdin.end(input);
+}
+
+main().catch((error) => {
+  console.error(`[oh-my-codex] plugin hook launcher failed: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
 });

package/plugins/oh-my-codex/hooks/hooks.json

@@ -18,8 +18,7 @@
             "type": "command",
             "command": "node \"${PLUGIN_ROOT}/hooks/codex-native-hook.mjs\""
           }
-        ],
-        "matcher": "Bash"
+        ]
       }
     ],
     "PostToolUse": [

package/plugins/oh-my-codex/skills/autopilot/SKILL.md

@@ -68,12 +68,14 @@ Before Phase `deep-interview` or `ralplan` starts or resumes:
 1. Derive a task slug from the request.
 2. Reuse the latest relevant `.omx/context/{slug}-*.md` snapshot when available.
 3. If none exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
-   - task statement
+   - activation prompt / task seed
+   - original task status (`activation-prompt`, `legacy-unverified`, or `unavailable`)
    - desired outcome
    - known facts/evidence
    - constraints
    - unknowns/open questions
    - likely codebase touchpoints
+   - a scope note that the seed is the Autopilot activation prompt, not guaranteed prior conversation context
 4. If brownfield facts are missing, run `explore` first before or during `$deep-interview` (`$deep-interview --quick <task>` remains acceptable for bounded low-ambiguity intake); do not skip the clarification gate merely because the task sounds actionable.
 5. Carry the snapshot path in Autopilot state and all handoff artifacts.
 </Pre-context Intake>

package/plugins/oh-my-codex/skills/code-review/SKILL.md

@@ -31,7 +31,7 @@ Delegates to the `code-reviewer` and `architect` agents in parallel for a two-la
 2. **Launch Parallel Review Lanes**
    - **`code-reviewer` lane** - owns spec compliance, security, code quality, performance, and maintainability findings
    - **`architect` lane** - owns the devil's-advocate / design-tradeoff perspective
-   - Both lanes run in parallel and produce distinct outputs before final synthesis
+   - Both lanes run in parallel on a clean context with explicit scope and artifacts, and produce distinct outputs before final synthesis
    - If either lane cannot be launched or does not return evidence, report `independent review unavailable`; do **not** substitute the current/authoring lane, and do **not** approve or mark the review merge-ready.
 
 3. **Review Categories**
@@ -71,10 +71,11 @@ Delegates to the `code-reviewer` and `architect` agents in parallel for a two-la
 
 Do not self-review as a fallback. If the `code-reviewer` or `architect` agent path is missing, unavailable, skipped, or fails, emit a clear unavailable-review result and block approval until the independent lane evidence exists.
 
+Respect the user's current model and reasoning/effort selection when launching review lanes. Do not pass `model` or `reasoning_effort` overrides in the review-lane task calls unless the user explicitly asks for review-specific overrides; omitting them lets native subagents inherit the active session settings.
+
 ```
-delegate(
-  role="code-reviewer",
-  tier="THOROUGH",
+task(
+  agent_type="code-reviewer",
   prompt="CODE REVIEW TASK
 
 Review code changes for quality, security, and maintainability.
@@ -98,9 +99,8 @@ Output: Code review report with:
 - Approval recommendation (APPROVE / REQUEST CHANGES / COMMENT)"
 )
 
-delegate(
-  role="architect",
-  tier="THOROUGH",
+task(
+  agent_type="architect",
   prompt="ARCHITECTURE / DEVIL'S-ADVOCATE REVIEW TASK
 
 Review the same code changes from the architecture/tradeoff perspective.

package/plugins/oh-my-codex/skills/deep-interview/SKILL.md

@@ -51,6 +51,11 @@ If no flag is provided, use **Standard**.
 - Gather codebase facts via `explore` before asking user about internals
 - `omx explore` is deprecated. Use normal repository inspection tools/subagents for simple read-only brownfield fact gathering; use `omx sparkshell` only for explicit shell-native read-only evidence, and keep ambiguous or non-shell-only investigation on the richer normal path.
 - Always run a preflight context intake before the first interview question
+- For brownfield work, preflight must include doc/context grounding before user-facing questions: inspect applicable `AGENTS.md` files, README/getting-started docs, relevant `docs/` contracts/plans/ADRs, existing `.omx/context/` snapshots, and any project-local glossary/context files such as `CONTEXT.md` or `CONTEXT-MAP.md` when present.
+- Treat existing repo language as evidence, not authority: if the user uses a fuzzy, overloaded, or conflicting term, surface the specific doc/code wording and ask which meaning should govern before implementation.
+- Cross-check user claims about current behavior against code or documented contracts when discoverable. If docs and code disagree, ask a confirmation question that names both sources instead of silently choosing one.
+- Use scenario-based edge-case grilling when relationships, boundaries, or handoff behavior are unclear: invent one concrete scenario that stresses the ambiguous boundary, then ask one focused question about the expected outcome.
+- Durable docs, glossary, ADR, or memory updates are opt-in and public-safe only. Deep-interview may recommend such updates in the handoff summary, but must not automatically create or dump public docs from interview transcripts unless the user explicitly chooses that as in-scope.
 - If initial context is oversized or would exceed the prompt budget, do not paste or forward the raw payload into interview prompts; request and record a prompt-safe initial-context summary first
 - The oversized initial-context summary gate is blocking: wait for the concise summary before ambiguity scoring, crystallizing artifacts, or any downstream execution handoff
 - The summary must preserve goals, constraints, success criteria, non-goals, decision boundaries, and references to any full source documents so downstream consumers receive a prompt-safe but faithful context
@@ -97,8 +102,15 @@ If no flag is provided, use **Standard**.
    - Unknowns/open questions
    - Decision-boundary unknowns
    - Likely codebase touchpoints
+   - Relevant repo docs/rules/context inspected
+   - Terminology or doc/code conflicts found
    - Prompt-safe initial-context summary status (`not_needed`, `needed`, or `recorded`)
-5. Save snapshot to `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) and reference it in mode state.
+5. For brownfield tasks, inspect the applicable documentation/rule surface before the first user-facing round. Prefer exact, nearby sources over broad scans:
+   - governing `AGENTS.md` files and template/runtime instruction surfaces that apply to the touched paths
+   - README/getting-started docs and relevant docs under `docs/`, especially contracts, plans, ADR-like records, and workflow docs
+   - existing `.omx/context/` snapshots, `.omx/specs/`, and planning artifacts relevant to the slug
+   - project-local glossary/context files such as `CONTEXT.md`, `CONTEXT-MAP.md`, or context-specific docs when they exist
+6. Save snapshot to `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) and reference it in mode state.
 
 ## Phase 1: Initialize
 
@@ -137,13 +149,14 @@ If no flag is provided, use **Standard**.
 Repeat until ambiguity `<= threshold`, the pressure pass is complete, the readiness gates are explicit, the user exits with warning, or max rounds are reached. This is a stop condition: below threshold, do not open a new ordinary interview branch.
 
 ### 2a) Generate next question
-If the initial context is oversized and no prompt-safe summary has been recorded yet, the next question must be only a summary request. Do not score ambiguity, do not run readiness gates, and do not hand off to `$ralplan`, `$autopilot`, `$ralph`, or `$team` until that summary answer is captured.
+If the initial context is oversized and no prompt-safe summary has been recorded yet, the next question must be only a summary request. Do not score ambiguity, do not run readiness gates, and do not hand off to `$ultragoal`, `$ralplan`, `$autopilot`, `$ralph`, or `$team` until that summary answer is captured.
 
 Use:
 - Original idea
 - Prior Q&A rounds
 - Current dimension scores
 - Brownfield context (if any)
+- Doc/context grounding notes, including existing terminology, governing rules, and any doc/code mismatch
 - Activated challenge mode injection (Phase 3)
 
 Target the lowest-scoring dimension, but respect stage priority:
@@ -155,12 +168,21 @@ Follow-up pressure ladder after each answer:
 1. Ask for a concrete example, counterexample, or evidence signal behind the latest claim
 2. Probe the hidden assumption, dependency, or belief that makes the claim true
 3. Force a boundary or tradeoff: what would you explicitly not do, defer, or reject?
-4. If the answer still describes symptoms, reframe toward essence / root cause before moving on
+4. Challenge fuzzy or conflicting terms against the repo's documented language and current code behavior
+5. Stress-test the boundary with one concrete scenario or edge case when a relationship or handoff remains ambiguous
+6. If the answer still describes symptoms, reframe toward essence / root cause before moving on
 
 Prefer staying on the same thread for multiple rounds when it has the highest leverage. Breadth without pressure is not progress.
 
 Maintain a **Breadth Ledger** across independent ambiguity tracks: scope, constraints, outputs, verification, brownfield integration, and any user-mentioned deliverable tracks. The ledger is a guard, not a mandatory rotation rule: stay deep on the current thread until it has been pressure-tested, then zoom out only when another material track remains unresolved and would change execution.
 
+Maintain a **Docs/Terminology Ledger** for brownfield interviews:
+- repo docs/rules/context sources inspected, with path references
+- canonical terms already used by the repo and terms to avoid or disambiguate
+- user terms that conflict with docs or current code behavior
+- doc/code mismatches that require a human decision before implementation
+- optional durable-doc follow-ups that are safe to propose but not auto-apply
+
 Detailed dimensions:
 - Intent Clarity — why the user wants this
 - Outcome Clarity — what end state they want
@@ -306,6 +328,7 @@ Append round result and updated scores via `omx state write --input '<json>' --j
 Use each mode once when applicable. These are normal escalation tools, not rare rescue moves:
 
 - **Contrarian** (round 2+ or immediately when an answer rests on an untested assumption): challenge core assumptions
+- **Terminologist** (brownfield, whenever a key term is fuzzy, overloaded, or conflicts with repo docs/code): force a canonical meaning against existing project language before implementation
 - **Simplifier** (round 4+ or when scope expands faster than outcome clarity): probe minimal viable scope
 - **Ontologist** (round 5+ and ambiguity > 0.25, or when the user keeps describing symptoms): ask for essence-level reframing
 
@@ -336,6 +359,9 @@ Spec should include:
 - Assumptions exposed + resolutions
 - Pressure-pass findings (which answer was revisited, and what changed)
 - Brownfield evidence vs inference notes for any repository-grounded confirmation questions
+- Docs/Terminology Ledger with inspected repo docs/rules/context, term conflicts, and any doc/code mismatch decisions
+- Scenario/edge-case pressure findings that materially shaped scope or acceptance criteria
+- Optional durable documentation recommendations, explicitly marked opt-in and public-safe; do not include raw private transcript dumps
 - Technical context findings
 - Full or condensed transcript
 
@@ -365,11 +391,11 @@ When the clarified task is specifically about `$autoresearch`, or the skill is i
 
 ## Phase 5: Execution Bridge
 
-Present execution options after artifact generation using explicit handoff contracts. Treat the deep-interview spec as the current requirements source of truth and preserve intent, non-goals, decision boundaries, acceptance criteria, and any residual-risk warnings across the handoff.
+Present execution options after artifact generation using explicit handoff contracts. Treat the deep-interview spec as the current requirements source of truth and preserve intent, non-goals, decision boundaries, acceptance criteria, docs/terminology grounding, and any residual-risk warnings across the handoff.
 
 ### Goal-mode follow-ups
 
-Include these product-facing suggestions when they fit the clarified spec, without removing the existing `$ralplan`, `$autopilot`, `$ralph`, and `$team` handoff options:
+Include these product-facing suggestions when they fit the clarified spec, without removing the existing `$ultragoal`, `$ralplan`, `$autopilot`, `$ralph`, and `$team` handoff options:
 
 - **`$ultragoal`** — default goal-mode follow-up for implementation or general goal-oriented follow-up specs that should be converted into durable Codex/OMX goals with sequential completion tracking.
 - **`$autoresearch-goal`** — use when the clarified context is a research project: a research question, reference/literature gathering, evaluator-backed analysis, or professor/critic-style deliverable.
@@ -377,7 +403,16 @@ Include these product-facing suggestions when they fit the clarified spec, witho
 
 Recommend `$ultragoal` as the default durable goal-mode follow-up because it supersedes Ralph for goal tracking. Preserve `$team` for coordinated parallel implementation and keep `$ralph` only as an explicit fallback for persistent single-owner execution/verification when the user specifically selects it.
 
-### 1. **`$ralplan` (Recommended)**
+### 1. **`$ultragoal` (Default durable execution follow-up)**
+- **Input Artifact:** `.omx/specs/deep-interview-{slug}.md` (optionally accompanied by the transcript/context snapshot for traceability)
+- **Invocation:** `$ultragoal create-goals --brief-file <spec-path>` followed by `$ultragoal complete-goals` in the active execution lane
+- **Consumer Behavior:** Convert the clarified spec into durable goal-mode work. Preserve intent, non-goals, decision boundaries, acceptance criteria, docs/terminology grounding, scenario-pressure findings, and residual-risk warnings as binding story constraints.
+- **Skipped / Already-Satisfied Stages:** Requirement interview, ambiguity clarification, doc/context preflight, and early intent-boundary elicitation
+- **Expected Output:** `.omx/ultragoal/brief.md`, `.omx/ultragoal/goals.json`, `.omx/ultragoal/ledger.jsonl`, implementation evidence, verification evidence, and final cleanup/review-gate evidence
+- **Best When:** The clarified spec is execution-ready or the user explicitly wants durable goal tracking as the next step
+- **Next Recommended Step:** Run the Ultragoal completion loop; launch `$team` only inside an active Ultragoal story when parallel lanes are warranted, and use `$ralph` only as an explicit fallback when the user asks for that legacy persistence mode
+
+### 2. **`$ralplan` (Recommended when architecture/test-shape review is still needed)**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md` (optionally accompanied by the transcript/context snapshot for traceability)
 - **Invocation:** `$plan --consensus --direct <spec-path>`
 - **Consumer Behavior:** Treat the deep-interview spec as the requirements source of truth. Do not repeat the interview by default; refine architecture/feasibility around the clarified intent and boundaries instead.
@@ -386,7 +421,7 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 - **Best When:** Requirements are clear enough to stop interviewing, but architectural validation / consensus planning is still desirable
 - **Next Recommended Step:** Use the approved planning artifacts with `$ultragoal` as the default durable goal-mode follow-up (optionally with `$team` for parallel lanes); choose `$autoresearch-goal` for research validation or `$performance-goal` for measurable optimization, and use `$ralph` only as an explicit fallback when a narrow single-owner persistence loop is requested
 
-### 2. **`$autopilot`**
+### 3. **`$autopilot`**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md`
 - **Invocation:** `$autopilot <spec-path>`
 - **Consumer Behavior:** Use the deep-interview spec as the clarified execution brief. Preserve intent, non-goals, decision boundaries, and acceptance criteria as binding context for planning/execution.
@@ -395,7 +430,7 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 - **Best When:** The clarified spec is already strong enough for direct planning + execution without an additional consensus gate
 - **Next Recommended Step:** Continue through autopilot's execution/QA/validation flow; if coordination-heavy execution emerges, prefer `$team` under a leader-owned `$ultragoal` ledger, using `$ralph` only as an explicit fallback when a narrow single-owner persistence loop is requested
 
-### 3. **`$ralph` (Explicit fallback only)**
+### 4. **`$ralph` (Explicit fallback only)**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md`
 - **Invocation:** `$ralph <spec-path>`
 - **Consumer Behavior:** Use the spec's acceptance criteria and boundary constraints as the persistence target. Do not reopen requirements discovery unless the user explicitly asks to refine further.
@@ -404,7 +439,7 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 - **Best When:** The user explicitly asks for Ralph's persistent sequential completion pressure; otherwise use `$ultragoal` for durable goal tracking and completion checkpoints
 - **Next Recommended Step:** If this explicit fallback is selected, continue Ralph's persistence loop; if work expands into coordination-heavy lanes, hand off to `$team` under `$ultragoal` checkpointing rather than promoting Ralph as the next default
 
-### 4. **`$team`**
+### 5. **`$team`**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md`
 - **Invocation:** `$team <spec-path>`
 - **Consumer Behavior:** Treat the spec as shared execution context for coordinated parallel work. Preserve the clarified intent, non-goals, decision boundaries, and acceptance criteria as common lane constraints.
@@ -413,7 +448,7 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 - **Best When:** The task is large, multi-lane, or blocker-sensitive enough to justify coordinated parallel execution instead of a single persistent loop
 - **Next Recommended Step:** Follow the team verification path when the coordinated execution phase finishes; checkpoint completion through `$ultragoal` by default, escalating to a separate Ralph loop only when the user explicitly asks for that persistent verification/fix owner
 
-### 5. **Refine further**
+### 6. **Refine further**
 - **Input Artifact:** Existing transcript, context snapshot, and current spec draft
 - **Invocation:** Continue the interview loop
 - **Consumer Behavior:** Re-enter questioning to resolve the highest-leverage remaining uncertainty
@@ -437,6 +472,7 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 - Use `omx state write/read --input '<json>' --json` for resumable mode state; `state_write` / `state_read` are explicit MCP compatibility fallbacks only
 - If the interview cannot ask a required `omx question` round, persist the blocker as terminal state with `active: false` and `current_phase: "blocked"`; do not write a terminal blocked phase with `active: true`
 - Read/write context snapshots under `.omx/context/`
+- Read applicable repo docs/rules/context during preflight; write durable docs, glossary, ADR, or memory updates only when the user explicitly opts in and the content is public-safe
 - Record whether the oversized-context summary gate is not needed, pending, or satisfied before any scoring or handoff step
 - Save transcript/spec artifacts under `.omx/interviews/` and `.omx/specs/`
 </Tool_Usage>
@@ -460,7 +496,11 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 - [ ] Transcript written to `.omx/interviews/{slug}-{timestamp}.md`
 - [ ] Spec written to `.omx/specs/deep-interview-{slug}.md`
 - [ ] Brownfield questions use evidence-backed confirmation when applicable
-- [ ] Handoff options provided (`$ralplan`, `$autopilot`, `$ralph`, `$team`) plus context-sensitive goal-mode suggestions (`$ultragoal`, `$autoresearch-goal`, `$performance-goal`) when applicable
+- [ ] Brownfield preflight inspected applicable repo docs/rules/context before user-facing questions
+- [ ] Fuzzy or conflicting terminology was challenged against repo language/current code behavior when applicable
+- [ ] Scenario-based edge-case grilling was used when boundary ambiguity would materially affect implementation
+- [ ] Durable docs/ADR/memory updates, if any, were explicitly opted into and public-safe
+- [ ] Handoff options provided (`$ultragoal`, `$ralplan`, `$autopilot`, `$ralph`, `$team`) plus context-sensitive goal-mode suggestions (`$autoresearch-goal`, `$performance-goal`) when applicable
 - [ ] No direct implementation performed in this mode
 </Final_Checklist>