oris-skills 2.1.0 → 2.2.1

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.1.0",
+  "version": "2.2.1",
   "author": {
     "name": "Davide Baldassarre"
   },
@@ -17,20 +17,6 @@
     "codex"
   ],
   "skills": [
-    "./skills/oris-flow",
-    "./skills/oris-flow-setup",
-    "./skills/oris-flow-new",
-    "./skills/oris-flow-discover",
-    "./skills/oris-flow-criteria",
-    "./skills/oris-flow-plan",
-    "./skills/oris-flow-implement",
-    "./skills/oris-flow-fix",
-    "./skills/oris-flow-verify",
-    "./skills/oris-flow-change",
-    "./skills/oris-flow-docs",
-    "./skills/oris-flow-architecture",
-    "./skills/oris-flow-merge",
-    "./skills/oris-loop",
-    "./skills/oris-help"
+    "./skills/oris-flow"
   ]
 }

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## 2.1.0 - 2026-07-05
+## 2.2.1 - 2026-07-07
+
+- **Loop roles are invisible to users**: the installer no longer writes `oris-loop-{executor,verifier,doctor,debriefer}` into `~/.cursor/agents/`, `~/.claude/agents/`, or `~/.codex/agents/` — they showed up as manually invocable subagents, but the loop orchestrator never spawns them by name (it passes each loop's `prompts/<role>.md` to a generic subagent). `agents/` stays in the repo as the canonical role definitions for development. Uninstall (and therefore reinstall/upgrade) now also removes adapters left behind by earlier versions.
+
+## 2.2.0 - 2026-07-07
+
+- **One skill**: users see only `/oris-flow`. Every former skill (setup, new, discover, criteria, plan, implement, fix, verify, change, architecture, merge, docs, help, loop) is now a route reference inside `skills/oris-flow/references/`; the router reads the intent, picks ONE route, and applies its reference in the same chat. Loop prompt templates moved to `skills/oris-flow/templates/`.
+- **Full skill revision, one skeleton**: essence paragraph, leading-word moves (READ / ASK / WRITE / NEVER), an explicit `## Never` block, and a `## Done when` checklist in every route, plus a silence contract — machinery (map reads, freshness checks, write-back) is never narrated. The router's description carries the whole trigger vocabulary so the model auto-enters the flow from plain chat.
+- **Routing hardened**: new `Precedence` section settles the ambiguous calls explicitly (rethink beats build; change vs discover; fix vs implement; verify once vs loop; new vs setup) — one menu question maximum, then enter.
+- **Loops are four decisions**: the craft interview shrank from nine questions to four (GOAL, PROOF, SCOPE, STOP); roles, limits, models, and improve mode are stated defaults, changed only when the user objects or the work demands it.
+- **SHA-anchored maps + write-back**: the scan records `headSha`; `npx oris-skills flow scan --check` answers "is the map fresh?" in one cheap call (SHA compare + changed-file list, zero reads when fresh). Skills refresh only the touched areas in place and write proved facts back (`confirmed` commands, corrected sections) silently at natural pauses — write-back never blocks or slows the work.
+- **Caveman response style**: `orisFlow.responseStyle: "caveman"` in `~/.oris/settings.json` switches chat to maximum token density (answer first, no warm-up, fragments fine); generated documents, gate labels, receipts, and error reports are never compressed. Set via `/oris-flow` → Setup → language & profiles.
+- **Every agent, honestly**: installer now targets GitHub Copilot too (user prompt file in the VS Code profile — enable `chat.promptFiles` once, then `/oris-flow`), and writes a universal pointer at `~/.oris/oris-flow.md` so ANY file-reading agent can join with one sentence. Support matrix: in-chat loop hooks on Cursor and Claude Code; headless loops via Codex/Claude CLIs; the full flow everywhere.
+- **Leaner core**: the merge-conflict route was removed — agents handle it natively and it never belonged to the flow discipline. Loop economy tightened: default limit is now 10 passes, and the craft guidance states when a loop pays for itself (~3 expected passes; below that, implement or verify directly). Canonical subagents aligned with the hardened templates: executors stop instead of half-doing oversized actions, verifiers run checks before judging, debriefers may never weaken the verification bar.
+- **Style is enforced, not hoped for**: new `scripts/tests/test-skill-style.mjs` checks front-matter naming, trigger-bearing descriptions, Never + Done when blocks, a line budget, and that every routing handle resolves to a real bundle file.
 
 - **Harness independence**: task documents default to `.oris-flow/tasks/{task}/` (`setup.tasksRoot` in the manifest) — Oris no longer writes into the project's `docs/`; repos already using `docs/tasks` keep it via a recorded setup choice.
 - **Adaptive setup**: the scan detects `projectType` (webapp/api/library/cli/monorepo), derives build/test commands for .NET, Python, Go, and Rust (marked `inferred` until confirmed), walks breadth-first with a `truncated` flag, and honors `--area` for partial refreshes. Refresh merges instead of overwriting: `confirmed` sections, commands, and decisions survive; missing evidence marks them stale.

package/README.md

@@ -1,67 +1,114 @@
 # Oris Skills
 
-One entry point, a guided software flow, and self-tuning verified loops — for **Cursor**, **Claude Code**, and **Codex**.
+**One command. A disciplined software flow. Loops that verify themselves.**
+For Cursor, Claude Code, Codex, GitHub Copilot — and any agent that can read a file.
 
 ```bash
 npx oris-skills@latest install
 ```
 
-The installer detects your agents (`~/.cursor`, `~/.claude`, `~/.codex`) or takes `--agents cursor,claude,codex`. Reload your agent, then type **`/oris-flow`** — the only command you need to remember.
+Reload your agent, then type **`/oris-flow`**. That is the entire user manual.
 
-## What you get
+## The idea
 
-**`/oris-flow`** routes any software-flow request to the right skill in the same chat:
+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:
 
-| Route | Purpose |
+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.
+
+## 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**.
+
+```text
+        idea ──► discover ──► criteria ──► plan ──► implement ──► verify
+                    │                                    ▲            │
+                    └── change (spec moved) ─────────────┘        fix ◄┘ (red)
+```
+
+| Route | You get |
 |-------|---------|
-| setup | map the repository into `.oris-flow/` so agents stop re-scanning |
-| discover | business-first interview → `functional-analysis.md` |
-| criteria | verifiable acceptance criteria → `acceptance-criteria.md` |
-| plan | technical interview → `implementation-plan.md` |
-| implement / fix | execute the plan, or the smallest safe bug fix |
-| verify | check every acceptance criterion against the real product, once → `verification-report.md` |
-| change | spec changed mid-flight: delta interview, all docs updated together → `change-log.md` (CH-xxx) |
-| loop | repeat work until verified, with subagents and receipts |
-| docs / help | keep task docs aligned; explain Oris |
-
-**Oris loops** run the cycle *observe → one bounded action → independent verify → record → repeat/stop* with two default roles (executor + verifier) — doctor and debriefer are opt-in — each driven by **an editable prompt file**:
+| **setup** | the repo mapped into `.oris-flow/` (type, commands, structure) so agents stop re-scanning; AI-readiness check |
+| **new** | a greenfield project born agent-native: sparse `AGENTS.md`, domain glossary, first ADR, red→green test observed |
+| **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 |
+| **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 |
+
+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        contract: goal, scope, roles, limits, per-role models, improve mode
-  prompts/       executor.md verifier.md (+ orchestrator/doctor/debriefer when opted in)  ← edit freely
-  context.md  receipts/  proposals/  history/
+  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/
 ```
 
-- **Per-role models** — `models:` in `loop.md`: `inherit` (session model), an adapter alias, or a platform model id.
-- **Self-tuning** — `improve.mode: auto` lets the debriefer rewrite the prompt files between passes (old versions archived in `history/`); scope and limits always require your approval.
-- **Cross-platform triggers** — Cursor stop hook, Claude Code Stop hook (same chat continues automatically), or `npx oris-skills loop run --agent codex|claude` for headless/CI where each role is a separate CLI process.
+- **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 a loop in 3 minutes
+Try it safely in three minutes — the demo touches only its own sandbox folder:
 
 ```bash
-npx oris-skills loop demo                    # creates a sandboxed tutorial loop
-npx oris-skills loop dry-run --loop oris-demo  # preview the exact pass message — runs nothing
-npx oris-skills loop chat --action start --loop oris-demo   # then end the chat turn; the hook does the rest
+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 anytime: `npx oris-skills loop chat --action stop`. Self-check the runtime: `npx oris-skills loop verify --temp`.
+Stop anything, anytime: `npx oris-skills loop chat --action stop`.
+
+## Tuning
+
+Settings live in `~/.oris/settings.json` (`/oris-flow` → Setup → language & profiles):
+chat and document language (`en`/`it`), test profiles, and `responseStyle: "caveman"` —
+chat shrinks to maximum token density while documents and safety gates stay complete.
 
 ## Repository layout
 
 | Path | Purpose |
 |------|---------|
-| `skills/` | the 12 Oris skills (`SKILL.md` each) |
-| `skills/oris-loop/templates/` | role prompt templates copied into new loops |
-| `references/` | shared contracts and JSON schemas |
-| `agents/` | canonical subagent definitions (Cursor/Claude/Codex adapters generated) |
+| `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 |
 | `docs/` | architecture, user guide, maintainer guide |
 
 ## Maintainers
 
 ```bash
-npm test               # cross-platform Node test suite
+npm test               # cross-platform Node test suite (includes the skill-style gate)
 npm run verify:loop    # end-to-end stop-hook simulation (cursor + claude)
 ```
 

package/agents/oris-loop-debriefer.md

@@ -13,6 +13,7 @@ Rules:
 3. improve.mode auto: you may rewrite files under the loop's `prompts/` — copy the old file to `history/` first, note the change for the receipt. One improvement per debrief.
 4. improve.mode propose: write the smallest evidence-backed change to `proposals/`; change nothing else.
 5. NEVER touch loop.md scope, limits, permissions, or verification — always a proposal.
+   NEVER weaken verification to make passes green — fix the loop, not the bar.
 6. Keep the summary compact.
 
 Output:

package/agents/oris-loop-executor.md

@@ -10,12 +10,15 @@ Rules:
 
 1. Verify the task includes `ORIS LOOP ACTIVE`.
 2. Read only the loop definition, context, and files in declared scope.
-3. Perform exactly one bounded action.
+3. Perform exactly one bounded action. Re-read the fresh state of every file
+   you touch before editing it. The action proves bigger than bounded → stop
+   and return blocked with what you found; half-done work is worse than none.
 4. Preserve unrelated user work.
 5. Do not commit, push, deploy, write DevOps, send external messages, expose
    credentials, or edit `.oris-flow/runtime/**`.
 6. Return a compact result with changed files, claim, risk, and suggested
-   verifier check.
+   verifier check. claim = what changed + the exact command or observation
+   that proves it.
 
 Output:
 

package/agents/oris-loop-verifier.md

@@ -8,10 +8,11 @@ You are the Oris Loop verifier.
 
 Rules:
 
-1. Do not trust the executor claim without evidence.
+1. Do not trust the executor claim without evidence. Run the checks FIRST,
+   judge after — a claim you could not check is inconclusive, never pass.
 2. Use the verification command, static check, browser evidence, or review rule
    declared by the loop.
-3. Do not edit product files.
+3. Do not edit product files — you only observe, never fix.
 4. Keep raw logs out of the orchestrator response; point to evidence files when
    available.
 5. Report pass, fail, blocked, or inconclusive.

package/docs/architecture.md

@@ -5,11 +5,11 @@ Read this before explaining or changing the project.
 ## Shape
 
 ```text
-skills/       15 skills; oris-flow is the router, oris-loop the loop system
-references/   shared contracts (conventions, loop-contract, settings, repo-map, doc-policy, clean-code-checklist) + JSON schemas
-agents/       canonical subagent definitions; adapters generated per platform
-scripts/      Node CLI (oris-skills.mjs), loop runtime, installer, tests
-docs/         this file, user-guide, maintainer-guide, distribution
+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
+docs/               this file, user-guide, maintainer-guide, distribution
 ```
 
 ## Principles
@@ -22,6 +22,7 @@ docs/         this file, user-guide, maintainer-guide, distribution
 
 ## Runtime
 
-- `/oris-flow` routes; destination skills own their gates.
+- `/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`.

package/docs/distribution.md

@@ -26,7 +26,7 @@ Project assets live only in each repository's `.oris-flow/` (adapter, loops, run
 
 ```bash
 npx oris-skills uninstall --dry-run   # preview
-npx oris-skills uninstall             # removes Oris-owned paths incl. legacy ~/.cursor locations
+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 reinstall
 ```
 

package/docs/maintainer-guide.md

@@ -6,13 +6,13 @@ Use when improving Oris Skills itself. Keep changes tiny; update the canonical f
 
 | Change | Canonical place |
 |--------|-----------------|
-| User-facing explanation | `docs/user-guide.md`, `skills/oris-help/SKILL.md` |
+| User-facing explanation | `docs/user-guide.md`, `skills/oris-flow/references/help.md` |
 | Project structure | `docs/architecture.md` |
 | 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-loop/` |
-| Loop prompt templates | `skills/oris-loop/templates/` |
+| Loop behavior | `references/loop-contract.md`, `skills/oris-flow/references/loop*.md` |
+| Loop prompt templates | `skills/oris-flow/templates/` |
 | Loop runtime | `scripts/loop/` |
 | Install lifecycle | `scripts/oris-skills.mjs`, `scripts/install/` |
 | Tests | `scripts/tests/` |

package/docs/user-guide.md

@@ -3,16 +3,17 @@
 Install once, remember one command:
 
 ```bash
-npx oris-skills@latest install     # detects Cursor / Claude Code / Codex
+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, merge conflicts, docs, help). On Codex use the installed `/oris-flow` prompt.
+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`.
 
-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; `merge` resolves merge/rebase conflicts. 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, `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.
 
 ## Loops in short
 
 A loop repeats: one bounded action → independent verification → receipt → continue or stop.
+Building one takes four decisions — goal, proof, scope, stop — everything else defaults.
 
 Learn it safely:
 
@@ -41,4 +42,4 @@ npx oris-skills reinstall
 ```
 
 Uninstall removes only Oris-owned paths (including legacy locations); preview with `--dry-run`.
-Settings (language, test profiles): `~/.oris/settings.json`, edited via `/oris-flow` → Setup.
+Settings (language, test profiles, `responseStyle: caveman` for ultra-short chat): `~/.oris/settings.json`, edited via `/oris-flow` → Setup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Oris Skills: one entry point (/oris-flow), guided discovery-to-implementation flow, and self-tuning verified loops for Cursor, Claude Code, and Codex.",
   "license": "MIT",
   "author": "Davide Baldassarre",

package/references/clean-code-checklist.md

@@ -17,4 +17,4 @@ Before removing anything: search references and call sites (including DI registr
 
 ## Never here
 
-Bug fixes (→ `skills/oris-flow-fix/SKILL.md`), architectural redesign, cross-feature refactors, DevOps, drive-by cleanup of code you did not touch.
+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

@@ -8,9 +8,17 @@ Shared rules for every Oris skill. Skills reference this file instead of repeati
 - Installed: `~/.oris/oris-skills/`
 - Repo checkout: repository root.
 
+## 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…".
+One announcement exists: the route entry line ("Entering <route>: <why>"). Everything
+else the user hears is the work itself.
+
 ## Routing handles
 
-Name a destination skill by its file path (`skills/oris-flow-fix/SKILL.md`) — the one canonical handle. Never by slash command or prose nickname.
+ONE user-facing skill exists: `skills/oris-flow/SKILL.md` (/oris-flow — the router). Every destination is one of its references — name it by file path (`skills/oris-flow/references/fix.md`), the one canonical handle. Never by slash command or prose nickname. Routing means: read the reference file and apply it in the same chat.
 
 ## CLI commands
 
@@ -36,9 +44,27 @@ The `oris-skills` CLI is NOT installed globally. ALWAYS invoke it as `npx oris-s
 - READ `references/settings.md` (user settings: `~/.oris/settings.json`).
 - Chat + questions: `uiLanguage`. Generated documents: `artifactLanguage`. Default both: `en`.
 
-## Setup map
+## Response style
+
+READ `orisFlow.responseStyle` (`standard` | `caveman`, default `standard`).
+
+`caveman` = the user pays per token; chat goes maximum density. The contract, in its own voice:
+
+> Caveman speak short. Answer first. No warm-up, no "I will now…", no repeat of what user said.
+> One line beat three. Fragment fine. Code speak for itself.
+> Caveman brain still big: same exploration, same gates, same evidence — only words shrink.
+> Question still one per turn, labels still full. Recap = counted facts, no prose.
+> 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.
 
 ## Gates

package/references/loop-contract.md

@@ -33,7 +33,7 @@ approved: true           # set by the user's approval at craft — loop cannot s
 phases: [work]
 roles: [executor, verifier]   # default; opt in doctor and/or debriefer only when needed
 limits:
-  maxIterations: 25
+  maxIterations: 10
   maxNoProgress: 2       # consecutive passes without verified progress → blocked
   maxMinutes: 240
 models:                  # per-role: "inherit" | adapter alias | platform model id

package/references/repo-map.schema.json

@@ -32,6 +32,10 @@
       "type": "string",
       "format": "date-time"
     },
+    "headSha": {
+      "type": ["string", "null"],
+      "description": "Commit SHA the last scan was anchored to; null outside git. Freshness = headSha vs current HEAD."
+    },
     "mapVersion": {
       "type": "string",
       "minLength": 1

package/references/settings.md

@@ -8,7 +8,7 @@ The installer creates it when missing; it NEVER overwrites an existing file.
 ```json
 {
   "version": 1,
-  "orisFlow": { "uiLanguage": "en", "artifactLanguage": "en" },
+  "orisFlow": { "uiLanguage": "en", "artifactLanguage": "en", "responseStyle": "standard" },
   "defaultProfiles": { "testing": "default" },
   "profiles": {
     "default": {
@@ -23,6 +23,7 @@ The installer creates it when missing; it NEVER overwrites an existing file.
 
 - `uiLanguage` → chat, menus, question labels, recaps (`en` | `it`, default `en`).
 - `artifactLanguage` → generated documents (`en` | `it`, default `en`).
+- `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.
 - `profiles` → repository-neutral test logins/config. The repo adapter maps profile fields to roles.
 - `flags.allowDataMutation` → data mutation allowed ONLY with `environment: local` + loopback URLs + this flag true.
 

package/references/settings.schema.json

@@ -22,6 +22,11 @@
         "artifactLanguage": {
           "type": "string",
           "enum": ["it", "en"]
+        },
+        "responseStyle": {
+          "type": "string",
+          "enum": ["standard", "caveman"],
+          "description": "Chat verbosity: standard prose or caveman (maximum token density; documents and gates never compressed)."
         }
       }
     },

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import childProcess from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
@@ -63,6 +64,68 @@ function fail(message) {
   process.exit(1);
 }
 
+function git(root, args) {
+  try {
+    const output = childProcess.execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Commit SHA the scan anchors to; null outside git (the anchor is then unavailable, never an error). */
+export function gitHeadSha(root) {
+  return git(root, ["rev-parse", "HEAD"]);
+}
+
+/**
+ * Files changed since the anchored SHA: committed delta + working-tree changes,
+ * deduped. The map's own files (.oris-flow/**) never count — they describe the
+ * code, they are not the code.
+ */
+export function gitChangedFiles(root, sinceSha) {
+  const diff = git(root, ["diff", "--name-only", `${sinceSha}..HEAD`]);
+  const status = git(root, ["status", "--porcelain", "-uall"]);
+  if (diff === null && status === null) return null;
+  const changed = new Set();
+  const add = (file) => {
+    const clean = file.replace(/^"|"$/g, "");
+    if (clean && !clean.startsWith(".oris-flow/")) changed.add(clean);
+  };
+  for (const line of (diff ?? "").split(/\r?\n/)) if (line.trim()) add(line.trim());
+  for (const line of (status ?? "").split(/\r?\n/)) {
+    const file = line.slice(3).trim();
+    if (file) add(file.includes(" -> ") ? file.split(" -> ")[1] : file);
+  }
+  return [...changed].sort();
+}
+
+/**
+ * Freshness in one cheap call (the delta-scan anchor): compare the manifest's
+ * headSha with the current HEAD. Equal and clean → fresh, zero reads. Moved →
+ * the changed file list tells the caller which map areas to refresh in place.
+ */
+export function checkFreshness(repositoryRoot) {
+  const root = path.resolve(repositoryRoot);
+  const manifest = readJson(path.join(root, ...ORIS_FLOW_MANIFEST.split("/")));
+  if (!manifest) return { manifest: false, fresh: false, reason: "no manifest — run a full scan" };
+  const headSha = gitHeadSha(root);
+  const scannedSha = manifest.headSha ?? null;
+  if (!headSha || !scannedSha) {
+    return { manifest: true, fresh: false, reason: "no SHA anchor — refresh writes one", headSha, scannedSha, changedFiles: null };
+  }
+  const changedFiles = gitChangedFiles(root, scannedSha) ?? [];
+  const fresh = headSha === scannedSha && changedFiles.length === 0;
+  return {
+    manifest: true,
+    fresh,
+    headSha,
+    scannedSha,
+    changedFiles: fresh ? [] : changedFiles.slice(0, 200),
+    sections: Object.keys(manifest.sections ?? {}),
+  };
+}
+
 function parseArgs(argv) {
   const options = {
     repositoryRoot: process.cwd(),
@@ -82,6 +145,7 @@ function parseArgs(argv) {
     else if (key === "--write") options.write = true;
     else if (key === "--json") options.json = true;
     else if (key === "--area" || key.startsWith("--area=")) [i, options.area] = readValue(i, raw);
+    else if (key === "--check") options.check = true;
     else fail(`Unknown argument: ${raw}`);
   }
   return options;
@@ -415,6 +479,7 @@ function mergeWithExisting(scan, existingManifest) {
 export function scanRepository(repositoryRoot, options = {}) {
   const root = path.resolve(repositoryRoot);
   const scannedAt = new Date().toISOString();
+  const headSha = gitHeadSha(root);
   const existingManifest = readJson(path.join(root, ...ORIS_FLOW_MANIFEST.split("/")));
   const { files, truncated } = walk(root, options);
   const stacks = detectStacks(files);
@@ -430,6 +495,7 @@ export function scanRepository(repositoryRoot, options = {}) {
     repository: path.basename(root),
     generatedAt: scannedAt,
     updatedAt: scannedAt,
+    headSha,
     projectType,
     truncated,
     setup: {
@@ -493,6 +559,10 @@ export function writeScanResult(scan, options = {}) {
 
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
   const options = parseArgs(process.argv.slice(2));
+  if (options.check) {
+    console.log(JSON.stringify(checkFreshness(options.repositoryRoot), null, 2));
+    process.exit(0);
+  }
   const scan = scanRepository(options.repositoryRoot, options);
   const written = options.write ? writeScanResult(scan, { area: options.area }) : null;
   const payload = {

package/scripts/install/generate-agent-adapters.mjs

@@ -58,7 +58,11 @@ function readAgents() {
     .map((name) => ({ name, ...readAgent(path.join(sourceRoot, name)) }));
 }
 
-/** Write adapters into repo-local .cursor/.claude/.codex dirs under root. */
+/**
+ * Write adapters into repo-local .cursor/.claude/.codex dirs under root.
+ * Development-only: the installer never copies these into user agent homes —
+ * loop roles are internal and reach subagents via per-loop prompts/<role>.md files.
+ */
 export function generateAgentAdapters(root = repoRoot) {
   const agents = readAgents();
   for (const agent of agents) {
@@ -69,20 +73,6 @@ export function generateAgentAdapters(root = repoRoot) {
   return agents.map((agent) => agent.frontMatter.name);
 }
 
-/**
- * Write adapters into explicit agent homes, e.g. { cursor: "~/.cursor", codex: "~/.codex" }.
- * Used by the installer so the generated adapters actually reach the user's agents.
- */
-export function writeAgentAdapters(targets) {
-  const agents = readAgents();
-  for (const agent of agents) {
-    if (targets.cursor) writeFile(path.join(targets.cursor, "agents", agent.name), renderMarkdownAgent(agent));
-    if (targets.claude) writeFile(path.join(targets.claude, "agents", agent.name), renderMarkdownAgent(agent));
-    if (targets.codex) writeFile(path.join(targets.codex, "agents", agent.name.replace(/\.md$/, ".toml")), renderCodexAgent(agent));
-  }
-  return agents.map((agent) => agent.frontMatter.name);
-}
-
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
   const rootArg = process.argv.find((arg) => arg.startsWith("--root="));
   const root = rootArg ? path.resolve(rootArg.slice("--root=".length)) : repoRoot;