oris-skills 2.0.0 → 2.2.0

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);
 }

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

@@ -85,6 +85,8 @@ function detectPlatform(argv, raw) {
   const explicit = argv.find((arg) => arg.startsWith("--platform="))?.slice("--platform=".length)
     ?? (argv.includes("--platform") ? argv[argv.indexOf("--platform") + 1] : "");
   if (explicit === "cursor" || explicit === "claude") return explicit;
+  // Cursor payloads carry conversation_id (and may ALSO carry session_id) — check it first.
+  if (raw.conversation_id !== undefined || raw.conversationId !== undefined) return "cursor";
   if (String(raw.hook_event_name ?? "") === "Stop" || raw.session_id !== undefined || raw.stop_hook_active !== undefined) {
     return "claude";
   }
@@ -146,10 +148,15 @@ function appendDebug(debugPath, entry) {
   }
 }
 
-function packageOutput(platform, followup) {
-  if (!followup) return {};
-  if (platform === "claude") return { decision: "block", reason: followup };
-  return { followup_message: followup };
+function packageOutput(platform, followup, notice) {
+  if (followup) {
+    if (platform === "claude") return { decision: "block", reason: followup };
+    return { followup_message: followup };
+  }
+  // A stopped/broken loop must never wedge the chat, but the user should hear
+  // about it. Claude Code shows systemMessage; Cursor has no non-resuming channel.
+  if (notice && platform === "claude") return { systemMessage: notice };
+  return {};
 }
 
 function finish(debugPath, baseEntry, result) {
@@ -160,7 +167,7 @@ function finish(debugPath, baseEntry, result) {
     reason: result.reason,
     emittedFollowup: Boolean(result.followup),
   });
-  emit(packageOutput(baseEntry.platform, result.followup));
+  emit(packageOutput(baseEntry.platform, result.followup, result.notice));
 }
 
 /** Resolve the orchestrator prompt: per-loop file > packaged template > embedded. */
