oris-skills 2.2.3 → 3.0.2

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "oris-skills",
-  "description": "Oris Skills: one entry point (/oris-flow), guided discovery-to-implementation flow, and self-tuning verified loops. Cross-model: Cursor, Claude Code, Codex.",
-  "version": "2.2.1",
+  "description": "Oris Skills: one entry point (/oris-flow) and a guided discovery-to-implementation flow. Cross-model: Cursor, Claude Code, Codex.",
+  "version": "3.0.1",
   "author": {
     "name": "Davide Baldassarre"
   },
@@ -11,7 +11,6 @@
     "skills",
     "workflow",
     "flow",
-    "loop",
     "cursor",
     "claude",
     "codex"

package/CHANGELOG.md

@@ -1,12 +1,30 @@
 # Changelog
 
-## Unreleased
+## 3.0.1 - 2026-07-10
 
-- **Settings are per-project and tiny**: moved out of the user-global `~/.oris/settings.json` into `.oris-flow/settings.json`, holding only `orisFlow.responseStyle` (`standard`/`caveman`) and `orisFlow.artifactLanguage` (document language, default `en`). The installer no longer creates a settings file.
-- **Test profiles removed**: the whole profile/secret subsystem is gone — `defaultProfiles`, `profiles`, the adapter `profile` block and its env mappings, and the loop's profile-gating. Every project drives its own e2e/CI tooling; Oris stores no credentials.
-- **No UI-language setting**: chat, menus, and question labels follow the language the user writes (deduced from context); only generated documents use `artifactLanguage`.
-- **No refresh-policy setting**: map freshness is answered by the `headSha` anchor (`flow scan --check`); the advisory `refreshPolicy` field was dropped from the manifest and schema.
-- **Questions & subagents fire reliably**: conventions now bind a platform question call (Claude `AskUserQuestion`) as a tool call rather than optional chat text, and treat entering an Oris route as the explicit request to spawn scan subagents — so gates open their UI and setup fans out by default.
+The lean core: one skill, one durable store, evidence on both sides of the repo boundary.
+(3.0.0 was published briefly and unpublished; npm never reuses a version number.)
+
+- **`AGENTS.md` is the single knowledge store.** Setup detects project type, stacks, and
+  commands (`flow scan --json`, a pure reporter that writes nothing), you confirm them,
+  and they land in `AGENTS.md` — the file every agent already loads. No manifests, no
+  map caches, no freshness bookkeeping, no state files in your repo.
+- **Per-project settings, tiny and non-secret.** `.oris-flow/settings.json` holds
+  `responseStyle` (`standard`/`caveman`), `artifactLanguage`, `tasksRoot` (default
+  `.oris-flow/tasks`), and `versionControl` (`commit` | `gitignore` for `.oris-flow/`).
+- **Research discipline.** New shared contract `references/research.md`, applied by fix,
+  plan, and implement (never discover): when the problem crosses the repo boundary —
+  third-party APIs, external errors, known-issue smells — search current official docs
+  at the repo's pinned versions, record sources in the task document, and mark
+  unverified claims `inferred`. "Code only" / "check online" from the user always wins.
+- **`/oris-flow` is user-invoked only.** `disable-model-invocation: true` in the skill
+  front matter: the model never auto-enters the flow; you type `/oris-flow` or nothing
+  happens. The description also drops out of always-loaded context.
+- **Loops removed.** The 2.x self-verifying loop runtime (subagent roles, receipts,
+  stop hooks, `oris-skills loop …` CLI) left the core — its niche was headless/batch
+  work, the core's is the interactive flow. Repeat-until-verified work runs as
+  implement → verify cycles.
+- **Questions & subagents fire reliably**: conventions bind a platform question call (Claude `AskUserQuestion`) as a tool call rather than optional chat text, and treat entering an Oris route as the explicit request to spawn scan subagents — so gates open their UI and setup fans out by default.
 
 ## 2.2.1 - 2026-07-07
 

package/README.md

@@ -1,6 +1,6 @@
 # Oris Skills
 
