oris-skills 2.0.0

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

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ORIS_LOOP_DOCUMENT_VERSION } from "../flow/oris-flow-layout.mjs";
+
+const slugPattern = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+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 IMPROVE_MODES = new Set(["propose", "auto"]);
+
+export function parseFrontMatter(text, filePath = "loop.md") {
+  const normalized = String(text ?? "").replace(/^\uFEFF/, "");
+  if (!normalized.startsWith("---\n") && !normalized.startsWith("---\r\n")) {
+    throw new Error(`${filePath} must start with front matter.`);
+  }
+  const match = normalized.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) throw new Error(`${filePath} front matter is not closed.`);
+  return {
+    data: parseSimpleYaml(match[1], filePath),
+    body: normalized.slice(match[0].length),
+  };
+}
+
+function parseSimpleYaml(source, filePath) {
+  const root = {};
+  const stack = [{ indent: -1, value: root }];
+  const lines = source.split(/\r?\n/);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    if (!raw.trim() || raw.trimStart().startsWith("#")) continue;
+    const indent = raw.match(/^ */)?.[0].length ?? 0;
+    const trimmed = raw.trim();
+    const match = trimmed.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
+    if (!match) throw new Error(`${filePath} front matter line ${index + 1} is not supported: ${raw}`);
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+    const parent = stack[stack.length - 1].value;
+    const key = match[1];
+    const valueText = match[2] ?? "";
+    if (valueText === "") {
+      const value = {};
+      parent[key] = value;
+      stack.push({ indent, value });
+    } else {
+      parent[key] = parseScalar(valueText);
+    }
+  }
+
+  return root;
+}
+
+function parseScalar(valueText) {
+  const value = valueText.trim();
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^-?\d+$/.test(value)) return Number.parseInt(value, 10);
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(",").map((item) => stripQuotes(item.trim())).filter(Boolean);
+  }
+  return stripQuotes(value);
+}
+
+function stripQuotes(value) {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+export function readLoopDocument(filePath) {
+  return parseFrontMatter(fs.readFileSync(filePath, "utf8"), filePath);
+}
+
+export function validateLoopDocumentText(text, filePath = "loop.md") {
+  const parsed = parseFrontMatter(text, filePath);
+  validateLoopMetadata(parsed.data, filePath);
+  if (!parsed.body.trim()) {
+    throw new Error(`${filePath} body must describe the loop goal and stop condition.`);
+  }
+  return parsed;
+}
+
+export function validateLoopMetadata(data, filePath = "loop.md") {
+  const errors = [];
+  if (data.schemaVersion !== ORIS_LOOP_DOCUMENT_VERSION) {
+    errors.push(`schemaVersion must be ${ORIS_LOOP_DOCUMENT_VERSION}`);
+  }
+  if (data.kind !== "oris-loop") errors.push("kind must be oris-loop");
+  if (typeof data.name !== "string" || !slugPattern.test(data.name)) errors.push("name must be a stable slug");
+  if (data.approved !== true) errors.push("approved must be true (the user approves the loop before it can run)");
+  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.limits || !Number.isInteger(data.limits.maxIterations) || data.limits.maxIterations < 1 || data.limits.maxIterations > 500) {
+    errors.push("limits.maxIterations must be 1..500");
+  }
+  if (!data.limits || !Number.isInteger(data.limits.maxNoProgress) || data.limits.maxNoProgress < 1 || data.limits.maxNoProgress > 50) {
+    errors.push("limits.maxNoProgress must be 1..50");
+  }
+  if (data.models !== undefined) {
+    if (!data.models || typeof data.models !== "object" || Array.isArray(data.models)) {
+      errors.push("models must be an object when present");
+    } else {
+      for (const key of ["default", ...ROLE_NAMES]) {
+        const value = data.models[key];
+        if (value !== undefined && (typeof value !== "string" || !value.trim())) {
+          errors.push(`models.${key} must be a non-empty string (model id, adapter alias, or "inherit")`);
+        }
+      }
+    }
+  }
+  if (data.improve !== undefined) {
+    if (!data.improve || typeof data.improve !== "object" || Array.isArray(data.improve)) {
+      errors.push("improve must be an object when present");
+    } else if (data.improve.mode !== undefined && !IMPROVE_MODES.has(data.improve.mode)) {
+      errors.push('improve.mode must be "propose" or "auto"');
+    }
+  }
+  if (!data.permissions || !Array.isArray(data.permissions.allowedPaths)) errors.push("permissions.allowedPaths must be an array");
+  if (!data.permissions || !Array.isArray(data.permissions.forbiddenActions) || data.permissions.forbiddenActions.length === 0) {
+    errors.push("permissions.forbiddenActions must be a non-empty array");
+  }
+  if (!data.verification || !Array.isArray(data.verification.commands)) errors.push("verification.commands must be an array");
+  if (!data.verification || typeof data.verification.evidenceRequired !== "boolean") {
+    errors.push("verification.evidenceRequired must be boolean");
+  }
+  if (errors.length > 0) throw new Error(`${filePath} is not a valid Oris Loop v${ORIS_LOOP_DOCUMENT_VERSION} document: ${errors.join("; ")}.`);
+  return data;
+}
+
+/**
+ * Resolve per-role models. `inherit` means "use the model of the current
+ * session"; any other value is an adapter alias or a platform model id.
+ */
+export function normalizeModels(models = {}, adapterModels = {}) {
+  const fallback = resolveModelAlias(models.default ?? INHERIT_MODEL, adapterModels);
+  const resolved = { default: fallback };
+  for (const role of ROLE_NAMES) {
+    resolved[role] = models[role] !== undefined
+      ? resolveModelAlias(models[role], adapterModels)
+      : fallback;
+  }
+  return resolved;
+}
+
+function resolveModelAlias(value, adapterModels) {
+  const name = String(value ?? INHERIT_MODEL).trim() || INHERIT_MODEL;
+  if (name === INHERIT_MODEL) return INHERIT_MODEL;
+  if (adapterModels && typeof adapterModels === "object" && typeof adapterModels[name] === "string") {
+    return adapterModels[name];
+  }
+  return name;
+}
+
+export function improveMode(data) {
+  return data?.improve?.mode === "auto" ? "auto" : "propose";
+}
+
+/** Check the per-loop prompts/ directory. Returns { promptsDir, missing }. */
+export function assessPromptFiles(loopDir) {
+  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}`);
+  }
+  return { promptsDir, missing };
+}
+
+export function loopPhasesFromMetadata(data) {
+  validateLoopMetadata(data);
+  return [...data.phases];
+}

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

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+/**
+ * `oris-skills loop dry-run --loop <slug>` — show exactly what the next pass
+ * would inject into the chat, without arming the runtime or changing state.
+ */
+
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { readAdapter, resolveLoopDocumentPathsBySlug } from "./oris-loop-paths.mjs";
+import {
+  assessPromptFiles,
+  improveMode,
+  normalizeModels,
+  validateLoopDocumentText,
+} from "./oris-loop-document.mjs";
+import { readTemplate, stripTemplateHeading, substitutePlaceholders } from "./oris-loop-templates.mjs";
+
+function fail(message) {
+  console.error(`[oris-skills] ERROR ${message}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const options = { repositoryRoot: "", loopSlug: "" };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    if (raw.startsWith("--loop=")) options.loopSlug = raw.slice("--loop=".length);
+    else if (raw === "--loop" && argv[i + 1]) {
+      options.loopSlug = argv[i + 1];
+      i += 1;
+    } 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));
+if (!options.loopSlug) fail("--loop <slug> is required. List loops with: oris-skills loop list");
+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));
+const models = normalizeModels(metadata.models, adapter.models);
+
+const perLoopOrchestrator = path.join(docs.promptsFull, "orchestrator.md");
+const template = fs.existsSync(perLoopOrchestrator)
+  ? stripTemplateHeading(fs.readFileSync(perLoopOrchestrator, "utf8"))
+  : readTemplate("orchestrator", import.meta.url);
+
+const followup = substitutePlaceholders(template, {
+  iteration: 1,
+  maxIterations: metadata.limits.maxIterations,
+  loop: metadata.name,
+  phase: metadata.phases[0],
+  phaseIndex: 1,
+  phaseCount: metadata.phases.length,
+  instruction: "continue the current phase",
+  loopPath: docs.loopRelative,
+  contextPath: docs.contextRelative,
+  promptsDir: docs.promptsRelative,
+  executorModel: models.executor,
+  verifierModel: models.verifier,
+  doctorModel: models.doctor,
+  debrieferModel: models.debriefer,
+  improveMode: improveMode(metadata),
+  taskPath: docs.taskPath,
+});
+
+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(`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`);
+console.log("");
+console.log("=== Message the stop hook would inject for pass 1 ===");
+console.log(followup);
+console.log("=== End of injected message ===");
+console.log("");
+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}`);

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

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  bootstrapLoop,
+  buildAdapterDraft,
+  writeHooksRegistration,
+  writeStopHookWrapper,
+} from "./oris-loop-bootstrap.mjs";
+import { defaultLoopDocumentPaths, readAdapter } from "./oris-loop-paths.mjs";
+import { ORIS_FLOW_ADAPTER } from "../flow/oris-flow-layout.mjs";
+
+export function writeMinimalAdapter(root) {
+  const adapterPath = path.join(root, ORIS_FLOW_ADAPTER);
+  fs.mkdirSync(path.dirname(adapterPath), { recursive: true });
+  const adapter = buildAdapterDraft(root);
+  adapter.preflight.minFreeDiskGiB = 0;
+  fs.writeFileSync(adapterPath, `${JSON.stringify(adapter, null, 2)}\n`, "utf8");
+  return adapterPath;
+}
+
+export function loopDocumentSource({
+  program = "oris-loop-smoke",
+  phases = ["work"],
+  improve = "propose",
+  models = {},
+  goal = "Run one deterministic smoke action, verify it, and record evidence.",
+  stop = "Stop when the smoke check passes once, or when blocked.",
+} = {}) {
+  const modelLines = ["models:", `  default: ${models.default ?? "inherit"}`];
+  for (const role of ["executor", "verifier", "doctor", "debriefer"]) {
+    if (models[role]) modelLines.push(`  ${role}: ${models[role]}`);
+  }
+  return `---
+schemaVersion: 2
+kind: oris-loop
+name: ${program}
+approved: true
+phases: [${phases.join(", ")}]
+limits:
+  maxIterations: 25
+  maxNoProgress: 2
+  maxMinutes: 240
+${modelLines.join("\n")}
+improve:
+  mode: ${improve}
+permissions:
+  allowedPaths: [.oris-flow/loops, .oris-flow/runtime]
+  forbiddenActions: [commit, push, deploy, external-message]
+verification:
+  commands: [node --version]
+  evidenceRequired: true
+---
+
+# ${program}
+
+Goal: ${goal}
+Stop: ${stop}
+
+Role prompts live in \`prompts/\`. Edit them there; the loop picks changes up on the next pass.
+`;
+}
+
+export function rolePromptFixtures() {
+  return {
+    "executor.md": `# Executor prompt
+
+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": "" }
+`,
+    "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": "" }
+`,
+  };
+}
+
+export function writeLoopTask(root, {
+  taskSlug = "oris-loop-smoke",
+  program = "oris-loop-smoke",
+  phases = ["work"],
+  phase = phases[0],
+  improve = "propose",
+  models = {},
+} = {}) {
+  const taskPath = taskSlug;
+  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.mkdirSync(loopDocs.promptsFull, { recursive: true });
+  for (const [name, content] of Object.entries(rolePromptFixtures())) {
+    fs.writeFileSync(path.join(loopDocs.promptsFull, name), content, "utf8");
+  }
+  fs.writeFileSync(contextPath, `# Oris Loop Context
+
+Run: inactive
+State: ready
+Current program: ${program}
+Current phase: ${phase}
+Current phase index: 0
+Current iteration: 0
+Phase iteration: 0
+Repair cycles: 0
+Updated: ${new Date().toISOString()}
+
+## Objective
+
+Verify the Oris Loop same-chat stop hook.
+
+## Next action
+
+Run one smoke pass.
+`, "utf8");
+  return {
+    taskPath,
+    taskRoot: path.join(root, ".oris-flow", "loops", taskSlug),
+    loopPath,
+    contextPath,
+    promptsPath: loopDocs.promptsFull,
+  };
+}
+
+export function writeStopHookRegistration(root) {
+  return writeHooksRegistration(root, "cursor");
+}
+
+export { writeStopHookWrapper };
+
+export function initSmokeRepository(root, options = {}) {
+  fs.mkdirSync(root, { recursive: true });
+  const git = spawnSync("git", ["init", "-q"], { cwd: root, encoding: "utf8" });
+  if (git.status !== 0) {
+    throw new Error(`git init failed: ${git.stderr}`);
+  }
+  bootstrapLoop(root);
+  return writeLoopTask(root, options);
+}

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

@@ -0,0 +1,81 @@
+#!/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 { discoverExistingLoops, readAdapter } from "./oris-loop-paths.mjs";
+import { ORIS_FLOW_ADAPTER, ORIS_FLOW_RUNTIME } from "../flow/oris-flow-layout.mjs";
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function parseArgs(argv) {
+  const options = {
+    repositoryRoot: "",
+    json: false,
+  };
+  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 === "--repository-root" || key.startsWith("--repository-root=")) [i, options.repositoryRoot] = readValue(i, raw);
+    else if (key === "--json") options.json = true;
+    else fail(`Unknown argument: ${raw}`);
+  }
+  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());
+}
+
+const options = parseArgs(process.argv.slice(2));
+const root = getRoot(options);
+const adapterPath = path.join(root, ORIS_FLOW_ADAPTER);
+const adapter = fs.existsSync(adapterPath) ? readAdapter(root, adapterPath) : readAdapter(root);
+const loops = discoverExistingLoops(root, adapter);
+const payload = {
+  repositoryRoot: root.replace(/\\/g, "/"),
+  runtimeRelative: adapter?.paths?.runtime ?? ORIS_FLOW_RUNTIME,
+  count: loops.length,
+  loops,
+};
+
+if (options.json) {
+  console.log(JSON.stringify(payload, null, 2));
+  process.exit(0);
+}
+
+if (loops.length === 0) {
+  console.log("No existing Oris loops found.");
+  process.exit(0);
+}
+
+console.log(`Existing Oris loops (${loops.length}):`);
+for (const loop of loops) {
+  console.log("");
+  console.log(`- slug: ${loop.slug}`);
+  console.log(`  task: ${loop.taskPath}`);
+  console.log(`  program: ${loop.program || "custom"}`);
+  console.log(`  run/state: ${loop.run || "inactive"} / ${loop.state || "unknown"}`);
+  console.log(`  loop: ${loop.loopRelative}`);
+  console.log(`  context: ${loop.contextRelative}`);
+  if (loop.objective) console.log(`  objective: ${loop.objective}`);
+}