oris-skills 2.2.3 → 3.0.2

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

@@ -59,7 +59,8 @@ test("shared conventions centralize question, language, and gate rules", () => {
   assert.match(conventions, /`Continua l'intervista`/);
   assert.match(conventions, /`Approva documento`/);
   assert.match(conventions, /`Annulla`/);
-  assert.match(conventions, /oris-flow-criteria.*writes first/i, "the criteria write-first exception must live where skills read it");
+  assert.match(conventions, /skills\/oris-flow\/references\/criteria\.md`.*writes first/i, "the criteria write-first exception must live where skills read it");
+  assert.doesNotMatch(conventions, /oris-flow-(criteria|implement|fix)/, "destinations are named by file path, never by prose nickname");
   assert.equal(exists("references/questions.md"), false, "questions.md was merged into conventions.md");
 });
 
@@ -72,58 +73,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 +135,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, triage, discover, criteria, plan, implement, fix, verify, change, architecture, docs, commit, pr, handoff, and help.
+disable-model-invocation: true
 ---
 
 # Oris Flow — the router
@@ -22,6 +23,7 @@ Match the desired outcome to ONE route, then apply its reference:
 |-------|----------------------|-------|
 | setup | prepare / map / refresh an existing repo for Oris and agents | `skills/oris-flow/references/setup.md` |
 | new | bootstrap a project from scratch, greenfield, empty directory | `skills/oris-flow/references/new.md` |
+| triage | capture an idea, bug report, or request as a work item with an agent-ready brief | `skills/oris-flow/references/triage.md` |
 | discover | understand or define product behavior, functional analysis | `skills/oris-flow/references/discover.md` |
 | criteria | acceptance criteria, QA checks, testable scenarios | `skills/oris-flow/references/criteria.md` |
 | plan | a technical implementation plan before coding | `skills/oris-flow/references/plan.md` |
@@ -29,11 +31,11 @@ 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` |
+| handoff | package session state — decisions, evidence, next move — to resume in a fresh session | `skills/oris-flow/references/handoff.md` |
 | help | how Oris works, install, update, troubleshooting | `skills/oris-flow/references/help.md` |
 
 ## Precedence (the calls that look ambiguous)
@@ -43,14 +45,18 @@ Match the desired outcome to ONE route, then apply its reference:
 2. RETHINK beats build: analyze, question, or reshape existing work →
    route to the interview owner (discover / plan / change), NEVER straight to implement.
 3. CHANGED spec on a feature that already has task docs or code → change, not discover —
-   change owns the delta and the history.
+   change owns the delta and the history. Spec unchanged but code/reality moved on and the
+   task docs lag behind → docs, not change.
 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.
+7. CAPTURE work for later (an idea, a report, backlog intake) → triage — it creates the
+   work item and stops. DOING the work now → discover / fix / implement.
+8. CONTINUE elsewhere — session ending, context full, "pass this to another agent" →
+   handoff.
 
 ## Menu (low confidence)
 
@@ -60,22 +66,26 @@ fallback in `references/conventions.md` `## Questions`), options:
 
 - Setup repository
 - New project from scratch
+- Capture an idea or bug as a work item (triage)
 - Understand / define behavior (discovery)
 - Acceptance criteria
 - Technical plan
 - Implement or fix
 - Verify acceptance criteria
 - Spec changed: update feature docs
-- Loop: repeat until verified
 - Architecture review
 - Update docs
 - Commit changes
 - Open a pull request
+- Hand off this session (continue elsewhere)
 - Help
 - Explain the options / Spiega le opzioni
 
-IF "Explain the options" → explain briefly, re-ask the same question.
-Every other label maps 1:1 to its route in the table above.
+IF "Explain the options" → ONE message that contains BOTH: one explanation line per
+option, THEN the full lettered list again below the explanations. Re-asking without the
+explanations visible in that same message is the failure this rule exists to prevent.
+Every other label maps to its route in the table above; "Implement or fix" is the one
+label that splits, with exactly one follow-up question (Precedence 4).
 
 ## Never
 

package/skills/oris-flow/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Oris Flow"
   short_description: "Start the Oris workflow menu"
-  default_prompt: "Use $oris-flow to choose the right Oris workflow command."
+  default_prompt: "Use $oris-flow to enter the right Oris workflow."

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;
@@ -37,10 +37,13 @@ WRITE a self-contained HTML file to the OS temp dir (`architecture-review-<times
 OPEN it (`start` | `open` | `xdg-open`), TELL the absolute path.
 
 FORMAT: Tailwind CDN + Mermaid CDN. Per candidate, one card:
-- title (names the deepening) + strength badge: `Strong` | `Worth exploring` | `Speculative`;
+- title (names the deepening) + strength badge — `Strong` (friction observed in the code,
+  fix shape clear) | `Worth exploring` (friction observed, fix shape uncertain) |
+  `Speculative` (pattern suggests it, not yet observed);
 - files (monospaced), Problem (one sentence), Solution (one sentence);
 - Before/After diagram side by side — Mermaid for graph-shaped, hand-built divs/SVG for
-  mass diagrams; if the diagram needs a paragraph, redraw the diagram;
+  mass diagrams; the diagram must explain itself without a caption — if it needs one,
+  simplify the diagram;
 - wins as bullets ≤6 words, glossary terms only — never "cleaner code";
 - ADR conflict → amber callout ("contradicts ADR-0007 — worth reopening because…").
 

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

@@ -3,6 +3,9 @@
 Specs changed while the feature exists (documented, planned, or half-built). Understand
 the delta, update EVERYTHING together, keep the history traceable.
 
+BOUNDARY: the business spec MOVED → this route. Spec unchanged but code/reality moved on
+and the docs lag behind → `skills/oris-flow/references/docs.md`.
+
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 
 ## Delta interview

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`.
 
@@ -12,9 +12,13 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
    preferred, never required — say once when missing) > current UI > code and tests.
 2. DEDUCE create vs update: existing `acceptance-criteria.md` → update, PRESERVE IDs.
 3. IDs: `AC-001`, `AC-002`, … stable across revisions.
-4. Each scenario declares ALL of: role + starting state · deterministic data · numbered
-   user steps · observable outcome under the step that causes it · negative coverage ·
-   regressions to keep.
+4. Each scenario declares ALL of:
+   - role + starting state;
+   - deterministic data;
+   - numbered user steps;
+   - observable outcome under the step that causes it;
+   - negative coverage;
+   - regressions to keep.
 5. CLASSIFY each: `Verifiable` | `Needs setup/data` | `Blocked by Open QA`.
 6. DISCARD criteria not checkable through observable product behavior. Unbuilt features:
    only confirmed intended behavior.

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