-**One command. A disciplined software flow. Loops that verify themselves.**
+**One command. A disciplined software flow. Evidence before "done".**
 For Cursor, Claude Code, Codex, GitHub Copilot — and any agent that can read a file.
 
 ```bash
@@ -12,23 +12,27 @@ Reload your agent, then type **`/oris-flow`**. That is the entire user manual.
 ## The idea
 
 AI agents are brilliant executors and terrible colleagues: they guess requirements,
-declare victory without evidence, and forget everything between sessions. Oris fixes the
-colleague part with three rules baked into every interaction:
+declare victory without evidence, and hallucinate the world outside your repo. Oris
+fixes the colleague part with three rules baked into every interaction:
 
-1. **Interview before writing.** Nothing lands in your repo — no document, no code — before
-   you explicitly approve it. One question per turn, recommended answer first.
+1. **Interview before writing.** Nothing lands in your repo — no document, no code —
+   before you explicitly approve it. One question per turn, recommended answer first.
 2. **Evidence before done.** "It works" means a command ran and its output says so.
-   Verification is independent from execution: the agent that writes code never grades
-   its own homework.
-3. **Remember without slowing down.** The repo map is anchored to a commit SHA; one cheap
-   check answers "is my knowledge fresh?", and only the changed areas are re-read.
-   Bookkeeping is silent — you see questions, answers, and results, never the machinery.
+   And when the problem crosses the repo boundary — a third-party API, a library
+   misbehaving — the flow checks current official docs at your pinned versions instead
+   of guessing, and records the sources.
+3. **Your repo stays yours.** Durable facts go in `AGENTS.md` (the file every agent
+   already reads), preferences in one small settings file, task documents in their own
+   folder. No caches, no state, no churn — and the skill never triggers itself: you
+   type `/oris-flow`, or nothing happens.
 
 ## One skill, every route
 
 `/oris-flow` reads your intent and enters the right route in the same chat — no other
 command exists. Say "the login button does nothing" and you are in **fix**; say "the
-client changed their mind about invoicing" and you are in **change**.
+client changed their mind about invoicing" and you are in **change**; say "a client
+reported this, park it" and **triage** captures it as a work item; say "I'm out of
+context" and **handoff** packages the session for the next one.
 
 ```text
         idea ──► discover ──► criteria ──► plan ──► implement ──► verify
@@ -38,79 +42,43 @@ client changed their mind about invoicing" and you are in **change**.
 
 | Route | You get |
 |-------|---------|
-| **setup** | the repo mapped into `.oris-flow/` (type, commands, structure) so agents stop re-scanning; AI-readiness check |
+| **setup** | the repo made agent-ready: detected commands and structure confirmed into `AGENTS.md`; AI-readiness check |
 | **new** | a greenfield project born agent-native: sparse `AGENTS.md`, domain glossary, first ADR, red→green test observed |
+| **triage** | raw intake — an idea, a bug report — becomes a work item with an agent-ready brief, duplicates linked, routed onward |
 | **discover** | business-first interview → `functional-analysis.md` |
 | **criteria** | observable, stable-ID acceptance criteria → `acceptance-criteria.md` |
-| **plan** | technical interview → `implementation-plan.md` with bounded, verifiable steps |
-| **implement / fix** | the plan executed step by step, or the smallest safe bug fix — root cause first |
+| **plan** | technical interview → `implementation-plan.md` with bounded, verifiable steps — external APIs verified against their docs, sources recorded |
+| **implement / fix** | the plan executed step by step, or the smallest safe bug fix — root cause first, researched when it crosses the repo boundary |
 | **verify** | every criterion checked against the *real* product, with evidence → `verification-report.md` |
 | **change** | spec delta interviewed, **all** documents updated in one approved pass → `change-log.md` |
-| **loop** | repeat-until-verified work with subagents and receipts (below) |
 | **architecture / docs / help** | deepening review, doc alignment, answers |
+| **commit / pr** | Conventional Commits and English PRs, work item linked, always gated |
+| **handoff** | session state packaged outside the repo — decisions, evidence, next move — so a fresh session resumes exactly there |
 
 Every route follows one skeleton — what to do, what **Never** to do, and a **Done when**
 checklist — enforced by the test suite, so the discipline survives refactors.
 
