oris-skills 2.0.0

package/scripts/oris-skills.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import childProcess from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { bootstrapLoop } from "./loop/oris-loop-bootstrap.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function runNode(script, args, options = {}) {
+  const result = childProcess.spawnSync(process.execPath, [path.join(repoRoot, "scripts", script), ...args], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+    shell: false,
+  });
+  const status = result.status ?? 1;
+  if (options.exit === false) return status;
+  process.exit(status);
+}
+
+function runGitRoot() {
+  const result = childProcess.spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: process.cwd(),
+    shell: process.platform === "win32",
+    encoding: "utf8",
+  });
+  return result.status === 0 && result.stdout.trim() ? path.resolve(result.stdout.trim()) : process.cwd();
+}
+
+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 uninstall [--dry-run]
+  oris-skills reinstall [--dry-run]
+
+Learn and test loops:
+  oris-skills loop demo                      create a safe tutorial loop
+  oris-skills loop dry-run --loop <slug>     preview the next pass, run nothing
+  oris-skills loop verify --temp             self-check the loop runtime
+
+Run and manage loops:
+  oris-skills loop list [--json]
+  oris-skills loop bootstrap [--platforms cursor,claude]
+  oris-skills loop chat --action start --loop <slug>
+  oris-skills loop chat --action status|set-state|repair|stop [...]
+  oris-skills loop run --loop <slug> --agent codex|claude   headless runner
+
+Repository tools:
+  oris-skills doctor
+  oris-skills validate
+  oris-skills flow scan [...]
+  oris-skills flow version-control [...]
+  oris-skills flow clean-runtime [...]
+`);
+}
+
+const [command, subcommand, ...rest] = process.argv.slice(2);
+const commandArgs = [subcommand, ...rest].filter(Boolean);
+
+if (!command || command === "help" || command === "--help" || command === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === "install") {
+  runNode("install/install-user-skills.mjs", commandArgs);
+}
+
+if (command === "uninstall") {
+  runNode("install/uninstall-user-skills.mjs", commandArgs);
+}
+
+if (command === "reinstall") {
+  const uninstallStatus = runNode("install/uninstall-user-skills.mjs", commandArgs, { exit: false });
+  if (uninstallStatus !== 0) process.exit(uninstallStatus);
+  runNode("install/install-user-skills.mjs", ["--force", ...commandArgs]);
+}
+
+if (command === "doctor") {
+  const root = runGitRoot();
+  const result = bootstrapLoop(root, { dryRun: true });
+  console.log(JSON.stringify({
+    repositoryRoot: root,
+    ready: result.ready,
+    missing: result.before.missing,
+    plannedActions: result.actions,
+  }, null, 2));
+  process.exit(result.ready ? 0 : 1);
+}
+
+if (command === "validate") {
+  runNode("tests/run-all-tests.mjs", ["--node-only", ...commandArgs]);
+}
+
+if (command === "loop") {
+  if (subcommand === "list") runNode("loop/oris-loop-list.mjs", rest);
+  if (subcommand === "bootstrap") runNode("loop/oris-loop-bootstrap.mjs", rest);
+  if (subcommand === "chat") runNode("loop/oris-loop-chat.mjs", rest);
+  if (subcommand === "verify") runNode("loop/oris-loop-verify.mjs", rest);
+  if (subcommand === "demo") runNode("loop/oris-loop-demo.mjs", rest);
+  if (subcommand === "dry-run") runNode("loop/oris-loop-dry-run.mjs", rest);
+  if (subcommand === "run") runNode("loop/oris-loop-run.mjs", rest);
+}
+
+if (command === "flow") {
+  if (subcommand === "scan") runNode("flow/oris-flow-scan.mjs", rest);
+  if (subcommand === "version-control") runNode("flow/oris-flow-version-control.mjs", rest);
+  if (subcommand === "clean-runtime") runNode("flow/oris-flow-clean-runtime.mjs", rest);
+}
+
+console.error(`Unknown command: ${[command, subcommand].filter(Boolean).join(" ")}`);
+printHelp();
+process.exit(1);

package/scripts/package-oris-skills.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const version = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
+
+function parseOut(argv) {
+  const arg = argv.find((item) => item.startsWith("--out="));
+  if (arg) return path.resolve(arg.slice("--out=".length));
+  const index = argv.indexOf("--out");
+  if (index >= 0 && argv[index + 1]) return path.resolve(argv[index + 1]);
+  return path.join(repoRoot, "dist");
+}
+
+function copyRecursive(source, target) {
+  if (!fs.existsSync(source)) return;
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: true });
+    for (const entry of fs.readdirSync(source)) {
+      copyRecursive(path.join(source, entry), path.join(target, entry));
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+const outRoot = parseOut(process.argv.slice(2));
+const packageRoot = path.join(outRoot, `oris-skills-${version}`);
+fs.rmSync(packageRoot, { recursive: true, force: true });
+fs.mkdirSync(packageRoot, { recursive: true });
+
+for (const item of [
+  ".cursor-plugin",
+  "skills",
+  "references",
+  "agents",
+  "docs",
+  "scripts",
+  "package.json",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+]) {
+  copyRecursive(path.join(repoRoot, item), path.join(packageRoot, item));
+}
+
+console.log(`Packaged ${packageRoot}`);

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import childProcess from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const nodeTestFiles = [
+  "scripts/tests/test-schemas.mjs",
+  "scripts/tests/test-oris-loop-document.mjs",
+  "scripts/tests/test-agent-adapters.mjs",
+  "scripts/tests/test-oris-1-0-cleanliness.mjs",
+  "scripts/tests/test-oris-flow-scan.mjs",
+  "scripts/tests/test-routing-lifecycle.mjs",
+  "scripts/tests/test-oris-loop-stop.mjs",
+  "scripts/tests/test-oris-loop-smoke.mjs",
+  "scripts/tests/test-oris-loop-bootstrap.mjs",
+  "scripts/tests/test-oris-flow-clean-runtime.mjs",
+  "scripts/tests/test-oris-loop-list.mjs",
+  "scripts/tests/test-oris-loop-run.mjs",
+  "scripts/tests/test-oris-gitignore.mjs",
+];
+
+function run(command, args, options = {}) {
+  console.log(`\n> ${[command, ...args].join(" ")}`);
+  const result = childProcess.spawnSync(command, args, {
+    cwd: root,
+    stdio: "inherit",
+    ...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-agent-adapters.mjs

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import assert from "node:assert/strict";
+import test from "node:test";
+import { generateAgentAdapters } from "../install/generate-agent-adapters.mjs";
+
+test("generates Cursor, Claude, and Codex agent adapters", () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "oris-agent-adapters-"));
+  try {
+    const generated = generateAgentAdapters(temp);
+    assert.ok(generated.includes("oris-loop-executor"));
+    assert.ok(fs.existsSync(path.join(temp, ".cursor", "agents", "oris-loop-executor.md")));
+    assert.ok(fs.existsSync(path.join(temp, ".claude", "agents", "oris-loop-verifier.md")));
+    assert.ok(fs.existsSync(path.join(temp, ".codex", "agents", "oris-loop-doctor.toml")));
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+});

package/scripts/tests/test-oris-1-0-cleanliness.mjs

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ignoredDirs = new Set([".git", "node_modules", ".cursor", ".claude", ".codex", "dist", ".cursor-plugin-install-backups", ".oris-flow"]);
+
+function walk(dir, matches = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (ignoredDirs.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, matches);
+    else matches.push(full);
+  }
+  return matches;
+}
+
+function repoFiles() {
+  return walk(repoRoot).map((filePath) => ({
+    filePath,
+    relative: path.relative(repoRoot, filePath).replace(/\\/g, "/"),
+  }));
+}
+
+test("repository contains no PowerShell scripts", () => {
+  const psFiles = repoFiles().filter((entry) => entry.relative.endsWith(".ps1"));
+  assert.deepEqual(psFiles.map((entry) => entry.relative), []);
+});
+
+test("Oris public loop text does not reference external loop brands", () => {
+  const offenders = repoFiles()
+    .filter((entry) => /\.(md|mjs|json|yml|yaml|cmd|sh|command)$/.test(entry.relative))
+    .filter((entry) => entry.relative !== "scripts/tests/test-oris-1-0-cleanliness.mjs")
+    .filter((entry) => entry.relative !== "CHANGELOG.md")
+    .filter((entry) => /loopy/i.test(fs.readFileSync(entry.filePath, "utf8")))
+    .map((entry) => entry.relative);
+  assert.deepEqual(offenders, []);
+});
+
+test("Oris Loop 1.0 does not use global preset storage", () => {
+  const offenders = repoFiles()
+    .filter((entry) => /\.(md|mjs|json|yml|yaml|cmd|sh|command)$/.test(entry.relative))
+    .filter((entry) => entry.relative !== "scripts/tests/test-oris-1-0-cleanliness.mjs")
+    .filter((entry) => /ORIS_FLOW_USER_PRESETS|~\/\.cursor\/oris-flow|oris-flow[\\/]presets/i.test(fs.readFileSync(entry.filePath, "utf8")))
+    .map((entry) => entry.relative);
+  assert.deepEqual(offenders, []);
+});
+
+test("Oris Loop does not ship or install loop libraries", () => {
+  const offenders = repoFiles()
+    .filter((entry) => /\.(md|mjs|json|yml|yaml|cmd|sh|command)$/.test(entry.relative))
+    .filter((entry) => entry.relative !== "scripts/tests/test-oris-1-0-cleanliness.mjs")
+    .filter((entry) => /\.oris-flow[\\/]library|flow[\\/]oris[\\/]library|oris-loop-library|ORIS_FLOW_(?:SOFTWARE_|CUSTOM_)?LIBRARY/i.test(fs.readFileSync(entry.filePath, "utf8")))
+    .map((entry) => entry.relative);
+  assert.deepEqual(offenders, []);
+});

package/scripts/tests/test-oris-flow-clean-runtime.mjs

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { cleanFlowRuntime, resolveCleanTargets } from "../flow/oris-flow-clean-runtime.mjs";
+import { ORIS_FLOW_ADAPTER, ORIS_FLOW_RUNTIME } from "../flow/oris-flow-layout.mjs";
+
+test("resolveCleanTargets defaults to .oris-flow runtime", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-clean-"));
+  try {
+    assert.deepEqual(resolveCleanTargets(root), [path.join(root, ORIS_FLOW_RUNTIME)]);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resolveCleanTargets honors adapter runtime under .oris-flow", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-clean-"));
+  try {
+    fs.mkdirSync(path.dirname(path.join(root, ORIS_FLOW_ADAPTER)), { recursive: true });
+    fs.writeFileSync(path.join(root, ORIS_FLOW_ADAPTER), `${JSON.stringify({
+      paths: { runtime: ".oris-flow/runtime" },
+    })}\n`, "utf8");
+    assert.deepEqual(resolveCleanTargets(root), [path.join(root, ORIS_FLOW_RUNTIME)]);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("cleanFlowRuntime removes loop logs and preserves setup files", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-clean-"));
+  try {
+    fs.mkdirSync(path.join(root, ".oris-flow", "maps"), { recursive: true });
+    fs.mkdirSync(path.join(root, ".oris-flow", "loops", "sample"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".oris-flow", "manifest.json"), "{}\n", "utf8");
+    fs.writeFileSync(path.join(root, ".oris-flow", "maps", "summary.md"), "# setup\n", "utf8");
+    fs.writeFileSync(path.join(root, ".oris-flow", "loops", "sample", "loop.md"), "# loop\n", "utf8");
+    fs.writeFileSync(path.join(root, ORIS_FLOW_ADAPTER), `${JSON.stringify({
+      paths: { runtime: ".oris-flow/runtime" },
+    })}\n`, "utf8");
+
+    const runtimeDir = path.join(root, ORIS_FLOW_RUNTIME);
+    fs.mkdirSync(path.join(runtimeDir, "failures"), { recursive: true });
+    fs.writeFileSync(path.join(runtimeDir, "chat-active.json"), "{}\n", "utf8");
+    fs.writeFileSync(path.join(runtimeDir, "hook-debug.jsonl"), "{}\n", "utf8");
+    fs.writeFileSync(path.join(runtimeDir, "sample.lock.json"), "{}\n", "utf8");
+    fs.writeFileSync(path.join(runtimeDir, "failures", "sample.stream.jsonl"), "{}\n", "utf8");
+    fs.writeFileSync(path.join(runtimeDir, "stack.json"), "{}\n", "utf8");
+
+    const result = cleanFlowRuntime(root);
+    assert.equal(result.cleaned, true);
+    assert.equal(fs.existsSync(path.join(root, ORIS_FLOW_RUNTIME)), false);
+    assert.ok(fs.existsSync(path.join(root, ".oris-flow", "manifest.json")));
+    assert.ok(fs.existsSync(path.join(root, ".oris-flow", "loops", "sample", "loop.md")));
+    assert.ok(fs.existsSync(path.join(root, ORIS_FLOW_ADAPTER)));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("cleanFlowRuntime dry run lists files without deleting them", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-clean-"));
+  try {
+    const runtimeDir = path.join(root, ORIS_FLOW_RUNTIME);
+    fs.mkdirSync(runtimeDir, { recursive: true });
+    fs.writeFileSync(path.join(runtimeDir, "hook-debug.jsonl"), "{}\n", "utf8");
+
+    const result = cleanFlowRuntime(root, { dryRun: true });
+    assert.equal(result.cleaned, true);
+    assert.ok(fs.existsSync(path.join(runtimeDir, "hook-debug.jsonl")));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+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 { ORIS_FLOW_MANIFEST } from "../flow/oris-flow-layout.mjs";
+
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+test("scanner creates only evidence-backed map sections", () => {
+  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`);
+    write(path.join(root, "src", "index.js"), "export const value = 1;\n");
+
+    const scan = scanRepository(root);
+    assert.ok(scan.manifest.sections.docs);
+    assert.ok(scan.manifest.sections.stack);
+    assert.ok(scan.manifest.sections.commands);
+    assert.ok(scan.manifest.sections.code);
+    assert.equal(scan.manifest.sections.backendData, undefined);
+    assert.equal(scan.manifest["known" + "Gaps"], undefined);
+
+    const written = writeScanResult(scan);
+    assert.equal(written.manifestPath, ORIS_FLOW_MANIFEST);
+    assert.ok(fs.existsSync(path.join(root, ORIS_FLOW_MANIFEST)));
+    assert.ok(fs.existsSync(path.join(root, ".oris-flow", "maps", "stack.md")));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("scanner supports documentation-only repositories", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  try {
+    write(path.join(root, "docs", "guide.md"), "# Guide\n");
+    const scan = scanRepository(root);
+    assert.deepEqual(Object.keys(scan.manifest.sections), ["docs"]);
+    assert.deepEqual(scan.stacks, []);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+

package/scripts/tests/test-oris-gitignore.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  applyOrisFlowVersionControl,
+  ORIS_FLOW_GITIGNORE_ENTRIES,
+} from "../flow/oris-gitignore.mjs";
+
+function makeTempRepo() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "oris-gitignore-"));
+}
+
+test("applyOrisFlowVersionControl appends and removes oris-flow entries", () => {
+  const root = makeTempRepo();
+  try {
+    const ignored = applyOrisFlowVersionControl(root, "gitignore");
+    assert.equal(ignored.action, "created");
+    const text = fs.readFileSync(path.join(root, ".gitignore"), "utf8");
+    for (const entry of ORIS_FLOW_GITIGNORE_ENTRIES) {
+      assert.match(text, new RegExp(entry.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+    }
+    const committed = applyOrisFlowVersionControl(root, "commit");
+    assert.equal(committed.action, "removed");
+    const after = fs.readFileSync(path.join(root, ".gitignore"), "utf8");
+    for (const entry of ORIS_FLOW_GITIGNORE_ENTRIES) {
+      assert.doesNotMatch(after, new RegExp(`^\\s*${entry.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "m"));
+    }
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+import {
+  assessLoopReadiness,
+  bootstrapLoop,
+  detectPlaywrightRoot,
+} from "../loop/oris-loop-bootstrap.mjs";
+import { ORIS_FLOW_ADAPTER } from "../flow/oris-flow-layout.mjs";
+
+function initGitRepo(root) {
+  const git = spawnSync("git", ["init", "-q"], { cwd: root, encoding: "utf8" });
+  assert.equal(git.status, 0, git.stderr);
+}
+
+test("bootstrap creates loop readiness files when missing", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-bootstrap-"));
+  try {
+    initGitRepo(root);
+    fs.mkdirSync(path.join(root, "Test", "e2e"), { recursive: true });
+    fs.writeFileSync(path.join(root, "Test", "e2e", "playwright.config.ts"), "export default { testDir: '.' };\n", "utf8");
+    fs.writeFileSync(path.join(root, "Test", "e2e", "package.json"), `${JSON.stringify({ scripts: { check: "playwright test --list" } })}\n`, "utf8");
+
+    const before = assessLoopReadiness(root);
+    assert.equal(before.ready, false);
+
+    const result = bootstrapLoop(root);
+    assert.equal(result.ready, true);
+    assert.ok(fs.existsSync(path.join(root, ORIS_FLOW_ADAPTER)));
+    assert.ok(fs.existsSync(path.join(root, ".cursor", "hooks.json")));
+    assert.ok(fs.existsSync(path.join(root, ".cursor", "hooks", "oris-loop-stop.mjs")));
+    assert.ok(fs.existsSync(path.join(root, ".claude", "settings.json")));
+    assert.ok(fs.existsSync(path.join(root, ".claude", "hooks", "oris-loop-stop.mjs")));
+    assert.match(fs.readFileSync(path.join(root, ".claude", "hooks", "oris-loop-stop.mjs"), "utf8"), /--platform", "claude/);
+    const claudeSettings = JSON.parse(fs.readFileSync(path.join(root, ".claude", "settings.json"), "utf8"));
+    assert.ok(JSON.stringify(claudeSettings.hooks.Stop).includes("oris-loop-stop"));
+    assert.match(fs.readFileSync(path.join(root, ".gitignore"), "utf8"), /\.oris-flow\/runtime\//);
+
+    const adapter = JSON.parse(fs.readFileSync(path.join(root, ORIS_FLOW_ADAPTER), "utf8"));
+    assert.equal(adapter.paths.testDir, "Test/e2e");
+    assert.ok(adapter.commands["e2e-check"]);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bootstrap is idempotent when loop is already configured", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-bootstrap-"));
+  try {
+    initGitRepo(root);
+    bootstrapLoop(root);
+    const adapterBefore = fs.readFileSync(path.join(root, ORIS_FLOW_ADAPTER), "utf8");
+    const result = bootstrapLoop(root);
+    assert.equal(result.ready, true);
+    assert.equal(fs.readFileSync(path.join(root, ORIS_FLOW_ADAPTER), "utf8"), adapterBefore);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bootstrap merges stop hook into existing hooks.json", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-bootstrap-"));
+  try {
+    initGitRepo(root);
+    fs.mkdirSync(path.join(root, ".cursor"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".cursor", "hooks.json"), `${JSON.stringify({
+      version: 1,
+      hooks: { stop: [{ command: "node .cursor/hooks/custom-stop.mjs", loop_limit: null }] },
+    }, null, 2)}\n`, "utf8");
+
+    const result = bootstrapLoop(root);
+    assert.equal(result.ready, true);
+    const hooks = JSON.parse(fs.readFileSync(path.join(root, ".cursor", "hooks.json"), "utf8"));
+    assert.equal(hooks.hooks.stop.length, 2);
+    assert.ok(hooks.hooks.stop.some((entry) => String(entry.command).includes("custom-stop")));
+    assert.ok(hooks.hooks.stop.some((entry) => String(entry.command).includes("oris-loop-stop")));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("detectPlaywrightRoot resolves config directory", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-bootstrap-"));
+  try {
+    fs.mkdirSync(path.join(root, "Test", "e2e"), { recursive: true });
+    fs.writeFileSync(path.join(root, "Test", "e2e", "playwright.config.ts"), "export default { testDir: '.' };\n", "utf8");
+    assert.equal(detectPlaywrightRoot(root), "Test/e2e");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  assessPromptFiles,
+  improveMode,
+  normalizeModels,
+  validateLoopDocumentText,
+} from "../loop/oris-loop-document.mjs";
+
+const validLoop = `---
+schemaVersion: 2
+kind: oris-loop
+name: bug-fix-loop
+approved: true
+phases: [observe, execute, verify, debrief]
+limits:
+  maxIterations: 10
+  maxNoProgress: 2
+  maxMinutes: 60
+models:
+  default: inherit
+  verifier: smart
+improve:
+  mode: auto
+permissions:
+  allowedPaths: [src, tests]
+  forbiddenActions: [commit, push, deploy, external-message]
+verification:
+  commands: [npm test]
+  evidenceRequired: true
+---
+
+# Bug Fix Loop
+
+Goal: fix one verified bug per pass.
+Stop: all listed bugs fixed or blocked.
+`;
+
+test("validates Oris Loop v2 front matter", () => {
+  const parsed = validateLoopDocumentText(validLoop, "bug-fix.loop.md");
+  assert.equal(parsed.data.schemaVersion, 2);
+  assert.equal(parsed.data.kind, "oris-loop");
+  assert.equal(parsed.data.approved, true);
+  assert.deepEqual(parsed.data.phases, ["observe", "execute", "verify", "debrief"]);
+  assert.equal(parsed.data.limits.maxIterations, 10);
+  assert.equal(parsed.data.verification.evidenceRequired, true);
+});
+
+test("rejects loops without user approval", () => {
+  assert.throws(
+    () => validateLoopDocumentText(validLoop.replace("approved: true", "approved: false"), "unapproved.loop.md"),
+    /approved must be true/,
+  );
+});
+
+test("rejects old schema versions", () => {
+  assert.throws(
+    () => validateLoopDocumentText(validLoop.replace("schemaVersion: 2", "schemaVersion: 1"), "old.loop.md"),
+    /schemaVersion must be 2/,
+  );
+});
+
+test("rejects empty model values but accepts arbitrary model ids", () => {
+  assert.throws(
+    () => validateLoopDocumentText(validLoop.replace("verifier: smart", 'verifier: ""'), "bad-model.loop.md"),
+    /models\.verifier/,
+  );
+  const custom = validateLoopDocumentText(validLoop.replace("verifier: smart", "verifier: any-platform-model"), "custom-model.loop.md");
+  assert.equal(custom.data.models.verifier, "any-platform-model");
+});
+
+test("rejects unknown improve modes", () => {
+  assert.throws(
+    () => validateLoopDocumentText(validLoop.replace("mode: auto", "mode: yolo"), "bad-improve.loop.md"),
+    /improve\.mode/,
+  );
+});
+
+test("normalizeModels resolves inherit, adapter aliases, and role fallbacks", () => {
+  const models = normalizeModels(
+    { default: "inherit", verifier: "smart", doctor: "explicit-model-id" },
+    { smart: "platform-smart-model" },
+  );
+  assert.equal(models.default, "inherit");
+  assert.equal(models.executor, "inherit");
+  assert.equal(models.verifier, "platform-smart-model");
+  assert.equal(models.doctor, "explicit-model-id");
+  assert.equal(models.debriefer, "inherit");
+});
+
+test("improveMode defaults to propose", () => {
+  assert.equal(improveMode({}), "propose");
+  assert.equal(improveMode({ improve: { mode: "auto" } }), "auto");
+});
+
+test("assessPromptFiles reports missing role prompt files", () => {
+  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"]);
+    fs.mkdirSync(path.join(dir, "prompts"), { recursive: true });
+    for (const file of ["executor.md", "verifier.md", "doctor.md"]) {
+      fs.writeFileSync(path.join(dir, "prompts", file), "prompt content\n", "utf8");
+    }
+    assert.deepEqual(assessPromptFiles(dir).missing, []);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});