oris-skills 2.0.0

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

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import {
+  isTaskPathUnderAdapterRoots,
+  readAdapter,
+  resolveLoopDocumentPaths,
+  resolveLoopDocumentPathsBySlug,
+  runtimeRelativePath,
+} from "./oris-loop-paths.mjs";
+import {
+  ORIS_FLOW_ADAPTER,
+  ORIS_LOOP_SCHEMA,
+  ORIS_LOOP_SCHEMA_VERSION,
+  ORIS_SKILLS_SETTINGS,
+} from "../flow/oris-flow-layout.mjs";
+import {
+  assessPromptFiles,
+  improveMode,
+  normalizeModels,
+  validateLoopDocumentText,
+} from "./oris-loop-document.mjs";
+
+const terminalStates = new Set(["complete", "blocked", "cancelled"]);
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function parseArgs(argv) {
+  const options = {
+    action: "status",
+    loopSlug: "",
+    taskPath: "",
+    state: "continue",
+    repositoryRoot: "",
+    runner: "chat",
+    maxIterations: 25,
+    maxRepairCycles: 10,
+    maxMinutes: 240,
+    profile: "",
+    settingsPath: ORIS_SKILLS_SETTINGS,
+  };
+  const readValue = (index, raw) => {
+    if (raw.includes("=")) return [index, raw.slice(raw.indexOf("=") + 1)];
+    if (index + 1 >= argv.length) fail(`Missing value for ${raw}.`);
+    return [index + 1, argv[index + 1]];
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    const key = raw.toLowerCase();
+    if (key === "--action" || key.startsWith("--action=")) [i, options.action] = readValue(i, raw);
+    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 === "--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);
+    else if (key === "--settings-path" || key.startsWith("--settings-path=")) [i, options.settingsPath] = readValue(i, raw);
+    else if (key === "--max-iterations" || key.startsWith("--max-iterations=")) {
+      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];
+      options.maxMinutes = Number.parseInt(parsed[1], 10);
+    } else fail(`Unknown argument: ${raw}`);
+  }
+  options.action = options.action.toLowerCase();
+  options.state = options.state.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 (!["chat", "headless"].includes(options.runner)) fail("Unsupported --runner (chat|headless).");
+  return options;
+}
+
+function run(command, args, cwd) {
+  return childProcess.spawnSync(command, args, {
+    cwd,
+    shell: process.platform === "win32",
+    encoding: "utf8",
+  });
+}
+
+function getRoot(options) {
+  if (options.repositoryRoot) return path.resolve(options.repositoryRoot);
+  const result = run("git", ["rev-parse", "--show-toplevel"], process.cwd());
+  if (result.status !== 0 || !result.stdout.trim()) fail("Run inside a Git worktree or pass --repository-root.");
+  return path.resolve(result.stdout.trim());
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  fs.renameSync(temporary, filePath);
+}
+
+function setContextField(content, name, value) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^${escaped}:\\s*.*$`, "m");
+  const replacement = `${name}: ${value}`;
+  return pattern.test(content) ? content.replace(pattern, replacement) : `${content.trimEnd()}\n${replacement}\n`;
+}
+
+function reconcileContext(root, state) {
+  if (!state.taskPath) return;
+  const contextPath = state.contextPath ? path.resolve(root, state.contextPath) : "";
+  if (!contextPath) return;
+  const contextRelative = path.relative(root, contextPath);
+  if (contextRelative.startsWith("..") || path.isAbsolute(contextRelative)) return;
+  if (!fs.existsSync(contextPath)) return;
+  let content = fs.readFileSync(contextPath, "utf8");
+  const phases = Array.isArray(state.phases) ? state.phases : ["execute"];
+  const phase = currentPhase({ ...state, phases });
+  for (const [name, value] of Object.entries({
+    Run: state.active === true ? "active" : "inactive",
+    State: state.state,
+    "Current program": state.program,
+    "Current phase": phase,
+    "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),
+    Updated: new Date().toISOString(),
+  })) {
+    content = setContextField(content, name, value);
+  }
+  const temporary = `${contextPath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+  fs.renameSync(temporary, contextPath);
+}
+
+function getPathValue(value, dottedPath) {
+  return dottedPath.split(".").filter(Boolean).reduce((current, key) => (
+    current != null && typeof current === "object" ? current[key] : undefined
+  ), value);
+}
+
+function validateRequiredProfile(options, adapter) {
+  if (adapter.profile?.required !== true) return;
+  const notArmed = "Oris chat loop was not armed; the stop hook will not resume this chat. Fix the profile, rerun start, then end the turn.";
+  if (!fs.existsSync(options.settingsPath)) fail(`Required Oris settings are missing: ${options.settingsPath}. ${notArmed}`);
+  const settings = JSON.parse(fs.readFileSync(options.settingsPath, "utf8"));
+  if (settings.version !== 1) fail(`Oris settings must use schema v1. ${notArmed}`);
+  const role = adapter.profile.defaultRole || "testing";
+  const profileName = options.profile || settings.defaultProfiles?.[role];
+  const profile = settings.profiles?.[profileName];
+  if (!profile) fail(`Required Oris profile '${profileName || "(none)"}' was not found. ${notArmed}`);
+  for (const mapping of adapter.profile.mappings ?? []) {
+    const value = getPathValue(profile, mapping.from);
+    if (mapping.required === true && (value == null || String(value).trim() === "")) {
+      fail(`Profile '${profileName}' is missing required field '${mapping.from}'. ${notArmed}`);
+    }
+  }
+}
+
+/** A same-chat loop needs at least one armed stop hook: Cursor or Claude Code. */
+function assessStopHooks(root) {
+  const registered = [];
+  const cursorHooks = path.join(root, ".cursor", "hooks.json");
+  if (fs.existsSync(cursorHooks)) {
+    try {
+      const hooks = JSON.parse(fs.readFileSync(cursorHooks, "utf8"));
+      const stops = hooks?.hooks?.stop ?? [];
+      if (stops.some((entry) => String(entry?.command ?? "").includes("oris-loop-stop"))) registered.push("cursor");
+    } catch {
+      // Unreadable hooks.json counts as not registered.
+    }
+  }
+  const claudeSettings = path.join(root, ".claude", "settings.json");
+  if (fs.existsSync(claudeSettings)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(claudeSettings, "utf8"));
+      const stops = settings?.hooks?.Stop ?? [];
+      const flat = JSON.stringify(stops);
+      if (flat.includes("oris-loop-stop")) registered.push("claude");
+    } catch {
+      // Unreadable settings.json counts as not registered.
+    }
+  }
+  return registered;
+}
+
+function currentPhase(state) {
+  const phases = Array.isArray(state.phases) && state.phases.length > 0 ? state.phases : ["execute"];
+  const index = Number.isInteger(Number(state.phaseIndex)) ? Number(state.phaseIndex) : 0;
+  return phases[Math.max(0, Math.min(index, phases.length - 1))] ?? phases[0];
+}
+
+function normalizeChatState(state) {
+  if (!state || typeof state !== "object") fail("Invalid Oris chat loop state.");
+  const normalized = { ...state };
+  const version = Number(normalized.schemaVersion ?? 0);
+  if (version !== 1) {
+    fail(`Unsupported chat loop schemaVersion: ${normalized.schemaVersion}`);
+  }
+  normalized.phases = Array.isArray(normalized.phases) && normalized.phases.length > 0
+    ? normalized.phases
+    : ["execute"];
+  normalized.phaseName = currentPhase(normalized);
+  normalized.iteration = Number(normalized.iteration ?? 0);
+  normalized.phaseIteration = Number(normalized.phaseIteration ?? 0);
+  normalized.repairCycles = Number(normalized.repairCycles ?? 0);
+  normalized.phaseIndex = Number.isInteger(Number(normalized.phaseIndex)) ? Number(normalized.phaseIndex) : 0;
+  if (normalized.state === "running" && normalized.active === true) {
+    normalized.state = "continue";
+  }
+  return normalized;
+}
+
+function readChatState() {
+  return normalizeChatState(JSON.parse(fs.readFileSync(statePath, "utf8")));
+}
+
+const options = parseArgs(process.argv.slice(2));
+const root = getRoot(options);
+const adapterForRuntime = readAdapter(root, ORIS_FLOW_ADAPTER);
+const runtimeRoot = path.join(root, runtimeRelativePath(adapterForRuntime));
+const statePath = path.join(runtimeRoot, "chat-active.json");
+
+if (options.action === "start") {
+  if (!options.taskPath && !options.loopSlug) fail("--task or --loop is required for start.");
+  if (options.taskPath && options.loopSlug) fail("Use either --task or --loop for start, not both.");
+  const adapterPath = path.join(root, ORIS_FLOW_ADAPTER);
+  if (!fs.existsSync(adapterPath)) fail(`Repository adapter is missing: ${adapterPath}. Run: oris-skills loop bootstrap`);
+  const adapter = JSON.parse(fs.readFileSync(adapterPath, "utf8"));
+  if (
+    adapter.$schema !== ORIS_LOOP_SCHEMA
+    || adapter.schemaVersion !== ORIS_LOOP_SCHEMA_VERSION
+    || !adapter.paths
+    || !Array.isArray(adapter.paths.allowed)
+  ) {
+    fail(`Repository adapter must use schemaVersion ${ORIS_LOOP_SCHEMA_VERSION}: ${adapterPath}`);
+  }
+  if (options.taskPath) {
+    const taskFull = path.resolve(root, options.taskPath);
+    const relative = path.relative(root, taskFull);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) fail("--task must be below the repository root.");
+    if (!isTaskPathUnderAdapterRoots(root, options.taskPath, adapter)) {
+      fail("--task is outside adapter paths.taskRoots.");
+    }
+  }
+  const loopDocs = options.loopSlug
+    ? resolveLoopDocumentPathsBySlug(root, options.loopSlug, adapter)
+    : resolveLoopDocumentPaths(root, options, adapter);
+  const loopPath = loopDocs.loopFull;
+  const contextPath = loopDocs.contextFull;
+  for (const required of [adapterPath, loopPath, contextPath]) {
+    if (!fs.existsSync(required)) fail(`Required loop file is missing: ${required}`);
+  }
+  if (options.runner === "chat") {
+    const hooks = assessStopHooks(root);
+    if (hooks.length === 0) {
+      fail("No Oris stop hook is registered (.cursor/hooks.json or .claude/settings.json). Run: oris-skills loop bootstrap");
+    }
+  }
+  validateRequiredProfile(options, adapter);
+  const minimumFreeDiskGiB = Number(adapter.preflight?.minFreeDiskGiB ?? 0);
+  if (typeof fs.statfsSync === "function") {
+    const disk = fs.statfsSync(root);
+    const freeDiskGiB = Number(disk.bavail) * Number(disk.bsize) / 1024 ** 3;
+    if (freeDiskGiB < minimumFreeDiskGiB) {
+      fail(`Disk preflight failed: ${freeDiskGiB.toFixed(2)} GiB free; ${minimumFreeDiskGiB} GiB required.`);
+    }
+  }
+  const loopText = fs.readFileSync(loopPath, "utf8");
+  let loopDocument;
+  try {
+    loopDocument = validateLoopDocumentText(loopText, loopPath);
+  } catch (error) {
+    fail(error.message);
+  }
+  const prompts = assessPromptFiles(path.dirname(loopPath));
+  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)) {
+      fail(`An Oris chat loop is already active for this workspace: ${existing.taskPath}. Run --action stop before starting again.`);
+    }
+  }
+  const loopMetadata = loopDocument.data;
+  const phases = [...loopMetadata.phases];
+  const nextState = {
+    schemaVersion: 1,
+    active: true,
+    state: "continue",
+    runner: options.runner,
+    program: loopMetadata.name,
+    phases,
+    phaseIndex: 0,
+    phaseName: phases[0],
+    phaseIteration: 0,
+    taskPath: (options.taskPath || loopDocs.taskPath).replaceAll("\\", "/"),
+    repositoryRoot: root.replaceAll("\\", "/"),
+    loopPath: loopDocs.loopRelative,
+    contextPath: loopDocs.contextRelative,
+    promptsPath: loopDocs.promptsRelative,
+    models: normalizeModels(loopMetadata.models, adapter.models),
+    improveMode: improveMode(loopMetadata),
+    conversationId: null,
+    iteration: 0,
+    maxIterations: loopMetadata.limits.maxIterations,
+    repairCycles: 0,
+    maxRepairCycles: options.maxRepairCycles,
+    maxMinutes: loopMetadata.limits.maxMinutes ?? options.maxMinutes,
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  writeJson(statePath, nextState);
+  reconcileContext(root, nextState);
+  console.log(`Oris loop armed (${options.runner}): ${loopMetadata.name} / ${(options.taskPath || loopDocs.taskPath).replaceAll("\\", "/")}`);
+  process.exit(0);
+}
+
+if (!fs.existsSync(statePath)) {
+  if (options.action === "status") {
+    console.log("No Oris chat loop state.");
+    process.exit(0);
+  }
+  fail(`No Oris chat loop state exists at ${statePath}`);
+}
+
+const current = readChatState();
+
+if (options.action === "repair") {
+  if (current.active === true) {
+    current.startedAt = new Date().toISOString();
+    delete current.stopReason;
+  } else if (
+    current.state === "blocked"
+    && /limit exhausted/.test(String(current.stopReason ?? ""))
+    && Number(current.iteration ?? 0) < Number(current.maxIterations ?? 25)
+  ) {
+    current.active = true;
+    current.state = "continue";
+    current.startedAt = new Date().toISOString();
+    delete current.stopReason;
+  }
+  current.conversationId = null;
+  current.updatedAt = new Date().toISOString();
+  writeJson(statePath, current);
+  reconcileContext(root, current);
+  console.log(`Oris chat loop repaired: schemaVersion ${current.schemaVersion}, state ${current.state}.`);
+  process.exit(0);
+}
+
+if (options.action === "set-state") {
+  const phases = Array.isArray(current.phases) && current.phases.length > 0 ? current.phases : ["execute"];
+  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);
+  }
+  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}`);
+  process.exit(0);
+}
+
+if (options.action === "stop") {
+  current.state = "cancelled";
+  current.active = false;
+  current.stopReason = "manual stop";
+  current.updatedAt = new Date().toISOString();
+  writeJson(statePath, current);
+  reconcileContext(root, current);
+  console.log("Oris chat loop cancelled.");
+  process.exit(0);
+}
+
+console.log(JSON.stringify({
+  active: Boolean(current.active),
+  state: current.state,
+  runner: current.runner ?? "chat",
+  program: current.program,
+  phase: currentPhase(current),
+  taskPath: current.taskPath,
+  iteration: Number(current.iteration ?? 0),
+  maxIterations: Number(current.maxIterations ?? 0),
+  improveMode: current.improveMode ?? "propose",
+  models: current.models ?? {},
+  conversationBound: Boolean(current.conversationId),
+  updatedAt: current.updatedAt,
+}, null, 2));

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

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+/**
+ * `oris-skills loop demo` — create a safe tutorial loop the user can run to
+ * learn Oris loops end to end. The demo only writes inside its own loop
+ * folder, so it cannot touch product files.
+ */
+
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { bootstrapLoop } from "./oris-loop-bootstrap.mjs";
+import { defaultLoopDocumentPaths, readAdapter } from "./oris-loop-paths.mjs";
+
+const DEMO_SLUG = "oris-demo";
+
+function fail(message) {
+  console.error(`[oris-skills] ERROR ${message}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const options = { repositoryRoot: "", force: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    if (raw === "--force") options.force = true;
+    else if (raw.startsWith("--repository-root=")) options.repositoryRoot = raw.slice("--repository-root=".length);
+    else if (raw === "--repository-root" && argv[i + 1]) {
+      options.repositoryRoot = argv[i + 1];
+      i += 1;
+    }
+  }
+  return options;
+}
+
+function getRoot(options) {
+  if (options.repositoryRoot) return path.resolve(options.repositoryRoot);
+  const result = childProcess.spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: process.cwd(),
+    shell: process.platform === "win32",
+    encoding: "utf8",
+  });
+  if (result.status !== 0 || !result.stdout.trim()) fail("Run inside a Git worktree or pass --repository-root.");
+  return path.resolve(result.stdout.trim());
+}
+
+const options = parseArgs(process.argv.slice(2));
+const root = getRoot(options);
+
+const bootstrap = bootstrapLoop(root, {});
+if (!bootstrap.ready) fail(`Loop bootstrap incomplete: ${bootstrap.after.missing.join(", ")}`);
+
+const adapter = readAdapter(root);
+const docs = defaultLoopDocumentPaths(root, DEMO_SLUG, adapter);
+const loopDir = path.dirname(docs.loopFull);
+if (fs.existsSync(docs.loopFull) && !options.force) {
+  fail(`Demo loop already exists: ${docs.loopRelative}. Re-run with --force to recreate it.`);
+}
+
+const workspaceRelative = `${docs.loopDir}/workspace`.replace(/\\/g, "/");
+fs.mkdirSync(path.join(loopDir, "workspace"), { recursive: true });
+fs.mkdirSync(path.join(loopDir, "prompts"), { recursive: true });
+fs.mkdirSync(path.join(loopDir, "receipts"), { recursive: true });
+fs.mkdirSync(path.join(loopDir, "proposals"), { recursive: true });
+fs.mkdirSync(path.join(loopDir, "history"), { recursive: true });
+
+fs.writeFileSync(path.join(loopDir, "workspace", "counter.txt"), "0\n", "utf8");
+
+fs.writeFileSync(docs.loopFull, `---
+schemaVersion: 2
+kind: oris-loop
+name: ${DEMO_SLUG}
+approved: true
+phases: [work]
+limits:
+  maxIterations: 3
+  maxNoProgress: 2
+  maxMinutes: 30
+models:
+  default: inherit
+improve:
+  mode: auto
+permissions:
+  allowedPaths: [${workspaceRelative}, ${docs.loopDir.replace(/\\/g, "/")}]
+  forbiddenActions: [commit, push, deploy, external-message]
+verification:
+  commands: []
+  evidenceRequired: true
+---
+
+# Oris demo loop
+
+Goal: increment the number in \`${workspaceRelative}/counter.txt\` by 1 per pass until it reaches 3.
+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;
+- 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.
+`, "utf8");
+
+fs.writeFileSync(path.join(loopDir, "prompts", "executor.md"), `# Executor prompt — demo loop (edit me and watch the next pass change)
+
+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:
+{ "role": "executor", "state": "claimed|blocked", "summary": "", "changedFiles": [], "claim": "counter is now N" }
+`, "utf8");
+
+fs.writeFileSync(path.join(loopDir, "prompts", "verifier.md"), `# Verifier prompt — demo loop
+
+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.
+
+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": "" }
+`, "utf8");
+
+fs.writeFileSync(path.join(loopDir, "prompts", "debriefer.md"), `# Debriefer prompt — demo loop (improve mode: auto)
+
+You are the debriefer. After each pass, read the latest receipt.
+IF a prompt caused friction: rewrite that file under prompts/ (copy the old one to history/ first) and note the change.
+ONE small improvement max per pass. NEVER touch loop.md.
+
+RETURN compact JSON only:
+{ "role": "debriefer", "outcome": "keep|tuned", "insight": "", "changedFiles": [] }
+`, "utf8");
+
+fs.writeFileSync(docs.contextFull, `# Oris Loop Context
+
+Run: inactive
+State: ready
+Current program: ${DEMO_SLUG}
+Current phase: work
+Current phase index: 0
+Current iteration: 0
+Phase iteration: 0
+Repair cycles: 0
+Updated: ${new Date().toISOString()}
+
+## Objective
+
+Learn the Oris loop system: counter 0 → 3, one increment per pass.
+
+## Next action
+
+Increment the counter from its current value.
+`, "utf8");
+
+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("     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`);