-## Loops: repeat until *proven*
-
-A loop is four decisions — **GOAL** (what done looks like), **PROOF** (how a pass proves
-it), **SCOPE** (what it may touch), **STOP** (when to quit) — everything else is a sane
-default. Each pass: *observe → one bounded action → independent verify → receipt →
-repeat or stop.*
-
-```text
-.oris-flow/loops/{slug}/
-  loop.md        the approved contract: goal, scope, roles, limits, models
-  prompts/       one editable file per role — the next pass obeys your edits
-  receipts/      one compact evidence record per pass
-  context.md  proposals/  history/
-```
-
-- **Two roles by default** — executor acts, verifier checks with evidence. Doctor
-  (multi-phase stop logic) and debriefer (learns across passes) are opt-in.
-- **Prompts are yours** — plain markdown files; edit them mid-run and the loop adapts.
-  With `improve.mode: auto` the debriefer tunes them itself (old versions archived);
-  scope and limits always require your approval.
-- **No false victories** — an exhausted limit, a missing tool, or an unverifiable claim
-  is never "success". Progress is counted only when the verifier confirms it.
-- **Cross-platform** — Cursor and Claude Code continue the same chat via stop hooks;
-  Codex/CI runs headless: `npx oris-skills loop run --loop <slug> --agent codex|claude`.
-  Copilot and every other agent get the full flow via prompt pointers; point any
-  file-reading agent at `~/.oris/oris-flow.md` and it is in.
-
-Try it safely in three minutes — the demo touches only its own sandbox folder:
-
-```bash
-npx oris-skills loop demo                       # 1. create the tutorial loop
-npx oris-skills loop dry-run --loop oris-demo   # 2. preview the exact pass — runs nothing
-npx oris-skills loop chat --action start --loop oris-demo   # 3. arm it, end your turn
-```
-
-Stop anything, anytime: `npx oris-skills loop chat --action stop`.
-
 ## Tuning
 
 Settings live in `.oris-flow/settings.json` (`/oris-flow` → Setup): document language
-(`artifactLanguage`, default `en`) and `responseStyle` (`standard`/`caveman`, where
-caveman shrinks chat to maximum token density while documents and safety gates stay
-complete). Chat language is deduced from your messages, not configured.
+(`artifactLanguage`, default `en`), `responseStyle` (`standard`/`caveman`, where caveman
+shrinks chat to maximum token density while documents and safety gates stay complete),
+`tasksRoot`, and whether `.oris-flow/` is committed or gitignored. Chat language is
+deduced from your messages, not configured.
 
 ## Repository layout
 
 | Path | Purpose |
 |------|---------|
-| `skills/oris-flow/` | the one skill: router (`SKILL.md`), route references, loop prompt templates |
-| `references/` | shared contracts (conventions, loop contract, doc policy) and JSON schemas |
-| `agents/` | canonical subagent definitions (platform adapters generated at install) |
-| `scripts/` | Node CLI, loop runtime, installer, tests |
+| `skills/oris-flow/` | the one skill: router (`SKILL.md`) + route references |
+| `references/` | shared contracts (conventions, doc-policy, devops, research, settings) and JSON schemas |
+| `scripts/` | Node CLI, repository scanner, installer, tests |
 | `docs/` | architecture, user guide, maintainer guide |
 
 ## Maintainers
 
 ```bash
 npm test               # cross-platform Node test suite (includes the skill-style gate)
-npm run verify:loop    # end-to-end stop-hook simulation (cursor + claude)
 ```
 
 Node.js 20+. License: MIT.

package/docs/architecture.md

@@ -5,10 +5,9 @@ Read this before explaining or changing the project.
 ## Shape
 
 ```text
-skills/oris-flow/   the ONE user-facing skill: SKILL.md routes; references/ hold every route (setup…loop); templates/ hold the loop role prompts
-references/         shared contracts (conventions, loop-contract, settings, repo-map, doc-policy, clean-code-checklist) + JSON schemas
-agents/             canonical loop-role definitions (internal); never installed into user agent homes — roles reach subagents via each loop's prompts/<role>.md
-scripts/            Node CLI (oris-skills.mjs), loop runtime, installer, tests
+skills/oris-flow/   the ONE user-facing skill: SKILL.md routes; references/ hold every route (setup…help)
+references/         shared contracts (conventions, doc-policy, devops, research, settings) + JSON schemas
+scripts/            Node CLI (oris-skills.mjs), repository scanner, installer, tests
 docs/               this file, user-guide, maintainer-guide, distribution
 ```
 
@@ -16,13 +15,18 @@ docs/               this file, user-guide, maintainer-guide, distribution
 
 - ONE source of truth per fact: contracts live in `references/`, skills point at them.
 - Skills use leading words (READ / ASK / NEVER / IF) and stay short; shared rules live in `references/conventions.md`.
