oris-skills 2.0.0

package/references/loop-adapter.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oris.dev/schemas/oris-loop-adapter-v1.json",
+  "title": "Oris Loop Repository Adapter",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "repository", "paths", "commands", "profile", "preflight"],
+  "properties": {
+    "$schema": {
+      "const": "https://oris.dev/schemas/oris-loop-adapter-v1.json"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "repository": {
+      "type": "string",
+      "minLength": 1
+    },
+    "paths": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtime", "allowed", "protected"],
+      "properties": {
+        "taskRoots": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/relativePath" }
+        },
+        "runtime": { "$ref": "#/$defs/relativePath" },
+        "loops": { "$ref": "#/$defs/relativePath" },
+        "allowed": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/relativePath" }
+        },
+        "protected": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/relativePath" }
+        },
+        "testDir": { "$ref": "#/$defs/relativePath" }
+      }
+    },
+    "commands": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "$ref": "#/$defs/command" }
+    },
+    "models": {
+      "type": "object",
+      "description": "Model alias map per repository, e.g. { \"smart\": \"composer-2.5\" }; loop.md can reference aliases",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "profile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["required", "defaultRole", "mappings"],
+      "properties": {
+        "required": { "type": "boolean" },
+        "defaultRole": {
+          "type": "string",
+          "pattern": "^[a-z][a-zA-Z0-9]*$"
+        },
+        "mappings": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/mapping" }
+        }
+      }
+    },
+    "preflight": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["minFreeDiskGiB"],
+      "properties": {
+        "minFreeDiskGiB": {
+          "type": "number",
+          "minimum": 0
+        }
+      }
+    }
+  },
+  "$defs": {
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "not": { "pattern": "(^|[\\\\/])\\.\\.([\\\\/]|$)" }
+    },
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["executable", "args", "cwd"],
+      "properties": {
+        "executable": { "type": "string", "minLength": 1 },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "cwd": { "$ref": "#/$defs/relativePath" },
+        "requiresFreeDiskGiB": {
+          "type": "number",
+          "minimum": 0
+        }
+      }
+    },
+    "mapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["env", "from", "required", "secret"],
+      "properties": {
+        "env": {
+          "type": "string",
+          "pattern": "^[A-Z_][A-Z0-9_]*$"
+        },
+        "from": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9]*(\\.[A-Za-z][A-Za-z0-9]*)*$"
+        },
+        "required": { "type": "boolean" },
+        "secret": { "type": "boolean" }
+      }
+    }
+  }
+}

package/references/loop-contract.md

