oris-skills 2.0.0 → 2.2.0

package/references/conventions.md

@@ -8,23 +8,63 @@ 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
+
+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
+
+The `oris-skills` CLI is NOT installed globally. ALWAYS invoke it as `npx oris-skills <command>` — a bare `oris-skills …` fails on user machines.
+
 ## Questions
 
 - ASK with the platform question UI (Cursor `AskQuestion`, Claude `AskUserQuestion`); ELSE ask plainly in chat.
 - ONE question per turn. Recommended answer FIRST.
 - ALWAYS include, localized to `uiLanguage`:
-  - `Explain the options` / `Spiega le opzioni` — explain, then re-ask.
-  - During interviews: `Enough questions — proceed` / `Basta domande — procedi` (early exit).
+  - `Explain the options` / `Spiega le opzioni` — explain, then re-ask the same question.
+  - 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.
+
 ## Language
 
 - 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/doc-policy.md

@@ -2,18 +2,34 @@
 
 Applies whenever an Oris skill writes or updates task documentation. Project-agnostic.
 
+## The {tasksRoot}
+
+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.
+
 ## Task folder
 
 One folder per feature, whole lifecycle:
 
 | File | Purpose | Written by |
 |------|---------|------------|
-| `docs/tasks/{task}/functional-analysis.md` | confirmed business behavior | discover |
-| `docs/tasks/{task}/acceptance-criteria.md` | QA criteria, stable `AC-xxx` IDs | criteria |
-| `docs/tasks/{task}/implementation-plan.md` | execution-ready technical plan | plan |
+| `{tasksRoot}/{task}/functional-analysis.md` | confirmed business behavior | discover |
+| `{tasksRoot}/{task}/acceptance-criteria.md` | QA criteria, stable `AC-xxx` IDs | criteria |
+| `{tasksRoot}/{task}/implementation-plan.md` | execution-ready technical plan | plan |
+| `{tasksRoot}/{task}/verification-report.md` | AC results with evidence | verify |
+| `{tasksRoot}/{task}/change-log.md` | spec changes, stable `CH-xxx` IDs | change |
 
 NEVER split one feature's docs across unrelated directories.
 
+## The {task} slug
+
+- DERIVE: kebab-case from the confirmed feature name (e.g. "Export invoices to CSV" → `export-invoices-csv`); prefix with the tracker ID when one exists (`feature-1213-export-invoices-csv`).
+- BEFORE creating: LIST `{tasksRoot}/` and REUSE the existing folder when it covers the same feature — one feature, one folder, forever.
+- IF two candidates could match → ask ONE question; never guess between them, never create a duplicate.
+
 ## Rules
 
 1. Language: documents in `artifactLanguage`; skill instructions stay English.

package/references/loop-contract.md

@@ -6,15 +6,15 @@ An Oris loop is a project-local feedback system: observe → choose ONE bounded
 
 ```text
 .oris-flow/
-  adapter.json          repo adapter (paths, commands, model aliases) — `oris-skills loop bootstrap`
+  adapter.json          repo adapter (paths, commands, model aliases) — `npx oris-skills loop bootstrap`
   loops/{slug}/
     loop.md             approved contract (front matter below)
-    prompts/            one editable file per role
+    prompts/            one editable file per ACTIVE role
       orchestrator.md   injected each pass by the stop hook (optional; default shipped)
       executor.md       required
       verifier.md       required
-      doctor.md         required
-      debriefer.md      optional (required for improve.mode: auto)
+      doctor.md         only when roles includes doctor
+      debriefer.md      only when roles includes debriefer (required for improve.mode: auto)
     context.md          living handoff snapshot (facts, next action)
     receipts/           one compact receipt per pass
     proposals/          unapproved improvement patches
@@ -31,9 +31,10 @@ kind: oris-loop
 name: my-loop            # stable slug
 approved: true           # set by the user's approval at craft — loop cannot start without it
 phases: [work]
+roles: [executor, verifier]   # default; opt in doctor and/or debriefer only when needed
 limits:
-  maxIterations: 25
-  maxNoProgress: 2
+  maxIterations: 10
+  maxNoProgress: 2       # consecutive passes without verified progress → blocked
   maxMinutes: 240
 models:                  # per-role: "inherit" | adapter alias | platform model id
   default: inherit
@@ -56,15 +57,19 @@ Schema: `references/loop.schema.json`. Body = human summary; prompts live in `pr
 
 ## Roles
 
