oris-skills 3.0.1 → 3.0.2

package/README.md

@@ -30,7 +30,9 @@ fixes the colleague part with three rules baked into every interaction:
 
 `/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
@@ -42,6 +44,7 @@ client changed their mind about invoicing" and you are in **change**.
 |-------|---------|
 | **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 — external APIs verified against their docs, sources recorded |
@@ -50,6 +53,7 @@ client changed their mind about invoicing" and you are in **change**.
 | **change** | spec delta interviewed, **all** documents updated in one approved pass → `change-log.md` |
 | **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.

package/docs/user-guide.md

@@ -6,9 +6,9 @@ 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, architecture review, docs, commit, pull request, 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`.
+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 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. 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.
 
 ## What setup leaves in your repo
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "3.0.1",
+  "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",

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

@@ -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
 

package/scripts/tests/test-routing-lifecycle.mjs

@@ -59,7 +59,8 @@ test("shared conventions centralize question, language, and gate rules", () => {
   assert.match(conventions, /`Continua l'intervista`/);
   assert.match(conventions, /`Approva documento`/);
   assert.match(conventions, /`Annulla`/);
-  assert.match(conventions, /oris-flow-criteria.*writes first/i, "the criteria write-first exception must live where skills read it");
+  assert.match(conventions, /skills\/oris-flow\/references\/criteria\.md`.*writes first/i, "the criteria write-first exception must live where skills read it");
+  assert.doesNotMatch(conventions, /oris-flow-(criteria|implement|fix)/, "destinations are named by file path, never by prose nickname");
   assert.equal(exists("references/questions.md"), false, "questions.md was merged into conventions.md");
 });
 

package/skills/oris-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oris-flow
-description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Routes setup, new project, discovery, acceptance criteria, technical plan, implement, fix, verify, spec change, architecture review, docs, commit, pull request, and help.
+description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Routes setup, new, triage, discover, criteria, plan, implement, fix, verify, change, architecture, docs, commit, pr, handoff, and help.
 disable-model-invocation: true
 ---
 
@@ -23,6 +23,7 @@ Match the desired outcome to ONE route, then apply its reference:
 |-------|----------------------|-------|
 | setup | prepare / map / refresh an existing repo for Oris and agents | `skills/oris-flow/references/setup.md` |
 | new | bootstrap a project from scratch, greenfield, empty directory | `skills/oris-flow/references/new.md` |
+| triage | capture an idea, bug report, or request as a work item with an agent-ready brief | `skills/oris-flow/references/triage.md` |
 | discover | understand or define product behavior, functional analysis | `skills/oris-flow/references/discover.md` |
 | criteria | acceptance criteria, QA checks, testable scenarios | `skills/oris-flow/references/criteria.md` |
 | plan | a technical implementation plan before coding | `skills/oris-flow/references/plan.md` |
@@ -34,6 +35,7 @@ Match the desired outcome to ONE route, then apply its reference:
 | docs | update task docs after a change | `skills/oris-flow/references/docs.md` |
 | commit | commit changes with the Oris standard — Conventional Commits, work item linked | `skills/oris-flow/references/commit.md` |
 | pr | open or update a pull request, English title/description linked to the work item | `skills/oris-flow/references/pr.md` |
+| handoff | package session state — decisions, evidence, next move — to resume in a fresh session | `skills/oris-flow/references/handoff.md` |
 | help | how Oris works, install, update, troubleshooting | `skills/oris-flow/references/help.md` |
 
 ## Precedence (the calls that look ambiguous)
@@ -43,13 +45,18 @@ Match the desired outcome to ONE route, then apply its reference:
 2. RETHINK beats build: analyze, question, or reshape existing work →
    route to the interview owner (discover / plan / change), NEVER straight to implement.
 3. CHANGED spec on a feature that already has task docs or code → change, not discover —
-   change owns the delta and the history.
+   change owns the delta and the history. Spec unchanged but code/reality moved on and the
+   task docs lag behind → docs, not change.
 4. BROKEN behavior → fix. NEW planned work → implement. The menu answer "Implement or
    fix" gets exactly one follow-up question to split them.
 5. EMPTY directory or from-scratch intent → new. Existing repo never touched by Oris
    (no `AGENTS.md`, no `.oris-flow/`) → recommend setup first; respect the user's choice.
 6. COMMIT staged/working changes with the standard → commit. OPEN or update a pull request
    → pr. Neither writes product code — they package and publish what implement/fix produced.
+7. CAPTURE work for later (an idea, a report, backlog intake) → triage — it creates the
+   work item and stops. DOING the work now → discover / fix / implement.
+8. CONTINUE elsewhere — session ending, context full, "pass this to another agent" →
+   handoff.
 
 ## Menu (low confidence)
 
@@ -59,6 +66,7 @@ fallback in `references/conventions.md` `## Questions`), options:
 
 - Setup repository
 - New project from scratch
+- Capture an idea or bug as a work item (triage)
 - Understand / define behavior (discovery)
 - Acceptance criteria
 - Technical plan
@@ -69,11 +77,15 @@ fallback in `references/conventions.md` `## Questions`), options:
 - Update docs
 - Commit changes
 - Open a pull request
+- Hand off this session (continue elsewhere)
 - Help
 - Explain the options / Spiega le opzioni
 
-IF "Explain the options" → explain briefly, re-ask the same question.
-Every other label maps 1:1 to its route in the table above.
+IF "Explain the options" → ONE message that contains BOTH: one explanation line per
+option, THEN the full lettered list again below the explanations. Re-asking without the
+explanations visible in that same message is the failure this rule exists to prevent.
+Every other label maps to its route in the table above; "Implement or fix" is the one
+label that splits, with exactly one follow-up question (Precedence 4).
 
 ## Never
 

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

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

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

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

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

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

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

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

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

@@ -3,6 +3,9 @@
 Bring `{tasksRoot}/{task}/` documents in line with a later change, keeping the change
 traceable ({tasksRoot} per doc-policy).
 
+BOUNDARY: the spec is unchanged but code/reality moved on → this route. The business spec
+itself changed → `skills/oris-flow/references/change.md` (it owns the delta and the history).
+
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 
 ## Workflow
@@ -18,7 +21,8 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
    - add one change-history row per document: date | source | short change | reason;
    - keep unresolved risks in open points;
    - preserve acceptance-criteria IDs.
-7. CLOSE with a concise summary. Offer next steps without auto-starting them.
+7. CLOSE with a concise summary. OFFER next: commit the doc updates
+   (`skills/oris-flow/references/commit.md`) | stop — never auto-started.
 
 ## Never
 

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

@@ -5,7 +5,7 @@ any edit, evidence before done.
 
 RULES: `references/conventions.md`. Research: `references/research.md`.
 
-## Triage
+## Intake
 
 1. IF no details given → ask ONE question: what happens, what was expected, where
    (link/ID when one exists).
@@ -37,7 +37,8 @@ RULES: `references/conventions.md`. Research: `references/research.md`.
 1. RUN the reproduction + targeted tests; broaden if the surface is shared.
 2. SUMMARIZE: cause, change, verification, residual risk.
 3. RECOMMEND: `skills/oris-flow/references/verify.md` when criteria exist; docs update
-   (`skills/oris-flow/references/docs.md`) when documented behavior changed.
+   (`skills/oris-flow/references/docs.md`) when documented behavior changed; commit
+   (`skills/oris-flow/references/commit.md`) when the fix is verified and ready to package.
 
 ## Never
 

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

@@ -0,0 +1,67 @@
+# Handoff
+
+Package this session's state so the next session — or another agent — resumes from the
+exact point: decisions, evidence, next move. The handoff is a bridge, not a store: task
+docs and `AGENTS.md` stay the truth, the handoff points at them and carries ONLY what
+lives nowhere else yet.
+
+RULES: `references/conventions.md`. Entering handoff IS the request to write it — no
+generation gate; the document lands outside the repo.
+
+## 1. Collect (silent)
+
+1. GATHER from this conversation: the active task and route, decisions the user
+   confirmed, evidence observed (commands seen green, verifications, reproductions),
+   open questions with their current best answer, and the next move.
+2. SPLIT what you gathered:
+   - already recorded in task docs or `AGENTS.md` → the handoff POINTS at the file;
+   - confirmed in chat but written nowhere → the handoff CARRIES it, marked with who
+     confirmed it;
+   - speculation → out, or listed as an open question.
+3. Durable project facts proved this session and missing from `AGENTS.md` → write them
+   back NOW (`references/conventions.md` `## Project facts`), so the handoff can point
+   instead of carry.
+
+## 2. Write (outside the repo)
+
+WRITE `handoff-{task-or-topic}-{timestamp}.md` to the OS temp directory — never inside
+the repo or `{tasksRoot}`. Language: `artifactLanguage` (another session reads this cold —
+never caveman-compressed). Structure:
+
+```markdown
+# Handoff — {task or topic}
+Date: … | Repo: {absolute path} | Route in progress: {route or none}
+## Where we are
+What was asked, what is done, what is verified — evidence, not claims.
+## Decisions confirmed in chat, not yet in docs
+- {decision} — confirmed by {user}, because {reason}
+## Read before acting
+- {file} — {why it matters first}
+## Open questions
+- {question} — current best answer: {answer or none}
+## Next move
+One imperative sentence: the first action the next session takes.
+## Resume with
+{the route reference to re-enter} — {one-line why}
+```
+
+TELL the absolute path + a one-line summary of the next move. OFFER: keep working here |
+stop.
+
+## Never
+
+- Write the handoff inside the repo or under `{tasksRoot}` — it is session luggage, not
+  a project document.
+- Duplicate task-doc or `AGENTS.md` content — point at the file.
+- Carry anything not observed in this session or confirmed by the user — a handoff that
+  guesses poisons the next session.
+- Include secrets or tokens — mask as `***`.
+- Auto-start the next route after writing.
+
+## Done when
+
+- [ ] Facts proved this session written back to `AGENTS.md` before the handoff.
+- [ ] Every item in the handoff is a pointer, an observed fact, or a user-confirmed
+      decision — nothing guessed.
+- [ ] Document written to the OS temp dir; absolute path and next move shown.
+- [ ] Resume route named; nothing auto-started.

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

@@ -12,6 +12,8 @@ details on request.
 | Copilot / any other agent | Copilot Chat: enable `chat.promptFiles` once, then `/oris-flow`. Anything else that reads files: point it at `~/.oris/oris-flow.md`. |
 | Uninstall / reinstall | `npx oris-skills uninstall` / `npx oris-skills reinstall` (preview with `--dry-run`). |
 | Skill missing after install | Reload the agent; check `~/.oris/oris-skills/` exists; re-run install with `--force`. |
+| Capture an idea or bug without doing it now | `/oris-flow` → Triage — it becomes a work item with a brief, routed to its route. |
+| Context window full / continue in a new session | `/oris-flow` → Hand off — writes a resume doc and names the route to re-enter. |
 | Change document language / chat verbosity | `/oris-flow` → Setup (settings live in `.oris-flow/settings.json`). |
 | Ultra-short answers | `/oris-flow` → Setup → set `responseStyle: caveman` — chat shrinks to maximum token density; documents stay complete. |
 

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

@@ -34,7 +34,8 @@ RULES: `references/conventions.md`. Research: `references/research.md`.
 1. RUN targeted verification first; broaden when the touched surface is shared.
 2. SUMMARIZE: touched files, verification results, residual risk.
 3. RECOMMEND next: `skills/oris-flow/references/verify.md` when acceptance criteria exist;
-   otherwise update docs (`skills/oris-flow/references/docs.md`).
+   otherwise update docs (`skills/oris-flow/references/docs.md`) or commit
+   (`skills/oris-flow/references/commit.md`) when the change is verified and ready to package.
 
 ## Never
 

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

@@ -22,8 +22,8 @@ RULES: `references/conventions.md`. DevOps config: `references/devops.md`.
 ## Gate (never skipped)
 
 SHOW the title + description + target branch. ASK: open PR | edit | cancel.
-ON open → create via the provider (Azure DevOps MCP `oris-devops`, or `gh` for GitHub)
-read from `references/devops.md`. Missing provider auth → say so; never guess credentials.
+ON open → create via the configured provider (`references/devops.md` — read `provider`,
+act generically). Missing provider auth → say so; never guess credentials.
 
 ## After
 

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

@@ -5,7 +5,8 @@ preferences in `.oris-flow/settings.json`, AI-readiness checked. ADAPT to what t
 IS; never force one structure. Writes ONLY after the user confirms the recap.
 
 RULES: `references/conventions.md`. Settings: `references/settings.md`.
-IF the repo is empty or brand-new → route to `skills/oris-flow/references/new.md` instead.
+IF the repo has no source files, or no commit beyond a scaffold-only init → route to
+`skills/oris-flow/references/new.md` instead.
 
 ## Mode
 
@@ -28,9 +29,9 @@ ELSE → create from scratch.
 4. FAN OUT parallel subagent scans (docs, frontend, backend/data, tests/build, local
    skills/rules) by DEFAULT whenever the repo has more than one of those areas —
    entering setup is the user's request to spawn (`references/conventions.md`
-   `## Subagents`). SKIP only when the repo is small enough that the baseline already
-   answers every §2 decision — say you skipped and why. No agent tool on the platform →
-   same scans inline, sequentially.
+   `## Subagents`). SKIP only when the baseline scan already answers EVERY §2 decision
+   (project type, tasks root, verify commands, version control) — say you skipped and
+   name the evidence. No agent tool on the platform → same scans inline, sequentially.
 
 ## 2. Present findings, decide one at a time
 

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

@@ -0,0 +1,69 @@
+# Triage
+
+Turn raw intake — an idea, a bug report, a request — into a work item on the DevOps
+provider with a brief the next route can act on. Capture, classify, route: the work
+itself stays with discover / fix / implement.
+
+RULES: `references/conventions.md`. Provider: `references/devops.md`.
+
+## 1. Understand the intake
+
+1. READ the resolved DevOps config (`references/devops.md`). Provider tools missing or
+   unauthenticated → degrade: compose everything below, show it, tell the user where to
+   paste it — never block on tooling.
+2. SEARCH the provider for existing work items matching the intake (title, keywords,
+   area) BEFORE composing anything. A match → propose linking/updating it, never a
+   duplicate.
+3. CLASSIFY on evidence: bug (behavior observed broken) | feature (new behavior) |
+   spec change on an existing feature | chore. Cheap checks against the repo or product
+   come before questions; a claim you could verify and didn't stays a claim.
+4. ASK one question at a time, only for gaps evidence cannot close: expected vs actual,
+   reproduction conditions, desired outcome, urgency. Early exit always available.
+
+## 2. Compose the work item
+
+BUILD title + description (language `artifactLanguage`; title says the behavior, not the
+solution). Description carries the brief:
+
+```markdown
+## Intake
+{verbatim request} — source: {who/where}, date: {date}
+## Type & evidence
+{bug|feature|spec change|chore} — {what was checked, what was observed}
+## Expected vs actual        ← bugs; features: ## Desired outcome
+…
+## Reproduction              ← bugs only
+1. …
+## Links
+{duplicates found, related items, task docs if any}
+## Next step
+{the Oris route that should pick this up}
+```
+
+Spec change on a feature that already has task docs → say so: the delta belongs to
+`skills/oris-flow/references/change.md`; the work item only tracks it.
+
+## 3. Gate, write, route
+
+1. SHOW the composed work item compactly (or the update to the existing one).
+2. ASK ONE question: Create the work item | Adjust | Stop. Update case: Update the
+   existing item | Adjust | Stop.
+3. ON approval → write via the provider; SHOW the id in the provider's `workItemSyntax`.
+   Degraded mode → deliver the composed item as text instead.
+4. OFFER next: enter the route named in the brief now | triage another intake | stop.
+
+## Never
+
+- Do the work here — no code, no task docs; triage captures and routes.
+- Write to the provider before the composed item is explicitly approved.
+- Recreate what exists — search first; duplicates get linked or updated.
+- Invent reporter, urgency, or behavior not present in the intake or observed.
+- Put secrets, tokens, or personal data beyond the reporter's name in a work item.
+
+## Done when
+
+- [ ] Intake classified with named evidence; duplicate search ran before composing.
+- [ ] Work item shown and explicitly approved before any provider write.
+- [ ] Work item created/updated with id shown in `workItemSyntax` — or degraded output
+      delivered and said so.
+- [ ] Next route offered, not auto-started.

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

@@ -41,6 +41,7 @@ Date: … | Source: acceptance-criteria.md | Verified by: oris-flow verify route
 
 ON fix → enter `skills/oris-flow/references/fix.md` with the failing AC as the bug report;
 re-verify the fixed criteria afterwards, as many fix-verify passes as the user approves.
+ON save with every AC Pass → also offer commit (`skills/oris-flow/references/commit.md`).
 
 ## Never