@@ -0,0 +1,119 @@
+# Oris Loop Contract (v2)
+
+An Oris loop is a project-local feedback system: observe → choose ONE bounded action → act → verify with real evidence → record → repeat or stop. It is never permission for work outside its approved scope.
+
+## Layout — everything lives in the project
+
+```text
+.oris-flow/
+  adapter.json          repo adapter (paths, commands, model aliases) — `oris-skills loop bootstrap`
+  loops/{slug}/
+    loop.md             approved contract (front matter below)
+    prompts/            one editable file per 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)
+    context.md          living handoff snapshot (facts, next action)
+    receipts/           one compact receipt per pass
+    proposals/          unapproved improvement patches
+    history/            archived loop.md and prompt versions
+  runtime/              machine-owned state — agents NEVER edit it
+```
+
+## loop.md front matter (the runtime contract)
+
+```yaml
+---
+schemaVersion: 2
+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]
+limits:
+  maxIterations: 25
+  maxNoProgress: 2
+  maxMinutes: 240
+models:                  # per-role: "inherit" | adapter alias | platform model id
+  default: inherit
+  verifier: inherit      # override any role independently
+improve:
+  mode: propose          # propose | auto (auto = debriefer may rewrite prompts/ between passes)
+permissions:
+  allowedPaths: []
+  forbiddenActions: [commit, push, deploy, external-message]
+verification:
+  commands: []
+  evidenceRequired: true
+---
+Goal: one sentence.
+Stop: one sentence.
+```
+
+Schema: `references/loop.schema.json`. Body = human summary; prompts live in `prompts/`, never inline.
+`approved: true` marks user approval of goal, scope, prompts, and limits. It never authorizes work outside the loop.
+
+## 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 |
+
+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/`.
+
+## Models
+
+`inherit` → the current session's model (no explicit model passed).
+Adapter aliases → `adapter.json` `models: { "smart": "<platform-model-id>" }`; loop.md references the alias, so the same loop.md ports across platforms.
+Anything else → passed through as a platform model id.
+
+## Triggers per platform
+
+| Platform | Mechanism |
+|----------|-----------|
+| 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 |
+
+`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`.
+Receipt results: `Success` | `Clean no-op` | `Blocked` | `Approval required` | `Exhausted` | `No progress`.
+Hitting any limit without meeting the goal = `blocked`, NEVER success.
+
+## Receipt (per pass)
+
+```markdown
+# Oris Loop Receipt
+Loop: <slug> | Pass: <n> | Result: <outcome>
+Scope: <inspected/changed>
+Check: <verification + conditions>
+Evidence:
+- <summary + pointer>
+Actions:
+- <bounded action + outcome>
+Improved: <prompt tuned this pass, or none>
+Next: <next action | approval | blocker | nothing>
+```
+
+No secrets, no private reasoning, no full transcripts in receipts.
+
+## Self-improvement
+
+- `improve.mode: auto` → debriefer may rewrite `prompts/*.md` (archive old file to `history/` first, note the change in the receipt). One improvement per pass, evidence-backed.
+- `improve.mode: propose` → every change lands in `proposals/` until the user approves.
+- BOTH modes: scope, limits, permissions, verification commands change only via approved proposal; previous `loop.md` → `history/loop.vN.md`.
+
+## Iteration rules
+
+- Re-read fresh state before consequential actions; preserve unrelated user work.
+- Only declared paths, commands, tools, and data policy.
+- NEVER: commit, push, branch, PR, deploy, DevOps writes, external messages, credential exposure — unless the loop explicitly permits that exact action.
+- Real verification before claiming success. Update only `context.md`, receipts, and declared write scopes.

package/references/loop.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oris.dev/schemas/oris-loop-v2.json",
+  "title": "Oris Loop document front matter (v2)",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "name",
+    "approved",
+    "phases",
+    "limits",
+    "permissions",
+    "verification"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 2
+    },
+    "kind": {
+      "const": "oris-loop"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$",
+      "minLength": 2,
+      "maxLength": 80
+    },
+    "approved": {
+      "type": "boolean",
+      "description": "true only after the user approved goal, scope, prompts, and limits"
+    },
+    "models": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Per-role model: \"inherit\" (session model), an adapter alias, or a platform model id",
+      "properties": {
+        "default": { "$ref": "#/$defs/model" },
+        "executor": { "$ref": "#/$defs/model" },
+        "verifier": { "$ref": "#/$defs/model" },
+        "doctor": { "$ref": "#/$defs/model" },
+        "debriefer": { "$ref": "#/$defs/model" }
+      }
+    },
+    "improve": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "mode": {
+          "enum": ["propose", "auto"],
+          "description": "auto lets the debriefer rewrite prompts/ between passes; propose requires user approval for every change"
+        }
+      }
+    },
+    "phases": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      }
+    },
+    "limits": {
+      "type": "object",
+      "required": [
+        "maxIterations",
+        "maxNoProgress"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "maxIterations": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 500
+        },
+        "maxNoProgress": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 50
+        },
+        "maxMinutes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1440
+        }
+      }
+    },
+    "permissions": {
+      "type": "object",
+      "required": [
+        "allowedPaths",
+        "forbiddenActions"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "allowedPaths": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "forbiddenActions": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "required": [
+        "commands",
+        "evidenceRequired"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "evidenceRequired": {
+          "type": "boolean"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    }
+  }
+}

package/references/questions.md

@@ -0,0 +1,38 @@
+# Oris Question Contract
+
+How every Oris skill asks. Base rules live in `references/conventions.md`; this file adds the standard options and localized labels.
+
+## Standard options
+
+Include in every Oris question, localized to `uiLanguage`:
+
+| Option | `en` | `it` |
+|--------|------|------|
+| explanation (always) | `Explain the options` | `Spiega le opzioni` |
+| early exit (interviews only) | `Enough questions — proceed` | `Basta domande — procedi` |
+
+- Explanation → explain briefly, re-ask the same question.
+- Early exit → stop asking, go to the matching generation gate. It is NOT approval to write or execute.
+
+## Generation gates
+
+Standard labels:
+
+| `en` | `it` |
+|------|------|
+| `Generate the document` | `Genera il documento` |
+| `Approve document` | `Approva documento` |
+| `Continue the interview` | `Continua l'intervista` |
+| `Cancel` | `Annulla` |
+
+Rules:
+1. NEVER write documents, code, or external changes before the explicit gate choice.
+2. Exception: `oris-flow-criteria` writes the file first, then asks once — confirmed only on `Approve document` / `Generate the document`.
+3. After a document is written: concise summary + contextual next-step menu. NEVER auto-start the next phase.
+
+## Interview standard
+
+Oris is a guided product, not a silent task runner.
+1. READ everything the repo can answer first; ask only real decisions.
+2. ONE focused question per turn until outcome, authority, evidence, and stop rules are clear.
+3. The agent recommends; the user's explicit choice decides the approved scope.

package/references/repo-map.md

@@ -0,0 +1,53 @@
+# Oris Repository Map
+
+Setup map = the default project context for every Oris skill and loop. It exists so agents stop re-scanning and users stop repeating project facts.
+
+## Files
+
+| File | Scope | Purpose |
+|------|-------|---------|
+| `.oris-flow/manifest.json` | repo | compact index: section paths, freshness, confidence, refresh policy |
+| `.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 |
+
+Manifest and maps are never task authority and NEVER hold secrets.
+
+## Manifest shape (v1)
+
+```json
+{
+  "$schema": "https://oris.dev/schemas/oris-flow-map-v1.json",
+  "schemaVersion": 1,
+  "repository": "",
+  "generatedAt": "",
+  "updatedAt": "",
+  "setup": { "versionControl": { "orisFlowMap": "commit" } },
+  "refreshPolicy": {},
+  "sections": {}
+}
+```
+
+- 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>`.
+- Schema: `references/repo-map.schema.json`.
+
+## Map sections
+
+`.oris-flow/maps/`: `README.md`, `docs.md`, `stack.md`, `commands.md`, `code.md`, `tests.md`.
+Each section: purpose, authoritative paths, confirmed decisions, key commands/conventions, confidence + stale notes, pointers instead of copied content.
+
+## Consumption rules
+
+1. MANIFEST first, then only the relevant map sections — before any broad scan.
+2. VERIFY stale or high-risk facts against the repository before consequential actions.
+3. Loops: the orchestrator passes relevant setup-map facts into role prompts at craft time; users never repeat project facts per loop.
+4. SUGGEST `/oris-flow` → Setup refresh only when a stale gap materially affects the task.
+5. Refresh policy is advisory — never a scheduler.
+
+## 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.

package/references/repo-map.schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oris.dev/schemas/oris-flow-map-v1.json",
+  "title": "Oris Flow Repository Map",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "repository",
+    "generatedAt",
+    "updatedAt",
+    "setup",
+    "sections"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "https://oris.dev/schemas/oris-flow-map-v1.json"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "repository": {
+      "type": "string",
+      "minLength": 1
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "mapVersion": {
+      "type": "string",
+      "minLength": 1
+    },
+    "setup": {
+      "$ref": "#/$defs/setup"
+    },
+    "refreshPolicy": {
+      "$ref": "#/$defs/refreshPolicy"
+    },
+    "sections": {
+      "$ref": "#/$defs/sections"
+    },
+    "stacks": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/stack"
+      }
+    },
+    "commands": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/detectedCommand"
+      }
+    }
+  },
+  "$defs": {
+    "confidence": {
+      "type": "string",
+      "enum": ["confirmed", "detected", "inferred", "stale"]
+    },
+    "sectionPointer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "confidence"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^\\.oris-flow/"
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        },
+        "lastScannedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "stale": {
+          "type": "boolean"
+        },
+        "summary": {
+          "type": "string"
+        }
+      }
+    },
+    "sections": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/sectionPointer"
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-zA-Z0-9-]*$"
+      }
+    },
+    "refreshPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["manual", "monthly", "after-major-refactor", "after-test-layout-change"]
+        },
+        "suggestAfterDays": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "triggers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["after-major-refactor", "after-test-layout-change"]
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "setup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "scanDepth"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["create", "refresh", "review-stale", "update-area", "summary"]
+        },
+        "scanDepth": {
+          "type": "string",
+          "enum": ["fast", "balanced", "manual-summary"]
+        },
+        "confirmedDecisions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tradeOff": {
+          "type": "string"
+        },
+        "versionControl": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "orisFlowMap": {
+              "type": "string",
+              "enum": ["commit", "gitignore"]
+            }
+          }
+        }
+      }
+    },
+    "stack": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "label", "evidence"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "detectedCommand": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "cwd", "command", "evidence"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "cwd": {
+          "type": "string"
+        },
+        "command": {
+          "type": "string"
+        },
+        "evidence": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}