-- Everything repeatable lives in the target project under `.oris-flow/`; the bundle at `~/.oris/oris-skills/` owns scripts and templates.
-- Oris never dirties the project: task documents default to `.oris-flow/tasks/` (`setup.tasksRoot` in the manifest; legacy `docs/tasks` supported).
-- Loop prompts are per-loop editable files (`prompts/*.md`), never hardcoded in scripts.
+- In target repositories, durable project facts live in `AGENTS.md` — the file every
+  agent already loads; Oris never builds a parallel knowledge store.
+- Oris never dirties the project: task documents default to `.oris-flow/tasks/`
+  (`orisFlow.tasksRoot` in `.oris-flow/settings.json`; legacy `docs/tasks` supported).
+- Evidence discipline crosses the repo boundary via `references/research.md`: external
+  claims are verified against current official docs at pinned versions, sources recorded.
 
 ## Runtime
 
-- `/oris-flow` routes; each route reference owns its gates.
-- The repo map is SHA-anchored: `flow scan --check` compares `headSha` to HEAD; only touched areas are refreshed; write-back is silent and never blocks work.
-- Loop triggers: Cursor stop hook + Claude Stop hook (shared `scripts/loop/oris-loop-stop.mjs`, `--platform` switch), headless `loop run` for Codex/CI.
-- State machine: `.oris-flow/runtime/chat-active.json`, managed only by `npx oris-skills loop chat`.
+- `/oris-flow` is user-invoked only (`disable-model-invocation: true`); once entered,
+  each route reference owns its gates.
+- `npx oris-skills flow scan` is a one-shot detector feeding the setup route: it reports
+  project type, stacks, commands, and areas, and writes nothing.
+- `npx oris-skills flow version-control` applies the settings `versionControl` choice
+  (`.oris-flow/` committed or gitignored).

package/docs/distribution.md

@@ -13,19 +13,19 @@ The installer detects Cursor / Claude Code / Codex from `~/.cursor`, `~/.claude`
 ## Installed assets
 
 ```text
-~/.oris/oris-skills/        bundle: scripts, skills, references, agents, docs
+~/.oris/oris-skills/        bundle: scripts, skills, references, docs
 ~/.cursor/skills/<name>/    Cursor skills (marker-managed)
 ~/.claude/skills/<name>/    Claude Code skills (marker-managed)
 ~/.codex/prompts/<name>.md  Codex prompts pointing to the bundled SKILL.md
 ```
 
-Project assets live only in each repository's `.oris-flow/` (adapter, settings, loops, runtime) plus thin hook wrappers in `.cursor/hooks/` and `.claude/hooks/` written by `npx oris-skills loop bootstrap`.
+Project assets live only in each repository's `.oris-flow/` (settings, task docs).
 
 ## Uninstall / reinstall
 
 ```bash
 npx oris-skills uninstall --dry-run   # preview
-npx oris-skills uninstall             # removes Oris-owned paths incl. legacy ~/.cursor locations and pre-2.2.1 loop agent adapters (~/.cursor|.claude|.codex/agents/oris-*)
+npx oris-skills uninstall             # removes only Oris-owned paths (bundle, skills, prompts, pointer, MCP seed)
 npx oris-skills reinstall
 ```
 

package/docs/maintainer-guide.md

@@ -11,9 +11,10 @@ Use when improving Oris Skills itself. Keep changes tiny; update the canonical f
 | Routing | `skills/oris-flow/SKILL.md` (route table) |
 | Shared interaction rules | `references/conventions.md` |
 | Task doc standards | `references/doc-policy.md` ({task} slug, per-doc ownership) |
-| Loop behavior | `references/loop-contract.md`, `skills/oris-flow/references/loop*.md` |
-| Loop prompt templates | `skills/oris-flow/templates/` |
-| Loop runtime | `scripts/loop/` |
+| Research discipline | `references/research.md` |
+| Settings contract | `references/settings.md` + `references/settings.schema.json` |
+| DevOps provider | `references/devops.md` + `references/devops.schema.json` |
+| Repository scanner | `scripts/flow/oris-flow-scan.mjs` |
 | Install lifecycle | `scripts/oris-skills.mjs`, `scripts/install/` |
 | Tests | `scripts/tests/` |
 
@@ -21,7 +22,6 @@ Use when improving Oris Skills itself. Keep changes tiny; update the canonical f
 
 ```bash
 npm test
-npm run verify:loop
 ```
 
 ## Release

package/docs/user-guide.md

@@ -6,32 +6,24 @@ Install once, remember one command:
 npx oris-skills@latest install     # detects Cursor / Claude Code / Codex / Copilot (VS Code)
 ```
 
-Then type **`/oris-flow`** in your agent chat. It routes your request or shows a short menu (setup, new project, discovery, criteria, plan, implement/fix, verify, spec change, loop, architecture review, docs, help). On Codex use the installed `/oris-flow` prompt; on Copilot Chat use `/oris-flow` too (enable the VS Code setting `chat.promptFiles` once). Any other agent: tell it to read `~/.oris/oris-flow.md`.
+Then type **`/oris-flow`** in your agent chat. It routes your request or shows a short menu (setup, new project, triage, discovery, criteria, plan, implement/fix, verify, spec change, architecture review, docs, commit, pull request, handoff, help). The skill never triggers itself — you invoke it. On Codex use the installed `/oris-flow` prompt; on Copilot Chat use `/oris-flow` too (enable the VS Code setting `chat.promptFiles` once). Any other agent: tell it to read `~/.oris/oris-flow.md`.
 
-The flow in one line: **discover → criteria → plan → implement → verify**, with `fix` for bugs, `change` when the spec changes mid-flight (it updates all task docs together and logs `CH-xxx` history), and `loop` for work that must repeat until verified. `new` bootstraps an AI-driven project from scratch; `architecture` maps deepening/refactor opportunities. Task documents live in `.oris-flow/tasks/` by default — your project's own docs stay untouched.
+The flow in one line: **discover → criteria → plan → implement → verify**, with `fix` for bugs and `change` when the spec changes mid-flight (it updates all task docs together and logs `CH-xxx` history). `new` bootstraps an AI-driven project from scratch; `architecture` maps deepening/refactor opportunities. `triage` turns raw ideas and bug reports into work items on your DevOps board before the flow starts; `handoff` packages a session's state — decisions, evidence, next move — so a fresh session resumes exactly where this one stopped. Task documents live in `.oris-flow/tasks/` by default — your project's own docs stay untouched.
 
-## Loops in short
+## What setup leaves in your repo
 
-A loop repeats: one bounded action → independent verification → receipt → continue or stop.
-Building one takes four decisions — goal, proof, scope, stop — everything else defaults.
+- **`AGENTS.md`** — the durable facts every agent loads: commands, structure pointers,
+  decisions. Setup detects them (`flow scan`), you confirm them, the file records them.
+- **`.oris-flow/settings.json`** — preferences: document language, chat verbosity,
+  tasks root, and whether `.oris-flow/` is committed or gitignored.
 
-Learn it safely:
+Nothing else. No manifests, no caches, no state files.
 
-```bash
-npx oris-skills loop demo                      # sandboxed tutorial loop
-npx oris-skills loop dry-run --loop oris-demo  # preview, nothing runs
-npx oris-skills loop chat --action start --loop oris-demo   # arm, then end the chat turn
-```
-
-Control it:
-
-```bash
-npx oris-skills loop list            # what exists
-npx oris-skills loop chat --action status
-npx oris-skills loop chat --action stop
-```
+## Research discipline
 
-Tune it: edit the files in `.oris-flow/loops/{slug}/prompts/` — the next pass obeys them. With `improve.mode: auto` in `loop.md`, the loop tunes those prompts itself and archives old versions in `history/`.
+When a fix or plan touches a third-party library or API, the flow checks current
+official docs at your pinned versions instead of guessing, and records the sources in
+the task document. Say "code only" or "check online" to steer it either way.
 
 ## Install lifecycle
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oris-skills",
-  "version": "2.2.3",
-  "description": "Oris Skills: one entry point (/oris-flow), guided discovery-to-implementation flow, and self-tuning verified loops for Cursor, Claude Code, and Codex.",
+  "version": "3.0.2",
+  "description": "Oris Skills: one entry point (/oris-flow) and a guided discovery-to-implementation flow for Cursor, Claude Code, and Codex.",
   "license": "MIT",
   "author": "Davide Baldassarre",
   "type": "module",
@@ -12,7 +12,6 @@
     "scripts",
     "skills",
     "references",
-    "agents",
     "docs",
     ".cursor-plugin",
     "README.md",
@@ -24,7 +23,6 @@
     "skills",
     "agent",
     "workflow",
-    "loop",
     "cursor",
     "claude",
     "codex"
@@ -39,8 +37,7 @@
   "scripts": {
     "test": "node scripts/tests/run-all-tests.mjs",
     "scan": "node scripts/flow/oris-flow-scan.mjs --json",
-    "install:dry-run": "node scripts/install/install-user-skills.mjs --dry-run",
-    "verify:loop": "node scripts/loop/oris-loop-verify.mjs --temp"
+    "install:dry-run": "node scripts/install/install-user-skills.mjs --dry-run"
   },
   "engines": {
     "node": ">=20"

package/references/clean-code-checklist.md

@@ -1,6 +1,6 @@
 # Clean Code Checklist
 
-Used by `oris-flow-implement` and `oris-flow-fix` while closing work: clean what YOU introduced, in the files you touched. Investigate before concluding; absence in one file is not proof of dead code.
+Used by `skills/oris-flow/references/implement.md` and `skills/oris-flow/references/fix.md` while closing work: clean what YOU introduced, in the files you touched. Investigate before concluding; absence in one file is not proof of dead code.
 
 ## Check, in the touched scope only
 
@@ -15,6 +15,6 @@ Used by `oris-flow-implement` and `oris-flow-fix` while closing work: clean what
 
 Before removing anything: search references and call sites (including DI registration, reflection, dynamic imports, routing, code generation, framework conventions). Tests, config, or registration may still require the symbol.
 
-## Never here
+## Never
 
 Bug fixes (→ `skills/oris-flow/references/fix.md`), architectural redesign, cross-feature refactors, DevOps, drive-by cleanup of code you did not touch.

package/references/conventions.md

@@ -10,9 +10,9 @@ Shared rules for every Oris skill. Skills reference this file instead of repeati
 
 ## Silence (the fluidity contract)
 
-The user sees questions, answers, results, and gates — NEVER the machinery. Reading maps,
-references, or settings, checking freshness, writing back facts, loading a route: all
-SILENT. Never say "let me read…", "I'm checking the manifest…", "updating the map…".
+The user sees questions, answers, results, and gates — NEVER the machinery. Reading
+`AGENTS.md`, references, or settings, writing back facts, loading a route: all SILENT.
+Never say "let me read…", "I'm checking the settings…", "updating AGENTS.md…".
 One announcement exists: the route entry line ("Entering <route>: <why>"). Everything
 else the user hears is the work itself.
 
@@ -37,16 +37,29 @@ The `oris-skills` CLI is NOT installed globally. ALWAYS invoke it as `npx oris-s
   MORE options → split into a two-level question (category first) or use the deliberate
   text fallback above.
 - ONE question per turn. Recommended answer FIRST.
