oris-skills 2.2.3 → 3.0.1

package/scripts/tests/test-cleanliness.mjs

@@ -0,0 +1,54 @@
+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), []);
+});
+
+// Machinery removed in 3.0: the loop runtime and the manifest/maps knowledge store.
+// The agent-facing surface (skills, references, docs, README) must never point at it;
+// CHANGELOG keeps the history, and the uninstaller/gitignore keep legacy-cleanup paths.
+const removedMachinery = /oris-skills loop |scripts\/loop\/|\.oris-flow\/(?:loops|runtime|manifest\.json|maps|adapter\.json)|loop-contract|references\/repo-map|flow scan[^\n]*--(?:check|write|area)|flow clean-runtime/;
+
+test("agent-facing text never references machinery removed in 3.0", () => {
+  const offenders = repoFiles()
+    .filter((entry) => /^(skills|references|docs)\/.*\.md$|^(README|AGENTS|CONTEXT)\.md$/.test(entry.relative))
+    .filter((entry) => removedMachinery.test(fs.readFileSync(entry.filePath, "utf8")))
+    .map((entry) => entry.relative);
+  assert.deepEqual(offenders, []);
+});
+
+test("production scripts never invoke machinery removed in 3.0", () => {
+  const offenders = repoFiles()
+    // scripts/tests assert absences; the uninstaller/gitignore clean legacy paths — both must name them.
+    .filter((entry) => /^scripts\/(flow|install)\/.*\.mjs$|^scripts\/[^/]+\.mjs$/.test(entry.relative))
+    .filter((entry) => entry.relative !== "scripts/install/uninstall-user-skills.mjs")
+    .filter((entry) => entry.relative !== "scripts/flow/oris-gitignore.mjs")
+    .filter((entry) => removedMachinery.test(fs.readFileSync(entry.filePath, "utf8")))
+    .map((entry) => entry.relative);
+  assert.deepEqual(offenders, []);
+});

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

