oris-skills 2.0.0 → 2.1.0

package/scripts/loop/oris-loop-chat.mjs

@@ -18,6 +18,7 @@ import {
   ORIS_SKILLS_SETTINGS,
 } from "../flow/oris-flow-layout.mjs";
 import {
+  activeRoles,
   assessPromptFiles,
   improveMode,
   normalizeModels,
@@ -36,10 +37,10 @@ function parseArgs(argv) {
     loopSlug: "",
     taskPath: "",
     state: "continue",
+    progress: "",
     repositoryRoot: "",
     runner: "chat",
     maxIterations: 25,
-    maxRepairCycles: 10,
     maxMinutes: 240,
     profile: "",
     settingsPath: ORIS_SKILLS_SETTINGS,
@@ -56,6 +57,7 @@ function parseArgs(argv) {
     else if (key === "--loop" || key === "--loop-slug" || key.startsWith("--loop=") || key.startsWith("--loop-slug=")) [i, options.loopSlug] = readValue(i, raw);
     else if (key === "--task" || key === "--task-path" || key.startsWith("--task=") || key.startsWith("--task-path=")) [i, options.taskPath] = readValue(i, raw);
     else if (key === "--state" || key.startsWith("--state=")) [i, options.state] = readValue(i, raw);
+    else if (key === "--progress" || key.startsWith("--progress=")) [i, options.progress] = readValue(i, raw);
     else if (key === "--repository-root" || key.startsWith("--repository-root=")) [i, options.repositoryRoot] = readValue(i, raw);
     else if (key === "--runner" || key.startsWith("--runner=")) [i, options.runner] = readValue(i, raw);
     else if (key === "--profile" || key.startsWith("--profile=")) [i, options.profile] = readValue(i, raw);
@@ -64,10 +66,6 @@ function parseArgs(argv) {
       const parsed = readValue(i, raw);
       i = parsed[0];
       options.maxIterations = Number.parseInt(parsed[1], 10);
-    } else if (key === "--max-repair-cycles" || key.startsWith("--max-repair-cycles=")) {
-      const parsed = readValue(i, raw);
-      i = parsed[0];
-      options.maxRepairCycles = Number.parseInt(parsed[1], 10);
     } else if (key === "--max-minutes" || key.startsWith("--max-minutes=")) {
       const parsed = readValue(i, raw);
       i = parsed[0];
@@ -76,9 +74,11 @@ function parseArgs(argv) {
   }
   options.action = options.action.toLowerCase();
   options.state = options.state.toLowerCase();
+  options.progress = options.progress.toLowerCase();
   options.runner = options.runner.toLowerCase();
   if (!["start", "set-state", "stop", "status", "repair"].includes(options.action)) fail("Unsupported --action.");
-  if (!["continue", "advance", "complete", "blocked", "cancelled"].includes(options.state)) fail("Unsupported --state.");
+  if (!["continue", "advance", "complete", "blocked", "cancelled", "ask-user"].includes(options.state)) fail("Unsupported --state.");
+  if (options.progress && !["yes", "no"].includes(options.progress)) fail("Unsupported --progress (yes|no).");
   if (!["chat", "headless"].includes(options.runner)) fail("Unsupported --runner (chat|headless).");
   return options;
 }
@@ -133,7 +133,7 @@ function reconcileContext(root, state) {
     "Current phase index": Number(state.phaseIndex ?? 0),
     "Current iteration": Number(state.iteration ?? 0),
     "Phase iteration": Number(state.phaseIteration ?? 0),
-    "Repair cycles": Number(state.repairCycles ?? 0),
+    "No-progress streak": Number(state.noProgressStreak ?? 0),
     Updated: new Date().toISOString(),
   })) {
     content = setContextField(content, name, value);
@@ -213,7 +213,7 @@ function normalizeChatState(state) {
   normalized.phaseName = currentPhase(normalized);
   normalized.iteration = Number(normalized.iteration ?? 0);
   normalized.phaseIteration = Number(normalized.phaseIteration ?? 0);
-  normalized.repairCycles = Number(normalized.repairCycles ?? 0);
+  normalized.noProgressStreak = Number(normalized.noProgressStreak ?? 0);
   normalized.phaseIndex = Number.isInteger(Number(normalized.phaseIndex)) ? Number(normalized.phaseIndex) : 0;
   if (normalized.state === "running" && normalized.active === true) {
     normalized.state = "continue";
@@ -283,13 +283,14 @@ if (options.action === "start") {
   } catch (error) {
     fail(error.message);
   }
-  const prompts = assessPromptFiles(path.dirname(loopPath));
+  const prompts = assessPromptFiles(path.dirname(loopPath), activeRoles(loopDocument.data));
   if (prompts.missing.length > 0) {
     fail(`Loop prompt files are missing or empty: ${prompts.missing.join(", ")}. Craft or copy them from skills/oris-loop/templates/.`);
   }
   if (fs.existsSync(statePath)) {
     const existing = normalizeChatState(JSON.parse(fs.readFileSync(statePath, "utf8")));
-    if (existing.active === true && !terminalStates.has(existing.state)) {
+    // ask-user is a pause awaiting input, not an active run — restart may take over.
+    if (existing.active === true && !terminalStates.has(existing.state) && existing.state !== "ask-user") {
       fail(`An Oris chat loop is already active for this workspace: ${existing.taskPath}. Run --action stop before starting again.`);
     }
   }
@@ -310,13 +311,14 @@ if (options.action === "start") {
     loopPath: loopDocs.loopRelative,
     contextPath: loopDocs.contextRelative,
     promptsPath: loopDocs.promptsRelative,
+    roles: activeRoles(loopMetadata),
     models: normalizeModels(loopMetadata.models, adapter.models),
     improveMode: improveMode(loopMetadata),
     conversationId: null,
     iteration: 0,
     maxIterations: loopMetadata.limits.maxIterations,
-    repairCycles: 0,
-    maxRepairCycles: options.maxRepairCycles,
+    noProgressStreak: 0,
+    maxNoProgress: loopMetadata.limits.maxNoProgress,
     maxMinutes: loopMetadata.limits.maxMinutes ?? options.maxMinutes,
     startedAt: new Date().toISOString(),
     updatedAt: new Date().toISOString(),
@@ -348,6 +350,7 @@ if (options.action === "repair") {
   ) {
     current.active = true;
     current.state = "continue";
+    current.noProgressStreak = 0;
     current.startedAt = new Date().toISOString();
     delete current.stopReason;
   }
@@ -364,20 +367,32 @@ if (options.action === "set-state") {
   if (options.state === "advance") {
     current.phaseIndex = phases.length === 1 ? 0 : (Number(current.phaseIndex ?? 0) + 1) % phases.length;
     current.phaseIteration = 0;
-    current.repairCycles = Number(current.repairCycles ?? 0);
     current.state = "advance";
     current.active = true;
   } else {
     current.state = options.state;
     current.active = !terminalStates.has(options.state);
   }
+  if (options.progress) {
+    current.noProgressStreak = options.progress === "yes" ? 0 : Number(current.noProgressStreak ?? 0) + 1;
+  }
+  const maxNoProgress = Number(current.maxNoProgress ?? 0);
+  if (
+    maxNoProgress >= 1
+    && Number(current.noProgressStreak ?? 0) >= maxNoProgress
+    && (current.state === "continue" || current.state === "advance")
+  ) {
+    current.state = "blocked";
+    current.active = false;
+    current.stopReason = "no-progress limit exhausted";
+  }
   current.phases = phases;
   current.phaseName = currentPhase(current);
   current.schemaVersion = 1;
   current.updatedAt = new Date().toISOString();
   writeJson(statePath, current);
   reconcileContext(root, current);
-  console.log(`Oris chat loop state: ${current.state}`);
+  console.log(`Oris chat loop state: ${current.state}${current.stopReason ? ` (${current.stopReason})` : ""}`);
   process.exit(0);
 }
 
@@ -401,6 +416,9 @@ console.log(JSON.stringify({
   taskPath: current.taskPath,
   iteration: Number(current.iteration ?? 0),
   maxIterations: Number(current.maxIterations ?? 0),
+  noProgressStreak: Number(current.noProgressStreak ?? 0),
+  maxNoProgress: Number(current.maxNoProgress ?? 0),
+  roles: Array.isArray(current.roles) ? current.roles : ["executor", "verifier"],
   improveMode: current.improveMode ?? "propose",
   models: current.models ?? {},
   conversationBound: Boolean(current.conversationId),

package/scripts/loop/oris-loop-demo.mjs

@@ -73,6 +73,7 @@ kind: oris-loop
 name: ${DEMO_SLUG}
 approved: true
 phases: [work]
+roles: [executor, verifier, debriefer]
 limits:
   maxIterations: 3
   maxNoProgress: 2
@@ -97,6 +98,7 @@ Stop: complete at 3; blocked if the file is missing or not a number.
 This loop exists to LEARN the loop system safely:
 - it only touches files inside its own folder;
 - it runs 3 short passes, then completes;
+- roles are executor + verifier (the default) plus the debriefer;
 - improve.mode is \`auto\`, so you can watch the debriefer tune \`prompts/\` between passes.
 
 Try: edit \`prompts/executor.md\` and see the next pass obey your change.
@@ -104,13 +106,14 @@ Try: edit \`prompts/executor.md\` and see the next pass obey your change.
 
 fs.writeFileSync(path.join(loopDir, "prompts", "executor.md"), `# Executor prompt — demo loop (edit me and watch the next pass change)
 
+ORIS LOOP ACTIVE — approved demo pass.
 You are the executor of the Oris demo loop.
 
 THIS PASS: iteration {{iteration}}.
 DO: read ${workspaceRelative}/counter.txt, add 1, write the new value back.
 ONLY touch files under ${workspaceRelative}.
 
-RETURN compact JSON only:
+RETURN compact JSON only (\`\`\`json fenced):
 { "role": "executor", "state": "claimed|blocked", "summary": "", "changedFiles": [], "claim": "counter is now N" }
 `, "utf8");
 
@@ -120,22 +123,10 @@ You are the independent verifier of the Oris demo loop.
 NEVER trust the executor claim without reading the file yourself.
 
 VERIFY: ${workspaceRelative}/counter.txt contains exactly the claimed number.
+goalMet = true ONLY when the verified counter equals 3 (the loop goal).
 
-RETURN compact JSON only:
-{ "role": "verifier", "state": "pass|fail|blocked", "summary": "", "evidence": "file content: N" }
-`, "utf8");
-
-fs.writeFileSync(path.join(loopDir, "prompts", "doctor.md"), `# Doctor prompt — demo loop
-
-You are the doctor of the Oris demo loop.
-
-DECIDE from the verifier evidence:
-- counter < 3 and verified → continue
-- counter = 3 and verified → complete
-- verification failed or file broken → stop
-
-RETURN compact JSON only:
-{ "role": "doctor", "decision": "continue|complete|stop", "diagnosis": "" }
+RETURN compact JSON only (\`\`\`json fenced):
+{ "role": "verifier", "state": "pass|fail|blocked|inconclusive", "goalMet": false, "summary": "", "evidence": "file content: N" }
 `, "utf8");
 
 fs.writeFileSync(path.join(loopDir, "prompts", "debriefer.md"), `# Debriefer prompt — demo loop (improve mode: auto)
@@ -157,7 +148,7 @@ Current phase: work
 Current phase index: 0
 Current iteration: 0
 Phase iteration: 0
-Repair cycles: 0
+No-progress streak: 0
 Updated: ${new Date().toISOString()}
 
 ## Objective
@@ -172,9 +163,9 @@ Increment the counter from its current value.
 console.log(`Demo loop created: ${docs.loopRelative}`);
 console.log("");
 console.log("Learn it in 3 steps:");
-console.log(`  1. Preview a pass (nothing runs):  oris-skills loop dry-run --loop ${DEMO_SLUG}`);
-console.log(`  2. Run it from your agent chat:    oris-skills loop chat --action start --loop ${DEMO_SLUG}`);
+console.log(`  1. Preview a pass (nothing runs):  npx oris-skills loop dry-run --loop ${DEMO_SLUG}`);
+console.log(`  2. Run it from your agent chat:    npx oris-skills loop chat --action start --loop ${DEMO_SLUG}`);
 console.log("     then end the turn — the stop hook schedules pass 1 automatically.");
 console.log(`  3. Watch and tune: edit ${docs.promptsRelative}/executor.md between passes.`);
 console.log("");
-console.log(`Stop anytime: oris-skills loop chat --action stop`);
+console.log(`Stop anytime: npx oris-skills loop chat --action stop`);

package/scripts/loop/oris-loop-document.mjs

@@ -7,8 +7,7 @@ const phasePattern = /^[a-z][a-z0-9-]*$/;
 
 export const INHERIT_MODEL = "inherit";
 export const ROLE_NAMES = ["executor", "verifier", "doctor", "debriefer"];
-export const REQUIRED_PROMPT_FILES = ["executor.md", "verifier.md", "doctor.md"];
-export const OPTIONAL_PROMPT_FILES = ["orchestrator.md", "debriefer.md"];
+export const DEFAULT_ROLES = ["executor", "verifier"];
 export const IMPROVE_MODES = new Set(["propose", "auto"]);
 
 export function parseFrontMatter(text, filePath = "loop.md") {
@@ -97,6 +96,19 @@ export function validateLoopMetadata(data, filePath = "loop.md") {
   if (!Array.isArray(data.phases) || data.phases.length < 1 || data.phases.some((phase) => typeof phase !== "string" || !phasePattern.test(phase))) {
     errors.push("phases must contain valid phase slugs");
   }
+  if (data.roles !== undefined) {
+    if (!Array.isArray(data.roles) || data.roles.some((role) => !ROLE_NAMES.includes(role))) {
+      errors.push(`roles must be an array of ${ROLE_NAMES.join("|")}`);
+    } else {
+      if (new Set(data.roles).size !== data.roles.length) errors.push("roles must not repeat");
+      for (const required of DEFAULT_ROLES) {
+        if (!data.roles.includes(required)) errors.push(`roles must include ${required}`);
+      }
+    }
+  }
+  if (data.improve?.mode === "auto" && !activeRoles(data).includes("debriefer")) {
+    errors.push("improve.mode auto requires the debriefer role (roles: [executor, verifier, debriefer])");
+  }
   if (!data.limits || !Number.isInteger(data.limits.maxIterations) || data.limits.maxIterations < 1 || data.limits.maxIterations > 500) {
     errors.push("limits.maxIterations must be 1..500");
   }
@@ -162,13 +174,18 @@ export function improveMode(data) {
   return data?.improve?.mode === "auto" ? "auto" : "propose";
 }
 
-/** Check the per-loop prompts/ directory. Returns { promptsDir, missing }. */
-export function assessPromptFiles(loopDir) {
+/** Roles a loop runs each pass; executor + verifier unless loop.md opts more in. */
+export function activeRoles(data) {
+  return Array.isArray(data?.roles) && data.roles.length > 0 ? [...data.roles] : [...DEFAULT_ROLES];
+}
+
+/** Check the per-loop prompts/ directory against the loop's active roles. */
+export function assessPromptFiles(loopDir, roles = DEFAULT_ROLES) {
   const promptsDir = path.join(loopDir, "prompts");
   const missing = [];
-  for (const file of REQUIRED_PROMPT_FILES) {
-    const full = path.join(promptsDir, file);
-    if (!fs.existsSync(full) || !fs.readFileSync(full, "utf8").trim()) missing.push(`prompts/${file}`);
+  for (const role of roles) {
+    const full = path.join(promptsDir, `${role}.md`);
+    if (!fs.existsSync(full) || !fs.readFileSync(full, "utf8").trim()) missing.push(`prompts/${role}.md`);
   }
   return { promptsDir, missing };
 }

package/scripts/loop/oris-loop-dry-run.mjs

@@ -11,6 +11,7 @@ import path from "node:path";
 import process from "node:process";
 import { readAdapter, resolveLoopDocumentPathsBySlug } from "./oris-loop-paths.mjs";
 import {
+  activeRoles,
   assessPromptFiles,
   improveMode,
   normalizeModels,
@@ -52,7 +53,7 @@ function getRoot(options) {
 }
 
 const options = parseArgs(process.argv.slice(2));
-if (!options.loopSlug) fail("--loop <slug> is required. List loops with: oris-skills loop list");
+if (!options.loopSlug) fail("--loop <slug> is required. List loops with: npx oris-skills loop list");
 const root = getRoot(options);
 const adapter = readAdapter(root);
 const docs = resolveLoopDocumentPathsBySlug(root, options.loopSlug, adapter);
@@ -65,7 +66,8 @@ try {
   fail(error.message);
 }
 const metadata = loopDocument.data;
-const prompts = assessPromptFiles(path.dirname(docs.loopFull));
+const roles = activeRoles(metadata);
+const prompts = assessPromptFiles(path.dirname(docs.loopFull), roles);
 const models = normalizeModels(metadata.models, adapter.models);
 
 const perLoopOrchestrator = path.join(docs.promptsFull, "orchestrator.md");
@@ -84,6 +86,7 @@ const followup = substitutePlaceholders(template, {
   loopPath: docs.loopRelative,
   contextPath: docs.contextRelative,
   promptsDir: docs.promptsRelative,
+  roles: roles.join(", "),
   executorModel: models.executor,
   verifierModel: models.verifier,
   doctorModel: models.doctor,
@@ -95,6 +98,7 @@ const followup = substitutePlaceholders(template, {
 console.log(`Oris loop dry run: ${metadata.name}`);
 console.log(`Definition: ${docs.loopRelative} (schemaVersion ${metadata.schemaVersion}, approved: ${metadata.approved})`);
 console.log(`Prompts: ${docs.promptsRelative} ${prompts.missing.length === 0 ? "(complete)" : `(MISSING: ${prompts.missing.join(", ")})`}`);
+console.log(`Roles: ${roles.join(", ")}`);
 console.log(`Models: executor=${models.executor} verifier=${models.verifier} doctor=${models.doctor} debriefer=${models.debriefer}`);
 console.log(`Improve mode: ${improveMode(metadata)}`);
 console.log(`Limits: ${metadata.limits.maxIterations} iterations, ${metadata.limits.maxNoProgress} no-progress, ${metadata.limits.maxMinutes ?? 240} minutes`);
@@ -107,4 +111,4 @@ if (prompts.missing.length > 0) {
   console.log("NOT runnable yet — create the missing prompt files first (templates: skills/oris-loop/templates/).");
   process.exit(1);
 }
-console.log(`Runnable. Start it with: oris-skills loop chat --action start --loop ${metadata.name}`);
+console.log(`Runnable. Start it with: npx oris-skills loop chat --action start --loop ${metadata.name}`);

package/scripts/loop/oris-loop-fixtures.mjs

@@ -8,7 +8,7 @@ import {
   writeStopHookWrapper,
 } from "./oris-loop-bootstrap.mjs";
 import { defaultLoopDocumentPaths, readAdapter } from "./oris-loop-paths.mjs";
-import { ORIS_FLOW_ADAPTER } from "../flow/oris-flow-layout.mjs";
+import { ORIS_FLOW_ADAPTER, ORIS_FLOW_TASKS_ROOT } from "../flow/oris-flow-layout.mjs";
 
 export function writeMinimalAdapter(root) {
   const adapterPath = path.join(root, ORIS_FLOW_ADAPTER);
@@ -22,6 +22,7 @@ export function writeMinimalAdapter(root) {
 export function loopDocumentSource({
   program = "oris-loop-smoke",
   phases = ["work"],
+  roles = ["executor", "verifier"],
   improve = "propose",
   models = {},
   goal = "Run one deterministic smoke action, verify it, and record evidence.",
@@ -37,6 +38,7 @@ kind: oris-loop
 name: ${program}
 approved: true
 phases: [${phases.join(", ")}]
+roles: [${roles.join(", ")}]
 limits:
   maxIterations: 25
   maxNoProgress: 2
@@ -65,20 +67,17 @@ export function rolePromptFixtures() {
   return {
     "executor.md": `# Executor prompt
 
+ORIS LOOP ACTIVE — approved smoke pass.
 Perform exactly one bounded smoke action inside allowed paths.
 Runtime: iteration {{iteration}}, phase {{phase}}, target {{currentTarget}}.
-RETURN compact JSON: { "role": "executor", "state": "claimed|blocked", "summary": "", "changedFiles": [], "claim": "" }
+RETURN compact JSON (\`\`\`json fenced): { "role": "executor", "state": "claimed|blocked", "summary": "", "changedFiles": [], "claim": "" }
 `,
     "verifier.md": `# Verifier prompt
 
 Verify independently: \`node --version\` exits 0. NEVER trust the executor without running the check.
 Runtime: iteration {{iteration}}; executor claim supplied by orchestrator.
-RETURN compact JSON: { "role": "verifier", "state": "pass|fail|blocked", "summary": "", "evidence": "" }
-`,
-    "doctor.md": `# Doctor prompt
-
-Diagnose from evidence. Stop rules: success when the smoke check passes; blocked on missing tools.
-RETURN compact JSON: { "role": "doctor", "decision": "continue|complete|stop", "diagnosis": "" }
+goalMet = true when the smoke check passed (the loop goal is one verified pass).
+RETURN compact JSON (\`\`\`json fenced): { "role": "verifier", "state": "pass|fail|blocked|inconclusive", "goalMet": false, "summary": "", "evidence": "" }
 `,
   };
 }
@@ -88,16 +87,18 @@ export function writeLoopTask(root, {
   program = "oris-loop-smoke",
   phases = ["work"],
   phase = phases[0],
+  roles = ["executor", "verifier"],
   improve = "propose",
   models = {},
 } = {}) {
-  const taskPath = taskSlug;
+  const taskPath = `${ORIS_FLOW_TASKS_ROOT}/${taskSlug}`;
+  fs.mkdirSync(path.join(root, ...taskPath.split("/")), { recursive: true });
   const adapter = readAdapter(root);
   const loopDocs = defaultLoopDocumentPaths(root, taskPath, adapter);
   const loopPath = loopDocs.loopFull;
   const contextPath = loopDocs.contextFull;
   fs.mkdirSync(path.dirname(loopPath), { recursive: true });
-  fs.writeFileSync(loopPath, loopDocumentSource({ program, phases, improve, models }), "utf8");
+  fs.writeFileSync(loopPath, loopDocumentSource({ program, phases, roles, improve, models }), "utf8");
   fs.mkdirSync(loopDocs.promptsFull, { recursive: true });
   for (const [name, content] of Object.entries(rolePromptFixtures())) {
     fs.writeFileSync(path.join(loopDocs.promptsFull, name), content, "utf8");
@@ -111,7 +112,7 @@ Current phase: ${phase}
 Current phase index: 0
 Current iteration: 0
 Phase iteration: 0
-Repair cycles: 0
+No-progress streak: 0
 Updated: ${new Date().toISOString()}
 
 ## Objective

package/scripts/loop/oris-loop-run.mjs

@@ -16,6 +16,7 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { readAdapter, resolveLoopDocumentPathsBySlug } from "./oris-loop-paths.mjs";
 import {
+  activeRoles,
   assessPromptFiles,
   improveMode,
   normalizeModels,
@@ -64,21 +65,24 @@ function getRoot(options) {
   return path.resolve(result.stdout.trim());
 }
 
+/** Roles flagged readonly must not get write access at the harness level. */
+const READONLY_ROLES = new Set(["verifier", "doctor"]);
+
 /** Build the CLI invocation for one role. Exported for tests. */
-export function buildRoleInvocation(agent, { prompt, model, root }) {
+export function buildRoleInvocation(agent, { prompt, model, root, readonly = false }) {
   if (agent === "claude") {
-    const args = ["-p", prompt, "--permission-mode", "acceptEdits"];
+    const args = ["-p", prompt, "--permission-mode", readonly ? "plan" : "acceptEdits"];
     if (model && model !== "inherit") args.push("--model", model);
     return { command: "claude", args, cwd: root };
   }
-  const args = ["exec", "--sandbox", "workspace-write", "--cd", root];
+  const args = ["exec", "--sandbox", readonly ? "read-only" : "workspace-write", "--cd", root];
   if (model && model !== "inherit") args.push("-m", model);
   args.push(prompt);
   return { command: "codex", args, cwd: root };
 }
 
 function runRole(agent, role, prompt, model, root, evidenceDir, pass) {
-  const invocation = buildRoleInvocation(agent, { prompt, model, root });
+  const invocation = buildRoleInvocation(agent, { prompt, model, root, readonly: READONLY_ROLES.has(role) });
   process.stdout.write(`  ${role} (${agent}${model && model !== "inherit" ? `, ${model}` : ""})... `);
   const result = childProcess.spawnSync(invocation.command, invocation.args, {
     cwd: invocation.cwd,
@@ -101,6 +105,15 @@ function runRole(agent, role, prompt, model, root, evidenceDir, pass) {
 /** Pull the last JSON object out of an agent's free-form output. */
 export function extractJson(output) {
   const text = String(output ?? "");
+  // Prefer the last ```json fenced block — the format the role prompts request.
+  const fenced = [...text.matchAll(/```json\s*\n?([\s\S]*?)```/gi)];
+  for (let i = fenced.length - 1; i >= 0; i -= 1) {
+    try {
+      return JSON.parse(fenced[i][1]);
+    } catch {
+      // fall through to the brace scan
+    }
+  }
   for (let start = text.lastIndexOf("{"); start !== -1; start = start === 0 ? -1 : text.lastIndexOf("{", start - 1)) {
     for (let end = text.indexOf("}", start); end !== -1; end = text.indexOf("}", end + 1)) {
       try {
@@ -113,14 +126,35 @@ export function extractJson(output) {
   return null;
 }
 
+/**
+ * Canonical doctor decisions (references/loop-contract.md):
+ * continue | advance | complete | ask-user | blocked | propose-patch.
+ * A proposed patch needs user approval, so it pauses like ask-user.
+ * Unknown decisions block — but loudly, never silently.
+ */
 export function doctorDecisionToState(decision) {
   const value = String(decision ?? "").toLowerCase();
   if (value === "complete") return "complete";
   if (value === "advance") return "advance";
   if (value === "continue" || value === "retry") return "continue";
+  if (value === "ask-user" || value === "ask_user" || value === "propose-patch") return "ask-user";
+  if (value !== "blocked" && value !== "block" && value !== "stop") {
+    console.warn(`  WARN unrecognized doctor decision "${decision}" — treating as blocked.`);
+  }
   return "blocked";
 }
 
+/**
+ * Without a doctor, the verifier verdict drives the state directly:
+ * pass + goalMet → complete; pass|fail → continue; anything else pauses.
+ */
+export function verifierVerdictToState(verifierResult) {
+  const state = String(verifierResult?.state ?? "").toLowerCase();
+  if (state === "pass") return verifierResult?.goalMet === true ? "complete" : "continue";
+  if (state === "fail") return "continue";
+  return "ask-user";
+}
+
 function chatAction(root, args) {
   const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "oris-loop-chat.mjs");
   const result = childProcess.spawnSync(process.execPath, [script, "--repository-root", root, ...args], {
@@ -156,7 +190,8 @@ try {
   fail(error.message);
 }
 const metadata = loopDocument.data;
-const prompts = assessPromptFiles(path.dirname(docs.loopFull));
+const roles = activeRoles(metadata);
+const prompts = assessPromptFiles(path.dirname(docs.loopFull), roles);
 if (prompts.missing.length > 0) fail(`Loop prompt files are missing: ${prompts.missing.join(", ")}`);
 const models = normalizeModels(metadata.models, adapter.models);
 const mode = improveMode(metadata);
@@ -166,9 +201,11 @@ const receiptsDir = path.join(path.dirname(docs.loopFull), "receipts");
 fs.mkdirSync(evidenceDir, { recursive: true });
 fs.mkdirSync(receiptsDir, { recursive: true });
 
-console.log(`Oris loop headless run: ${metadata.name} (agent: ${options.agent}, improve: ${mode})`);
+console.log(`Oris loop headless run: ${metadata.name} (agent: ${options.agent}, roles: ${roles.join("+")}, improve: ${mode})`);
 chatAction(root, ["--action", "start", "--loop", options.loopSlug, "--runner", "headless"]);
 
+const maxNoProgress = Number(metadata.limits.maxNoProgress ?? 0);
+let noProgressStreak = 0;
 let state = "continue";
 for (let pass = 1; pass <= maxPasses && (state === "continue" || state === "advance"); pass += 1) {
   console.log(`Pass ${pass}/${maxPasses}:`);
@@ -191,20 +228,35 @@ for (let pass = 1; pass <= maxPasses && (state === "continue" || state === "adva
     models.verifier, root, evidenceDir, pass);
   const verifierResult = extractJson(verifier.output);
 
-  const doctor = runRole(options.agent, "doctor",
-    rolePrompt(prompts.promptsDir, "doctor.md", runtimeValues,
-      `EXECUTOR:\n${JSON.stringify(executorResult, null, 2)}\nVERIFIER:\n${JSON.stringify(verifierResult, null, 2)}`),
-    models.doctor, root, evidenceDir, pass);
-  const doctorResult = extractJson(doctor.output);
-  state = doctorDecisionToState(doctorResult?.decision);
+  let doctor = null;
+  let doctorResult = null;
+  if (roles.includes("doctor")) {
+    doctor = runRole(options.agent, "doctor",
+      rolePrompt(prompts.promptsDir, "doctor.md", runtimeValues,
+        `EXECUTOR:\n${JSON.stringify(executorResult, null, 2)}\nVERIFIER:\n${JSON.stringify(verifierResult, null, 2)}`),
+      models.doctor, root, evidenceDir, pass);
+    doctorResult = extractJson(doctor.output);
+    if (doctorResult === null) {
+      console.warn("  WARN doctor output was not parseable JSON — pausing for user review.");
+      state = "ask-user";
+    } else {
+      state = doctorDecisionToState(doctorResult.decision);
+    }
+  } else {
+    state = verifierVerdictToState(verifierResult);
+  }
 
-  if (mode === "auto" && fs.existsSync(path.join(prompts.promptsDir, "debriefer.md"))) {
+  if (roles.includes("debriefer") && mode === "auto" && fs.existsSync(path.join(prompts.promptsDir, "debriefer.md"))) {
     runRole(options.agent, "debriefer",
       rolePrompt(prompts.promptsDir, "debriefer.md", { ...runtimeValues, IMPROVE_MODE: mode },
-        `DOCTOR VERDICT:\n${JSON.stringify(doctorResult, null, 2)}\nPROMPTS DIR: ${docs.promptsRelative}`),
+        `VERDICT:\n${JSON.stringify(doctorResult ?? verifierResult, null, 2)}\nPROMPTS DIR: ${docs.promptsRelative}`),
       models.debriefer, root, evidenceDir, pass);
   }
 
+  const progressed = verifierResult?.state === "pass"
+    || (Array.isArray(executorResult?.changedFiles) && executorResult.changedFiles.length > 0);
+  noProgressStreak = progressed ? 0 : noProgressStreak + 1;
+
   const receiptPath = path.join(receiptsDir, `pass-${String(pass).padStart(3, "0")}.md`);
   fs.writeFileSync(receiptPath, `# Oris Loop Receipt
 
@@ -215,16 +267,20 @@ Result: ${state}
 
 Executor: ${executorResult?.summary ?? executorResult?.claim ?? "see evidence"}
 Verifier: ${verifierResult?.state ?? "unknown"} — ${verifierResult?.summary ?? "see evidence"}
-Doctor: ${doctorResult?.decision ?? "unknown"} — ${doctorResult?.diagnosis ?? "see evidence"}
-
+${doctor ? `Doctor: ${doctorResult?.decision ?? "unknown"} — ${doctorResult?.diagnosis ?? "see evidence"}\n` : ""}
 Evidence:
 - ${path.relative(root, executor.evidencePath).replace(/\\/g, "/")}
 - ${path.relative(root, verifier.evidencePath).replace(/\\/g, "/")}
-- ${path.relative(root, doctor.evidencePath).replace(/\\/g, "/")}
-`, "utf8");
+${doctor ? `- ${path.relative(root, doctor.evidencePath).replace(/\\/g, "/")}\n` : ""}`, "utf8");
 
-  chatAction(root, ["--action", "set-state", "--state", state === "advance" ? "advance" : state]);
-  console.log(`  state: ${state} | receipt: ${path.relative(root, receiptPath).replace(/\\/g, "/")}`);
+  chatAction(root, ["--action", "set-state", "--state", state === "advance" ? "advance" : state,
+    "--progress", progressed ? "yes" : "no"]);
+  console.log(`  state: ${state} | progress: ${progressed ? "yes" : "no"} | receipt: ${path.relative(root, receiptPath).replace(/\\/g, "/")}`);
+
+  if (maxNoProgress >= 1 && noProgressStreak >= maxNoProgress && (state === "continue" || state === "advance")) {
+    state = "blocked";
+    console.log(`No-progress limit exhausted (${maxNoProgress} passes without progress) — state set to blocked.`);
+  }
 }
 
 if (state === "continue" || state === "advance") {
@@ -232,6 +288,10 @@ if (state === "continue" || state === "advance") {
   console.log("Pass budget exhausted before completion — state set to blocked.");
   process.exit(1);
 }
+if (state === "ask-user") {
+  console.log("Headless run paused: the loop needs user input or approval. Review the last receipt, then resume with: npx oris-skills loop run --loop " + metadata.name);
+  process.exit(1);
+}
 console.log(`Headless run finished: ${state}`);
 process.exit(state === "complete" ? 0 : 1);
 }