@@ -213,7 +220,11 @@ try {
   try {
     state = normalizeState(parseJsonText(fs.readFileSync(statePath, "utf8")));
   } catch {
-    finish(debugPath, baseEntry, { decision: "noop", reason: "chat-active-invalid-json" });
+    finish(debugPath, baseEntry, {
+      decision: "noop",
+      reason: "chat-active-invalid-json",
+      notice: `Oris loop halted: ${statePath} is not valid JSON. Repair it with: npx oris-skills loop chat --action repair`,
+    });
     process.exit(0);
   }
 
@@ -222,7 +233,11 @@ try {
   baseEntry.runtimeIteration = state?.iteration ?? null;
 
   if (!state) {
-    finish(debugPath, baseEntry, { decision: "noop", reason: "chat-active-unsupported-schema" });
+    finish(debugPath, baseEntry, {
+      decision: "noop",
+      reason: "chat-active-unsupported-schema",
+      notice: `Oris loop halted: ${statePath} uses an unsupported schema. Re-arm it with: npx oris-skills loop chat --action repair`,
+    });
     process.exit(0);
   }
 
@@ -260,13 +275,32 @@ try {
 
   if (iteration >= maxIterations || input.loopCount >= maxIterations) {
     stopState(statePath, state, "iteration limit exhausted");
-    finish(debugPath, baseEntry, { decision: "stop", reason: "iteration-limit-exhausted" });
+    finish(debugPath, baseEntry, {
+      decision: "stop",
+      reason: "iteration-limit-exhausted",
+      notice: `Oris loop "${state.program ?? ""}" stopped: iteration limit exhausted (${maxIterations}). Goal NOT confirmed met. Resume with: npx oris-skills loop chat --action repair`,
+    });
     process.exit(0);
   }
 
   if (elapsedMinutes >= maxMinutes) {
     stopState(statePath, state, "wall-clock limit exhausted");
-    finish(debugPath, baseEntry, { decision: "stop", reason: "wall-clock-limit-exhausted" });
+    finish(debugPath, baseEntry, {
+      decision: "stop",
+      reason: "wall-clock-limit-exhausted",
+      notice: `Oris loop "${state.program ?? ""}" stopped: wall-clock limit exhausted (${maxMinutes} min). Goal NOT confirmed met. Resume with: npx oris-skills loop chat --action repair`,
+    });
+    process.exit(0);
+  }
+
+  const maxNoProgress = Number(state.maxNoProgress ?? 0);
+  if (maxNoProgress >= 1 && Number(state.noProgressStreak ?? 0) >= maxNoProgress) {
+    stopState(statePath, state, "no-progress limit exhausted");
+    finish(debugPath, baseEntry, {
+      decision: "stop",
+      reason: "no-progress-limit-exhausted",
+      notice: `Oris loop "${state.program ?? ""}" stopped: ${maxNoProgress} passes in a row without progress. Goal NOT confirmed met.`,
+    });
     process.exit(0);
   }
 
@@ -280,6 +314,10 @@ try {
     ? state.repositoryRoot
     : input.workspaceRoots.find((root) => typeof root === "string" && fs.existsSync(root)) ?? process.cwd();
 
+  const roles = Array.isArray(state.roles) && state.roles.length > 0
+    ? state.roles
+    : ["executor", "verifier"];
+
   const followup = buildFollowup(state, repositoryRoot, {
     iteration: nextIteration,
     maxIterations,
@@ -291,6 +329,7 @@ try {
     loopPath: state.loopPath ?? "",
     contextPath: state.contextPath ?? "",
     promptsDir: state.promptsPath ?? "",
+    roles: roles.join(", "),
     executorModel: String(models.executor ?? defaultModel),
     verifierModel: String(models.verifier ?? defaultModel),
     doctorModel: String(models.doctor ?? defaultModel),

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

@@ -3,7 +3,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 /**
- * Prompt templates live in skills/oris-loop/templates/*.md so users and
+ * Prompt templates live in skills/oris-flow/templates/*.md so users and
  * agents can read and copy them. Scripts fall back to an embedded
  * orchestrator prompt so the stop hook can never fail on a missing file.
  */
@@ -12,6 +12,7 @@ export const TEMPLATE_NAMES = ["orchestrator", "executor", "verifier", "doctor",
 export const EMBEDDED_ORCHESTRATOR = `ORIS LOOP RUN — pass {{iteration}}/{{maxIterations}}
 Loop: {{loop}} | Phase: {{phase}} ({{phaseIndex}}/{{phaseCount}}) | Do: {{instruction}}
 Definition: {{loopPath}} | Context: {{contextPath}} | Prompts: {{promptsDir}}
+Active roles: {{roles}}
 Models: executor={{executorModel}} verifier={{verifierModel}} doctor={{doctorModel}} debriefer={{debrieferModel}} ("inherit" = current session model)
 Improve mode: {{improveMode}}
 
@@ -21,13 +22,15 @@ EACH PASS:
 1. READ {{contextPath}}; pick exactly ONE bounded next step.
 2. SPAWN executor subagent with {{promptsDir}}/executor.md (fill runtime values), model {{executorModel}}.
 3. SPAWN verifier subagent with {{promptsDir}}/verifier.md + the executor claim, model {{verifierModel}}.
-4. SPAWN doctor subagent with {{promptsDir}}/doctor.md + both compact summaries, model {{doctorModel}}.
+4. DECIDE the state:
+   - doctor in active roles → SPAWN doctor subagent with {{promptsDir}}/doctor.md + both compact summaries, model {{doctorModel}}; use its decision.
+   - no doctor → map the verifier verdict: pass + goalMet → complete; pass → continue; fail → continue; blocked or inconclusive → ask-user.
 5. WRITE a compact receipt to the loop receipts/ folder; update context.md with durable facts only.
-6. RUN: \`oris-skills loop chat --action set-state --state <continue|advance|complete|blocked>\`.
-7. END the turn with exactly: \`ORIS_LOOP_STATE: continue | advance | complete | blocked | ask_user\`.
+6. RUN: \`npx oris-skills loop chat --action set-state --state <continue|advance|complete|blocked|ask-user> --progress <yes|no>\` (progress yes = the verifier confirmed forward movement).
+7. END the turn with exactly: \`ORIS_LOOP_STATE: <continue|advance|complete|blocked|ask-user>\`.
 
-IMPROVE ({{improveMode}}):
-- auto → after the doctor verdict, the debriefer may rewrite files under {{promptsDir}} (archive the old version to history/ first). It must NEVER change scope, limits, permissions, or verification in loop.md — those go to proposals/.
+IMPROVE ({{improveMode}}, only when debriefer is in active roles):
+- auto → after the verdict, the debriefer may rewrite files under {{promptsDir}} (archive the old version to history/ first). It must NEVER change scope, limits, permissions, or verification in loop.md — those go to proposals/.
 - propose → the debriefer writes proposals/ only; nothing changes until the user approves.
 
 ALWAYS:
@@ -35,17 +38,17 @@ ALWAYS:
 - Tell the user in one line what this pass will do before spawning workers.
 
 NEVER:
-- Continue when the doctor says blocked, scope is violated, or the same failure repeats.
+- Continue when the verdict is blocked, scope is violated, or the same failure repeats.
 - Commit, push, deploy, edit .oris-flow/runtime/**, or touch paths outside the approved scope.
 - Ask "run next pass?" after continue/advance — end the turn; the hook schedules the next pass.
 
-IF prompts files are missing or subagents cannot be spawned: \`set-state --state blocked\`, say why, end the turn.`;
+IF prompt files are missing or subagents cannot be spawned: \`set-state --state blocked\`, say why, end the turn.`;
 
 export function resolveTemplatesDir(fromImportMetaUrl) {
   const scriptsLoop = path.dirname(fileURLToPath(fromImportMetaUrl));
   const candidates = [
-    path.resolve(scriptsLoop, "..", "..", "skills", "oris-loop", "templates"),
-    path.resolve(scriptsLoop, "..", "skills", "oris-loop", "templates"),
+    path.resolve(scriptsLoop, "..", "..", "skills", "oris-flow", "templates"),
+    path.resolve(scriptsLoop, "..", "skills", "oris-flow", "templates"),
   ];
   for (const candidate of candidates) {
     if (fs.existsSync(path.join(candidate, "orchestrator.md"))) return candidate;

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

@@ -98,7 +98,6 @@ if (options.temp) {
       "--action", "start",
       "--task", task.taskPath,
       "--repository-root", repoRoot,
-      "--max-repair-cycles", "0",
     ], { cwd: repoRoot, encoding: "utf8" });
     if (start.status !== 0) {
       console.error(start.stderr || start.stdout);
@@ -132,7 +131,7 @@ const chat = readJson(statePath);
 console.log("");
 console.log("chat-active.json:");
 if (!chat) {
-  console.log("(missing - run oris-skills loop chat --action start first)");
+  console.log("(missing - run npx oris-skills loop chat --action start first)");
 } else {
   console.log(JSON.stringify(chat, null, 2));
 }

package/scripts/oris-skills.mjs

@@ -32,7 +32,7 @@ function printHelp() {
   console.log(`Oris Skills
 
 Install for your agents (Cursor, Claude Code, Codex):
-  oris-skills install [--agents cursor,claude,codex] [--dry-run]
+  oris-skills install [--agents cursor,claude,codex,copilot] [--dry-run]
   oris-skills uninstall [--dry-run]
   oris-skills reinstall [--dry-run]
 
@@ -92,7 +92,8 @@ if (command === "doctor") {
 }
 
 if (command === "validate") {
-  runNode("tests/run-all-tests.mjs", ["--node-only", ...commandArgs]);
+  // Kept as an alias of the full test suite for older docs and muscle memory.
+  runNode("tests/run-all-tests.mjs", []);
 }
 
 if (command === "loop") {

package/scripts/tests/run-all-tests.mjs

@@ -14,6 +14,7 @@ const nodeTestFiles = [
   "scripts/tests/test-oris-1-0-cleanliness.mjs",
   "scripts/tests/test-oris-flow-scan.mjs",
   "scripts/tests/test-routing-lifecycle.mjs",
+  "scripts/tests/test-skill-style.mjs",
   "scripts/tests/test-oris-loop-stop.mjs",
   "scripts/tests/test-oris-loop-smoke.mjs",
   "scripts/tests/test-oris-loop-bootstrap.mjs",
@@ -33,6 +34,4 @@ function run(command, args, options = {}) {
   if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
-const nodeOnly = process.argv.includes("--node-only");
 run(process.execPath, ["--test", ...nodeTestFiles]);
-

package/scripts/tests/test-oris-flow-scan.mjs

@@ -3,7 +3,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
-import { scanRepository, writeScanResult } from "../flow/oris-flow-scan.mjs";
+import childProcess from "node:child_process";
+import { checkFreshness, scanRepository, writeScanResult } from "../flow/oris-flow-scan.mjs";
 import { ORIS_FLOW_MANIFEST } from "../flow/oris-flow-layout.mjs";
 
 function write(filePath, content) {
@@ -47,3 +48,110 @@ test("scanner supports documentation-only repositories", () => {
   }
 });
 
+test("scanner detects project type and derives inferred stack commands", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  try {
+    write(path.join(root, "App.sln"), "");
+    write(path.join(root, "src", "App", "App.csproj"), "<Project />\n");
+    write(path.join(root, "src", "App", "Controllers", "HomeController.cs"), "class HomeController {}\n");
+
+    const scan = scanRepository(root);
+    assert.equal(scan.projectType.id, "api");
+    assert.ok(scan.stacks.some((stack) => stack.id === "dotnet"));
+    const dotnetTest = scan.commands.find((command) => command.command.startsWith("dotnet test"));
+    assert.ok(dotnetTest, "expected an inferred dotnet test command");
+    assert.equal(dotnetTest.confidence, "inferred");
+    assert.equal(scan.manifest.setup.tasksRoot, ".oris-flow/tasks");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("refresh preserves confirmed sections, commands, and tasksRoot", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  try {
+    write(path.join(root, "README.md"), "# Demo\n");
+    write(path.join(root, "package.json"), `${JSON.stringify({ scripts: { test: "node --test" } })}\n`);
+
+    const first = scanRepository(root);
+    first.manifest.setup.tasksRoot = "docs/tasks";
+    first.manifest.setup.confirmedDecisions = ["tests live under scripts/tests"];
+    first.manifest.sections.docs.confidence = "confirmed";
+    first.manifest.commands[0].confidence = "confirmed";
+    writeScanResult(first);
+    const enriched = "# Docs\n\nUser-confirmed enrichment that must survive refresh.\n";
+    write(path.join(root, ".oris-flow", "maps", "docs.md"), enriched);
+
+    const second = scanRepository(root);
+    assert.equal(second.manifest.setup.tasksRoot, "docs/tasks");
+    assert.deepEqual(second.manifest.setup.confirmedDecisions, ["tests live under scripts/tests"]);
+    assert.equal(second.manifest.sections.docs.confidence, "confirmed");
+    assert.equal(second.manifest.sections.docs.stale, false);
+    assert.equal(second.manifest.commands[0].confidence, "confirmed");
+    assert.ok(second.preservedSections.has("docs"));
+
+    writeScanResult(second);
+    assert.equal(fs.readFileSync(path.join(root, ".oris-flow", "maps", "docs.md"), "utf8"), enriched);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("confirmed section without fresh evidence is marked stale, not deleted", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  try {
+    write(path.join(root, "README.md"), "# Demo\n");
+    const first = scanRepository(root);
+    first.manifest.sections.docs.confidence = "confirmed";
+    writeScanResult(first);
+
+    fs.rmSync(path.join(root, "README.md"));
+    const second = scanRepository(root);
+    assert.equal(second.manifest.sections.docs.confidence, "confirmed");
+    assert.equal(second.manifest.sections.docs.stale, true);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+
+test("scan anchors the map to HEAD; --check answers freshness from the SHA + changed files", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  const git = (...args) => childProcess.execFileSync("git", args, { cwd: root, encoding: "utf8" });
+  try {
+    write(path.join(root, "README.md"), "# Demo\n");
+    write(path.join(root, "package.json"), `${JSON.stringify({ scripts: { test: "node --test" } })}\n`);
+    git("init", "-q");
+    git("-c", "user.email=t@t", "-c", "user.name=t", "add", ".");
+    git("-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "-m", "init");
+
+    const scan = scanRepository(root);
+    assert.equal(typeof scan.manifest.headSha, "string", "scan records the HEAD anchor");
+    writeScanResult(scan);
+
+    const fresh = checkFreshness(root);
+    assert.equal(fresh.fresh, true, "same SHA + clean tree → fresh, zero reads");
+    assert.deepEqual(fresh.changedFiles, []);
+
+    write(path.join(root, "src", "new.js"), "export const later = 1;\n");
+    const stale = checkFreshness(root);
+    assert.equal(stale.fresh, false, "working-tree change → stale");
+    assert.ok(stale.changedFiles.some((file) => file.includes("new.js")), "changed files name the delta");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("outside git the map still works — no anchor, never an error", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  try {
+    write(path.join(root, "README.md"), "# Demo\n");
+    const scan = scanRepository(root);
+    assert.equal(scan.manifest.headSha, null);
+    writeScanResult(scan);
+    const check = checkFreshness(root);
+    assert.equal(check.fresh, false, "no anchor → refresh advised, not an error");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

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

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import {
+  activeRoles,
   assessPromptFiles,
   improveMode,
   normalizeModels,
@@ -16,6 +17,7 @@ kind: oris-loop
 name: bug-fix-loop
 approved: true
 phases: [observe, execute, verify, debrief]
+roles: [executor, verifier, debriefer]
 limits:
   maxIterations: 10
   maxNoProgress: 2
@@ -79,6 +81,35 @@ test("rejects unknown improve modes", () => {
   );
 });
 
+test("roles default to executor + verifier and must always include both", () => {
+  assert.deepEqual(activeRoles({}), ["executor", "verifier"]);
+  assert.deepEqual(activeRoles({ roles: ["executor", "verifier", "doctor"] }), ["executor", "verifier", "doctor"]);
+  assert.throws(
+    () => validateLoopDocumentText(
+      validLoop.replace("roles: [executor, verifier, debriefer]", "roles: [executor, debriefer]"),
+      "no-verifier.loop.md",
+    ),
+    /roles must include verifier/,
+  );
+  assert.throws(
+    () => validateLoopDocumentText(
+      validLoop.replace("roles: [executor, verifier, debriefer]", "roles: [executor, verifier, narrator]"),
+      "bad-role.loop.md",
+    ),
+    /roles must be an array/,
+  );
+});
+
+test("improve.mode auto requires the debriefer role", () => {
+  assert.throws(
+    () => validateLoopDocumentText(
+      validLoop.replace("roles: [executor, verifier, debriefer]", "roles: [executor, verifier]"),
+      "auto-without-debriefer.loop.md",
+    ),
+    /improve\.mode auto requires the debriefer role/,
+  );
+});
+
 test("normalizeModels resolves inherit, adapter aliases, and role fallbacks", () => {
   const models = normalizeModels(
     { default: "inherit", verifier: "smart", doctor: "explicit-model-id" },
@@ -96,16 +127,21 @@ test("improveMode defaults to propose", () => {
   assert.equal(improveMode({ improve: { mode: "auto" } }), "auto");
 });
 
-test("assessPromptFiles reports missing role prompt files", () => {
+test("assessPromptFiles reports missing prompts for the active roles only", () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-prompts-"));
   try {
     const empty = assessPromptFiles(dir);
-    assert.deepEqual(empty.missing, ["prompts/executor.md", "prompts/verifier.md", "prompts/doctor.md"]);
+    assert.deepEqual(empty.missing, ["prompts/executor.md", "prompts/verifier.md"]);
     fs.mkdirSync(path.join(dir, "prompts"), { recursive: true });
-    for (const file of ["executor.md", "verifier.md", "doctor.md"]) {
+    for (const file of ["executor.md", "verifier.md"]) {
       fs.writeFileSync(path.join(dir, "prompts", file), "prompt content\n", "utf8");
     }
     assert.deepEqual(assessPromptFiles(dir).missing, []);
+    assert.deepEqual(
+      assessPromptFiles(dir, ["executor", "verifier", "doctor"]).missing,
+      ["prompts/doctor.md"],
+      "opting in a role requires its prompt file",
+    );
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }