oris-skills 2.0.0 → 2.1.0

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.0.0",
+  "version": "2.1.0",
   "author": {
     "name": "Davide Baldassarre"
   },
@@ -19,12 +19,17 @@
   "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"
   ]

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 2.1.0 - 2026-07-05
+
+- **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.
+- `oris-flow-setup` rewritten: explore → present findings → decisions one at a time with explainers; AI-readiness check (AGENTS.md, CONTEXT.md, ADRs, project skills, confirmed verify commands) with per-file scaffold offers.
+- New skills: `oris-flow-new` (bootstrap an AI-driven project: sparse commands-first AGENTS.md, CONTEXT.md glossary, ADR-0001, test+lint observed green, flow armed), `oris-flow-architecture` (deepening-opportunity review with visual HTML report in the OS temp dir), `oris-flow-merge` (intent-preserving merge/rebase conflict resolution).
+- **Loops default to 2 roles** (executor + verifier); doctor and debriefer are opt-in via `roles:` in loop.md. Without a doctor, the verifier verdict (`goalMet`) drives the state directly.
+- New flow skills: `oris-flow-verify` (one-shot acceptance-criteria verification with evidence report) and `oris-flow-change` (spec-change delta interview, homogeneous doc updates, `CH-xxx` change log). Implement/fix now route verification to `oris-flow-verify` instead of suggesting a loop.
+- Canonical doctor decision enum (`continue|advance|complete|ask-user|propose-patch|blocked`) unified across agent specs, templates, and the headless runner; `ask-user` now pauses the loop instead of silently killing it.
+- `limits.maxNoProgress` is enforced at runtime (stop hook + headless runner + `set-state --progress yes|no`); previously declared but never checked.
+- Read-only roles (verifier, doctor) run without write access in headless mode.
+- Stop hook: Cursor auto-detection fixed (payloads carrying both `conversation_id` and `session_id`); exhausted limits and corrupt state now surface a user-visible message on Claude Code.
+- Executor gate literal `ORIS LOOP ACTIVE` ships in the executor prompt template; role output is a ```json fenced block (robust extraction in the headless runner).
+- All CLI commands in skills, templates, and docs use `npx oris-skills …` (the CLI is not installed globally).
+- Installer now generates Cursor/Claude/Codex loop-agent adapters into the detected agent homes.
+- `{task}` slug convention defined once in `references/doc-policy.md`; `references/questions.md` merged into `references/conventions.md`; clean-code checklist trimmed to its implement/fix use.
+- Removed dead surface: `repairCycles`, `--node-only`/`test:node`/`npm run validate` duplication, empty `scripts/maintenance/`, unused `.gitattributes` rules.
+
+## 2.0.0 - 2026-07-04
+
+- Public npm package (MIT): `npx oris-skills@latest install`, multi-agent installer for Cursor, Claude Code, and Codex; bundle moved to `~/.oris/`.
+- Flattened layout: `skills/`, `references/`, `agents/`; 10 essential skills, single entry point `/oris-flow` with inline routing.
+- Loop document schemaVersion 2: `approved` gate, per-role `models` (`inherit` | adapter alias | model id), `improve.mode: auto|propose`.
+- Role prompts moved to per-loop editable files `prompts/{orchestrator,executor,verifier,doctor,debriefer}.md`; orchestrator prompt no longer hardcoded in the stop hook.
+- Self-tuning loops: in `auto` mode the debriefer rewrites prompt files between passes and archives old versions to `history/`.
+- Cross-model triggers: shared stop hook now speaks Cursor (`followup_message`) and Claude Code (`decision: block`); new headless runner `oris-skills loop run --agent codex|claude` (one CLI process per role).
+- Learnability: `oris-skills loop demo` (sandboxed tutorial loop), `oris-skills loop dry-run` (preview the injected pass message).
+- Skill texts rewritten with leading words (~60% shorter); shared rules centralized in `references/conventions.md`.
+- Removed: org-specific MCP config, DevOps story skills, scaffold/service standards, utility skills, demo showcase, legacy fallbacks.
+
+## 1.0.0 - 2026-06-29
+
+- Release Oris Skills 1.0 with Node-based install, validation, packaging, and cross-platform CI.
+- Add Oris Loop 1.0 with project-local `.oris-flow/` storage, schemaVersion 1 loop documents, compact receipts, Doctor proposals, and subagent-first orchestration.
+- Add canonical subagent contracts for executor, verifier, Doctor, and debriefer, plus generated Cursor, Claude, and Codex adapters.
+- Add clean Node CLI entrypoints through `oris-skills install`, `oris-skills validate`, `oris-skills doctor`, and `oris-skills loop`.

package/README.md

@@ -19,37 +19,39 @@ The installer detects your agents (`~/.cursor`, `~/.claude`, `~/.codex`) or take
 | 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 four roles (executor, verifier, doctor, debriefer), each driven by **an editable prompt file**:
+**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**:
 
 ```text
 .oris-flow/loops/{slug}/
-  loop.md        contract: goal, scope, limits, per-role models, improve mode
-  prompts/       orchestrator.md executor.md verifier.md doctor.md debriefer.md  ← edit freely
+  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/
 ```
 
 - **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 `oris-skills loop run --agent codex|claude` for headless/CI where each role is a separate CLI process.
+- **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.
 
 ## Try a loop in 3 minutes
 
 ```bash
-oris-skills loop demo                    # creates a sandboxed tutorial loop
-oris-skills loop dry-run --loop oris-demo  # preview the exact pass message — runs nothing
-oris-skills loop chat --action start --loop oris-demo   # then end the chat turn; the hook does the rest
+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
 ```
 
-Stop anytime: `oris-skills loop chat --action stop`. Self-check the runtime: `oris-skills loop verify --temp`.
+Stop anytime: `npx oris-skills loop chat --action stop`. Self-check the runtime: `npx oris-skills loop verify --temp`.
 
 ## Repository layout
 
 | Path | Purpose |
 |------|---------|
-| `skills/` | the 10 Oris skills (`SKILL.md` each) |
+| `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) |
@@ -60,7 +62,6 @@ Stop anytime: `oris-skills loop chat --action stop`. Self-check the runtime: `or
 
 ```bash
 npm test               # cross-platform Node test suite
-npm run validate
 npm run verify:loop    # end-to-end stop-hook simulation (cursor + claude)
 ```
 

package/agents/oris-loop-doctor.md

@@ -22,7 +22,7 @@ Output:
 ```json
 {
   "role": "doctor",
-  "decision": "continue|complete|block|ask-user|propose-patch",
+  "decision": "continue|advance|complete|ask-user|propose-patch|blocked",
   "diagnosis": "",
   "evidence": "",
   "patchSummary": "",

package/agents/oris-loop-verifier.md

@@ -22,6 +22,7 @@ Output:
 {
   "role": "verifier",
   "state": "pass|fail|blocked|inconclusive",
+  "goalMet": false,
   "summary": "",
   "evidence": "",
   "evidencePath": "",
@@ -29,3 +30,5 @@ Output:
   "nextRecommendation": ""
 }
 ```
+
+`goalMet` is true only when the loop goal itself is satisfied, not just this pass.

package/docs/architecture.md

@@ -5,8 +5,8 @@ Read this before explaining or changing the project.
 ## Shape
 
 ```text
-skills/       10 skills; oris-flow is the router, oris-loop the loop system
-references/   shared contracts (conventions, loop-contract, settings, questions, repo-map, doc-policy) + schemas
+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
@@ -17,10 +17,11 @@ 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.
 
 ## Runtime
 
 - `/oris-flow` routes; destination skills own their gates.
 - 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 `oris-skills loop chat`.
+- State machine: `.oris-flow/runtime/chat-active.json`, managed only by `npx oris-skills loop chat`.

package/docs/distribution.md

@@ -20,7 +20,7 @@ The installer detects Cursor / Claude Code / Codex from `~/.cursor`, `~/.claude`
 ~/.codex/prompts/<name>.md  Codex prompts pointing to the bundled SKILL.md
 ```
 
-Project assets live only in each repository's `.oris-flow/` (adapter, loops, runtime) plus thin hook wrappers in `.cursor/hooks/` and `.claude/hooks/` written by `oris-skills loop bootstrap`.
+Project assets live only in each repository's `.oris-flow/` (adapter, loops, runtime) plus thin hook wrappers in `.cursor/hooks/` and `.claude/hooks/` written by `npx oris-skills loop bootstrap`.
 
 ## Uninstall / reinstall
 

package/docs/maintainer-guide.md

@@ -9,7 +9,8 @@ Use when improving Oris Skills itself. Keep changes tiny; update the canonical f
 | User-facing explanation | `docs/user-guide.md`, `skills/oris-help/SKILL.md` |
 | Project structure | `docs/architecture.md` |
 | Routing | `skills/oris-flow/SKILL.md` (route table) |
-| Shared interaction rules | `references/conventions.md`, `references/questions.md` |
+| 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 runtime | `scripts/loop/` |
@@ -20,7 +21,6 @@ Use when improving Oris Skills itself. Keep changes tiny; update the canonical f
 
 ```bash
 npm test
-npm run validate
 npm run verify:loop
 ```
 

package/docs/user-guide.md

@@ -6,7 +6,9 @@ Install once, remember one command:
 npx oris-skills@latest install     # detects Cursor / Claude Code / Codex
 ```
 
-Then type **`/oris-flow`** in your agent chat. It routes your request or shows a short menu (setup, discovery, criteria, plan, implement/fix, loop, 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, merge conflicts, docs, help). On Codex use the installed `/oris-flow` prompt.
+
+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.
 
 ## Loops in short
 
@@ -15,17 +17,17 @@ A loop repeats: one bounded action → independent verification → receipt →
 Learn it safely:
 
 ```bash
-oris-skills loop demo                      # sandboxed tutorial loop
-oris-skills loop dry-run --loop oris-demo  # preview, nothing runs
-oris-skills loop chat --action start --loop oris-demo   # arm, then end the chat turn
+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
-oris-skills loop list            # what exists
-oris-skills loop chat --action status
-oris-skills loop chat --action stop
+npx oris-skills loop list            # what exists
+npx oris-skills loop chat --action status
+npx oris-skills loop chat --action stop
 ```
 
 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/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "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",
@@ -16,6 +16,7 @@
     "docs",
     ".cursor-plugin",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [
@@ -37,8 +38,6 @@
   },
   "scripts": {
     "test": "node scripts/tests/run-all-tests.mjs",
-    "test:node": "node scripts/tests/run-all-tests.mjs --node-only",
-    "validate": "node scripts/oris-skills.mjs validate",
     "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"

package/references/clean-code-checklist.md

@@ -1,107 +1,20 @@
-# Clean Code Checklist
-
-Use this reference during `/oris-flow-clean-code` audits. Investigate before concluding; absence in one file is not proof of dead code.
-
-## Analysis Order
-
-1. Resolve scope from task folder, recent diff, or user-provided section.
-2. Read project conventions: README, `docs/**`, `.cursor/rules/**`, `.cursor/skills/**`, linter config, and formatting rules.
-3. List scoped files and their relationships: imports, tests, config, translations, DI registration, routing, and feature flags.
-4. Audit category by category below.
-5. Record only findings with file, line, severity, problem, and proposed fix.
-
-## In Scope
-
-### Dead and unused code
-
-- Unused imports, variables, parameters, private methods, classes, constants, and files
-- Unreachable branches left from earlier attempts
-- Commented-out code blocks that are not active documentation
-- Feature flags or toggles that no longer gate anything
-- Orphan tests for removed behavior
-
-Verify with cross-file search, DI/container registration, reflection, dynamic imports, string-based dispatch, routing tables, Razor/tag helpers, code generation, and framework conventions before marking dead.
-
-### Duplication
-
-- Copy-pasted logic with only naming changes
-- Parallel helpers that should be one function
-- Repeated validation, mapping, or query patterns in the same feature area
-
-Prefer the existing project abstraction level. Do not introduce new shared layers for one-off duplication unless the user approves.
-
-### Abandoned attempts
-
-- Half-finished branches with TODO/FIXME/HACK tied to the current feature
-- Alternate implementations left in place after a chosen approach
-- Debug logging, temporary guards, or experimental code paths no longer needed
-- Stale comments describing behavior that no longer exists
-
-### Typos and wording
-
-- Misspellings in user-visible strings when the task scope includes them
-- Wrong identifiers that reduce readability but are not public API contracts
-- Misleading names for variables or methods introduced in the current work
-
-Do not rename public API surface, routes, database fields, or serialized property names unless the user explicitly approves.
-
-### Obvious inefficiencies
-
-- Duplicate queries or remote calls inside loops
-- Repeated allocations or parsing in hot paths within the scoped change
-- Redundant null checks, casts, or conversions introduced during iteration
-
-Flag only clear wins with low regression risk. Do not micro-optimize unrelated code.
-
-### Style and format
-
-Apply only when conventions are explicit in project docs or `.cursor/rules`:
-
-- Naming patterns
-- Import/order rules
-- Formatter or analyzer expectations
-- File layout conventions
-
-Avoid formatting-only churn outside the scoped files.
-
-## Out of Scope
-
-- Bug fixes or behavior corrections - use `/oris-flow-fix`
-- Architectural deepening, module consolidation, or seam redesign
-- Large refactors, API redesign, or cross-feature rewrites
-- DevOps, commits, branches, pull requests, or documentation updates
-- Rewriting tests to change behavior instead of removing obsolete coverage
-
-## Evidence Bar
-
-Before reporting a finding:
-
-- Search references and call sites in the scoped area and direct dependents
-- Check whether tests, config, or registration files still require the symbol
-- For dead code candidates, note what search was performed
-- For duplication, cite both locations and why consolidation is safe
-- For abandoned attempts, tie the finding to the current feature or recent diff when possible
-
-## Report Shape
-
-Keep chat output compact:
-
-```text
-Blue src/Feature/Foo.cs:42 - unused import `System.Linq`
-Yellow src/Feature/Bar.cs:18-31 - duplicated validation with Baz.cs:44-57 - extract local helper
-Red src/Feature/Qux.cs:90 - private method appears unused but referenced via reflection in Registry.cs
-```
-
-## Post-Fix Recap Shape
-
-After approved fixes, show a short bulleted recap in settings `uiLanguage`:
-
-```text
-- Removed unused imports in Foo.cs and Bar.cs - no references remained after cross-file search.
-- Deleted commented fallback block in Qux.cs - superseded by current handler.
-- Aligned member order in Baz.cs to project rule X.
-```
-
-## Last updated
-
-2026-06-23
+# 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.
+
+## Check, in the touched scope only
+
+- **Dead code you left behind**: unused imports, variables, parameters, helpers; unreachable branches from earlier attempts; commented-out code that is not documentation.
+- **Abandoned attempts**: half-finished alternates, debug logging, temporary guards, TODO/FIXME tied to this change, stale comments describing behavior that no longer exists.
+- **Duplication you introduced**: copy-pasted logic that should be one function — at the project's existing abstraction level, no new shared layers without approval.
+- **Naming and wording**: misleading identifiers introduced in this work; misspellings in user-visible strings when in scope. NEVER rename public API surface, routes, DB fields, or serialized names without explicit approval.
+- **Obvious inefficiencies**: duplicate queries/calls in loops, repeated parsing in hot paths — only clear wins with low regression risk.
+- **Style**: match the file's existing conventions (naming, import order, layout). No formatting-only churn outside touched files.
+
+## Evidence bar
+
+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
+
+Bug fixes (→ `skills/oris-flow-fix/SKILL.md`), architectural redesign, cross-feature refactors, DevOps, drive-by cleanup of code you did not touch.

package/references/conventions.md

@@ -8,15 +8,29 @@ Shared rules for every Oris skill. Skills reference this file instead of repeati
 - Installed: `~/.oris/oris-skills/`
 - Repo checkout: repository root.
 
+## 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.
+
+## 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`).

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
+  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.