+- VISIBILITY: assume the user sees ONLY what the question tool itself renders — chat text
+  emitted in the same turn as the tool call can be hidden by the platform UI. Therefore
+  everything the answer depends on rides INSIDE the call: the recap/context in the
+  `question` text (compact — counted facts, not prose), each option's meaning and
+  consequence in its description. NEVER put a recap or summary in chat text and then call
+  the question tool in the same turn — the user may see the bare question and nothing else.
 - ALWAYS include, in the user's language:
-  - `Explain the options` / `Spiega le opzioni` — explain, then re-ask the same question.
+  - `Explain the options` / `Spiega le opzioni` — when picked, RE-ASK the same question
+    WITH the explanations embedded in the call itself: every option's description states
+    what it means and what happens if chosen; the `question` text may add one context
+    line. Re-asking the question unchanged, or explaining only in chat text before the
+    call, is a failure — the user reported seeing the bare question again. In text-fallback
+    menus: explanations first, then the full lettered list again, in ONE message.
   - During interviews: `Enough questions — proceed` / `Basta domande — procedi` (early exit → go to the generation gate; NOT approval to write).
 - NEVER ask what the workspace, docs, code, or setup map already answer. Explore first.
 
 ## Generation gates
 
 - Standard labels, localized: `Generate the document` / `Genera il documento`, `Approve document` / `Approva documento`, `Continue the interview` / `Continua l'intervista`, `Cancel` / `Annulla`.
-- NEVER write documents before the explicit gate choice. Exception: `oris-flow-criteria` writes first, then asks ONCE — the document is confirmed only on approval.
-- After a document is written: concise summary + contextual next-step menu. NEVER auto-start the next phase.
+- NEVER write documents before the explicit gate choice. Exception: `skills/oris-flow/references/criteria.md` writes first, then asks ONCE — the document is confirmed only on approval.
+- After a document is written: concise summary + contextual next-step menu. The summary
+  rides inside the next-step question (`## Questions` VISIBILITY rule) — never as chat
+  text the tool call can hide. NEVER auto-start the next phase.
 
 ## Language
 
