loopmath 0.1.0__tar.gz → 0.2.0__tar.gz

{loopmath-0.1.0 → loopmath-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopmath
-Version: 0.1.0
+Version: 0.2.0
 Summary: Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs
 Author: QKV Labs
 License-Expression: MIT
@@ -65,17 +65,31 @@ python3 -m venv .venv
 ## First run
 
 ```sh
-loopmath doctor                        # what loopmath can see: logs, agents, store, fit, prices, skill
-loopmath skill install --target both   # teach Claude Code and Codex how to use loopmath
+loopmath skill install      # teach your coding agents how to use loopmath
 ```
 
-`skill install` writes one `SKILL.md` for Claude Code (under `~/.claude/skills/loopmath/`) and one for Codex (under `~/.codex/skills/loopmath/`). If your Codex has no skills folder, it writes the file to `~/.codex/loopmath/SKILL.md` instead and adds a short marked block to `~/.codex/AGENTS.md` that points to it. Add `--scope project` to install into the current repository. It is safe to run again, and it rewrites only its own files. `loopmath skill uninstall` removes them.
+Then ask your agent to onboard, for example "onboard loopmath". The agent runs a dry run, asks you one question (which model labels your sessions, with the cost of each option), onboards, fits, and opens the results page.
 
-Next, turn your history into a starting point:
+`skill install` writes six skills, one per job, and a shared `reference.md` with every command and JSON field they use. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
+
+| Skill | Ask your agent |
+|---|---|
+| `loopmath` | loopmath named without a job: "use loopmath", "what can loopmath do", "what next with loopmath" |
+| `loopmath-onboard` | "onboard", "set up", "start" or "try" loopmath; or loopmath has no runs yet |
+| `loopmath-import-runs` | OCP files (`*.ocp.json`), a folder of finished runs, or the output of an orchestrator or experiment harness that writes OCP |
+| `loopmath-update-fit` | "update", "refresh" or "rerun" the fit; what loopmath learned; runs imported or recorded without a refit |
+| `loopmath-plan-task` | "plan a task with loopmath"; which workflow, model or effort to use; a coding task of more than a few minutes in a repo that uses loopmath |
+| `loopmath-record-run` | a task planned with loopmath is done; "record", "log" or "save" a run; both runs of a pair need a blind judge |
+
+By default the skills go to every agent whose home exists: Claude Code (`~/.claude/skills/<name>/`, or under `$CLAUDE_CONFIG_DIR`) and Codex (`~/.codex/skills/<name>/`, or under `$CODEX_HOME`). `--target claude-code`, `codex` or `both` picks them yourself. If your Codex has no skills folder, the files go to `~/.codex/loopmath/<name>/` instead, with a short marked block in `~/.codex/AGENTS.md` that lists them. Add `--scope project` to install into the current repository (or `--dir PATH` for another one).
+
+It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills.
+
+To onboard by hand instead:
 
 ```sh
-loopmath onboard --labeler claude:claude-haiku-4-5 --dry-run    # see what it found and what labelling costs
-loopmath onboard --labeler claude:claude-haiku-4-5 --yes        # record it and run a first fit
+loopmath onboard --dry-run                                  # what it found, and what each labeller costs
+loopmath onboard --labeler claude:claude-haiku-4-5 --yes    # record it and run a first fit
 ```
 
 `onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository, and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
@@ -85,17 +99,28 @@ loopmath onboard --labeler claude:claude-haiku-4-5 --yes        # record it and
 - `command:<cmd>`, any local command such as `command:ollama run <model>`, so nothing leaves the machine;
 - `none`, to skip labelling.
 
+Reading the history uses up to 8 worker processes (one per CPU, at most 8). Set `LOOPMATH_WORKERS=1` to keep everything in one process, or another number to change the count.
+
 loopmath ships with a prior built from our own sweeps and experiments, so `recommend` gives an answer before you have any history. Your own runs then move it.
 
 ## The loop
 
-The skill tells an orchestrator agent to follow these steps. You can run the same commands by hand.
+The plan and record skills take an agent through the loop in three commands:
+
+```sh
+loopmath recommend --type bug_fix --repo acme/api --title "Fix the parser crash" --json --brief --html
+loopmath run start --rec REC --choice goal --base-commit SHA --json      # the harness, model and effort per piece
+loopmath run record --run RUN --session UUID --verified tests=pass --json  # costs from the logs, the outcome, the receipt
+```
+
+The same loop step by step, for a tool of your own:
 
 ```sh
 # 1. Plan: classify the task, then ask.
 loopmath task-types
 loopmath recommend --type bug_fix --repo acme/api --feature size=s --feature lang=python --json
-#    the usual workflow, the success-cost curve, alternatives, two exploration picks, a suggested pair
+#    the usual workflow (without one, your best recorded workflow is the reference), the success-cost curve,
+#    alternatives, two exploration picks, a suggested pair
 
 # 2. Record: one run per workflow you run, one attempt per agent you launch.
 loopmath run start --type bug_fix --repo acme/api --base-commit SHA --config CFG --source usual --rec REC
@@ -119,6 +144,8 @@ A pair runs the goal workflow and an exploration pick from the same base commit,
 
 A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE`, and the spending cap with `loopmath budget --usd X --period month`.
 
+Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
+
 ## The three views
 
 Each view is a self-contained HTML file written by a command; there is no server. The same numbers are available with `--json`.
@@ -133,9 +160,9 @@ Without a path, `--html` writes the page under `~/.loopmath/views/` and prints w
 
 | Group | Commands |
 |---|---|
-| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend`, `plan` |
+| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend` |
 | Record | `run` (start, attempt, artifact, finish, import), `outcome`, `budget`, `config` (get, set) |
-| Learn | `fit`, `onboard`, `share` |
+| Learn | `fit`, `onboard`, `share`, `prior` |
 | View | `runs`, `posterior`, `status`, `report`, `doctor` |
 | Skill | `skill` (install, uninstall, show) |
 | OCP | `ocp` (validate, migrate) |
@@ -230,7 +257,7 @@ loopmath graph --workspace NAME --format html --out graph.html
 
 ## More
 
-- [OCP, the run format](spec/OCP.md), with its [schemas](spec/) and [versioning promise](spec/VERSIONING.md)
+- [OCP, the run format](spec/OCP.md): the normative note that goes with the [schemas](spec/), and the [versioning promise](spec/VERSIONING.md)
 - [Release policy](docs/release.md)
 - [Packaged model prices](src/loopmath/prices.toml)
 

{loopmath-0.1.0 → loopmath-0.2.0}/README.md

@@ -27,17 +27,31 @@ python3 -m venv .venv
 ## First run
 
 ```sh
-loopmath doctor                        # what loopmath can see: logs, agents, store, fit, prices, skill
-loopmath skill install --target both   # teach Claude Code and Codex how to use loopmath
+loopmath skill install      # teach your coding agents how to use loopmath
 ```
 
-`skill install` writes one `SKILL.md` for Claude Code (under `~/.claude/skills/loopmath/`) and one for Codex (under `~/.codex/skills/loopmath/`). If your Codex has no skills folder, it writes the file to `~/.codex/loopmath/SKILL.md` instead and adds a short marked block to `~/.codex/AGENTS.md` that points to it. Add `--scope project` to install into the current repository. It is safe to run again, and it rewrites only its own files. `loopmath skill uninstall` removes them.
+Then ask your agent to onboard, for example "onboard loopmath". The agent runs a dry run, asks you one question (which model labels your sessions, with the cost of each option), onboards, fits, and opens the results page.
 
-Next, turn your history into a starting point:
+`skill install` writes six skills, one per job, and a shared `reference.md` with every command and JSON field they use. An agent loads only the skill for the job at hand, and each phrase belongs to one skill:
+
+| Skill | Ask your agent |
+|---|---|
+| `loopmath` | loopmath named without a job: "use loopmath", "what can loopmath do", "what next with loopmath" |
+| `loopmath-onboard` | "onboard", "set up", "start" or "try" loopmath; or loopmath has no runs yet |
+| `loopmath-import-runs` | OCP files (`*.ocp.json`), a folder of finished runs, or the output of an orchestrator or experiment harness that writes OCP |
+| `loopmath-update-fit` | "update", "refresh" or "rerun" the fit; what loopmath learned; runs imported or recorded without a refit |
+| `loopmath-plan-task` | "plan a task with loopmath"; which workflow, model or effort to use; a coding task of more than a few minutes in a repo that uses loopmath |
+| `loopmath-record-run` | a task planned with loopmath is done; "record", "log" or "save" a run; both runs of a pair need a blind judge |
+
+By default the skills go to every agent whose home exists: Claude Code (`~/.claude/skills/<name>/`, or under `$CLAUDE_CONFIG_DIR`) and Codex (`~/.codex/skills/<name>/`, or under `$CODEX_HOME`). `--target claude-code`, `codex` or `both` picks them yourself. If your Codex has no skills folder, the files go to `~/.codex/loopmath/<name>/` instead, with a short marked block in `~/.codex/AGENTS.md` that lists them. Add `--scope project` to install into the current repository (or `--dir PATH` for another one).
+
+It is safe to run again. It records the files it wrote, with their hashes, in `.loopmath-skills.json` beside the skill folders, and it replaces or removes only those. A skill file you changed is kept, with a note. Any other file where a skill goes stops the install before it writes anything, and names the path to move aside. The single skill that 0.1 installed is replaced when it is as 0.1 wrote it. `loopmath skill show NAME` prints one skill, and `loopmath skill uninstall` removes the files it wrote. `loopmath doctor` shows what loopmath can see: logs, agents, store, fit, prices and skills.
+
+To onboard by hand instead:
 
 ```sh
-loopmath onboard --labeler claude:claude-haiku-4-5 --dry-run    # see what it found and what labelling costs
-loopmath onboard --labeler claude:claude-haiku-4-5 --yes        # record it and run a first fit
+loopmath onboard --dry-run                                  # what it found, and what each labeller costs
+loopmath onboard --labeler claude:claude-haiku-4-5 --yes    # record it and run a first fit
 ```
 
 `onboard` reads your recent Claude Code and Codex sessions (the last 90 days unless you pass `--since`). It groups them into runs, labels each group's task type with a model you choose, names your usual workflow per task type and repository, and fits. loopmath never picks the labelling model for you. `--labeler` takes one of:
@@ -47,17 +61,28 @@ loopmath onboard --labeler claude:claude-haiku-4-5 --yes        # record it and
 - `command:<cmd>`, any local command such as `command:ollama run <model>`, so nothing leaves the machine;
 - `none`, to skip labelling.
 
+Reading the history uses up to 8 worker processes (one per CPU, at most 8). Set `LOOPMATH_WORKERS=1` to keep everything in one process, or another number to change the count.
+
 loopmath ships with a prior built from our own sweeps and experiments, so `recommend` gives an answer before you have any history. Your own runs then move it.
 
 ## The loop
 
-The skill tells an orchestrator agent to follow these steps. You can run the same commands by hand.
+The plan and record skills take an agent through the loop in three commands:
+
+```sh
+loopmath recommend --type bug_fix --repo acme/api --title "Fix the parser crash" --json --brief --html
+loopmath run start --rec REC --choice goal --base-commit SHA --json      # the harness, model and effort per piece
+loopmath run record --run RUN --session UUID --verified tests=pass --json  # costs from the logs, the outcome, the receipt
+```
+
+The same loop step by step, for a tool of your own:
 
 ```sh
 # 1. Plan: classify the task, then ask.
 loopmath task-types
 loopmath recommend --type bug_fix --repo acme/api --feature size=s --feature lang=python --json
-#    the usual workflow, the success-cost curve, alternatives, two exploration picks, a suggested pair
+#    the usual workflow (without one, your best recorded workflow is the reference), the success-cost curve,
+#    alternatives, two exploration picks, a suggested pair
 
 # 2. Record: one run per workflow you run, one attempt per agent you launch.
 loopmath run start --type bug_fix --repo acme/api --base-commit SHA --config CFG --source usual --rec REC
@@ -81,6 +106,8 @@ A pair runs the goal workflow and an exploration pick from the same base commit,
 
 A run counts as a success when it is accepted under your rule. By default that means the task's tests pass. A rule can also be a score target: `loopmath recommend ... --target 'heldout_perf>=2400'` or `--target 'runtime_s<=200'` gives the expected score and the chance of reaching the target. Set standing rules and other options with `loopmath config set KEY VALUE`, and the spending cap with `loopmath budget --usd X --period month`.
 
+Runs recorded by another tool that writes OCP v0.3, such as an experiment runner, come in with `loopmath run import DIR --finish`: several files or a directory, with one refit at the end (`--no-fit` skips it). Runs in your store always count as yours, whatever source their documents name. `loopmath fit --without SOURCE` leaves out one shipped prior source, and `loopmath status` names the options of the current fit.
+
 ## The three views
 
 Each view is a self-contained HTML file written by a command; there is no server. The same numbers are available with `--json`.
@@ -95,9 +122,9 @@ Without a path, `--html` writes the page under `~/.loopmath/views/` and prints w
 
 | Group | Commands |
 |---|---|
-| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend`, `plan` |
+| Plan | `task-types`, `workflows` (list, show, validate, diff), `recommend` |
 | Record | `run` (start, attempt, artifact, finish, import), `outcome`, `budget`, `config` (get, set) |
-| Learn | `fit`, `onboard`, `share` |
+| Learn | `fit`, `onboard`, `share`, `prior` |
 | View | `runs`, `posterior`, `status`, `report`, `doctor` |
 | Skill | `skill` (install, uninstall, show) |
 | OCP | `ocp` (validate, migrate) |
@@ -192,7 +219,7 @@ loopmath graph --workspace NAME --format html --out graph.html
 
 ## More
 
-- [OCP, the run format](spec/OCP.md), with its [schemas](spec/) and [versioning promise](spec/VERSIONING.md)
+- [OCP, the run format](spec/OCP.md): the normative note that goes with the [schemas](spec/), and the [versioning promise](spec/VERSIONING.md)
 - [Release policy](docs/release.md)
 - [Packaged model prices](src/loopmath/prices.toml)
 

{loopmath-0.1.0 → loopmath-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopmath"
-version = "0.1.0"
+version = "0.2.0"
 description = "Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs"
 readme = "README.md"
 license = "MIT"
@@ -88,7 +88,8 @@ where = ["src"]
 loopmath = [
     "prices.toml",
     "workflows/catalog/*.toml",
-    "skill/SKILL.md",
+    "skill/skills/*.md",
+    "skill/skills/*/SKILL.md",
     "priors/*.toml",
     "priors/bundle/*",
     "views/assets/*",

{loopmath-0.1.0 → loopmath-0.2.0}/spec/ocp-v0.2.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "urn:ocp:run:0.2",
   "title": "OCP v0.2 run document",
-  "description": "Orchestration Context Protocol v0.2. One JSON document describes one orchestration run: DAG topology (nodes, edges), per-node attempts with model and reasoning-effort labels, token cost records, acceptance outcomes with evidence tiers, timestamps, producer identity, and a declared privacy profile. v0.2 adds, over v0.1: an 'artifacts' entity (files one attempt wrote and others read) with 'artifact' edges; the 'launch' edge kind (one harness starting another through its CLI, distinct from in-harness 'spawn'); attempt 'origin', 'role' and 'phase' records, each with an evidence tier; cost fields for the 5-minute and 1-hour cache-creation buckets; and a 'tier' on every edge. Unknown fields are ignored by consumers (forward compatibility); the sanctioned place for producer-specific data is the 'ext' object present on every entity, with dotted-namespace keys such as 'dev.dagr.graph'. String vocabularies are open sets with recommended lists except for evidence tier, privacy profile, attempt status and outcome result. Referential rules a consumer must check that JSON Schema cannot express: edge endpoints and attempt.node name existing node ids; group.parent edges are acyclic; dep and fan_in edges form a DAG (spawn, launch and artifact edges are exempt); event refs name existing nodes/attempts; terminal attempt statuses agree with outcome.result; artifact producer/writers/consumers and origin.launched_by name existing attempts; an 'artifact' edge names an existing artifact and its from_attempt/to_attempt (both required) belong to its from/to nodes, from_attempt is the artifact's producer and to_attempt is one of its consumers; artifact.producer equals writers[0], writers is non-empty with no duplicates, a non-null n_writes is at least the number of writers and a non-null n_reads at least the number of consumers (a null count is unknown and is neither checked nor counted as satisfying); attempts need not carry origin, role or phase, but each record present carries every listed field, with null for unknowns; an attempt whose origin names a launcher has a matching 'launch' edge, and origin.external true together with a non-null launched_by is a contradiction; cache_creation_5m_tokens + cache_creation_1h_tokens equals cache_creation_tokens when all three are present; every edge carries a tier, whoever the producer is; when the producer is the extractor (producer.name 'dagr', optionally suffixed after a non-word character) every cost record has basis 'measured'; under privacy profile 'metadata_only' no free-text field may contain prompt or transcript text. Every one of these is a conformance error, not a warning. Values outside recommended vocabularies produce warnings. The reference checker for these rules ships at spec/ocp_conformance.py.",
+  "description": "Orchestration Context Protocol v0.2. One JSON document describes one orchestration run: DAG topology (nodes, edges), per-node attempts with model and reasoning-effort labels, token cost records, acceptance outcomes with evidence tiers, timestamps, producer identity, and a declared privacy profile. v0.2 adds, over v0.1: an 'artifacts' entity (files one attempt wrote and others read) with 'artifact' edges; the 'launch' edge kind (one harness starting another through its CLI, distinct from in-harness 'spawn'); attempt 'origin', 'role' and 'phase' records, each with an evidence tier; cost fields for the 5-minute and 1-hour cache-creation buckets; and a 'tier' on every edge. Unknown fields are ignored by consumers (forward compatibility); the sanctioned place for producer-specific data is the 'ext' object present on every entity, with dotted-namespace keys such as 'com.example.graph'. String vocabularies are open sets with recommended lists except for evidence tier, privacy profile, attempt status and outcome result. Referential rules a consumer must check that JSON Schema cannot express: edge endpoints and attempt.node name existing node ids; group.parent edges are acyclic; dep and fan_in edges form a DAG (spawn, launch and artifact edges are exempt); event refs name existing nodes/attempts; terminal attempt statuses agree with outcome.result; artifact producer/writers/consumers and origin.launched_by name existing attempts; an 'artifact' edge names an existing artifact and its from_attempt/to_attempt (both required) belong to its from/to nodes, from_attempt is the artifact's producer and to_attempt is one of its consumers; artifact.producer equals writers[0], writers is non-empty with no duplicates, a non-null n_writes is at least the number of writers and a non-null n_reads at least the number of consumers (a null count is unknown and is neither checked nor counted as satisfying); attempts need not carry origin, role or phase, but each record present carries every listed field, with null for unknowns; an attempt whose origin names a launcher has a matching 'launch' edge, and origin.external true together with a non-null launched_by is a contradiction; cache_creation_5m_tokens + cache_creation_1h_tokens equals cache_creation_tokens when all three are present; every edge carries a tier, whoever the producer is; when the producer is the extractor (producer.name 'loopmath', or 'dagr' before the rename, optionally suffixed after a non-word character) every cost record has basis 'measured'; under privacy profile 'metadata_only' no free-text field may contain prompt or transcript text. Every one of these is a conformance error, not a warning. Values outside recommended vocabularies produce warnings. The reference checker for these rules ships at spec/ocp_conformance.py.",
   "type": "object",
   "required": ["ocp", "producer", "privacy", "run", "nodes"],
   "properties": {
@@ -16,7 +16,7 @@
     "groups": {
       "type": "array",
       "items": { "$ref": "#/$defs/group" },
-      "description": "Optional named visual/organizational scopes (contract v3 'projects'). Grouping is orthogonal to dependency structure."
+      "description": "Optional named visual/organizational scopes, such as projects. Grouping is orthogonal to dependency structure."
     },
     "nodes": {
       "type": "array",
@@ -63,7 +63,7 @@
     },
     "ext": {
       "type": "object",
-      "description": "Producer-specific extension data. Keys should be dotted-namespaced, e.g. 'dev.dagr.graph', 'langgraph.thread_id'. Consumers must ignore namespaces they do not understand."
+      "description": "Producer-specific extension data. Keys should be dotted-namespaced, e.g. 'com.example.graph', 'langgraph.thread_id'. Consumers must ignore namespaces they do not understand."
     },
     "evidenceTier": {
       "enum": ["verified", "heuristic", "reported"],
@@ -73,11 +73,11 @@
       "type": "object",
       "required": ["name"],
       "properties": {
-        "name": { "type": "string", "maxLength": 200, "description": "The emitting software (plugin or converter), e.g. 'ocp-from-contractv3'. The dagr extractor uses 'dagr' (optionally suffixed after a non-word character, e.g. 'dagr/graph'); that name switches on the extractor-only rule (cost.basis 'measured')." },
+        "name": { "type": "string", "maxLength": 200, "description": "The emitting software (plugin or converter), e.g. 'my-orchestrator-ocp'. loopmath's log extractor names itself 'loopmath' ('dagr' in documents written before its rename), optionally suffixed after a non-word character, e.g. 'loopmath/graph'; that name switches on the extractor-only rule E171 (cost.basis 'measured')." },
         "version": { "type": "string", "maxLength": 100 },
-        "framework": { "type": "string", "maxLength": 200, "description": "The orchestration framework the run executed under, e.g. 'herdr-dagr', 'claude-code', 'langgraph', 'crewai'." },
+        "framework": { "type": "string", "maxLength": 200, "description": "The orchestration framework the run executed under, e.g. 'my-orchestrator', 'claude-code', 'langgraph', 'crewai'." },
         "framework_version": { "type": "string", "maxLength": 100 },
-        "source_contract": { "type": "string", "maxLength": 200, "description": "Upstream native format this document was derived from, e.g. 'dagr/3' or 'dagr_graph/1'." },
+        "source_contract": { "type": "string", "maxLength": 200, "description": "Upstream native format this document was derived from, e.g. 'my-orchestrator/1.2'." },
         "emitted_at": { "$ref": "#/$defs/timestamp" },
         "capabilities": {
           "type": "object",
@@ -153,7 +153,7 @@
           "x-recommended": ["queued", "working", "review", "blocked", "done", "failed", "rejected", "canceled", "settled_unverified"],
           "$comment": "This list is recommended vocabulary; readers must accept other values.",
           "maxLength": 100,
-          "description": "Producer's current projection over the node's attempts. Recommended vocabulary (from dagr contract v3): queued, working, review, blocked, done, failed, rejected, canceled, settled_unverified. Consumers learning from settled runs should trust attempt outcomes over this field."
+          "description": "Producer's current projection over the node's attempts. Recommended vocabulary: queued, working, review, blocked, done, failed, rejected, canceled, settled_unverified. Consumers learning from settled runs should trust attempt outcomes over this field."
         },
         "labels": { "$ref": "#/$defs/labels" },
         "ext": { "$ref": "#/$defs/ext" }
@@ -161,7 +161,7 @@
     },
     "edge": {
       "type": "object",
-      "$comment": "'tier' is required on every edge of a v0.2 document, whatever its kind (dep, fan_in, spawn, launch, artifact) and whoever the producer is. EXTRACTOR-SPEC section 5, P1 amendment (b), settled 14:15 by the Analyst: attempts 2 and 4 were reviewed to opposite readings of the sentence; the stricter one stands. Its value is one of evidenceTier's three words and nothing else.",
+      "$comment": "'tier' is required on every edge of a v0.2 document, whatever its kind (dep, fan_in, spawn, launch, artifact) and whoever the producer is. Its value is one of evidenceTier's three words and nothing else.",
       "required": ["from", "to", "tier"],
       "properties": {
         "from": { "type": "string", "maxLength": 200, "description": "Source node id (the prerequisite / input / spawner / launcher / producer's node)." },
@@ -193,7 +193,7 @@
           "type": "object",
           "required": ["value", "tier"],
           "properties": {
-            "value": { "type": ["string", "null"], "x-recommended": ["plan", "review", "spec", "report", "code", "test", "config", "doc", "data", "log", "other"], "$comment": "This list is recommended vocabulary; readers must accept other values.", "maxLength": 100, "description": "Open set. Recommended vocabulary: plan, review, spec, report, code, test, config, doc, data, log, other. null when the kind is unknown (amendment (b), settled 14:15); the key is always present and the tier stays required beside it." },
+            "value": { "type": ["string", "null"], "x-recommended": ["plan", "review", "spec", "report", "code", "test", "config", "doc", "data", "log", "other"], "$comment": "This list is recommended vocabulary; readers must accept other values.", "maxLength": 100, "description": "Open set. Recommended vocabulary: plan, review, spec, report, code, test, config, doc, data, log, other. null when the kind is unknown; the key is always present and the tier stays required beside it." },
             "tier": { "$ref": "#/$defs/evidenceTier" },
             "evidence": { "$ref": "#/$defs/shortText", "description": "What the kind was inferred from, e.g. 'path pattern' or 'heredoc first line'." },
             "ext": { "$ref": "#/$defs/ext" }
@@ -213,7 +213,7 @@
           "items": { "type": "string", "maxLength": 200 },
           "description": "Attempt ids that read the artifact after a write by another attempt, in first-read order, each listed once. May be empty (written, never read by another attempt)."
         },
-        "first_write_at": { "anyOf": [{ "$ref": "#/$defs/timestamp" }, { "type": "null" }], "description": "Timestamp of the first write event; null when the producer cannot compute it. The key is always present (amendment 13:10 (a)): unknown is an explicit null, never an absent key." },
+        "first_write_at": { "anyOf": [{ "$ref": "#/$defs/timestamp" }, { "type": "null" }], "description": "Timestamp of the first write event; null when the producer cannot compute it. The key is always present: unknown is an explicit null, never an absent key." },
         "n_writes": { "type": ["integer", "null"], "minimum": 1, "description": "Number of write events across all writers; null when the producer cannot count them. A known count must be at least the number of writers; a smaller count undercounts and is a conformance error. A null count is unknown: it neither satisfies nor fails that check." },
         "n_reads": { "type": ["integer", "null"], "minimum": 0, "description": "Number of read events across all consumers; null when the producer cannot count them. A known count must be at least the number of consumers; a smaller count undercounts and is a conformance error. A null count is unknown: it neither satisfies nor fails that check." },
         "labels": { "$ref": "#/$defs/labels" },
@@ -241,7 +241,7 @@
       "description": "What the attempt did in the run. All three fields are present; evidence is null when there is nothing to cite.",
       "required": ["value", "tier", "evidence"],
       "properties": {
-        "value": { "type": ["string", "null"], "x-recommended": ["lead", "solo", "planner", "dev", "reviewer", "cli", "subagent"], "$comment": "This list is recommended vocabulary; readers must accept other values.", "maxLength": 100, "description": "Open set. Recommended vocabulary: lead (top-level session that spawned or launched others), solo (top-level session that did not), planner, dev, reviewer, cli (launched through a CLI with no role signal), subagent. null when the role is unknown (amendment (b), settled 14:15); the key is always present and the tier stays required beside it." },
+        "value": { "type": ["string", "null"], "x-recommended": ["lead", "solo", "planner", "dev", "reviewer", "cli", "subagent"], "$comment": "This list is recommended vocabulary; readers must accept other values.", "maxLength": 100, "description": "Open set. Recommended vocabulary: lead (top-level session that spawned or launched others), solo (top-level session that did not), planner, dev, reviewer, cli (launched through a CLI with no role signal), subagent. null when the role is unknown; the key is always present and the tier stays required beside it." },
         "tier": { "$ref": "#/$defs/evidenceTier" },
         "evidence": { "anyOf": [{ "$ref": "#/$defs/shortText" }, { "type": "null" }], "description": "What the label rests on, e.g. \"declared type 'Plan'\" or 'launch command mentions review'; null when nothing can be cited." },
         "ext": { "$ref": "#/$defs/ext" }
@@ -252,7 +252,7 @@
       "description": "When in the run the attempt happened. All three fields are present; evidence is null when there is nothing to cite.",
       "required": ["value", "tier", "evidence"],
       "properties": {
-        "value": { "type": ["string", "null"], "x-recommended": ["build", "post", "external"], "$comment": "This list is recommended vocabulary; readers must accept other values.", "maxLength": 100, "description": "Open set. Recommended vocabulary: build (during the lead's activity), post (after the lead ended, e.g. a post-build review), external (outside the run's workspace). null when the phase is unknown (amendment (b), settled 14:15); the key is always present and the tier stays required beside it." },
+        "value": { "type": ["string", "null"], "x-recommended": ["build", "post", "external"], "$comment": "This list is recommended vocabulary; readers must accept other values.", "maxLength": 100, "description": "Open set. Recommended vocabulary: build (during the lead's activity), post (after the lead ended, e.g. a post-build review), external (outside the run's workspace). null when the phase is unknown; the key is always present and the tier stays required beside it." },
         "tier": { "$ref": "#/$defs/evidenceTier" },
         "evidence": { "anyOf": [{ "$ref": "#/$defs/shortText" }, { "type": "null" }], "description": "What the label rests on; null when nothing can be cited." },
         "ext": { "$ref": "#/$defs/ext" }
@@ -261,7 +261,7 @@
     "modelRef": {
       "type": "object",
       "properties": {
-        "raw": { "type": "string", "maxLength": 200, "description": "The label exactly as the producer knew it, always preserved (e.g. 'fable·xhigh', 'opus5.xhigh'). Canonicalization is the consumer's job; the raw label is the ground truth." },
+        "raw": { "type": "string", "maxLength": 200, "description": "The label exactly as the producer knew it, always preserved (e.g. 'opus5.xhigh'). A label the source wrote with the effort in it, such as 'fable·xhigh', is kept as written; a producer never builds one itself (see effort). Canonicalization is the consumer's job; the raw label is the ground truth." },
         "id": { "type": "string", "maxLength": 200, "description": "Canonical provider model id when known, e.g. 'claude-fable-5'." },
         "family": { "type": "string", "maxLength": 100, "description": "Coarse family label for grouping attempts by model family, e.g. 'fable', 'opus5', 'sol5.6'." },
         "provider": { "type": "string", "maxLength": 100, "description": "e.g. 'anthropic', 'openai'." },
@@ -278,8 +278,8 @@
         "cache_creation_tokens": { "type": "integer", "minimum": 0, "description": "Input tokens written to cache, all retention buckets together, when the provider bills them separately. When the two bucket fields are also present their sum must equal this." },
         "cache_creation_5m_tokens": { "type": "integer", "minimum": 0, "description": "Cache-creation tokens in the 5-minute retention bucket." },
         "cache_creation_1h_tokens": { "type": "integer", "minimum": 0, "description": "Cache-creation tokens in the 1-hour retention bucket, priced higher than the 5-minute bucket." },
-        "output_tokens": { "type": "integer", "minimum": 0 },
-        "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "Thinking/reasoning tokens when the provider reports them separately from output." },
+        "output_tokens": { "type": "integer", "minimum": 0, "description": "Output tokens, reasoning (thinking) tokens included. When the source reports reasoning separately from output, the producer adds it in here." },
+        "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "The reasoning (thinking) share of output_tokens, as a breakdown: output_tokens already includes these tokens, so a reader never adds the two." },
         "requests": { "type": "integer", "minimum": 0, "description": "Number of model API requests aggregated into this record." },
         "usd": { "type": "number", "minimum": 0, "description": "Billed cost in US dollars when the producer knows it. Consumers should prefer recomputing from tokens and a dated price table." },
         "basis": {
@@ -319,7 +319,7 @@
           "type": "string",
           "x-recommended": ["verified", "reported", "heuristic", "asserted"],
           "$comment": "This list is recommended vocabulary; readers must accept other values.",
-          "description": "How the result is known (dagr contract v3 tiers). verified: mechanically checked (tests, provenance receipt). reported: the actor asserted it through a typed envelope. heuristic: inferred. asserted: bare claim. Missing evidence must be treated as 'asserted', never upgraded."
+          "description": "How the result is known. verified: mechanically checked (tests, provenance receipt). reported: the actor asserted it through a typed envelope. heuristic: inferred. asserted: bare claim. Missing evidence must be treated as 'asserted', never upgraded."
         },
         "via": { "type": "string", "maxLength": 200, "description": "Node id of the gate or review that produced this acceptance signal, when one did." },
         "receipt": { "$ref": "#/$defs/shortText" },
@@ -329,7 +329,7 @@
     },
     "attempt": {
       "type": "object",
-      "$comment": "origin, role and phase are deliberately NOT in 'required'. EXTRACTOR-SPEC section 5, P1 amendment 13:10 (a), Clarified 13:40: 'Attempts are NOT required to carry origin, role or phase at all (a v0.1 attempt has none); the extractor's own output always carries all three, and P2 is where that is enforced, not the schema.' Once one of the three records is present, every field listed for it is required inside that record (see the origin, role and phase definitions).",
+      "$comment": "origin, role and phase are deliberately NOT in 'required': an attempt need not carry origin, role or phase at all (a v0.1 attempt has none); the extractor's own output always carries all three, and the extractor, not the schema, enforces that. Once one of the three records is present, every field listed for it is required inside that record (see the origin, role and phase definitions).",
       "required": ["id", "node", "status"],
       "properties": {
         "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique within the document." },
@@ -338,7 +338,7 @@
         "actor": { "type": "string", "maxLength": 200, "description": "Logical agent/role that ran the attempt (not a volatile runtime locator)." },
         "harness": { "type": "string", "maxLength": 100, "description": "The agent harness that ran the attempt, e.g. 'claude-code', 'codex'." },
         "model": { "$ref": "#/$defs/modelRef" },
-        "effort": { "type": "string", "maxLength": 100, "description": "Reasoning-effort label as configured, e.g. low, medium, high, xhigh, max. Open set; producers must not fold it into the model label." },
+        "effort": { "type": "string", "maxLength": 100, "description": "Reasoning-effort label as configured, e.g. low, medium, high, xhigh, max. Open set. Producers must not fold it into the model label: a producer never builds a fused label such as 'fable·xhigh' itself. When the source already wrote one, model.raw keeps it as written, and effort known separately goes here." },
         "cause": { "$ref": "#/$defs/cause" },
         "origin": { "$ref": "#/$defs/origin", "description": "How this attempt came to run: which scanned attempt launched it through a CLI, in which workspace, or that an unscanned program did." },
         "role": { "$ref": "#/$defs/role", "description": "What part the attempt played in the run (lead, planner, dev, reviewer, ...), with the tier and evidence the label rests on." },

{loopmath-0.1.0 → loopmath-0.2.0}/spec/ocp-v0.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "urn:ocp:run:0.1",
   "title": "OCP v0 run document",
-  "description": "Orchestration Context Protocol v0. One JSON document describes one orchestration run: DAG topology (nodes, edges), per-node attempts with model and reasoning-effort labels, token cost records, acceptance outcomes with evidence tiers, timestamps, producer identity, and a declared privacy profile. Unknown fields are ignored by consumers (forward compatibility); the sanctioned place for producer-specific data is the 'ext' object present on every entity, with dotted-namespace keys such as 'dev.dagr.policy'. Referential rules a consumer must check that JSON Schema cannot express: edge endpoints and attempt.node name existing node ids, group.parent edges are acyclic, dep and fan_in edges form a DAG, event refs name existing nodes/attempts, terminal attempt statuses agree with outcome.result, and under privacy profile 'metadata_only' no free-text field may contain prompt or transcript text. A reference checker for these rules ships at spec/ocp_conformance.py.",
+  "description": "Orchestration Context Protocol v0. One JSON document describes one orchestration run: DAG topology (nodes, edges), per-node attempts with model and reasoning-effort labels, token cost records, acceptance outcomes with evidence tiers, timestamps, producer identity, and a declared privacy profile. Unknown fields are ignored by consumers (forward compatibility); the sanctioned place for producer-specific data is the 'ext' object present on every entity, with dotted-namespace keys such as 'com.example.policy'. Referential rules a consumer must check that JSON Schema cannot express: edge endpoints and attempt.node name existing node ids, group.parent edges are acyclic, dep and fan_in edges form a DAG, event refs name existing nodes/attempts, terminal attempt statuses agree with outcome.result, and under privacy profile 'metadata_only' no free-text field may contain prompt or transcript text. A reference checker for these rules ships at spec/ocp_conformance.py.",
   "type": "object",
   "required": ["ocp", "producer", "privacy", "run", "nodes"],
   "properties": {
@@ -16,7 +16,7 @@
     "groups": {
       "type": "array",
       "items": { "$ref": "#/$defs/group" },
-      "description": "Optional named visual/organizational scopes (contract v3 'projects'). Grouping is orthogonal to dependency structure."
+      "description": "Optional named visual/organizational scopes, such as projects. Grouping is orthogonal to dependency structure."
     },
     "nodes": {
       "type": "array",
@@ -58,17 +58,17 @@
     },
     "ext": {
       "type": "object",
-      "description": "Producer-specific extension data. Keys should be dotted-namespaced, e.g. 'dev.dagr.policy', 'langgraph.thread_id'. Consumers must ignore namespaces they do not understand."
+      "description": "Producer-specific extension data. Keys should be dotted-namespaced, e.g. 'com.example.policy', 'langgraph.thread_id'. Consumers must ignore namespaces they do not understand."
     },
     "producer": {
       "type": "object",
       "required": ["name"],
       "properties": {
-        "name": { "type": "string", "maxLength": 200, "description": "The emitting software (plugin or converter), e.g. 'ocp-from-contractv3'." },
+        "name": { "type": "string", "maxLength": 200, "description": "The emitting software (plugin or converter), e.g. 'my-orchestrator-ocp'." },
         "version": { "type": "string", "maxLength": 100 },
-        "framework": { "type": "string", "maxLength": 200, "description": "The orchestration framework the run executed under, e.g. 'herdr-dagr', 'langgraph', 'crewai'." },
+        "framework": { "type": "string", "maxLength": 200, "description": "The orchestration framework the run executed under, e.g. 'my-orchestrator', 'langgraph', 'crewai'." },
         "framework_version": { "type": "string", "maxLength": 100 },
-        "source_contract": { "type": "string", "maxLength": 200, "description": "Upstream native format this document was derived from, e.g. 'dagr/3'." },
+        "source_contract": { "type": "string", "maxLength": 200, "description": "Upstream native format this document was derived from, e.g. 'my-orchestrator/1.2'." },
         "emitted_at": { "$ref": "#/$defs/timestamp" },
         "ext": { "$ref": "#/$defs/ext" }
       }
@@ -123,7 +123,7 @@
         "state": {
           "type": "string",
           "maxLength": 100,
-          "description": "Producer's current projection over the node's attempts. Recommended vocabulary (from dagr contract v3): queued, working, review, blocked, done, failed, rejected, canceled, settled_unverified. Consumers learning from settled runs should trust attempt outcomes over this field."
+          "description": "Producer's current projection over the node's attempts. Recommended vocabulary: queued, working, review, blocked, done, failed, rejected, canceled, settled_unverified. Consumers learning from settled runs should trust attempt outcomes over this field."
         },
         "labels": { "$ref": "#/$defs/labels" },
         "ext": { "$ref": "#/$defs/ext" }
@@ -146,7 +146,7 @@
     "modelRef": {
       "type": "object",
       "properties": {
-        "raw": { "type": "string", "maxLength": 200, "description": "The label exactly as the producer knew it, always preserved (e.g. 'fable·xhigh', 'opus5.xhigh'). Canonicalization is the consumer's job; the raw label is the ground truth." },
+        "raw": { "type": "string", "maxLength": 200, "description": "The label exactly as the producer knew it, always preserved (e.g. 'opus5.xhigh'). A label the source wrote with the effort in it, such as 'fable·xhigh', is kept as written; a producer never builds one itself (see effort). Canonicalization is the consumer's job; the raw label is the ground truth." },
         "id": { "type": "string", "maxLength": 200, "description": "Canonical provider model id when known, e.g. 'claude-fable-5'." },
         "family": { "type": "string", "maxLength": 100, "description": "Coarse family label for arm grouping, e.g. 'fable', 'opus5', 'sol5.6'." },
         "provider": { "type": "string", "maxLength": 100, "description": "e.g. 'anthropic', 'openai'." },
@@ -160,8 +160,8 @@
         "input_tokens": { "type": "integer", "minimum": 0, "description": "Uncached input tokens." },
         "cached_input_tokens": { "type": "integer", "minimum": 0, "description": "Input tokens served from cache (cache reads)." },
         "cache_creation_tokens": { "type": "integer", "minimum": 0, "description": "Input tokens written to cache, when the provider bills them separately." },
-        "output_tokens": { "type": "integer", "minimum": 0 },
-        "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "Thinking/reasoning tokens when the provider reports them separately from output." },
+        "output_tokens": { "type": "integer", "minimum": 0, "description": "Output tokens, reasoning (thinking) tokens included. When the source reports reasoning separately from output, the producer adds it in here." },
+        "reasoning_tokens": { "type": "integer", "minimum": 0, "description": "The reasoning (thinking) share of output_tokens, as a breakdown: output_tokens already includes these tokens, so a reader never adds the two." },
         "requests": { "type": "integer", "minimum": 0, "description": "Number of model API requests aggregated into this record." },
         "usd": { "type": "number", "minimum": 0, "description": "Billed cost in US dollars when the producer knows it. Consumers should prefer recomputing from tokens and a dated price table." },
         "basis": {
@@ -195,7 +195,7 @@
         },
         "evidence": {
           "enum": ["verified", "reported", "heuristic", "asserted"],
-          "description": "How the result is known (dagr contract v3 tiers). verified: mechanically checked (tests, provenance receipt). reported: the actor asserted it through a typed envelope. heuristic: inferred. asserted: bare claim. Missing evidence must be treated as 'asserted', never upgraded."
+          "description": "How the result is known. verified: mechanically checked (tests, provenance receipt). reported: the actor asserted it through a typed envelope. heuristic: inferred. asserted: bare claim. Missing evidence must be treated as 'asserted', never upgraded."
         },
         "via": { "type": "string", "maxLength": 200, "description": "Node id of the gate or review that produced this acceptance signal, when one did." },
         "receipt": { "$ref": "#/$defs/shortText" },
@@ -212,7 +212,7 @@
         "n": { "type": "integer", "minimum": 1, "description": "1-based ordinal within the node." },
         "actor": { "type": "string", "maxLength": 200, "description": "Logical agent/role that ran the attempt (not a volatile runtime locator)." },
         "model": { "$ref": "#/$defs/modelRef" },
-        "effort": { "type": "string", "maxLength": 100, "description": "Reasoning-effort label as configured, e.g. low, medium, high, xhigh, max. Open set; producers must not fold it into the model label." },
+        "effort": { "type": "string", "maxLength": 100, "description": "Reasoning-effort label as configured, e.g. low, medium, high, xhigh, max. Open set. Producers must not fold it into the model label: a producer never builds a fused label such as 'fable·xhigh' itself. When the source already wrote one, model.raw keeps it as written, and effort known separately goes here." },
         "cause": { "$ref": "#/$defs/cause" },
         "status": {
           "enum": ["queued", "working", "done", "failed", "rejected", "canceled", "settled_unverified", "lost"],

{loopmath-0.1.0 → loopmath-0.2.0}/src/loopmath/__init__.py

@@ -5,4 +5,4 @@ The command line (`loopmath`, or its alias `loop`) is the interface; see the
 README and `loopmath --help`.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{loopmath-0.1.0 → loopmath-0.2.0}/src/loopmath/adapters/opencode_store.py

@@ -116,6 +116,24 @@ def _nested_nonnegative_int(value: Any, path: tuple[str, ...]) -> int | None:
     return current
 
 
+def _message_tokens(tokens: Any, output_name: str) -> int | None:
+    """One assistant message's count for an OCP cost field, or None when unknown.
+
+    OCP's output_tokens includes reasoning, with reasoning_tokens as a breakdown.
+    OpenCode stores them apart: 1.17.11's session usage keeps output as
+    outputTokens - reasoningTokens and reasoning on its own, and its stats command
+    adds the two back. So output_tokens is output + reasoning here; a message with
+    no reasoning count adds 0.
+    """
+    value = _nested_nonnegative_int(tokens, _TOKEN_FIELDS[output_name])
+    if output_name != "output_tokens" or value is None:
+        return value
+    if _as_mapping(tokens).get("reasoning") is None:
+        return value
+    reasoning = _nested_nonnegative_int(tokens, ("reasoning",))
+    return None if reasoning is None else value + reasoning
+
+
 def _nonnegative_number(value: Any) -> int | float | None:
     if (
         isinstance(value, bool)
@@ -309,10 +327,9 @@ def _cost_record(
 ) -> tuple[dict[str, Any], dict[str, int]]:
     cost: dict[str, Any] = {"requests": len(assistants), "basis": "measured"}
     incomplete: dict[str, int] = {}
-    for output_name, source_path in _TOKEN_FIELDS.items():
+    for output_name in _TOKEN_FIELDS:
         values = [
-            _nested_nonnegative_int(item.get("tokens"), source_path)
-            for item in assistants
+            _message_tokens(item.get("tokens"), output_name) for item in assistants
         ]
         if all(value is not None for value in values):
             cost[output_name] = sum(value for value in values if value is not None)
@@ -352,9 +369,9 @@ def _message_models(
             ),
             "requests": len(messages),
         }
-        for output_name, source_path in _TOKEN_FIELDS.items():
+        for output_name in _TOKEN_FIELDS:
             values = [
-                _nested_nonnegative_int(message.get("tokens"), source_path)
+                _message_tokens(message.get("tokens"), output_name)
                 for message in messages
             ]
             if all(value is not None for value in values):

{loopmath-0.1.0 → loopmath-0.2.0}/src/loopmath/belief/__init__.py

@@ -1,6 +1,4 @@
 """The belief model: grouping forest, cost, gate, success and score heads, Gaussian engine, look-ahead (spec 04).
-
-Owner: lane 05. Spec: design/0.1/. Stub written by the scaffold.
 """
 
 from __future__ import annotations