oris-skills 2.2.1 → 2.2.3

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

@@ -433,9 +433,9 @@ function resolveTasksRoot(root, existingManifest) {
 
 /**
  * Refresh keeps user truth: confirmed decisions, tasksRoot, version control,
- * refresh policy, confirmed commands, and confirmed sections (whose map files
- * are also left untouched). A confirmed section the scan no longer sees is
- * marked stale, never deleted.
+ * confirmed commands, and confirmed sections (whose map files are also left
+ * untouched). A confirmed section the scan no longer sees is marked stale,
+ * never deleted.
  */
 function mergeWithExisting(scan, existingManifest) {
   if (!existingManifest || typeof existingManifest !== "object") return scan;
@@ -447,9 +447,6 @@ function mergeWithExisting(scan, existingManifest) {
   if (existingManifest.setup?.versionControl?.orisFlowMap) {
     merged.manifest.setup.versionControl.orisFlowMap = existingManifest.setup.versionControl.orisFlowMap;
   }
-  if (existingManifest.refreshPolicy && typeof existingManifest.refreshPolicy === "object") {
-    merged.manifest.refreshPolicy = existingManifest.refreshPolicy;
-  }
   if (existingManifest.projectType?.confidence === "confirmed") {
     merged.manifest.projectType = existingManifest.projectType;
   }
@@ -507,9 +504,6 @@ export function scanRepository(repositoryRoot, options = {}) {
         orisFlowMap: options.versionControl ?? "commit",
       },
     },
-    refreshPolicy: {
-      mode: "manual",
-    },
     stacks,
     commands,
     sections: sectionPointers,

package/scripts/install/install-user-skills.mjs

@@ -22,6 +22,8 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { buildMcpServer, mcpServerName, resolveDevops } from "../flow/oris-flow-devops.mjs";
+import { MCP_AGENTS, seedMcpServer } from "./oris-mcp.mjs";
 
 const markerName = ".oris-skills-managed.json";
 const installManifestName = ".oris-skills-install.json";
@@ -47,7 +49,6 @@ function defaultPaths() {
   const home = os.homedir();
   return {
     bundleRoot: path.join(home, ".oris", "oris-skills"),
-    settingsPath: path.join(home, ".oris", "settings.json"),
     agentRoots: {
       cursor: path.join(home, ".cursor"),
       claude: path.join(home, ".claude"),
@@ -62,9 +63,9 @@ function parseArgs(argv) {
   const options = {
     dryRun: false,
     force: false,
+    noMcp: false,
     agents: [],
     bundleRoot: paths.bundleRoot,
-    settingsPath: paths.settingsPath,
     agentRoots: paths.agentRoots,
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -78,10 +79,10 @@ function parseArgs(argv) {
     };
     if (key === "--dry-run") options.dryRun = true;
     else if (key === "--force") options.force = true;
+    else if (key === "--no-mcp") options.noMcp = true;
     else if (key === "--agents" || key.startsWith("--agents=")) {
       options.agents = value().split(",").map((name) => name.trim().toLowerCase()).filter(Boolean);
     } else if (key === "--bundle-root" || key.startsWith("--bundle-root=")) options.bundleRoot = value();
-    else if (key === "--settings" || key.startsWith("--settings=")) options.settingsPath = value();
     else if (key === "--cursor-root" || key.startsWith("--cursor-root=")) options.agentRoots.cursor = value();
     else if (key === "--claude-root" || key.startsWith("--claude-root=")) options.agentRoots.claude = value();
     else if (key === "--codex-root" || key.startsWith("--codex-root=")) options.agentRoots.codex = value();
@@ -160,28 +161,24 @@ function manifestSkills(manifest, repoRoot) {
   });
 }
 
-function defaultSettings() {
-  return {
-    version: 1,
-    orisFlow: {
-      uiLanguage: "en",
-      artifactLanguage: "en",
-      responseStyle: "standard",
-    },
-    defaultProfiles: {
-      testing: "default",
-    },
-    profiles: {
-      default: {
-        environment: "local",
-        values: {},
-        secrets: {},
-        flags: {
-          allowDataMutation: false,
-        },
-      },
-    },
-  };
+/**
+ * Rewrite bundle-root-relative Oris paths to skill-root-relative in a standalone skill
+ * copy. The source keeps bundle-relative paths (`skills/<name>/references/…`) so the bundle
+ * and the Codex/Copilot pointers resolve; a standalone Claude/Cursor skill has no bundle
+ * root above it, so its own `.md` files must point at `references/…` and `templates/…`.
+ */
+function rewriteBundlePaths(skillDir, relativePath) {
+  // In a standalone skill the skill folder IS the root, so any `skills/<name>/…` pointer
+  // (SKILL.md, references/…, templates/…, agents/…) becomes root-relative once the prefix
+  // is stripped.
+  const prefix = `${relativePath.replace(/\\/g, "/").replace(/\/+$/, "")}/`;
+  const entries = fs.readdirSync(skillDir, { recursive: true, withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const filePath = path.join(entry.parentPath ?? entry.path, entry.name);
+    const text = fs.readFileSync(filePath, "utf8");
+    if (text.includes(prefix)) fs.writeFileSync(filePath, text.split(prefix).join(""), "utf8");
+  }
 }
 
 function installSkillDirs(skills, skillsRoot, manifest, bundleRoot, options) {
@@ -193,6 +190,13 @@ function installSkillDirs(skills, skillsRoot, manifest, bundleRoot, options) {
     }
     fs.rmSync(target, { recursive: true, force: true });
     copy(skill.sourceDir, target);
+    // Make the standalone skill self-contained: the shared references it points to
+    // (conventions.md, doc-policy.md, …) live in the bundle root, not inside the skill
+    // folder, so they were never copied — the whole reason `references/conventions.md`
+    // dangled at runtime. Merge them in, then rewrite the paths to skill-relative.
+    const bundleReferences = path.join(bundleRoot, "references");
+    if (fs.existsSync(bundleReferences)) copy(bundleReferences, path.join(target, "references"));
+    rewriteBundlePaths(target, skill.relativePath);
     writeJson(path.join(target, markerName), {
       package: manifest.name,
       version: manifest.version,
@@ -256,13 +260,16 @@ function main() {
   const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
   const manifest = readJson(path.join(repoRoot, ".cursor-plugin", "plugin.json"));
   const skills = manifestSkills(manifest, repoRoot);
+  const devops = resolveDevops(null).devops;
+  const mcpServer = buildMcpServer(devops);
+  const mcpName = mcpServerName(devops);
+  const mcpAgents = options.noMcp ? [] : (options.agents.length > 0 ? options.agents : detectAgents(options.agentRoots)).filter((agent) => MCP_AGENTS.includes(agent));
   const agents = options.agents.length > 0 ? options.agents : detectAgents(options.agentRoots);
   if (agents.length === 0) {
     fail("No agent detected (~/.cursor, ~/.claude, ~/.codex). Pass --agents cursor,claude,codex explicitly.");
   }
 
   assertInsideHome(options.bundleRoot);
-  assertInsideHome(options.settingsPath);
   for (const agent of agents) assertInsideHome(options.agentRoots[agent]);
 
   if (options.dryRun) {
@@ -274,7 +281,7 @@ function main() {
       else log(`Would write ${agent} skills: ${path.join(options.agentRoots[agent], "skills")}`);
     }
     log(`Would write universal pointer: ${path.join(path.dirname(options.bundleRoot), "oris-flow.md")}`);
-    log(`Would create settings if missing: ${options.settingsPath}`);
+    if (mcpAgents.length > 0) log(`Would seed MCP server '${mcpName}' for: ${mcpAgents.join(", ")}`);
     return;
   }
 
@@ -303,7 +310,11 @@ function main() {
   }
   installUniversalPointer(skills, options.bundleRoot);
 
-  if (!fs.existsSync(options.settingsPath)) writeJson(options.settingsPath, defaultSettings());
+  for (const agent of mcpAgents) {
+    const result = seedMcpServer(agent, options.agentRoots, mcpName, mcpServer, { force: options.force });
+    log(`MCP ${mcpName} for ${agent}: ${result.status}`);
+  }
+
   writeJson(path.join(options.bundleRoot, installManifestName), {
     package: manifest.name,
     version: manifest.version,

package/scripts/install/oris-mcp.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Agents that receive an MCP seed. Copilot has no home-scoped MCP target here. */
+export const MCP_AGENTS = ["cursor", "claude", "codex"];
+
+/** MCP config file + format per agent, derived from the (overridable) agent roots. */
+export function mcpConfigTarget(agent, agentRoots) {
+  if (agent === "cursor") return { kind: "json", filePath: path.join(agentRoots.cursor, "mcp.json") };
+  if (agent === "claude") return { kind: "json", filePath: path.join(path.dirname(agentRoots.claude), ".claude.json") };
+  if (agent === "codex") return { kind: "toml", filePath: path.join(agentRoots.codex, "config.toml") };
+  return null;
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function tomlBlock(name, server) {
+  const args = server.args.map((arg) => JSON.stringify(arg)).join(", ");
+  return `\n[mcp_servers.${name}]\ncommand = ${JSON.stringify(server.command)}\nargs = [${args}]\n`;
+}
+
+/**
+ * Seed one MCP server into an agent's config, idempotently. Already present → skip unless
+ * `force`. `dryRun` reports the plan without writing. Returns a status per agent:
+ * "seeded" | "present" | "planned" | "skipped".
+ */
+export function seedMcpServer(agent, agentRoots, name, server, options = {}) {
+  const target = mcpConfigTarget(agent, agentRoots);
+  if (!target) return { status: "skipped", agent };
+
+  if (target.kind === "json") {
+    let data = {};
+    const existing = readText(target.filePath);
+    if (existing.trim()) {
+      try {
+        data = JSON.parse(existing);
+      } catch {
+        data = {};
+      }
+    }
+    const servers = data.mcpServers && typeof data.mcpServers === "object" ? data.mcpServers : {};
+    const present = Object.prototype.hasOwnProperty.call(servers, name);
+    if (present && !options.force) return { status: "present", agent, filePath: target.filePath };
+    if (options.dryRun) return { status: "planned", agent, filePath: target.filePath };
+    servers[name] = server;
+    data.mcpServers = servers;
+    fs.mkdirSync(path.dirname(target.filePath), { recursive: true });
+    fs.writeFileSync(target.filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    return { status: "seeded", agent, filePath: target.filePath };
+  }
+
+  // TOML (Codex config.toml)
+  const text = readText(target.filePath);
+  const present = text.includes(`[mcp_servers.${name}]`);
+  if (present) return { status: "present", agent, filePath: target.filePath };
+  if (options.dryRun) return { status: "planned", agent, filePath: target.filePath };
+  fs.mkdirSync(path.dirname(target.filePath), { recursive: true });
+  fs.writeFileSync(target.filePath, `${text}${tomlBlock(name, server)}`, "utf8");
+  return { status: "seeded", agent, filePath: target.filePath };
+}

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

@@ -168,11 +168,6 @@ export function buildAdapterDraft(repositoryRoot, hints = {}) {
     },
     commands,
     models: {},
-    profile: {
-      required: false,
-      defaultRole: "testing",
-      mappings: [],
-    },
     preflight: {
       minFreeDiskGiB: 5,
     },

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

@@ -15,7 +15,6 @@ import {
   ORIS_FLOW_ADAPTER,
   ORIS_LOOP_SCHEMA,
   ORIS_LOOP_SCHEMA_VERSION,
-  ORIS_SKILLS_SETTINGS,
 } from "../flow/oris-flow-layout.mjs";
 import {
   activeRoles,
@@ -42,8 +41,6 @@ function parseArgs(argv) {
     runner: "chat",
     maxIterations: 10,
     maxMinutes: 240,
-    profile: "",
-    settingsPath: ORIS_SKILLS_SETTINGS,
   };
   const readValue = (index, raw) => {
     if (raw.includes("=")) return [index, raw.slice(raw.indexOf("=") + 1)];
@@ -60,8 +57,6 @@ function parseArgs(argv) {
     else if (key === "--progress" || key.startsWith("--progress=")) [i, options.progress] = 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];
@@ -143,30 +138,6 @@ function reconcileContext(root, state) {
   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 = [];
@@ -267,7 +238,6 @@ if (options.action === "start") {
       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);

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

@@ -11,8 +11,11 @@ const nodeTestFiles = [
   "scripts/tests/test-schemas.mjs",
   "scripts/tests/test-oris-loop-document.mjs",
   "scripts/tests/test-agent-adapters.mjs",
+  "scripts/tests/test-skill-self-contained.mjs",
   "scripts/tests/test-oris-1-0-cleanliness.mjs",
   "scripts/tests/test-oris-flow-scan.mjs",
+  "scripts/tests/test-oris-flow-devops.mjs",
+  "scripts/tests/test-install-mcp.mjs",
   "scripts/tests/test-routing-lifecycle.mjs",
   "scripts/tests/test-skill-style.mjs",
   "scripts/tests/test-oris-loop-stop.mjs",

package/scripts/tests/test-install-mcp.mjs

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function runCli(args, homeDir) {
+  return childProcess.spawnSync(process.execPath, ["scripts/oris-skills.mjs", ...args], {
+    cwd: root,
+    encoding: "utf8",
+    env: { ...process.env, HOME: homeDir, USERPROFILE: homeDir },
+    shell: false,
+  });
+}
+
+test("install --dry-run plans the oris-devops MCP server", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-mcp-dry-"));
+  try {
+    const result = runCli(["install", "--dry-run", "--agents", "claude,cursor,codex"], home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /Would seed MCP server 'oris-devops'/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("--no-mcp skips seeding", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-mcp-off-"));
+  try {
+    const result = runCli(["install", "--dry-run", "--agents", "claude", "--no-mcp"], home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stdout, /Would seed MCP/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("real install seeds oris-devops into the Claude config, idempotently", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-mcp-real-"));
+  try {
+    fs.mkdirSync(path.join(home, ".claude"), { recursive: true });
+    const first = runCli(["install", "--force", "--agents", "claude"], home);
+    assert.equal(first.status, 0, first.stderr);
+
+    const claudeConfig = path.join(home, ".claude.json");
+    assert.ok(fs.existsSync(claudeConfig), "~/.claude.json written");
+    const data = JSON.parse(fs.readFileSync(claudeConfig, "utf8"));
+    assert.ok(data.mcpServers["oris-devops"], "oris-devops seeded");
+    assert.deepEqual(
+      data.mcpServers["oris-devops"].args.slice(0, 3),
+      ["-y", "@azure-devops/mcp@2.7.0", "orislineweb"],
+    );
+
+    const second = runCli(["install", "--force", "--agents", "claude"], home);
+    assert.equal(second.status, 0, second.stderr);
+    const after = JSON.parse(fs.readFileSync(claudeConfig, "utf8"));
+    assert.equal(Object.keys(after.mcpServers).length, 1, "no duplicate server on re-install");
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,64 @@
+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 { fileURLToPath } from "node:url";
+import { DEFAULT_DEVOPS, resolveDevops, buildMcpServer, mcpServerName } from "../flow/oris-flow-devops.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+test("default provider is Azure DevOps with the oris-devops MCP and #{id} work items", () => {
+  const d = DEFAULT_DEVOPS.devops;
+  assert.equal(d.provider, "azure-devops");
+  assert.equal(d.organization, "orislineweb");
+  assert.equal(d.workItemSyntax, "#{id}");
+  assert.equal(d.commitLanguage, "en");
+  assert.equal(d.prLanguage, "en");
+  assert.equal(mcpServerName(d), "oris-devops");
+});
+
+test("buildMcpServer produces the exact Azure DevOps command", () => {
+  const server = buildMcpServer(DEFAULT_DEVOPS.devops);
+  assert.deepEqual(server, {
+    command: "npx",
+    args: ["-y", "@azure-devops/mcp@2.7.0", "orislineweb", "-d", "core", "work", "work-items", "repositories"],
+  });
+});
+
+test("buildMcpServer honours explicit args for a non-Azure provider", () => {
+  const server = buildMcpServer({ organization: "x", mcp: { command: "node", args: ["jira-mcp.js"] } });
+  assert.deepEqual(server, { command: "node", args: ["jira-mcp.js"] });
+});
+
+test("resolution order is default -> org -> repo, each overriding the previous", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-devops-home-"));
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), "oris-devops-repo-"));
+  try {
+    fs.mkdirSync(path.join(home, ".oris"), { recursive: true });
+    fs.writeFileSync(
+      path.join(home, ".oris", "devops.json"),
+      JSON.stringify({ version: 1, devops: { organization: "acme", workItemSyntax: "AB#{id}" } }),
+    );
+    fs.mkdirSync(path.join(repo, ".oris-flow"), { recursive: true });
+    fs.writeFileSync(
+      path.join(repo, ".oris-flow", "devops.json"),
+      JSON.stringify({ version: 1, devops: { workItemSyntax: "JIRA-{id}" } }),
+    );
+    const resolved = resolveDevops(repo, { home }).devops;
+    assert.equal(resolved.provider, "azure-devops", "provider inherited from default");
+    assert.equal(resolved.organization, "acme", "organization from org layer");
+    assert.equal(resolved.workItemSyntax, "JIRA-{id}", "repo layer wins over org layer");
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("devops schema is a versioned v1 contract", () => {
+  const schema = JSON.parse(fs.readFileSync(path.join(root, "references", "devops.schema.json"), "utf8"));
+  assert.equal(schema.$id, "https://oris.dev/schemas/oris-flow-devops-v1.json");
+  assert.equal(schema.properties.version.const, 1);
+  assert.deepEqual(schema.required, ["version", "devops"]);
+  assert.ok(schema.properties.devops.properties.provider);
+});

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

@@ -6,7 +6,7 @@ import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { initSmokeRepository } from "../loop/oris-loop-fixtures.mjs";
-import { ORIS_FLOW_ADAPTER, ORIS_FLOW_RUNTIME } from "../flow/oris-flow-layout.mjs";
+import { ORIS_FLOW_RUNTIME } from "../flow/oris-flow-layout.mjs";
 
 const scriptsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "loop");
 
@@ -118,46 +118,3 @@ test("same-chat start accepts an existing loop slug", () => {
   }
 });
 
-test("missing required profile leaves same-chat loop unarmed", () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-profile-"));
-  try {
-    initSmokeRepository(root, {
-      taskSlug: "profile-smoke",
-      program: "profile-smoke",
-    });
-    const adapterPath = path.join(root, ORIS_FLOW_ADAPTER);
-    const adapter = JSON.parse(fs.readFileSync(adapterPath, "utf8"));
-    adapter.profile = {
-      required: true,
-      defaultRole: "testing",
-      mappings: [
-        { env: "BASE_URL", from: "values.baseUrl", required: true, secret: false },
-      ],
-    };
-    fs.writeFileSync(adapterPath, `${JSON.stringify(adapter, null, 2)}\n`, "utf8");
-    const settingsPath = path.join(root, "settings.json");
-    fs.writeFileSync(settingsPath, `${JSON.stringify({
-      version: 1,
-      orisFlow: { uiLanguage: "en", artifactLanguage: "en" },
-      defaultProfiles: { testing: "default" },
-      profiles: {
-        default: { environment: "local", values: {}, secrets: {}, flags: {} },
-      },
-    }, null, 2)}\n`, "utf8");
-
-    const chat = path.join(scriptsRoot, "oris-loop-chat.mjs");
-    const start = spawnSync(process.execPath, [
-      chat,
-      "--action", "start",
-      "--loop", "profile-smoke",
-      "--repository-root", root,
-      "--settings-path", settingsPath,
-    ], { encoding: "utf8" });
-    assert.notEqual(start.status, 0);
-    assert.match(start.stderr, /missing required field 'values\.baseUrl'/);
-    assert.match(start.stderr, /Oris chat loop was not armed; the stop hook will not resume this chat/);
-    assert.equal(fs.existsSync(path.join(root, ORIS_FLOW_RUNTIME, "chat-active.json")), false);
-  } finally {
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});

package/scripts/tests/test-schemas.mjs

@@ -12,26 +12,27 @@ function read(relativePath) {
   return JSON.parse(fs.readFileSync(path.join(root, relativePath), "utf8"));
 }
 
-test("settings schema is the generic v1 contract", () => {
+test("settings schema is the minimal v1 contract: only responseStyle and artifactLanguage", () => {
   const schema = read("references/settings.schema.json");
   assert.equal(schema.properties.version.const, 1);
-  assert.deepEqual(schema.required, ["version", "orisFlow", "defaultProfiles", "profiles"]);
-  assert.ok(schema.$defs.profile.properties.values);
-  assert.ok(schema.$defs.profile.properties.secrets);
-  assert.ok(schema.$defs.profile.properties.flags);
+  assert.deepEqual(schema.required, ["version", "orisFlow"]);
+  assert.ok(schema.properties.orisFlow.properties.responseStyle);
+  assert.ok(schema.properties.orisFlow.properties.artifactLanguage);
+  assert.ok(!schema.properties.defaultProfiles, "test profiles were removed from settings");
+  assert.ok(!schema.properties.profiles, "test profiles were removed from settings");
 });
 
-test("adapter schema v1 declares paths, commands, model aliases, profile, preflight", () => {
+test("adapter schema v1 declares paths, commands, model aliases, preflight (no test profiles)", () => {
   const schema = read("references/loop-adapter.schema.json");
   assert.equal(schema.$id, "https://oris.dev/schemas/oris-loop-adapter-v1.json");
   assert.equal(schema.properties.schemaVersion.const, 1);
   assert.deepEqual(
     schema.required,
-    ["$schema", "schemaVersion", "repository", "paths", "commands", "profile", "preflight"],
+    ["$schema", "schemaVersion", "repository", "paths", "commands", "preflight"],
   );
   assert.ok(schema.properties.paths.properties.loops);
   assert.ok(schema.properties.models, "adapter schema must allow a model alias map");
-  assert.equal(schema.$defs.mapping.properties.secret.type, "boolean");
+  assert.ok(!schema.properties.profile, "test profiles were removed from the adapter");
 });
 
 test("loop document schema is v2 with approved gate, per-role models, and improve mode", () => {

package/scripts/tests/test-skill-self-contained.mjs

@@ -0,0 +1,66 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import assert from "node:assert/strict";
+import process from "node:process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function runCli(args, homeDir) {
+  return childProcess.spawnSync(process.execPath, ["scripts/oris-skills.mjs", ...args], {
+    cwd: root,
+    encoding: "utf8",
+    env: { ...process.env, HOME: homeDir, USERPROFILE: homeDir },
+    shell: false,
+  });
+}
+
+function markdownFiles(dir) {
+  return fs
+    .readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => path.join(entry.parentPath ?? entry.path, entry.name));
+}
+
+// A standalone skill (Claude/Cursor) has no bundle root above it, so every reference it
+// points to must resolve inside the skill folder — the regression that broke
+// `references/conventions.md` at runtime.
+test("installed Claude skill is self-contained", () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-self-contained-"));
+  try {
+    fs.mkdirSync(path.join(homeDir, ".claude"), { recursive: true });
+    const result = runCli(["install", "--force"], homeDir);
+    assert.equal(result.status, 0, result.stderr);
+
+    const skill = path.join(homeDir, ".claude", "skills", "oris-flow");
+    assert.ok(fs.existsSync(skill), "oris-flow skill was installed");
+
+    // The shared references that used to dangle must now be present.
+    for (const name of ["conventions.md", "doc-policy.md"]) {
+      assert.ok(
+        fs.existsSync(path.join(skill, "references", name)),
+        `shared reference ${name} is bundled into the skill`,
+      );
+    }
+
+    const files = markdownFiles(skill);
+    const pathToken = /(?:references|templates|agents)\/[A-Za-z0-9._/-]+\.(?:md|json|toml)/g;
+    const missing = [];
+    let bundlePrefixLeaks = 0;
+    for (const file of files) {
+      const text = fs.readFileSync(file, "utf8");
+      // No bundle-root-relative pointer may survive in a standalone skill.
+      if (text.includes("skills/oris-flow/")) bundlePrefixLeaks += 1;
+      for (const cited of text.match(pathToken) ?? []) {
+        if (!fs.existsSync(path.join(skill, cited))) missing.push(`${path.basename(file)} → ${cited}`);
+      }
+    }
+    assert.equal(bundlePrefixLeaks, 0, "no `skills/oris-flow/` paths remain in the standalone skill");
+    assert.deepEqual(missing, [], "every cited reference resolves inside the skill");
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});