-| Role | Does | Never |
-|------|------|-------|
-| orchestrator (main chat) | reads context, spawns roles, writes receipts, sets state | executor/verifier/doctor work |
-| executor | ONE bounded action per pass | self-verify, exceed scope |
-| verifier | independent evidence check per user criteria | trust claims, edit product files |
-| doctor | continue / advance / complete / stop from evidence | edit files, patch loop.md |
-| debriefer | learn across receipts; tune prompts (auto) or propose (propose) | touch scope/limits/permissions |
+Default roles are **executor + verifier** — enough for most loops. Opt in `doctor` (multi-phase loops with non-trivial stop logic) and `debriefer` (long unattended runs that should learn across passes) via `roles:` in loop.md.
 
-Every prompt is a file the user can edit; the next pass obeys the edited file. Subagent output stays compact; raw logs go to `.oris-flow/runtime/evidence/`.
+| Role | Default | Does | Never |
+|------|---------|------|-------|
+| orchestrator (main chat) | always | reads context, spawns roles, writes receipts, sets state | executor/verifier/doctor work |
+| executor | yes | ONE bounded action per pass | self-verify, exceed scope |
+| verifier | yes | independent evidence check per user criteria; sets `goalMet` when the LOOP goal is satisfied | trust claims, edit product files |
+| doctor | opt-in | decision from evidence: `continue \| advance \| complete \| ask-user \| propose-patch \| blocked` (canonical enum — every doctor prompt uses exactly these) | edit files, patch loop.md |
+| debriefer | opt-in | learn across receipts; tune prompts (auto) or propose (propose) | touch scope/limits/permissions |
+
+Without a doctor, the verifier verdict maps to the state directly: `pass` + `goalMet` → complete; `pass`/`fail` → continue; `blocked`/`inconclusive` → ask-user.
+
+Every prompt is a file the user can edit; the next pass obeys the edited file. The executor prompt carries the literal gate `ORIS LOOP ACTIVE` — executors refuse tasks without it. Subagent output is a single ```json fenced block; raw logs go to `.oris-flow/runtime/evidence/`. Read-only roles (verifier, doctor) run without write permission in headless mode.
 
 ## Models
 
@@ -78,14 +83,16 @@ Anything else → passed through as a platform model id.
 |----------|-----------|
 | Cursor | `.cursor/hooks.json` stop hook → injects the next pass into the same chat |
 | Claude Code | `.claude/settings.json` Stop hook → `decision: block` continues the same session |
-| Codex / CI | `oris-skills loop run` — each role is a separate CLI process |
+| Codex / CI | `npx oris-skills loop run` — each role is a separate CLI process |
 
-`oris-skills loop bootstrap` writes adapter + hooks + wrappers. The injected pass message comes from `prompts/orchestrator.md` (or the shipped default) with `{{placeholders}}` filled from runtime state.
+`npx oris-skills loop bootstrap` writes adapter + hooks + wrappers. The injected pass message comes from `prompts/orchestrator.md` (or the shipped default) with `{{placeholders}}` filled from runtime state.
 
 ## States and outcomes
 
-Machine states: `continue` | `advance` | `complete` | `blocked` | `cancelled`.
+Machine states: `continue` | `advance` | `complete` | `ask-user` | `blocked` | `cancelled`.
+`ask-user` pauses the loop for input or approval — the hook stops resuming until the state is set back to `continue` (or the loop is restarted). It is NOT a failure.
 Receipt results: `Success` | `Clean no-op` | `Blocked` | `Approval required` | `Exhausted` | `No progress`.
+Every `set-state` carries `--progress yes|no` (yes = the verifier confirmed forward movement); `maxNoProgress` consecutive `no` passes force `blocked`.
 Hitting any limit without meeting the goal = `blocked`, NEVER success.
 
 ## Receipt (per pass)

package/references/loop.schema.json

@@ -62,6 +62,19 @@
         "pattern": "^[a-z][a-z0-9-]*$"
       }
     },
+    "roles": {
+      "type": "array",
+      "description": "Active roles per pass. Default [executor, verifier]; opt in doctor and/or debriefer. Executor and verifier are always required.",
+      "minItems": 2,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["executor", "verifier", "doctor", "debriefer"]
+      },
+      "allOf": [
+        { "contains": { "const": "executor" } },
+        { "contains": { "const": "verifier" } }
+      ]
+    },
     "limits": {
       "type": "object",
       "required": [

package/references/repo-map.md

@@ -10,7 +10,7 @@ Setup map = the default project context for every Oris skill and loop. It exists
 | `.oris-flow/maps/**` | repo | short markdown maps: docs, stack, commands, code areas, tests |
 | `.oris-flow/adapter.json` | repo | loop adapter: paths, commands, model aliases |
 | `~/.oris/settings.json` | user | language + test profiles |
-| `docs/tasks/{task}/…` | task | business artifacts only |
+| `{tasksRoot}/{task}/…` | task | business artifacts only — `setup.tasksRoot` in the manifest, default `.oris-flow/tasks` (see `references/doc-policy.md`) |
 
 Manifest and maps are never task authority and NEVER hold secrets.
 
@@ -32,7 +32,7 @@ Manifest and maps are never task authority and NEVER hold secrets.
 - Small: only sections that exist for the detected stack; no placeholders.
 - Each section: file path, one-line summary, `confidence`, `lastScannedAt`, stale flag.
 - Confidence: `confirmed` (user/authoritative) | `detected` (strong scan evidence) | `inferred` (unverified) | `stale` (no longer matches).
-- `setup.versionControl.orisFlowMap`: `commit` | `gitignore` — applied via `oris-skills flow version-control --mode <choice>`.
+- `setup.versionControl.orisFlowMap`: `commit` | `gitignore` — applied via `npx oris-skills flow version-control --mode <choice>`.
 - Schema: `references/repo-map.schema.json`.
 
 ## Map sections
@@ -50,4 +50,4 @@ Each section: purpose, authoritative paths, confirmed decisions, key commands/co
 
 ## Command surface
 
-In target repositories always use the installed CLI (`oris-skills flow scan|version-control|clean-runtime`, `oris-skills loop …`), never `node scripts/...` paths — those exist only in the OrisSkills source checkout.
+In target repositories always use the installed CLI (`npx oris-skills flow scan|version-control|clean-runtime`, `npx oris-skills loop …`), never `node scripts/...` paths — those exist only in the OrisSkills source checkout.

package/references/repo-map.schema.json

@@ -32,10 +32,20 @@
       "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
     },
+    "projectType": {
+      "$ref": "#/$defs/projectType"
+    },
+    "truncated": {
+      "type": "boolean"
+    },
     "setup": {
       "$ref": "#/$defs/setup"
     },
@@ -132,6 +142,10 @@
           "type": "string",
           "enum": ["fast", "balanced", "manual-summary"]
         },
+        "tasksRoot": {
+          "type": "string",
+          "minLength": 1
+        },
         "confirmedDecisions": {
           "type": "array",
           "items": {
@@ -191,6 +205,33 @@
         },
         "evidence": {
           "type": "string"
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        }
+      }
+    },
+    "projectType": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "label", "confidence"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "enum": ["empty", "monorepo", "webapp", "api", "library", "cli", "unknown"]
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       }
     }

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-layout.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 export const ORIS_FLOW_ROOT = ".oris-flow";
 export const ORIS_FLOW_MANIFEST = ".oris-flow/manifest.json";
 export const ORIS_FLOW_MAPS_ROOT = ".oris-flow/maps";
+export const ORIS_FLOW_TASKS_ROOT = ".oris-flow/tasks";
 export const ORIS_FLOW_ADAPTER = ".oris-flow/adapter.json";
 export const ORIS_FLOW_LOOPS_ROOT = ".oris-flow/loops";
 export const ORIS_FLOW_RUNTIME = ".oris-flow/runtime";