oris-skills 2.0.0

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

@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  ORIS_FLOW_ADAPTER,
+  ORIS_FLOW_LOOPS_ROOT,
+  ORIS_FLOW_RUNTIME,
+  safeSlug,
+  toPosixPath,
+} from "../flow/oris-flow-layout.mjs";
+import { parseFrontMatter, validateLoopMetadata } from "./oris-loop-document.mjs";
+
+const DEFAULT_RUNTIME_RELATIVE = ORIS_FLOW_RUNTIME;
+const DEFAULT_LOOPS_RELATIVE = ORIS_FLOW_LOOPS_ROOT;
+
+export function safeTaskSlug(taskPath) {
+  return safeSlug(taskPath, "loop");
+}
+
+export function runtimeRelativePath(adapter) {
+  const value = adapter?.paths?.runtime ?? DEFAULT_RUNTIME_RELATIVE;
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
+    throw new Error("Adapter paths.runtime must be a non-empty repository-relative path without '..'.");
+  }
+  return value.replace(/\\/g, "/");
+}
+
+export function loopsRelativePath(adapter) {
+  const value = adapter?.paths?.loops ?? DEFAULT_LOOPS_RELATIVE;
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
+    throw new Error("Adapter paths.loops must be a non-empty repository-relative path without '..'.");
+  }
+  return value.replace(/\\/g, "/");
+}
+
+export function loopDocsDirectory(loopsRelative, taskSlug) {
+  return path.join(loopsRelative, taskSlug).replace(/\\/g, "/");
+}
+
+function resolveExplicitOrDefault(root, explicit, defaultRelative) {
+  if (explicit) return path.resolve(root, explicit);
+  return path.resolve(root, defaultRelative);
+}
+
+/**
+ * Resolve loop.md and context.md paths under `.oris-flow/loops/{slug}/`.
+ */
+export function resolveLoopDocumentPaths(root, options, adapter = null) {
+  const taskPath = String(options.taskPath ?? "").replace(/\\/g, "/");
+  if (!taskPath) throw new Error("--task is required.");
+  const slug = safeTaskSlug(taskPath);
+  const resolvedAdapter = adapter ?? readAdapter(root, options.adapterPath);
+  const runtimeRelative = runtimeRelativePath(resolvedAdapter);
+  const loopsRelative = loopsRelativePath(resolvedAdapter);
+  const loopDir = loopDocsDirectory(loopsRelative, slug);
+  const defaultLoopRelative = path.join(loopDir, "loop.md").replace(/\\/g, "/");
+  const defaultContextRelative = path.join(loopDir, "context.md").replace(/\\/g, "/");
+
+  const loopFull = options.loopPath
+    ? resolveExplicitOrDefault(root, options.loopPath, defaultLoopRelative)
+    : resolveExplicitOrDefault(root, "", defaultLoopRelative);
+  const contextFull = options.contextPath
+    ? resolveExplicitOrDefault(root, options.contextPath, defaultContextRelative)
+    : resolveExplicitOrDefault(root, "", defaultContextRelative);
+
+  return {
+    taskPath,
+    taskSlug: slug,
+    runtimeRelative,
+    loopsRelative,
+    loopDir,
+    runtimeDir: runtimeRelative,
+    loopFull,
+    contextFull,
+    promptsFull: path.join(path.dirname(loopFull), "prompts"),
+    loopRelative: path.relative(root, loopFull).replace(/\\/g, "/"),
+    contextRelative: path.relative(root, contextFull).replace(/\\/g, "/"),
+    promptsRelative: path.join(path.dirname(path.relative(root, loopFull)), "prompts").replace(/\\/g, "/"),
+  };
+}
+
+export function resolveLoopDocumentPathsBySlug(root, loopSlug, adapter = null) {
+  const slug = String(loopSlug ?? "").trim();
+  if (!slug || safeSlug(slug) !== slug) {
+    throw new Error("--loop must be an existing loop slug, not a path.");
+  }
+  const resolvedAdapter = adapter ?? readAdapter(root);
+  const runtimeRelative = runtimeRelativePath(resolvedAdapter);
+  const loopsRelative = loopsRelativePath(resolvedAdapter);
+  const loopDir = loopDocsDirectory(loopsRelative, slug);
+  const loopFull = path.resolve(root, loopDir, "loop.md");
+  const contextFull = path.resolve(root, loopDir, "context.md");
+  return {
+    taskPath: slug,
+    taskSlug: slug,
+    runtimeRelative,
+    loopsRelative,
+    loopDir,
+    runtimeDir: runtimeRelative,
+    loopFull,
+    contextFull,
+    promptsFull: path.resolve(root, loopDir, "prompts"),
+    loopRelative: path.relative(root, loopFull).replace(/\\/g, "/"),
+    contextRelative: path.relative(root, contextFull).replace(/\\/g, "/"),
+    promptsRelative: path.join(loopDir, "prompts").replace(/\\/g, "/"),
+  };
+}
+
+export function defaultLoopDocumentPaths(root, taskPath, adapter = null) {
+  const slug = safeTaskSlug(taskPath);
+  const resolvedAdapter = adapter ?? readAdapter(root);
+  const runtimeRelative = runtimeRelativePath(resolvedAdapter);
+  const loopsRelative = loopsRelativePath(resolvedAdapter);
+  const loopDir = loopDocsDirectory(loopsRelative, slug);
+  return {
+    taskPath: toPosixPath(taskPath),
+    taskSlug: slug,
+    runtimeRelative,
+    loopsRelative,
+    loopDir,
+    runtimeDir: runtimeRelative,
+    loopFull: path.resolve(root, loopDir, "loop.md"),
+    contextFull: path.resolve(root, loopDir, "context.md"),
+    promptsFull: path.resolve(root, loopDir, "prompts"),
+    loopRelative: path.join(loopDir, "loop.md").replace(/\\/g, "/"),
+    contextRelative: path.join(loopDir, "context.md").replace(/\\/g, "/"),
+    promptsRelative: path.join(loopDir, "prompts").replace(/\\/g, "/"),
+  };
+}
+
+export function readAdapter(root, adapterPath = ORIS_FLOW_ADAPTER) {
+  const adapterFull = path.resolve(root, adapterPath);
+  if (!fs.existsSync(adapterFull)) return { paths: { runtime: DEFAULT_RUNTIME_RELATIVE, loops: DEFAULT_LOOPS_RELATIVE } };
+  return JSON.parse(fs.readFileSync(adapterFull, "utf8"));
+}
+
+export function isTaskPathUnderAdapterRoots(root, taskPath, adapter) {
+  const taskFull = path.resolve(root, taskPath);
+  const taskRoots = adapter?.paths?.taskRoots ?? [];
+  if (!Array.isArray(taskRoots) || taskRoots.length === 0) return true;
+  return taskRoots.some((value) => {
+    const parent = path.resolve(root, value);
+    const relative = path.relative(parent, taskFull);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+  });
+}
+
+function readMarkdownField(text, fieldName) {
+  const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = text.match(new RegExp(`^${escaped}:\\s*(.+)$`, "m"));
+  return match ? match[1].trim() : "";
+}
+
+function readMarkdownSection(text, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = text.match(new RegExp(`^## ${escaped}\\s*\\n+([\\s\\S]*?)(?:\\n## |\\n*$)`, "m"));
+  if (!match) return "";
+  return match[1]
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 3)
+    .join(" ");
+}
+
+function readLoopMetadata(loopText) {
+  try {
+    const { data } = parseFrontMatter(loopText);
+    validateLoopMetadata(data);
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function summarizeLoopDocuments(root, entry) {
+  const loopText = fs.existsSync(entry.loopFull) ? fs.readFileSync(entry.loopFull, "utf8") : "";
+  const contextText = fs.existsSync(entry.contextFull) ? fs.readFileSync(entry.contextFull, "utf8") : "";
+  const objective = readMarkdownSection(contextText, "Objective");
+  const nextAction = readMarkdownSection(contextText, "Next action");
+  const summary = objective || nextAction || loopText.split(/\r?\n/).find((line) => line.trim() && !line.startsWith("#"))?.trim() || "";
+  const metadata = readLoopMetadata(loopText);
+  return {
+    ...entry,
+    program: metadata?.name ?? "",
+    runtime: metadata?.runtime ?? "",
+    phases: metadata?.phases ?? [],
+    phase: readMarkdownField(contextText, "Current phase") || "",
+    run: readMarkdownField(contextText, "Run") || "inactive",
+    state: readMarkdownField(contextText, "State") || "",
+    updated: readMarkdownField(contextText, "Updated") || "",
+    objective: summary,
+  };
+}
+
+/**
+ * Discover loop documents under `.oris-flow/loops/{slug}/`.
+ */
+export function discoverExistingLoops(root, adapter = null) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedAdapter = adapter ?? readAdapter(resolvedRoot);
+  const runtimeRelative = runtimeRelativePath(resolvedAdapter);
+  const loopsRelative = loopsRelativePath(resolvedAdapter);
+  const loopsFull = path.resolve(resolvedRoot, loopsRelative);
+  const loops = [];
+
+  if (!fs.existsSync(loopsFull)) {
+    return loops;
+  }
+
+  for (const entry of fs.readdirSync(loopsFull, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const slug = entry.name;
+    const loopFull = path.join(loopsFull, slug, "loop.md");
+    const contextFull = path.join(loopsFull, slug, "context.md");
+    if (!fs.existsSync(loopFull) || !fs.existsSync(contextFull)) continue;
+    loops.push(summarizeLoopDocuments(resolvedRoot, {
+      root: resolvedRoot,
+      slug,
+      taskPath: slug,
+      runtimeRelative,
+      loopsRelative,
+      loopDir: loopDocsDirectory(loopsRelative, slug),
+      runtimeDir: runtimeRelative,
+      loopFull,
+      contextFull,
+      loopRelative: path.relative(resolvedRoot, loopFull).replace(/\\/g, "/"),
+      contextRelative: path.relative(resolvedRoot, contextFull).replace(/\\/g, "/"),
+    }));
+  }
+
+  return loops.sort((left, right) => left.slug.localeCompare(right.slug));
+}

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

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+/**
+ * `oris-skills loop run --loop <slug> --agent codex|claude` — headless runner.
+ *
+ * Platforms without an injectable stop hook (Codex today) still get true
+ * role isolation: every role runs as a separate CLI invocation with its own
+ * prompt file and its own model. The same runner also works with Claude Code
+ * (`claude -p`) for CI-style unattended loops.
+ */
+
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { readAdapter, resolveLoopDocumentPathsBySlug } from "./oris-loop-paths.mjs";
+import {
+  assessPromptFiles,
+  improveMode,
+  normalizeModels,
+  validateLoopDocumentText,
+} from "./oris-loop-document.mjs";
+import { substitutePlaceholders } from "./oris-loop-templates.mjs";
+import { ORIS_FLOW_RUNTIME } from "../flow/oris-flow-layout.mjs";
+
+const ROLE_TIMEOUT_MS = 15 * 60 * 1000;
+
+function fail(message) {
+  console.error(`[oris-skills] ERROR ${message}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const options = { repositoryRoot: "", loopSlug: "", agent: "codex", maxPasses: 0 };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    const value = (flag) => {
+      if (raw.includes("=")) return raw.slice(raw.indexOf("=") + 1);
+      if (i + 1 >= argv.length) fail(`Missing value for ${flag}.`);
+      i += 1;
+      return argv[i];
+    };
+    if (raw === "--loop" || raw.startsWith("--loop=")) options.loopSlug = value("--loop");
+    else if (raw === "--agent" || raw.startsWith("--agent=")) options.agent = value("--agent");
+    else if (raw === "--max-passes" || raw.startsWith("--max-passes=")) options.maxPasses = Number.parseInt(value("--max-passes"), 10);
+    else if (raw === "--repository-root" || raw.startsWith("--repository-root=")) options.repositoryRoot = value("--repository-root");
+    else fail(`Unknown argument: ${raw}`);
+  }
+  options.agent = options.agent.toLowerCase();
+  if (!["codex", "claude"].includes(options.agent)) fail("--agent must be codex or claude.");
+  if (!options.loopSlug) fail("--loop <slug> is required.");
+  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());
+}
+
+/** Build the CLI invocation for one role. Exported for tests. */
+export function buildRoleInvocation(agent, { prompt, model, root }) {
+  if (agent === "claude") {
+    const args = ["-p", prompt, "--permission-mode", "acceptEdits"];
+    if (model && model !== "inherit") args.push("--model", model);
+    return { command: "claude", args, cwd: root };
+  }
+  const args = ["exec", "--sandbox", "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 });
+  process.stdout.write(`  ${role} (${agent}${model && model !== "inherit" ? `, ${model}` : ""})... `);
+  const result = childProcess.spawnSync(invocation.command, invocation.args, {
+    cwd: invocation.cwd,
+    shell: process.platform === "win32",
+    encoding: "utf8",
+    timeout: ROLE_TIMEOUT_MS,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+  const evidencePath = path.join(evidenceDir, `pass-${pass}-${role}.log`);
+  fs.writeFileSync(evidencePath, output || "(no output)", "utf8");
+  if (result.error) {
+    console.log("FAILED");
+    fail(`${invocation.command} could not run (${result.error.message}). Is the ${agent} CLI installed and on PATH?`);
+  }
+  console.log(result.status === 0 ? "done" : `exit ${result.status}`);
+  return { status: result.status ?? 1, output, evidencePath };
+}
+
+/** Pull the last JSON object out of an agent's free-form output. */
+export function extractJson(output) {
+  const text = String(output ?? "");
+  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 {
+        return JSON.parse(text.slice(start, end + 1));
+      } catch {
+        // widen to the next closing brace
+      }
+    }
+  }
+  return null;
+}
+
+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";
+  return "blocked";
+}
+
+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], {
+    cwd: root,
+    encoding: "utf8",
+  });
+  if (result.status !== 0) fail(`loop chat ${args.join(" ")} failed: ${result.stderr || result.stdout}`);
+  return result.stdout;
+}
+
+function readContextSection(contextText, heading) {
+  const match = contextText.match(new RegExp(`^## ${heading}\\s*\\n+([\\s\\S]*?)(?:\\n## |$)`, "m"));
+  return match ? match[1].trim() : "";
+}
+
+function rolePrompt(promptsDir, name, values, extra) {
+  const text = fs.readFileSync(path.join(promptsDir, name), "utf8");
+  const filled = substitutePlaceholders(text, values);
+  return extra ? `${filled}\n\n${extra}` : filled;
+}
+
+function main() {
+const options = parseArgs(process.argv.slice(2));
+const root = getRoot(options);
+const adapter = readAdapter(root);
+const docs = resolveLoopDocumentPathsBySlug(root, options.loopSlug, adapter);
+if (!fs.existsSync(docs.loopFull)) fail(`Loop not found: ${docs.loopRelative}`);
+
+let loopDocument;
+try {
+  loopDocument = validateLoopDocumentText(fs.readFileSync(docs.loopFull, "utf8"), docs.loopRelative);
+} catch (error) {
+  fail(error.message);
+}
+const metadata = loopDocument.data;
+const prompts = assessPromptFiles(path.dirname(docs.loopFull));
+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);
+const maxPasses = options.maxPasses > 0 ? Math.min(options.maxPasses, metadata.limits.maxIterations) : metadata.limits.maxIterations;
+const evidenceDir = path.join(root, ORIS_FLOW_RUNTIME, "evidence");
+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})`);
+chatAction(root, ["--action", "start", "--loop", options.loopSlug, "--runner", "headless"]);
+
+let state = "continue";
+for (let pass = 1; pass <= maxPasses && (state === "continue" || state === "advance"); pass += 1) {
+  console.log(`Pass ${pass}/${maxPasses}:`);
+  const contextText = fs.readFileSync(docs.contextFull, "utf8");
+  const runtimeValues = {
+    iteration: pass,
+    phase: metadata.phases[0],
+    currentTarget: readContextSection(contextText, "Next action") || "(see context)",
+  };
+  const contextBlock = `CURRENT CONTEXT (${docs.contextRelative}):\n${contextText}`;
+
+  const executor = runRole(options.agent, "executor",
+    rolePrompt(prompts.promptsDir, "executor.md", runtimeValues, contextBlock),
+    models.executor, root, evidenceDir, pass);
+  const executorResult = extractJson(executor.output);
+
+  const verifier = runRole(options.agent, "verifier",
+    rolePrompt(prompts.promptsDir, "verifier.md", runtimeValues,
+      `EXECUTOR CLAIM:\n${JSON.stringify(executorResult ?? { raw: "see evidence" }, null, 2)}`),
+    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);
+
+  if (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}`),
+      models.debriefer, root, evidenceDir, pass);
+  }
+
+  const receiptPath = path.join(receiptsDir, `pass-${String(pass).padStart(3, "0")}.md`);
+  fs.writeFileSync(receiptPath, `# Oris Loop Receipt
+
+Loop: ${metadata.name}
+Pass: ${pass}
+Runner: headless (${options.agent})
+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"}
+
+Evidence:
+- ${path.relative(root, executor.evidencePath).replace(/\\/g, "/")}
+- ${path.relative(root, verifier.evidencePath).replace(/\\/g, "/")}
+- ${path.relative(root, doctor.evidencePath).replace(/\\/g, "/")}
+`, "utf8");
+
+  chatAction(root, ["--action", "set-state", "--state", state === "advance" ? "advance" : state]);
+  console.log(`  state: ${state} | receipt: ${path.relative(root, receiptPath).replace(/\\/g, "/")}`);
+}
+
+if (state === "continue" || state === "advance") {
+  chatAction(root, ["--action", "set-state", "--state", "blocked"]);
+  console.log("Pass budget exhausted before completion — state set to blocked.");
+  process.exit(1);
+}
+console.log(`Headless run finished: ${state}`);
+process.exit(state === "complete" ? 0 : 1);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  main();
+}