@@ -1,18 +1,16 @@
-import assert from "node:assert/strict";
+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 childProcess from "node:child_process";
-import { checkFreshness, scanRepository, writeScanResult } from "../flow/oris-flow-scan.mjs";
-import { ORIS_FLOW_MANIFEST } from "../flow/oris-flow-layout.mjs";
+import { scanRepository } from "../flow/oris-flow-scan.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", () => {
+test("scanner reports only evidence-backed areas and writes nothing", () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
   try {
     write(path.join(root, "README.md"), "# Demo\n");
@@ -20,17 +18,13 @@ test("scanner creates only evidence-backed map sections", () => {
     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);
+    assert.ok(scan.areas.docs);
+    assert.ok(scan.areas.code);
+    assert.ok(scan.stacks.some((stack) => stack.id === "node"));
+    assert.ok(scan.commands.some((command) => command.command === "npm run test"));
+    assert.equal(scan.areas.tests, undefined, "no test evidence → no tests area");
 
-    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")));
+    assert.equal(fs.existsSync(path.join(root, ".oris-flow")), false, "scan never writes");
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
@@ -41,8 +35,9 @@ test("scanner supports documentation-only repositories", () => {
   try {
     write(path.join(root, "docs", "guide.md"), "# Guide\n");
     const scan = scanRepository(root);
-    assert.deepEqual(Object.keys(scan.manifest.sections), ["docs"]);
+    assert.deepEqual(Object.keys(scan.areas), ["docs"]);
     assert.deepEqual(scan.stacks, []);
+    assert.deepEqual(scan.commands, []);
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
@@ -61,96 +56,31 @@ test("scanner detects project type and derives inferred stack commands", () => {
     const dotnetTest = scan.commands.find((command) => command.command.startsWith("dotnet test"));
     assert.ok(dotnetTest, "expected an inferred dotnet test command");
     assert.equal(dotnetTest.confidence, "inferred");
-    assert.equal(scan.manifest.setup.tasksRoot, ".oris-flow/tasks");
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
 
-test("refresh preserves confirmed sections, commands, and tasksRoot", () => {
+test("scanner flags truncation instead of silently under-reporting", () => {
   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`);
-
-    const first = scanRepository(root);
-    first.manifest.setup.tasksRoot = "docs/tasks";
-    first.manifest.setup.confirmedDecisions = ["tests live under scripts/tests"];
-    first.manifest.sections.docs.confidence = "confirmed";
-    first.manifest.commands[0].confidence = "confirmed";
-    writeScanResult(first);
-    const enriched = "# Docs\n\nUser-confirmed enrichment that must survive refresh.\n";
-    write(path.join(root, ".oris-flow", "maps", "docs.md"), enriched);
-
-    const second = scanRepository(root);
-    assert.equal(second.manifest.setup.tasksRoot, "docs/tasks");
-    assert.deepEqual(second.manifest.setup.confirmedDecisions, ["tests live under scripts/tests"]);
-    assert.equal(second.manifest.sections.docs.confidence, "confirmed");
-    assert.equal(second.manifest.sections.docs.stale, false);
-    assert.equal(second.manifest.commands[0].confidence, "confirmed");
-    assert.ok(second.preservedSections.has("docs"));
-
-    writeScanResult(second);
-    assert.equal(fs.readFileSync(path.join(root, ".oris-flow", "maps", "docs.md"), "utf8"), enriched);
+    for (let index = 0; index < 12; index += 1) {
+      write(path.join(root, "src", `file-${index}.js`), "export {};\n");
+    }
+    const scan = scanRepository(root, { maxFiles: 5 });
+    assert.equal(scan.truncated, true);
+    assert.ok(scan.fileCount <= 5);
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
 
-test("confirmed section without fresh evidence is marked stale, not deleted", () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
-  try {
-    write(path.join(root, "README.md"), "# Demo\n");
-    const first = scanRepository(root);
-    first.manifest.sections.docs.confidence = "confirmed";
-    writeScanResult(first);
-
-    fs.rmSync(path.join(root, "README.md"));
-    const second = scanRepository(root);
-    assert.equal(second.manifest.sections.docs.confidence, "confirmed");
-    assert.equal(second.manifest.sections.docs.stale, true);
-  } finally {
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-
-test("scan anchors the map to HEAD; --check answers freshness from the SHA + changed files", () => {
+test("empty repository classifies as empty", () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
-  const git = (...args) => childProcess.execFileSync("git", args, { cwd: root, encoding: "utf8" });
   try {
-    write(path.join(root, "README.md"), "# Demo\n");
-    write(path.join(root, "package.json"), `${JSON.stringify({ scripts: { test: "node --test" } })}\n`);
-    git("init", "-q");
-    git("-c", "user.email=t@t", "-c", "user.name=t", "add", ".");
-    git("-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "-m", "init");
-
-    const scan = scanRepository(root);
-    assert.equal(typeof scan.manifest.headSha, "string", "scan records the HEAD anchor");
-    writeScanResult(scan);
-
-    const fresh = checkFreshness(root);
-    assert.equal(fresh.fresh, true, "same SHA + clean tree → fresh, zero reads");
-    assert.deepEqual(fresh.changedFiles, []);
-
-    write(path.join(root, "src", "new.js"), "export const later = 1;\n");
-    const stale = checkFreshness(root);
-    assert.equal(stale.fresh, false, "working-tree change → stale");
-    assert.ok(stale.changedFiles.some((file) => file.includes("new.js")), "changed files name the delta");
-  } finally {
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test("outside git the map still works — no anchor, never an error", () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
-  try {
-    write(path.join(root, "README.md"), "# Demo\n");
     const scan = scanRepository(root);
-    assert.equal(scan.manifest.headSha, null);
-    writeScanResult(scan);
-    const check = checkFreshness(root);
-    assert.equal(check.fresh, false, "no anchor → refresh advised, not an error");
+    assert.equal(scan.projectType.id, "empty");
+    assert.deepEqual(scan.areas, {});
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }

package/scripts/tests/test-routing-lifecycle.mjs

@@ -72,58 +72,27 @@ test("every skill points at conventions instead of repeating shared rules", () =
   }
 });
 
-test("loop skill covers craft, demo, run, audit, improve and editable prompt files", () => {
-  const skill = read("skills/oris-flow/references/loop.md");
-  assert.match(skill, /references\/loop-craft\.md/);
-  assert.match(skill, /references\/loop-run\.md/);
-  assert.match(skill, /references\/loop-improve\.md/);
-  assert.match(skill, /oris-skills loop demo/);
-  assert.match(skill, /oris-skills loop dry-run/);
-  assert.match(skill, /oris-skills loop list --json/);
-  assert.match(skill, /prompts\//);
-  assert.match(skill, /improve\.mode: auto/);
-  assert.match(skill, /Cursor|Claude Code|Codex/);
-  for (const reference of ["craft", "run", "improve"]) {
-    assert.equal(exists(`skills/oris-flow/references/loop-${reference}.md`), true, reference);
-  }
-  for (const template of ["orchestrator", "executor", "verifier", "doctor", "debriefer"]) {
-    assert.equal(exists(`skills/oris-flow/templates/${template}.md`), true, template);
-  }
-});
-
-test("loop contract stays subagent-first with per-role editable prompts", () => {
-  const contract = read("references/loop-contract.md");
-  assert.match(contract, /schemaVersion: 2/);
-  assert.match(contract, /approved: true/);
-  assert.match(contract, /prompts\/orchestrator\.md/);
-  assert.match(contract, /improve/);
-  assert.match(contract, /inherit/);
-  assert.match(contract, /NEVER success/i);
-  const run = read("skills/oris-flow/references/loop-run.md");
-  assert.match(run, /oris-skills loop chat --action start --loop <slug>/);
-  assert.match(run, /NEVER do executor\/verifier\/doctor work in the main chat/i);
-  assert.match(run, /set-state blocked/);
-  assert.match(run, /oris-skills loop run --loop <slug> --agent codex\|claude/);
-  const craft = read("skills/oris-flow/references/loop-craft.md");
-  assert.match(craft, /skills\/oris-flow\/templates\//);
-  assert.match(craft, /write the loop \| edit verifier \| edit executor \| edit doctor/);
-  assert.match(contract, /ORIS LOOP ACTIVE/, "the contract defines the executor gate literal");
-  for (const text of [contract, run, craft, read("skills/oris-flow/references/loop.md")]) {
-    assert.doesNotMatch(text, /node scripts\/(?:flow|loop)\//);
-    assert.doesNotMatch(text, /composer-2\.5/);
-  }
-  for (const text of [run, craft, read("skills/oris-flow/references/loop.md")]) {
-    assert.doesNotMatch(text, /ORIS LOOP ACTIVE/, "the gate literal lives in the contract and executor prompts only");
+test("the loop runtime is fully removed", () => {
+  for (const legacy of [
+    "scripts/loop",
+    "agents",
+    "skills/oris-flow/templates",
+    "skills/oris-flow/references/loop.md",
+    "references/loop-contract.md",
+    "references/repo-map.md",
+  ]) {
+    assert.equal(exists(legacy), false, `${legacy} must not exist`);
   }
+  const skill = read("skills/oris-flow/SKILL.md");
+  assert.doesNotMatch(skill, /\bloop\b/i, "the router must not mention loops");
 });
 
-test("setup and repo-map keep the installed CLI as the command surface", () => {
+test("setup keeps the installed CLI as the command surface and AGENTS.md as the store", () => {
   const setup = read("skills/oris-flow/references/setup.md");
   assert.match(setup, /oris-skills flow scan --repository-root <repo> --json/);
-  assert.match(setup, /oris-skills loop bootstrap --repository-root <repo>/);
-  assert.match(setup, /oris-skills flow clean-runtime --repository-root <repo> --dry-run/);
-  const repoMap = read("references/repo-map.md");
-  assert.match(repoMap, /never `node scripts\/\.\.\.` paths/);
+  assert.match(setup, /oris-skills flow version-control --repository-root <repo> --mode commit\|gitignore/);
+  assert.doesNotMatch(setup, /node scripts\//, "always the installed CLI, never source paths");
+  assert.match(setup, /AGENTS\.md/);
 });
 
 test("no markdown references the pre-2.0 layout", () => {
@@ -165,18 +134,18 @@ test("uninstall and reinstall dry-runs show destructive plan before action", ()
   }
 });
 
-test("CLI exposes install, loop learnability, and flow helper commands", () => {
+test("CLI exposes install and flow helper commands, and no loop surface", () => {
   const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-cli-help-"));
   try {
     const help = runCli(["help"], homeDir);
     assert.equal(help.status, 0, help.stderr);
     assert.match(help.stdout, /--agents cursor,claude,codex/);
-    assert.match(help.stdout, /oris-skills loop demo/);
-    assert.match(help.stdout, /oris-skills loop dry-run --loop <slug>/);
-    assert.match(help.stdout, /oris-skills loop verify --temp/);
-    assert.match(help.stdout, /oris-skills loop chat --action start --loop <slug>/);
-    assert.match(help.stdout, /oris-skills loop run --loop <slug> --agent codex\|claude/);
     assert.match(help.stdout, /oris-skills flow scan/);
+    assert.match(help.stdout, /oris-skills flow version-control/);
+    assert.doesNotMatch(help.stdout, /loop/i);
+
+    const loop = runCli(["loop", "list"], homeDir);
+    assert.equal(loop.status, 1, "loop is an unknown command in 3.0");
   } finally {
     fs.rmSync(homeDir, { recursive: true, force: true });
   }

package/scripts/tests/test-schemas.mjs

@@ -12,45 +12,31 @@ function read(relativePath) {
   return JSON.parse(fs.readFileSync(path.join(root, relativePath), "utf8"));
 }
 
-test("settings schema is the minimal v1 contract: only responseStyle and artifactLanguage", () => {
+test("settings schema is the v1 contract: preferences only, no secrets, no profiles", () => {
   const schema = read("references/settings.schema.json");
   assert.equal(schema.properties.version.const, 1);
   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, 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);
+  const properties = schema.properties.orisFlow.properties;
   assert.deepEqual(
-    schema.required,
-    ["$schema", "schemaVersion", "repository", "paths", "commands", "preflight"],
+    Object.keys(properties).sort(),
+    ["artifactLanguage", "responseStyle", "tasksRoot", "versionControl"],
   );
-  assert.ok(schema.properties.paths.properties.loops);
-  assert.ok(schema.properties.models, "adapter schema must allow a model alias map");
-  assert.ok(!schema.properties.profile, "test profiles were removed from the adapter");
+  assert.deepEqual(properties.versionControl.enum, ["commit", "gitignore"]);
+  assert.ok(!schema.properties.defaultProfiles, "test profiles were removed from settings");
+  assert.ok(!schema.properties.profiles, "test profiles were removed from settings");
 });
 
-test("loop document schema is v2 with approved gate, per-role models, and improve mode", () => {
-  const schema = read("references/loop.schema.json");
-  assert.equal(schema.$id, "https://oris.dev/schemas/oris-loop-v2.json");
-  assert.equal(schema.properties.schemaVersion.const, 2);
-  assert.ok(schema.required.includes("approved"));
-  assert.ok(!schema.required.includes("runtime"), "runtime field was removed in v2");
-  for (const role of ["default", "executor", "verifier", "doctor", "debriefer"]) {
-    assert.ok(schema.properties.models.properties[role], `models.${role}`);
+test("no loop or repo-map schemas survive the 3.0 cleanup", () => {
+  for (const legacy of [
+    "references/loop.schema.json",
+    "references/loop-adapter.schema.json",
+    "references/repo-map.schema.json",
+  ]) {
+    assert.equal(fs.existsSync(path.join(root, legacy)), false, `${legacy} must not exist`);
   }
-  assert.deepEqual(schema.properties.improve.properties.mode.enum, ["propose", "auto"]);
-  assert.equal(schema.$defs.model.type, "string", "models are free strings (inherit | alias | model id), not a hardcoded enum");
 });
 
-test("repository map schema v1 allows stack-aware optional sections", () => {
-  const schema = read("references/repo-map.schema.json");
-  assert.equal(schema.properties.schemaVersion.const, 1);
-  assert.deepEqual(schema.required, ["$schema", "schemaVersion", "repository", "generatedAt", "updatedAt", "setup", "sections"]);
-  assert.ok(schema.$defs.sections.additionalProperties);
+test("devops schema stays the only other JSON contract", () => {
+  const schemas = fs.readdirSync(path.join(root, "references")).filter((name) => name.endsWith(".schema.json"));
+  assert.deepEqual(schemas.sort(), ["devops.schema.json", "settings.schema.json"]);
 });

package/scripts/tests/test-skill-style.mjs

@@ -36,8 +36,11 @@ test("skill style: oris-flow", () => {
   assert.match(front[1], /^name: oris-flow$/m, "front matter name matches the folder");
   const description = front[1].match(/^description: (.+)$/m)?.[1];
   assert.ok(description, "front matter has description");
-  assert.match(description, /Use for/, "description names its triggers");
-  assert.doesNotMatch(front[1], /disable-model-invocation/, "the single entry point must stay model-invocable");
+  assert.match(
+    front[1],
+    /^disable-model-invocation: true$/m,
+    "the entry point is user-invoked only (/oris-flow) — decision 2026-07-10, never auto-triggered",
+  );
   assert.ok(text.includes("## Never"), "carries an explicit Never block");
   assert.ok(text.includes("## Done when"), "ends with a Done when checklist");
   const lines = text.split(/\r?\n/).length;

package/skills/oris-flow/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: oris-flow
-description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Use for /oris-flow and whenever the user wants to set up a repo for agents, start a project, understand or define behavior, write acceptance criteria, plan, implement, fix a bug, verify criteria, handle a spec change, run a work loop (fix until green, repeat until verified), review architecture, update task docs, commit changes, open a pull request, or asks how Oris works.
+description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Routes setup, new project, discovery, acceptance criteria, technical plan, implement, fix, verify, spec change, architecture review, docs, commit, pull request, and help.
+disable-model-invocation: true
 ---
 
 # Oris Flow — the router
@@ -29,10 +30,9 @@ Match the desired outcome to ONE route, then apply its reference:
 | fix | broken behavior, a regression, a failed QA check | `skills/oris-flow/references/fix.md` |
 | verify | check acceptance criteria against the real product, once | `skills/oris-flow/references/verify.md` |
 | change | the spec changed — update analysis, criteria, plan, and history together | `skills/oris-flow/references/change.md` |
-| loop | repeat work until verified — fix until green, step through a plan | `skills/oris-flow/references/loop.md` |
 | architecture | review architecture, find deepening/refactor opportunities | `skills/oris-flow/references/architecture.md` |
 | docs | update task docs after a change | `skills/oris-flow/references/docs.md` |
-| commit | commit changes with the Oris standard — map fresh, Conventional Commits, work item linked | `skills/oris-flow/references/commit.md` |
+| commit | commit changes with the Oris standard — Conventional Commits, work item linked | `skills/oris-flow/references/commit.md` |
 | pr | open or update a pull request, English title/description linked to the work item | `skills/oris-flow/references/pr.md` |
 | help | how Oris works, install, update, troubleshooting | `skills/oris-flow/references/help.md` |
 
@@ -46,10 +46,9 @@ Match the desired outcome to ONE route, then apply its reference:
    change owns the delta and the history.
 4. BROKEN behavior → fix. NEW planned work → implement. The menu answer "Implement or
    fix" gets exactly one follow-up question to split them.
-5. CHECK once → verify. Repeat-until-verified → loop.
-6. EMPTY directory or from-scratch intent → new. Existing repo without
-   `.oris-flow/manifest.json` → recommend setup first; respect the user's choice.
-7. COMMIT staged/working changes with the standard → commit. OPEN or update a pull request
+5. EMPTY directory or from-scratch intent → new. Existing repo never touched by Oris
+   (no `AGENTS.md`, no `.oris-flow/`) → recommend setup first; respect the user's choice.
+6. COMMIT staged/working changes with the standard → commit. OPEN or update a pull request
    → pr. Neither writes product code — they package and publish what implement/fix produced.
 
 ## Menu (low confidence)
@@ -66,7 +65,6 @@ fallback in `references/conventions.md` `## Questions`), options:
 - Implement or fix
 - Verify acceptance criteria
 - Spec changed: update feature docs
-- Loop: repeat until verified
 - Architecture review
 - Update docs
 - Commit changes

package/skills/oris-flow/references/architecture.md

@@ -22,7 +22,7 @@ routes to plan/implement.
 
 ## 1. Explore
 
-1. READ first: setup map, `CONTEXT.md` (domain names for good seams), `docs/adr/`
+1. READ first: `AGENTS.md`, `CONTEXT.md` (domain names for good seams), `docs/adr/`
    (decisions NOT to re-litigate).
 2. WALK the codebase with parallel subagents. No rigid heuristics — note real friction:
    - understanding one concept requires bouncing between many small modules;

package/skills/oris-flow/references/commit.md

@@ -1,15 +1,16 @@
 # Commit
 
-Turn staged or working changes into one clean commit — map fresh, message in English,
-work item linked. NEVER commit without showing the message and getting a yes.
+Turn staged or working changes into one clean commit — message in English, work item
+linked. NEVER commit without showing the message and getting a yes.
 
 RULES: `references/conventions.md`. DevOps config: `references/devops.md`.
 
 ## Before the commit
 
-1. FRESHEN the map: `npx oris-skills flow scan --repository-root <repo> --check`. Stale →
-   refresh ONLY the changed areas (`--area <section>`) and stage `.oris-flow/` with the change.
-2. READ the diff (`git status`, `git diff --staged`) to know what actually changed.
+1. READ the diff (`git status`, `git diff --staged`) to know what actually changed.
+2. IF the diff proved a durable fact `AGENTS.md` lacks or contradicts (a new command, a
+   moved area) → correct `AGENTS.md` and stage it with the change (`references/conventions.md`
+   `## Project facts`).
 3. RESOLVE the work item id from context — current branch, the active task doc, or the
    DevOps provider's active items. Unsure → ASK once for the id; never invent one.
 
@@ -23,7 +24,7 @@ RULES: `references/conventions.md`. DevOps config: `references/devops.md`.
 
 ## Gate (never skipped)
 
-SHOW the full message + the files it will commit (code + refreshed map). ASK:
+SHOW the full message + the files it will commit. ASK:
 commit | edit message | cancel. ON commit → `git commit`; NEVER `--no-verify`.
 
 ## After
@@ -36,10 +37,10 @@ commit | edit message | cancel. ON commit → `git commit`; NEVER `--no-verify`.
 - Commit before the message and file list are shown and confirmed.
 - Write the message in any language but English.
 - Invent a work item id, or bypass hooks with `--no-verify`.
-- Refresh confirmed map sections, or scan-rewrite areas the diff did not touch.
+- Touch `AGENTS.md` sections the diff did not contradict.
 
 ## Done when
 
-- [ ] Map checked, and refreshed in place only where the diff touched.
+- [ ] Diff read; `AGENTS.md` corrected only where the diff proved it wrong.
 - [ ] English Conventional message with the work item linked, confirmed at the gate.
 - [ ] Commit made without `--no-verify`; next step offered, not auto-run.

package/skills/oris-flow/references/criteria.md

@@ -1,8 +1,8 @@
 # Acceptance Criteria
 
 Generate verifiable criteria grounded in observable product behavior — UI, API response,
-CLI output, or a visible system effect. They later feed verify-route checks and
-loop VERIFIER prompts — precision here pays twice.
+CLI output, or a visible system effect. They are the exact checklist the verify route
+executes — precision here pays twice.
 
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 

package/skills/oris-flow/references/discover.md

@@ -1,7 +1,7 @@
 # Discovery
 
 Interview the stakeholder until the desired business behavior is clear enough to
-document. The cornerstone of the flow: everything downstream (criteria, plan, loops)
+document. The cornerstone of the flow: everything downstream (criteria, plan, implement)
 builds on this.
 
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
@@ -9,7 +9,7 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 ## Before asking
 
 1. EXPLORE first: task folder (`{tasksRoot}/{task}/`), existing task docs, project docs,
-   setup map, code evidence, DevOps context when available.
+   `AGENTS.md`, code evidence, DevOps context when available.
 2. DEDUCE create vs update: existing `functional-analysis.md` → update; missing → create.
    Ask only on contradictory signals.
 3. Technical evidence = private input. TRANSLATE it to business language; never show file

package/skills/oris-flow/references/fix.md

@@ -3,7 +3,7 @@
 The smallest safe change near the failing behavior. Reproduce first, root cause before
 any edit, evidence before done.
 
-RULES: `references/conventions.md`.
+RULES: `references/conventions.md`. Research: `references/research.md`.
 
 ## Triage
 
@@ -19,8 +19,12 @@ RULES: `references/conventions.md`.
 - REPRODUCE or trace the failure path in code before proposing anything.
 - FIND root cause, not symptom. Check whether the documented behavior
   (criteria/analysis) defines "correct".
-- SUMMARIZE: root cause → proposed minimal fix → files → verification plan.
-  CONFIRM explicitly.
+- RESEARCH when the cause crosses the repo boundary (`references/research.md`): a
+  third-party error, a library behaving unlike its docs, a known-issue smell → search
+  for the documented behavior and standard workarounds at the repo's pinned versions,
+  instead of guessing.
+- SUMMARIZE: root cause → proposed minimal fix → files → verification plan (+ sources
+  when research ran). CONFIRM explicitly.
 
 ## Fix
 

package/skills/oris-flow/references/help.md

@@ -8,24 +8,19 @@ details on request.
 | Need | Answer |
 |------|--------|
 | Start anything | Type `/oris-flow` — it routes or shows the menu. The only command to remember. |
-| Try loops safely | `npx oris-skills loop demo` → follow the 3 printed steps (`dry-run` previews, `chat --action start` runs). |
 | Install / update | `npx oris-skills@latest install` (detects Cursor, Claude Code, Codex, Copilot; or `--agents cursor,claude,codex,copilot`). Reload the agent afterwards. |
 | Copilot / any other agent | Copilot Chat: enable `chat.promptFiles` once, then `/oris-flow`. Anything else that reads files: point it at `~/.oris/oris-flow.md`. |
 | Uninstall / reinstall | `npx oris-skills uninstall` / `npx oris-skills reinstall` (preview with `--dry-run`). |
-| Stop a loop | `npx oris-skills loop chat --action stop` |
-| Loop status | `npx oris-skills loop chat --action status` / `npx oris-skills loop list` |
 | Skill missing after install | Reload the agent; check `~/.oris/oris-skills/` exists; re-run install with `--force`. |
-| Hook not firing | `npx oris-skills loop verify --temp` self-checks the runtime; `npx oris-skills loop bootstrap` re-arms repo hooks. |
 | Change document language / chat verbosity | `/oris-flow` → Setup (settings live in `.oris-flow/settings.json`). |
 | Ultra-short answers | `/oris-flow` → Setup → set `responseStyle: caveman` — chat shrinks to maximum token density; documents stay complete. |
-| Edit a loop's behavior | Edit the files in `.oris-flow/loops/{slug}/prompts/` — the next pass obeys them. |
 
 Deeper docs: `docs/user-guide.md`, `docs/architecture.md` in the bundle (`~/.oris/oris-skills/`).
 
 ## Never
 
 - Tell users to paste secrets anywhere.
-- Dump internals (manifest JSON, hook mechanics) unless the user asks for technical
+- Dump internals (settings JSON, install layout) unless the user asks for technical
   troubleshooting.
 
 ## Done when

package/skills/oris-flow/references/implement.md

@@ -2,14 +2,14 @@
 
 Execute the confirmed plan — nothing more, nothing less.
 
-RULES: `references/conventions.md`.
+RULES: `references/conventions.md`. Research: `references/research.md`.
 
 ## Prepare
 
 1. FIND `{tasksRoot}/{task}/implementation-plan.md`. IF missing → reconstruct a technical
    recap from chat, task docs, and code; SHOW it; CONFIRM before any edit.
-2. READ setup map, project standards, local skills/rules, tests and build conventions for
-   the touched area.
+2. READ `AGENTS.md`, project standards, local skills/rules, tests and build conventions
+   for the touched area.
 3. MAP the code, tests, config, and translations the plan touches (parallel subagents
    when available).
 
@@ -22,6 +22,8 @@ RULES: `references/conventions.md`.
 ## While coding
 
 - FOLLOW existing project patterns; no new abstractions without need.
+- RESEARCH mid-build only when an external API resists (`references/research.md`) —
+  verify its current docs at the repo's pinned version; never guess signatures.
 - STAY inside the confirmed scope; park discoveries as notes, don't chase them.
 - ADD or update focused tests for the changed behavior.
 - CLEAN as you finish (`references/clean-code-checklist.md`): remove dead code, debug