cclaw-cli 1.0.0 → 2.0.0

package/dist/content/node-hooks.js

@@ -83,6 +83,10 @@ const EARLY_LOOP_ENABLED = ${JSON.stringify(earlyLoopEnabled)};
 const EARLY_LOOP_MAX_ITERATIONS = ${JSON.stringify(earlyLoopMaxIterations)};
 const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
 const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
+const SESSION_DIGEST_SCHEMA_VERSION = 1;
+const SESSION_DIGEST_CACHE_FILE = "session-digest.json";
+const SESSION_DIGEST_REFRESH_MARKER_FILE = "session-digest.refresh.json";
+const SESSION_DIGEST_REFRESH_STALE_MS = 30000;
 
 ${SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS}
 ${SHARED_STAGE_SUPPORT_SNIPPETS}
@@ -508,9 +512,10 @@ function hookEventNameForOutput(hookName) {
   if (hookName === "session-start") return "SessionStart";
   if (hookName === "prompt-guard") return "PreToolUse";
   if (hookName === "workflow-guard") return "PreToolUse";
+  if (hookName === "pre-tool-pipeline") return "PreToolUse";
+  if (hookName === "prompt-pipeline") return "UserPromptSubmit";
   if (hookName === "context-monitor") return "PostToolUse";
   if (hookName === "stop-handoff") return "Stop";
-  if (hookName === "pre-compact") return "PreCompact";
   if (hookName === "verify-current-state") return "UserPromptSubmit";
   return "SessionStart";
 }
@@ -919,78 +924,55 @@ async function readFlowState(root) {
   };
 }
 
-
-async function buildKnowledgeDigest(root, currentStage, prereadRaw) {
-  const knowledgeFile = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
-  // Caller may supply pre-read raw bytes to avoid re-reading knowledge.jsonl.
-  // Falls back to a local read if nothing is passed in.
-  const raw = typeof prereadRaw === "string"
-    ? prereadRaw
-    : await readTextFile(knowledgeFile, "");
-  const digest = parseKnowledgeDigest(raw, currentStage, 6);
-  return {
-    digestLines: digest.lines,
-    learningsCount: digest.learningsCount
-  };
+async function readFileMtimeMs(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) return 0;
+    return Math.trunc(stat.mtimeMs);
+  } catch {
+    return 0;
+  }
 }
 
-async function readStageSupportContext(root, currentStage) {
-  if (!isKnownStageId(currentStage)) return [];
-  const stage = currentStage;
-
-  const parts = [];
-  const contractPath = path.join(root, RUNTIME_ROOT, "templates", "state-contracts", stage + ".json");
-  const contract = (await readTextFile(contractPath, "")).trim();
-  if (contract.length > 0) {
-    parts.push(
-      "Current stage state contract (read before drafting or editing the stage artifact):\\n" +
-        contract
-    );
-  }
+function parseNumericMs(value) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.trunc(value)
+    : -1;
+}
 