@@ -72,21 +85,28 @@ READ `orisFlow.responseStyle` from `.oris-flow/settings.json` (`standard` | `cav
 > Danger, error, secret → caveman speak clear, full sentence. Safety never shrink.
 
 SCOPE: chat replies, recaps, status lines. NEVER compressed: generated documents, gate
-labels, receipts, error reports, and anything another session must read cold.
-
-## Setup map & write-back
-
-- WHEN `.oris-flow/manifest.json` exists: read it + only the relevant `.oris-flow/maps/**` sections BEFORE scanning broadly.
-- FRESHNESS is one call: `npx oris-skills flow scan --repository-root <repo> --check` — compares the manifest's `headSha` anchor to the current HEAD. `fresh: true` → trust the map, zero extra reads. Stale → refresh ONLY the areas the `changedFiles` list touches (`--area <section>`), in place; full rescans belong to setup.
-- WRITE BACK what the flow proved — silently, at natural pauses (after verification, at close; never mid-move): a command observed green → mark it `confirmed`; a map fact the repo contradicts → correct that section in place. Small scoped edits only.
-- Write-back must NEVER slow the work: nothing durable learned → write nothing; batch at the end of the turn; never block an edit or a verification on map bookkeeping; never full-rescan mid-task.
-- VERIFY stale or high-risk map facts against the repository before consequential actions.
+labels, error reports, and anything another session must read cold.
+
+## Project facts
+
+- `AGENTS.md` (or the agent file that exists — `CLAUDE.md`) is the ONE durable store of
+  project facts: commands, structure pointers, decisions. READ it before scanning broadly;
+  never build a parallel store.
+- VERIFY high-risk facts against the repository before consequential actions — agent
+  files describe intent, the code is the authority.
+- WRITE BACK what the flow proved — silently, at natural pauses (after verification, at
+  close; never mid-move): a command observed green and missing from `AGENTS.md` → add it;
+  a recorded fact the repo contradicts → correct it in place. Small scoped edits only;
+  nothing durable learned → write nothing.
+- Preferences (`tasksRoot`, version control for `.oris-flow/`, `responseStyle`,
+  `artifactLanguage`) live in `.oris-flow/settings.json` (`references/settings.md`),
+  never in agent files.
 
 ## Gates
 
 - NEVER write documents, code, settings, Git, or DevOps without explicit user confirmation in this flow.
 - The skill that performs the action owns its confirmation gate; routing never grants it.
-- NEVER store secrets in `.oris-flow/**`, docs, receipts, or logs. Mask passwords as `***`.
+- NEVER store secrets in `.oris-flow/**`, docs, or logs. Mask passwords as `***`.
 
 ## Subagents
 

package/references/doc-policy.md

@@ -6,9 +6,9 @@ Applies whenever an Oris skill writes or updates task documentation. Project-agn
 
 Oris keeps its artifacts in its own folder — it never dirties the project's docs by default.
 
-- RESOLVE: `setup.tasksRoot` from `.oris-flow/manifest.json`; DEFAULT `.oris-flow/tasks` when missing.
-- LEGACY: a repo with populated `docs/tasks/` and no manifest value keeps `docs/tasks` — setup records the choice once.
-- NEVER mix roots in one repo; the manifest value is the single truth.
+- RESOLVE: `orisFlow.tasksRoot` from `.oris-flow/settings.json`; DEFAULT `.oris-flow/tasks` when missing.
+- LEGACY: a repo with populated `docs/tasks/` and no settings value keeps `docs/tasks` — setup records the choice once.
+- NEVER mix roots in one repo; the settings value is the single truth.
 
 ## Task folder
 
@@ -34,7 +34,7 @@ NEVER split one feature's docs across unrelated directories.
 
 1. Language: documents in `artifactLanguage` (default `en`); chat/UI language is deduced from context. Skill instructions and code stay English.
 2. Steps are independent: any document may be created without the previous one. State the missing source once, use the strongest confirmed source, record the gap in the document ("not available" localized). Never block on a missing predecessor.
-3. INSPECT the task folder + setup map before asking the user or writing.
+3. INSPECT the task folder + `AGENTS.md` before asking the user or writing.
 4. Every document ends with a change-history table: date | source | change | reason. Later changes rewrite the affected sections AND add a history row — no inline "changed!" notes.
 5. Facts only from confirmed sources; open questions go to open points. NEVER invent behavior, labels, or commands.
-6. Verification artifacts (test plans, specs) are technical follow-ups owned by loops or the project's own conventions — they never replace `acceptance-criteria.md`.
+6. Verification artifacts (test plans, specs) are technical follow-ups owned by the project's own conventions — they never replace `acceptance-criteria.md`.

package/references/research.md

@@ -0,0 +1,45 @@
+# Oris Research
+
+Evidence discipline beyond the repository: when a route touches third-party behavior,
+CHECK the world instead of guessing. Applied by fix, plan, and implement — never by
+discover (business interviews stay non-technical).
+
+## When to search
+
+SEARCH (web, official docs, the platform's docs tools) when the problem crosses the
+repository boundary:
+
+- behavior or API of a third-party library, framework, or service;
+- an error message produced by an external tool, not by project code;
+- a "known issue" smell — the local code cannot explain the behavior;
+- a standard workaround or reference implementation likely exists for exactly this.
+
+STAY code-only when the repository fully explains the behavior — internal logic,
+project conventions, local data. Searching there is noise.
+
+The user's explicit instruction wins in BOTH directions: "code only" → no search;
+"check online" → search even when the smell is weak.
+
+## How to search
+
+1. OFFICIAL docs of the exact dependency FIRST; community sources (issues, answers,
+   posts) second and marked as such.
+2. PIN versions: read the versions the repo actually uses (lockfile, project file) and
+   match findings to them — an answer for another major version is not evidence.
+3. RECORD sources in the task document under `## Sources` — link + one line on what it
+   settled. No sources recorded → the research never happened.
+4. External claims stay `inferred` until verified against the repo or the running
+   product; state them as possibilities, never as facts.
+
+## Never
+
+- State external behavior as fact from memory — memory of an API is a guess.
+- Apply a workaround without recording where it came from and why it fits this version.
+- Interrupt a business interview (discover) with research — it belongs to the
+  technical routes.
+
+## Done when
+
+- [ ] Searched exactly when the boundary rule says so — no reflex searches, no blind guesses.
+- [ ] Findings version-matched to the repo; sources recorded in the task document.
+- [ ] Unverified external claims marked `inferred`, never asserted.

package/references/settings.md

@@ -1,24 +1,30 @@
 # Oris Settings
 
-Per-project preferences. Path: `.oris-flow/settings.json`. Small and non-secret —
-chat verbosity and document language, nothing else. Missing file → defaults below.
-Created/edited via `/oris-flow` → Setup, or by hand.
+Per-project preferences. Path: `.oris-flow/settings.json`. Small and non-secret.
+Missing file → defaults below. Created/edited via `/oris-flow` → Setup, or by hand.
 
 ## Shape (v1)
 
 ```json
 {
   "version": 1,
-  "orisFlow": { "responseStyle": "standard", "artifactLanguage": "en" }
+  "orisFlow": {
+    "responseStyle": "standard",
+    "artifactLanguage": "en",
+    "tasksRoot": ".oris-flow/tasks",
+    "versionControl": "commit"
+  }
 }
 ```
 
 - `responseStyle` → chat verbosity (`standard` | `caveman`, default `standard`). Caveman = maximum token density in chat; contract in `references/conventions.md` `## Response style`. Documents and gates are never compressed.
 - `artifactLanguage` → language for generated documents (ISO code, default `en`). Chat/UI language is NOT configured here — it is deduced from the conversation.
+- `tasksRoot` → where task documents live (default `.oris-flow/tasks`; legacy `docs/tasks` supported when a team already treats task docs as project docs).
+- `versionControl` → whether `.oris-flow/` is committed (`commit`, team default) or ignored (`gitignore`, personal). Applied via `npx oris-skills flow version-control --mode <choice>`.
 
 ## Rules
 
 1. READ settings before the first workflow decision; missing/invalid → defaults above.
 2. Current user instructions override settings for the turn.
-3. Oris stores no credentials. Test/CI secrets belong to each project's own tooling — never Oris files, docs, loop state, receipts, or logs.
+3. Oris stores no credentials. Test/CI secrets belong to each project's own tooling — never Oris files, docs, or logs.
 4. CONFIRM before writing settings. Update via `/oris-flow` → Setup.

package/references/settings.schema.json

@@ -23,6 +23,16 @@
           "type": "string",
           "minLength": 2,
           "description": "Language for generated documents (ISO code, e.g. en, it). Default en. Chat language is deduced from the conversation, not configured here."
+        },
+        "tasksRoot": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Repository-relative root for task documents. Default .oris-flow/tasks; legacy docs/tasks supported."
+        },
+        "versionControl": {
+          "type": "string",
+          "enum": ["commit", "gitignore"],
+          "description": "Whether .oris-flow/ is committed (team default) or gitignored (personal). Default commit."
         }
       }
     }