-  const promptName = reviewPromptFileName(stage);
-  if (typeof promptName === "string") {
-    const promptPath = path.join(root, RUNTIME_ROOT, "skills", "review-prompts", promptName);
-    const prompt = (await readTextFile(promptPath, "")).trim();
-    if (prompt.length > 0) {
-      parts.push(
-        "Current stage calibrated review prompt (use before asking for approval/completion):\\n" +
-          prompt
-      );
-    }
+async function readSessionDigestLines(stateDir, state, flowStateMtimeMs) {
+  const cachePath = path.join(stateDir, SESSION_DIGEST_CACHE_FILE);
+  const cache = toObject(await readJsonFile(cachePath, {})) || {};
+  const cachedMtimeMs = parseNumericMs(cache.flowStateMtimeMs);
+  const sameStage = typeof cache.currentStage === "string" ? cache.currentStage === state.currentStage : true;
+  const sameRun = typeof cache.activeRunId === "string" ? cache.activeRunId === state.activeRunId : true;
+  const fresh = cachedMtimeMs === flowStateMtimeMs && sameStage && sameRun;
+  if (!fresh) {
+    return {
+      ralphLoopLine: "",
+      earlyLoopLine: "",
+      compoundReadinessLine: "",
+      fresh: false
+    };
   }
-
-  return parts;
+  return {
+    ralphLoopLine: typeof cache.ralphLoopLine === "string" ? cache.ralphLoopLine : "",
+    earlyLoopLine: typeof cache.earlyLoopLine === "string" ? cache.earlyLoopLine : "",
+    compoundReadinessLine: typeof cache.compoundReadinessLine === "string" ? cache.compoundReadinessLine : "",
+    fresh: true
+  };
 }
 
-async function handleSessionStart(runtime) {
-  const state = await readFlowState(runtime.root);
-  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
-  const ironLawsFile = path.join(stateDir, "iron-laws.json");
-  const metaSkillFile = path.join(runtime.root, RUNTIME_ROOT, "skills", "using-cclaw", "SKILL.md");
-
-
-  // Read knowledge.jsonl exactly once per session-start while holding the
-  // SAME lock CLI writers acquire in \`appendKnowledge\`. Guarantees we never
-  // see a partial (mid-write) snapshot. Both the digest and
-  // compound-readiness derive from this single read.
-  const knowledgeFilePath = path.join(runtime.root, RUNTIME_ROOT, "knowledge.jsonl");
-  const knowledgeRaw = await readTextFileLocked(
-    knowledgeLockPathInline(runtime.root),
-    knowledgeFilePath,
-    ""
-  );
-  const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage, knowledgeRaw);
-
-  // Refresh Ralph Loop status each session-start so /cc and the model
-  // both read a consistent "iter=N, acClosed=[...]" snapshot. Runs only when
-  // we are in tdd — other stages skip the write to keep the file stable.
+async function refreshSessionDigestCache(root, state, flowStateMtimeMs) {
+  const stateDir = path.join(root, RUNTIME_ROOT, "state");
   let ralphLoopLine = "";
   let earlyLoopLine = "";
+  let compoundReadinessLine = "";
+
   if (state.currentStage === "tdd") {
     try {
       const internalRalph = await runCclawInternal(
-        runtime.root,
+        root,
         ["tdd-loop-status", "--json", "--write"],
         { captureStdout: true }
       );
@@ -1003,12 +985,8 @@ async function handleSessionStart(runtime) {
       }
       ralphLoopLine = formatRalphLoopStatusLineFromJson(ralphStatus);
     } catch (err) {
-      // Best-effort — a malformed cycle log should never break
-      // session-start. But we DO leave a breadcrumb in
-      // hook-errors.jsonl so \`npx cclaw-cli sync\` can surface chronic
-      // failures (previously this was a silent swallow).
       await recordHookError(
-        runtime.root,
+        root,
         "session-start:ralph-loop",
         err instanceof Error ? err.message : String(err)
       );
@@ -1020,7 +998,7 @@ async function handleSessionStart(runtime) {
   ) {
     try {
       const internalEarly = await runCclawInternal(
-        runtime.root,
+        root,
         [
           "early-loop-status",
           "--json",
@@ -1042,21 +1020,17 @@ async function handleSessionStart(runtime) {
       earlyLoopLine = formatEarlyLoopStatusLineFromJson(earlyLoopStatus);
     } catch (err) {
       await recordHookError(
-        runtime.root,
+        root,
         "session-start:early-loop",
         err instanceof Error ? err.message : String(err)
       );
     }
   }
 
-  // Keep compound-readiness.json fresh on every session-start (cheap derived
-  // summary). Surface a one-line nudge only from review and ship stages
-  // where lifting becomes relevant; earlier stages update the file silently.
-  let compoundReadinessLine = "";
   try {
     const shouldShowReadiness = state.currentStage === "review" || state.currentStage === "ship";
     const internalReadiness = await runCclawInternal(
-      runtime.root,
+      root,
       shouldShowReadiness ? ["compound-readiness"] : ["compound-readiness", "--quiet"],
       { captureStdout: true }
     );
@@ -1067,17 +1041,169 @@ async function handleSessionStart(runtime) {
       compoundReadinessLine = firstStdoutLine(internalReadiness.stdout);
     }
   } catch (err) {
-    // Best-effort — a malformed knowledge.jsonl must never break
-    // session-start. But we DO leave a breadcrumb in
-    // hook-errors.jsonl so config/IO problems become visible in
-    // \`npx cclaw-cli sync\` instead of silently degrading readiness output.
     await recordHookError(
-      runtime.root,
+      root,
       "session-start:compound-readiness",
       err instanceof Error ? err.message : String(err)
     );
   }
 
+  const digestPath = path.join(stateDir, SESSION_DIGEST_CACHE_FILE);
+  await writeJsonFile(digestPath, {
+    schemaVersion: SESSION_DIGEST_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    flowStateMtimeMs,
+    currentStage: state.currentStage,
+    activeRunId: state.activeRunId,
+    ralphLoopLine,
+    earlyLoopLine,
+    compoundReadinessLine
+  });
+}
+
+async function scheduleSessionDigestRefresh(runtime, state, flowStateMtimeMs) {
+  if (flowStateMtimeMs <= 0) return;
+  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
+  const digestPath = path.join(stateDir, SESSION_DIGEST_CACHE_FILE);
+  const markerPath = path.join(stateDir, SESSION_DIGEST_REFRESH_MARKER_FILE);
+
+  const cache = toObject(await readJsonFile(digestPath, {})) || {};
+  const cachedMtimeMs = parseNumericMs(cache.flowStateMtimeMs);
+  if (cachedMtimeMs === flowStateMtimeMs) return;
+
+  const marker = toObject(await readJsonFile(markerPath, {})) || {};
+  const markerMtimeMs = parseNumericMs(marker.flowStateMtimeMs);
+  const markerStartedAtMs = parseNumericMs(marker.startedAtMs);
+  const markerFresh =
+    markerMtimeMs === flowStateMtimeMs &&
+    markerStartedAtMs > 0 &&
+    Date.now() - markerStartedAtMs < SESSION_DIGEST_REFRESH_STALE_MS;
+  if (markerFresh) return;
+
+  await writeJsonFile(markerPath, {
+    flowStateMtimeMs,
+    startedAtMs: Date.now(),
+    currentStage: state.currentStage,
+    activeRunId: state.activeRunId
+  });
+
+  try {
+    const child = spawn(process.execPath, [process.argv[1], "session-start-refresh"], {
+      cwd: runtime.root,
+      stdio: "ignore",
+      windowsHide: true,
+      detached: true,
+      env: {
+        ...process.env,
+        CCLAW_PROJECT_ROOT: runtime.root,
+        CCLAW_BG_WORKER: "1"
+      }
+    });
+    child.unref();
+  } catch (err) {
+    await fs.rm(markerPath, { force: true }).catch(() => undefined);
+    await recordHookError(
+      runtime.root,
+      "session-start:spawn-refresh",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+async function handleSessionStartRefresh(runtime) {
+  const state = await readFlowState(runtime.root);
+  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
+  const markerPath = path.join(stateDir, SESSION_DIGEST_REFRESH_MARKER_FILE);
+  try {
+    const flowStateMtimeMs = await readFileMtimeMs(state.filePath);
+    await refreshSessionDigestCache(runtime.root, state, flowStateMtimeMs);
+  } finally {
+    await fs.rm(markerPath, { force: true }).catch(() => undefined);
+  }
+  return 0;
+}
+
+
+async function buildKnowledgeDigest(root, currentStage, prereadRaw) {
+  const knowledgeFile = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
+  // Caller may supply pre-read raw bytes to avoid re-reading knowledge.jsonl.
+  // Falls back to a local read if nothing is passed in.
+  const raw = typeof prereadRaw === "string"
+    ? prereadRaw
+    : await readTextFile(knowledgeFile, "");
+  const digest = parseKnowledgeDigest(raw, currentStage, 6);
+  return {
+    digestLines: digest.lines,
+    learningsCount: digest.learningsCount
+  };
+}
+
+async function readStageSupportContext(root, currentStage) {
+  if (!isKnownStageId(currentStage)) return [];
+  const stage = currentStage;
+
+  const parts = [];
+  const contractPath = path.join(root, RUNTIME_ROOT, "templates", "state-contracts", stage + ".json");
+  const contract = (await readTextFile(contractPath, "")).trim();
+  if (contract.length > 0) {
+    parts.push(
+      "Current stage state contract (read before drafting or editing the stage artifact):\\n" +
+        contract
+    );
+  }
+
+  const promptName = reviewPromptFileName(stage);
+  if (typeof promptName === "string") {
+    const promptPath = path.join(root, RUNTIME_ROOT, "skills", "review-prompts", promptName);
+    const prompt = (await readTextFile(promptPath, "")).trim();
+    if (prompt.length > 0) {
+      parts.push(
+        "Current stage calibrated review prompt (use before asking for approval/completion):\\n" +
+          prompt
+      );
+    }
+  }
+
+  return parts;
+}
+
+async function handleSessionStart(runtime) {
+  const state = await readFlowState(runtime.root);
+  const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
+  const ironLawsFile = path.join(stateDir, "iron-laws.json");
+  const metaSkillFile = path.join(runtime.root, RUNTIME_ROOT, "skills", "using-cclaw", "SKILL.md");
+
+
+  // Read knowledge.jsonl exactly once per session-start while holding the
+  // SAME lock CLI writers acquire in \`appendKnowledge\`. Guarantees we never
+  // see a partial (mid-write) snapshot. Both the digest and
+  // compound-readiness derive from this single read.
+  const knowledgeFilePath = path.join(runtime.root, RUNTIME_ROOT, "knowledge.jsonl");
+  const knowledgeRaw = await readTextFileLocked(
+    knowledgeLockPathInline(runtime.root),
+    knowledgeFilePath,
+    ""
+  );
+  const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage, knowledgeRaw);
+
+  // Fast path: read precomputed status lines from session-digest cache.
+  // If cache is stale, schedule a debounced background refresh so this hook
+  // returns quickly inside harness startup.
+  const flowStateMtimeMs = await readFileMtimeMs(state.filePath);
+  const forceSyncRefresh =
+    normalizeText(process.env.CCLAW_SESSION_START_BG_SYNC).toLowerCase() === "1" ||
+    ["1", "true", "yes"].includes(normalizeText(process.env.VITEST).toLowerCase());
+  let sessionDigest = await readSessionDigestLines(stateDir, state, flowStateMtimeMs);
+  if (forceSyncRefresh && flowStateMtimeMs > 0) {
+    await refreshSessionDigestCache(runtime.root, state, flowStateMtimeMs);
+    sessionDigest = await readSessionDigestLines(stateDir, state, flowStateMtimeMs);
+  } else if (!sessionDigest.fresh) {
+    await scheduleSessionDigestRefresh(runtime, state, flowStateMtimeMs);
+  }
+  const ralphLoopLine = sessionDigest.ralphLoopLine;
+  const earlyLoopLine = sessionDigest.earlyLoopLine;
+  const compoundReadinessLine = sessionDigest.compoundReadinessLine;
+
   const ironLawsObj = toObject(await readJsonFile(ironLawsFile, {})) || {};
   const laws = Array.isArray(ironLawsObj.laws) ? ironLawsObj.laws : [];
   const ironLawLines = laws
@@ -1091,6 +1217,15 @@ async function handleSessionStart(runtime) {
     });
   const staleStages = toObject(state.raw.staleStages) || {};
   const staleStageNames = Object.keys(staleStages);
+  const interactionHints = toObject(state.raw.interactionHints) || {};
+  const stageInteractionHint = toObject(interactionHints[state.currentStage]);
+  const skipQuestionsHintActive = stageInteractionHint?.skipQuestions === true;
+  const skipQuestionsSource = typeof stageInteractionHint?.sourceStage === "string"
+    ? stageInteractionHint.sourceStage
+    : "";
+  const skipQuestionsRecordedAt = typeof stageInteractionHint?.recordedAt === "string"
+    ? stageInteractionHint.recordedAt
+    : "";
   const metaContent = (await readTextFile(metaSkillFile, "")).trim();
   const stageSupportContext = await readStageSupportContext(runtime.root, state.currentStage);
 
@@ -1123,6 +1258,14 @@ async function handleSessionStart(runtime) {
         " (use npx cclaw-cli internal rewind --ack <stage> after redo)."
     );
   }
+  if (skipQuestionsHintActive) {
+    parts.push(
+      "Adaptive elicitation hint: this stage inherits a prior user stop signal (--skip-questions" +
+        (skipQuestionsSource ? " from " + skipQuestionsSource : "") +
+        (skipQuestionsRecordedAt ? " at " + skipQuestionsRecordedAt : "") +
+        "). Draft with available context unless irreversible/security override checks still require explicit confirmation."
+    );
+  }
   if (knowledge.digestLines.length > 0) {
     parts.push(
       "Knowledge digest (top relevant entries):\\n" +
@@ -1235,10 +1378,6 @@ async function handleStopHandoff(runtime) {
   return 0;
 }
 
-async function handlePreCompact(_runtime) {
-  return 0;
-}
-
 async function handlePromptGuard(runtime) {
   const mode = resolveStrictness();
   const stateDir = path.join(runtime.root, RUNTIME_ROOT, "state");
@@ -1740,15 +1879,38 @@ async function handleVerifyCurrentState(runtime) {
   return 0;
 }
 
+async function handlePreToolPipeline(runtime) {
+  const promptExitCode = await handlePromptGuard(runtime);
+  if (promptExitCode !== 0) {
+    return promptExitCode;
+  }
+  return await handleWorkflowGuard(runtime);
+}
+
+async function handlePromptPipeline(runtime) {
+  const promptExitCode = await handlePromptGuard(runtime);
+  if (promptExitCode !== 0) {
+    return promptExitCode;
+  }
+  const verifyExitCode = await handleVerifyCurrentState(runtime);
+  if (verifyExitCode !== 0) {
+    return verifyExitCode;
+  }
+  runtime.writeJson({ ok: true });
+  return 0;
+}
+
 function normalizeHookName(rawName) {
   const value = normalizeText(rawName).toLowerCase();
   if (value === "session-start") return "session-start";
+  if (value === "session-start-refresh") return "session-start-refresh";
   if (value === "stop-handoff" || value === "stop") return "stop-handoff";
   if (value === "stop-checkpoint") return "stop-handoff";
-  if (value === "pre-compact" || value === "precompact") return "pre-compact";
   if (value === "session-rehydrate") return "session-start";
   if (value === "prompt-guard") return "prompt-guard";
   if (value === "workflow-guard") return "workflow-guard";
+  if (value === "pre-tool-pipeline" || value === "pretool-pipeline") return "pre-tool-pipeline";
+  if (value === "prompt-pipeline" || value === "promptpipeline") return "prompt-pipeline";
   if (value === "context-monitor") return "context-monitor";
   if (value === "verify-current-state") return "verify-current-state";
   return "";
@@ -1760,7 +1922,7 @@ async function main() {
     process.stderr.write(
       "[cclaw] run-hook: usage: node " +
         RUNTIME_ROOT +
-        "/hooks/run-hook.mjs <session-start|stop-handoff|pre-compact|prompt-guard|workflow-guard|context-monitor|verify-current-state>\\n"
+        "/hooks/run-hook.mjs <session-start|session-start-refresh|stop-handoff|prompt-guard|workflow-guard|pre-tool-pipeline|prompt-pipeline|context-monitor|verify-current-state>\\n"
     );
     process.exitCode = 1;
     return;
@@ -1792,12 +1954,12 @@ async function main() {
       process.exitCode = await handleSessionStart(runtime);
       return;
     }
-    if (hookName === "stop-handoff") {
-      process.exitCode = await handleStopHandoff(runtime);
+    if (hookName === "session-start-refresh") {
+      process.exitCode = await handleSessionStartRefresh(runtime);
       return;
     }
-    if (hookName === "pre-compact") {
-      process.exitCode = await handlePreCompact(runtime);
+    if (hookName === "stop-handoff") {
+      process.exitCode = await handleStopHandoff(runtime);
       return;
     }
     if (hookName === "prompt-guard") {
@@ -1808,6 +1970,14 @@ async function main() {
       process.exitCode = await handleWorkflowGuard(runtime);
       return;
     }
+    if (hookName === "pre-tool-pipeline") {
+      process.exitCode = await handlePreToolPipeline(runtime);
+      return;
+    }
+    if (hookName === "prompt-pipeline") {
+      process.exitCode = await handlePromptPipeline(runtime);
+      return;
+    }
     if (hookName === "context-monitor") {
       process.exitCode = await handleContextMonitor(runtime);
       return;

package/dist/content/observe.js

@@ -56,20 +56,20 @@ function buildCursorEvents() {
 }
 export function claudeHooksJsonWithObservation() {
     return JSON.stringify({
-        cclawHookSchemaVersion: 1,
+        cclawHookSchemaVersion: 2,
         hooks: buildClaudeLikeEvents("claude")
     }, null, 2);
 }
 export function cursorHooksJsonWithObservation() {
     return JSON.stringify({
-        cclawHookSchemaVersion: 1,
+        cclawHookSchemaVersion: 2,
         version: 1,
         hooks: buildCursorEvents()
     }, null, 2);
 }
 export function codexHooksJsonWithObservation() {
     return JSON.stringify({
-        cclawHookSchemaVersion: 1,
+        cclawHookSchemaVersion: 2,
         hooks: buildClaudeLikeEvents("codex")
     }, null, 2);
 }

package/dist/content/opencode-plugin.js

@@ -607,12 +607,6 @@ export default function cclawPlugin(ctx) {
         eventType === "session.compacted" ||
         eventType === "session.cleared" ||
         eventType === "session.updated";
-      // session.compacted must run pre-compact BEFORE canonical rehydration,
-      // otherwise the injected system prompt can show the pre-compact
-      // digest/state until the next lifecycle event.
-      if (eventType === "session.compacted") {
-        await runHookScript("pre-compact", eventData ?? {});
-      }
       if (isSessionLifecycle) {
         // Keep OpenCode aligned with Claude/Cursor/Codex: session-start is
         // the canonical rehydrate path that refreshes derived state such as

package/dist/content/skills-elicitation.d.ts

@@ -0,0 +1 @@
+export declare function adaptiveElicitationSkillMarkdown(): string;

package/dist/content/skills-elicitation.js

@@ -0,0 +1,123 @@
+import { RUNTIME_ROOT } from "../constants.js";
+import { questionBudgetHint } from "../track-heuristics.js";
+import { FLOW_TRACKS } from "../types.js";
+const ELICITATION_STAGES = ["brainstorm", "scope", "design"];
+function renderQuestionBudgetHintTable() {
+    const rows = [];
+    for (const track of FLOW_TRACKS) {
+        for (const stage of ELICITATION_STAGES) {
+            const hint = questionBudgetHint(track, stage);
+            rows.push(`| \`${track}\` | \`${stage}\` | ${hint.min} | ${hint.recommended} | ${hint.hardCapWarning} |`);
+        }
+    }
+    return `| Track | Stage | Min | Recommended | Hard cap warning |
+|---|---|---|---|---|
+${rows.join("\n")}`;
+}
+export function adaptiveElicitationSkillMarkdown() {
+    const budgetTable = renderQuestionBudgetHintTable();
+    return `---
+name: adaptive-elicitation
+description: "Harness-native one-question-at-a-time dialogue for brainstorm/scope/design with stop signals, smart-skip, and append-only Q&A logging."
+---
+
+# Adaptive Elicitation
+
+Pinned anchor: "Don't tell it what to do, give it success criteria and watch it go."
+
+## HARD-GATE
+- User does not run cclaw manually. Do not tell the user to run CLI commands for answers.
+- Ask exactly one question per turn and wait for the answer before asking the next one.
+- Use harness-native question tools first; prose fallback is allowed only when the tool is unavailable.
+- Keep a running Q&A trace in the active artifact under \`## Q&A Log\` in \`${RUNTIME_ROOT}/artifacts/\` as append-only rows.
+
+## Harness Question Surface
+
+Preferred native tool names:
+- Claude Code: \`AskUserQuestion\`
+- Codex: \`request_user_input\`
+- Gemini: \`ask_user\`
+- Cursor: \`AskQuestion\`
+
+If unavailable, ask one concise prose question and explicitly wait for chat answer.
+
+## Core Protocol
+
+1. Ask one decision-changing question.
+2. Wait for the answer.
+3. Append one row to \`## Q&A Log\`: \`Turn | Question | User answer (1-line) | Decision impact\`.
+4. Self-evaluate:
+   - What did I learn?
+   - Is context enough to draft now? (yes/no + reason)
+   - If no, what is the next most decision-changing question?
+5. Repeat until context is clear OR user asks to proceed.
+
+## Question Shape Rules
+
+- Prefer single-select multiple choice when one direction/priority/next step must be chosen.
+- Use multi-select only for compatible sets (goals, constraints, non-goals).
+- Smart-skip questions already answered earlier (directly or implicitly) and log "skipped (already covered)" when relevant.
+
+## Stop Signals (Natural Language)
+
+Treat these as stop-and-draft signals:
+- RU: "достаточно", "хватит", "давай драфт"
+- EN: "enough", "skip", "just draft it", "stop asking", "move on"
+- UA: "досить", "вистачить", "давай драфт", "рухаємось далі"
+
+When detected:
+- Do not ask another question in this stage loop.
+- Move to drafting with available context.
+- For internal agent calls only, pass \`--skip-questions\` on the next advance helper call.
+
+## Conditional Grilling (Only On Risk Triggers)
+
+Ask an extra 3-5 sharp questions only when one of these triggers appears:
+- Irreversibility (data deletion, schema migration, breaking API/contract)
+- Security/auth boundary changes
+- Domain-model ambiguity with multiple plausible invariants
+
+Do not ask extra questions "for theater" on simple low-risk work.
+
+## Question Budget Hint (Soft Guidance)
+
+Use as orientation, never as a hard stop. Source of truth is \`questionBudgetHint(track, stage)\`:
+
+${budgetTable}
+
+Track mapping note: \`quick\` ~= lightweight, \`medium\` ~= standard, \`standard\` ~= deep.
+Stop based on clarity/user signal, not raw count.
+
+## Stage Forcing Questions
+
+Always keep at least one unresolved forcing question in play until answered or explicitly waived:
+
+- Brainstorm:
+  - What pain are we solving?
+  - What is the most direct path?
+  - What happens if we do nothing?
+  - Who is the operator/user impacted first?
+  - What are non-negotiable no-go boundaries?
+- Scope:
+  - What is definitely in and definitely out?
+  - Which decisions are already locked upstream?
+  - What is the rollback path if this fails?
+  - What are the top failure modes we must design for?
+- Design:
+  - What is the data flow end-to-end?
+  - Where are the seams/interfaces and ownership boundaries?
+  - Which invariants must always hold?
+  - What will we explicitly NOT refactor now?
+
+## One-Way Override (Irreversible Decisions)
+
+For irreversible moves (deletion, schema migration, breaking API):
+- Ask for explicit confirmation even if user asked to stop questions.
+- Proceed only after explicit override ("I understand the irreversible risk; proceed").
+- Record the override in \`## Q&A Log\` and in the stage artifact decision section.
+
+## Completion Rule
+
+"Continue until clear OR user wants to proceed."
+Never force a fixed N-question script.`;
+}