loopmath 0.3.3__py3-none-any.whl → 0.3.5__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. loopmath/__init__.py +1 -1
  2. loopmath/cli.py +19 -3
  3. loopmath/cli_registry.py +20 -8
  4. loopmath/onboard/commands.py +1 -1
  5. loopmath/prices.toml +29 -3
  6. loopmath/skill/commands.py +17 -19
  7. loopmath/skill/doctor.py +35 -8
  8. loopmath/skill/guide.py +52 -0
  9. loopmath/skill/{skills/loopmath-update-fit/SKILL.md → guides/fit.md} +2 -8
  10. loopmath/skill/{skills/loopmath-import-runs/SKILL.md → guides/import.md} +1 -7
  11. loopmath/skill/{skills/loopmath-onboard/SKILL.md → guides/onboard.md} +2 -8
  12. loopmath/skill/{skills/loopmath-plan-task/SKILL.md → guides/plan.md} +3 -9
  13. loopmath/skill/{skills/loopmath-record-run/SKILL.md → guides/record.md} +2 -8
  14. loopmath/skill/{skills → guides}/reference.md +3 -3
  15. loopmath/skill/install.py +144 -71
  16. loopmath/skill/skills/loopmath/SKILL.md +45 -23
  17. loopmath/store/commands.py +2 -0
  18. loopmath/update.py +299 -0
  19. {loopmath-0.3.3.dist-info → loopmath-0.3.5.dist-info}/METADATA +19 -16
  20. {loopmath-0.3.3.dist-info → loopmath-0.3.5.dist-info}/RECORD +27 -25
  21. {loopmath-0.3.3.data → loopmath-0.3.5.data}/data/spec/ocp-v0.2.schema.json +0 -0
  22. {loopmath-0.3.3.data → loopmath-0.3.5.data}/data/spec/ocp-v0.schema.json +0 -0
  23. {loopmath-0.3.3.data → loopmath-0.3.5.data}/data/spec/ocp_conformance.py +0 -0
  24. {loopmath-0.3.3.dist-info → loopmath-0.3.5.dist-info}/WHEEL +0 -0
  25. {loopmath-0.3.3.dist-info → loopmath-0.3.5.dist-info}/entry_points.txt +0 -0
  26. {loopmath-0.3.3.dist-info → loopmath-0.3.5.dist-info}/licenses/LICENSE +0 -0
  27. {loopmath-0.3.3.dist-info → loopmath-0.3.5.dist-info}/top_level.txt +0 -0
loopmath/__init__.py CHANGED
@@ -5,4 +5,4 @@ The command line (`loopmath`, or its alias `loop`) is the interface; see the
5
5
  README and `loopmath --help`.
6
6
  """
7
7
 
8
- __version__ = "0.3.3"
8
+ __version__ = "0.3.5"
loopmath/cli.py CHANGED
@@ -14,9 +14,11 @@ Verbs:
14
14
  plan: task-types workflows recommend builder plan
15
15
  record: run start|record|import|attempt|artifact|finish|sessions outcome budget config
16
16
  learn: fit onboard share
17
- view: runs posterior status report doctor skill ocp
17
+ view: runs posterior status report doctor guide skill update ocp
18
18
 
19
- No verb in this CLI connects to another machine; builder serves on 127.0.0.1 only.
19
+ No verb in this CLI connects to another machine, except the daily update check (update.py): once a
20
+ day, after any command, loopmath asks pypi.org for its latest version, sending only its own
21
+ (LOOPMATH_NO_UPDATE_CHECK=1 or CI turns it off). builder serves on 127.0.0.1 only.
20
22
  Verbs write only to the store ($LOOPMATH_HOME, default ~/.loopmath, which also
21
23
  holds the parse cache and the fit --full compile folder), to the skill folders
22
24
  skill install names, and to paths the user names.
@@ -550,9 +552,23 @@ def _add_verify_receipts(sub) -> None:
550
552
 
551
553
 
552
554
  def main(argv: list[str] | None = None) -> int:
553
- from .cli_errors import JsonErrorParser, run_guarded, wants_json
555
+ """Run one command, then the daily update check (update.py), which never changes the exit code or stdout.
556
+ A command that ends in an exception other than SystemExit, or in Ctrl-C, skips the check."""
557
+ from .update import after_command
554
558
 
555
559
  raw_args = sys.argv[1:] if argv is None else argv
560
+ try:
561
+ code = _main(raw_args)
562
+ except SystemExit: # --help, --version and usage errors too
563
+ after_command(raw_args)
564
+ raise
565
+ after_command(raw_args)
566
+ return code
567
+
568
+
569
+ def _main(raw_args: list[str]) -> int:
570
+ from .cli_errors import JsonErrorParser, run_guarded, wants_json
571
+
556
572
  JsonErrorParser.json_mode = wants_json(raw_args) # under --json a usage error is a JSON object on stdout too
557
573
  JsonErrorParser.argv = list(raw_args)
558
574
  parser = JsonErrorParser(
loopmath/cli_registry.py CHANGED
@@ -633,9 +633,23 @@ def _add_viewing(sub) -> None:
633
633
  _common(p)
634
634
  p.set_defaults(func=_lazy("loopmath.skill.commands:doctor"))
635
635
 
636
- p = sub.add_parser("skill", help="install, remove or print the orchestrator skills")
636
+ p = sub.add_parser("guide", help="print the instructions for one job (onboard, import, plan, record, fit) or "
637
+ "the command reference, for an agent to follow; read only")
638
+ p.add_argument("topic", nargs="?", default=None, metavar="TOPIC",
639
+ help="onboard, import, plan, record, fit or reference (default: list them, with when to use each)")
640
+ p.set_defaults(func=_lazy("loopmath.skill.guide:command"))
641
+
642
+ p = sub.add_parser("update", help="is a newer loopmath out? the installed and latest versions and the upgrade "
643
+ "command; never upgrades")
644
+ p.add_argument("--refresh", action="store_true", help="ask pypi.org now, instead of reusing the last answer "
645
+ "(kept for 24 h, a failed check for 6 h)")
646
+ _common(p)
647
+ p.set_defaults(func=_lazy("loopmath.update:command"))
648
+
649
+ p = sub.add_parser("skill", help="install, remove or print the loopmath skill")
637
650
  ss = p.add_subparsers(dest="skill_command", required=True)
638
- for verb, helptext in (("install", "write the six skills for Claude Code, Codex or both"),
651
+ for verb, helptext in (("install", "write the loopmath skill for Claude Code, Codex or both, and remove the job "
652
+ "skills 0.3.3 and older installed"),
639
653
  ("uninstall", "remove what install wrote")):
640
654
  q = ss.add_parser(verb, help=helptext)
641
655
  q.add_argument("--target", default="auto", choices=["auto", "claude-code", "codex", "both"],
@@ -645,14 +659,12 @@ def _add_viewing(sub) -> None:
645
659
  q.add_argument("--dir", default=None, metavar="PATH", help="the project folder for --scope project "
646
660
  "(default: this folder)")
647
661
  if verb == "install":
648
- q.add_argument("--dry-run", action="store_true", help="print every file install would write or "
649
- "change, and write nothing")
662
+ q.add_argument("--dry-run", action="store_true", help="print every file install would write, change "
663
+ "or remove, and write nothing")
650
664
  _common(q)
651
665
  q.set_defaults(func=_lazy(f"loopmath.skill.commands:{verb}"))
652
- q = ss.add_parser("show", help="print one skill (default loopmath, the start-here skill) or the shared reference")
653
- q.add_argument("name", nargs="?", default="loopmath", metavar="NAME",
654
- help="loopmath, loopmath-onboard, loopmath-import-runs, loopmath-update-fit, loopmath-plan-task, "
655
- "loopmath-record-run, or reference")
666
+ q = ss.add_parser("show", help="print the loopmath skill (the job guides are `loopmath guide`)")
667
+ q.add_argument("name", nargs="?", default="loopmath", metavar="NAME", help="loopmath, the one skill")
656
668
  q.set_defaults(func=_lazy("loopmath.skill.commands:show"))
657
669
 
658
670
  p = sub.add_parser("ocp", help="validate or migrate OCP documents")
@@ -127,7 +127,7 @@ def onboard(args: argparse.Namespace) -> int:
127
127
  print(f"onboard: reading Claude Code and Codex history, {_window_words(since)}"
128
128
  + ("" if H.parse_cache().is_file() else "; a large history can take several minutes on the first read"),
129
129
  file=sys.stderr, flush=True)
130
- # Then, also when captured, what the answers start from, once (the skill shows this line to the user).
130
+ # Then, also when captured, what the answers start from, once (the onboard guide shows this line to the user).
131
131
  prior = starting_prior()
132
132
  print(prior["line"], file=sys.stderr, flush=True)
133
133
  hist = deps.load_history(since_days, logs=deps.logs, progress=_progress, stage=_stage)
loopmath/prices.toml CHANGED
@@ -143,15 +143,20 @@ source = "OpenCode 1.17.11 model catalog, opencode free route"
143
143
 
144
144
  # ---------------------------------------------------------------------------
145
145
  # Rows checked on the provider pages on 2026-09-23; gpt-6.1-sol added and
146
- # gpt-6-luna checked again on 2026-10-12 (no newer luna is listed). as_of
147
- # stays the copied table's date: a row with no "checked" date takes it as
148
- # the date of its tariff, and those rows were not read again.
146
+ # gpt-6-luna checked again on 2026-10-12 (no newer luna is listed);
147
+ # claude-sonnet-5-5 and claude-haiku-5-5 confirmed and gpt-6.1-terra added
148
+ # on 2026-11-03. as_of stays the copied table's date: a row with no
149
+ # "checked" date takes it as the date of its tariff, and those rows were
150
+ # not read again.
149
151
  # Each source names its page and the date it was read; the tariff record
150
152
  # written with every priced attempt takes its date from "checked YYYY-MM-DD".
151
153
  #
152
154
  # Anthropic (https://platform.claude.com/docs/en/about-claude/pricing): cache_write is the 1-hour write rate (2x input), as
153
155
  # for the rows above. Claude Code writes the 1-hour cache: 64.2M of 64.2M
154
156
  # cache-write tokens in 200 recent sessions on the build machine were 1h.
157
+ # Claude Haiku 5.5 is priced by prompt length: its row is the tier for
158
+ # prompts up to 100,000 input tokens, a longer prompt bills 5x those rates
159
+ # and is priced at the same rate here, so a Haiku 5.5 figure is a floor.
155
160
  # OpenAI (https://developers.openai.com/api/docs/pricing and each model's
156
161
  # page): GPT-6 bills cache writes (1.25x input), but Codex reported 0
157
162
  # cache-write tokens in all 91 recent GPT-6 sessions on the build machine,
@@ -168,6 +173,20 @@ cache_write = 8.00
168
173
  output = 20.00
169
174
  source = "official list, https://platform.claude.com/docs/en/about-claude/pricing, checked 2026-09-23: Claude Opus 5.5 at $4 input, $8 1h cache write, $0.20 cache read (0.05x input), $20 output; cache_write is the 1h rate"
170
175
 
176
+ ["claude-sonnet-5-5"]
177
+ input = 2.00
178
+ cache_read = 0.10
179
+ cache_write = 4.00
180
+ output = 10.00
181
+ source = "official list, https://platform.claude.com/docs/en/about-claude/pricing, checked 2026-11-03: Claude Sonnet 5.5 at $2 input, $4 1h cache write, $0.10 cache read (0.05x input), $10 output; cache_write is the 1h rate"
182
+
183
+ ["claude-haiku-5-5"]
184
+ input = 0.10
185
+ cache_read = 0.01
186
+ cache_write = 0.20
187
+ output = 0.50
188
+ source = "official list, https://platform.claude.com/docs/en/about-claude/pricing, checked 2026-11-03: Claude Haiku 5.5 at $0.10 input, $0.20 1h cache write, $0.01 cache read, $0.50 output for prompts up to 100,000 tokens; prompts over 100,000 tokens bill $0.50 input, $1 1h cache write, $0.05 cache read, $2.50 output and are priced at this rate (a floor); cache_write is the 1h rate"
189
+
171
190
  ["gpt-6-astra"]
172
191
  input = 10.00
173
192
  cache_read = 1.00
@@ -189,6 +208,13 @@ cache_write = 2.50
189
208
  output = 10.00
190
209
  source = "official list, https://developers.openai.com/api/docs/models/gpt-6.1-sol, checked 2026-10-12: standard tier, $2 input, $0.10 cached input, $2.50 cache write, $10 output; prompts over 272K input tokens bill more and are priced at this rate (a floor)"
191
210
 
211
+ ["gpt-6.1-terra"]
212
+ input = 1.00
213
+ cache_read = 0.05
214
+ cache_write = 1.25
215
+ output = 5.00
216
+ source = "official list, https://developers.openai.com/api/docs/models/gpt-6.1-terra, checked 2026-11-03: standard tier, $1 input, $0.05 cached input, $1.25 cache write (30-minute retention; 12-hour retention is $2.50), $5 output; prompts over 272K input tokens bill more and are priced at this rate (a floor)"
217
+
192
218
  ["gpt-6-luna"]
193
219
  input = 0.10
194
220
  cache_read = 0.01
@@ -1,4 +1,5 @@
1
1
  """Handlers for `loopmath doctor` and `loopmath skill install|uninstall|show`.
2
+ (`loopmath guide` is guide.py's, which imports nothing else.)
2
3
  """
3
4
 
4
5
  from __future__ import annotations
@@ -36,16 +37,9 @@ _WOULD = {"created": "to write", "updated": "to update", "replaced": "to replace
36
37
  "removed": "to remove", "unchanged": "unchanged", "kept": "kept"}
37
38
 
38
39
 
39
- def _count(entries: list[dict], dry_run: bool = False) -> str:
40
- counts: dict[str, int] = {}
41
- for e in entries:
42
- counts[e["action"]] = counts.get(e["action"], 0) + 1
43
- return ", ".join(f"{n} {_WOULD[action] if dry_run else action}" for action, n in counts.items())
44
-
45
-
46
40
  def _results(verb: str, results: list[dict], as_json: bool) -> None:
47
41
  if as_json:
48
- emit_json("loopmath.skill/2", {"verb": verb, "results": results})
42
+ emit_json("loopmath.skill/3", {"verb": verb, "results": results})
49
43
  return
50
44
  dry = any(r.get("dry_run") for r in results)
51
45
  if dry:
@@ -53,19 +47,20 @@ def _results(verb: str, results: list[dict], as_json: bool) -> None:
53
47
  for r in results:
54
48
  form = " (AGENTS.md block)" if r["method"] == "agents_block" else ""
55
49
  head = f"{r['target']} {r['scope']}{form}"
56
- actions = {e["action"] for e in r["skills"] + r["reference"]}
57
- if verb == "uninstall" and actions <= {"absent"}:
50
+ [skill] = r["skills"]
51
+ if verb == "uninstall" and skill["action"] == "absent" and not r["removed"]:
58
52
  print(f"{head}: not installed in {r['root']}, nothing to remove")
59
- elif verb == "uninstall" and actions <= {"removed", "absent"}:
60
- n = sum(e["action"] == "removed" for e in r["skills"])
61
- print(f"{head}: removed {n} skill{'s' if n != 1 else ''} and the reference.md beside each from {r['root']}")
62
- else:
63
- print(f"{head}: {len(r['skills'])} skills in {r['root']}: {_count(r['skills'], dry)}")
64
- if dry:
65
- print(f" and in each skill folder a copy of the shared reference.md ({_count(r['reference'], dry)}), "
66
- f"and {r['manifest']}, the list of the files install wrote")
53
+ continue
54
+ print(f"{head}:")
55
+ if skill["action"] != "absent":
56
+ print(f" {_WOULD[skill['action']] if dry else skill['action']} {skill['path']}, the loopmath skill")
57
+ action = r.get("manifest_action")
58
+ if dry and action:
59
+ print(f" {_WOULD[action]} {r['manifest']}, the list of the files install wrote")
67
60
  for e in r["removed"]:
68
61
  print(f" {'to remove' if dry else 'removed'} {e['path']}")
62
+ if any(e["path"].endswith(f"/{name}/SKILL.md") for e in r["removed"] for name in _install.RETIRED_SKILLS):
63
+ print(" (0.3.4 installs one skill; the job skills' text comes from `loopmath guide` now)")
69
64
  block, where = r.get("block"), r.get("block_file") or r.get("agents_md")
70
65
  if block == "removed":
71
66
  print(f" {'to remove' if dry else 'removed'} the loopmath block from {where}")
@@ -104,5 +99,8 @@ def show(args: argparse.Namespace) -> int:
104
99
  try:
105
100
  sys.stdout.write(_install.skill_text(name))
106
101
  except KeyError:
107
- return fail(f"no skill {name!r}; one of {', '.join(_install.SKILLS)}, or reference")
102
+ topic = "reference" if name == "reference" else _install.RETIRED_SKILLS.get(name)
103
+ if topic:
104
+ return fail(f"0.3.4 has one skill, loopmath; {name} is `loopmath guide {topic}` now")
105
+ return fail(f"no skill {name!r}; the one skill is loopmath, and `loopmath guide` lists the job guides")
108
106
  return EXIT_OK
loopmath/skill/doctor.py CHANGED
@@ -6,9 +6,11 @@ Six checks, each `ok`, `warn` or `fail`:
6
6
  store the store root exists and is writable
7
7
  fit `fits/latest` present, and its age
8
8
  prices every model seen in the scan window has a price
9
- skill where the skill set is installed (and which Codex form), and whether it is whole and current
9
+ skill where the loopmath skill is installed (and which Codex form), whether it is the one this
10
+ loopmath writes, and the job skills 0.3.3 and older installed that are still on disk
10
11
 
11
- Nothing here opens a network connection. Log files are read through the
12
+ Nothing here opens a network connection (the daily update check runs after the command, from
13
+ cli.main). Log files are read through the
12
14
  parse cache, which doctor keeps up to date in the store's cache folder (the
13
15
  report's `cache` says where and how large); it writes nothing else there, and
14
16
  creates the store folder only when it is missing. Codex auth files are never
@@ -28,6 +30,7 @@ from collections import Counter
28
30
  from pathlib import Path
29
31
  from typing import Callable, Mapping
30
32
 
33
+ from .. import __version__
31
34
  from ..belief.design import other_design
32
35
  from . import install as _install
33
36
 
@@ -189,28 +192,52 @@ def _install_cmd(place: dict) -> str:
189
192
  return f"loopmath skill install --target {place['target']} --scope {place['scope']}"
190
193
 
191
194
 
195
+ def _folders(paths: list[str]) -> str:
196
+ """The retired files, by the skill folder each is in (`loopmath/reference.md` by its name)."""
197
+ names = []
198
+ for path in paths:
199
+ folder, file = Path(path).parent.name, Path(path).name
200
+ name = f"{folder}/{file}" if folder == "loopmath" else folder
201
+ if name not in names:
202
+ names.append(name)
203
+ return ", ".join(names)
204
+
205
+
192
206
  def check_skill(cwd: Path | None, env: Mapping[str, str] | None) -> dict:
193
- """`ok` when the full set is installed and current for some target, with nothing old or partial
194
- left anywhere; else a warning with the exact install command."""
207
+ """`ok` when the skill is installed and current for some target, with nothing old, partial or
208
+ retired left anywhere; else a warning with the exact install command. Retired files loopmath still
209
+ owns go with that command; the others were kept, and the warning says why."""
195
210
  places = _install.status(cwd=cwd, env=env)
196
- n = len(_install.SKILLS)
197
211
  seen = [p for p in places if p["any"]]
198
212
  if not seen:
199
213
  return _check("skill", "warn", "not installed: run `loopmath skill install`", places=places)
200
214
  problems = []
201
215
  for p in seen:
202
216
  where = f"{p['target']} {p['scope']}"
217
+ retired = p["retired"]
203
218
  if p["old"]:
204
219
  problems.append(f"{where} still has the 0.1 single skill: run `{_install_cmd(p)}`")
205
220
  elif p["missing"]:
206
- problems.append(f"{where} lacks {', '.join(p['missing'])}: run `{_install_cmd(p)}`")
221
+ problems.append(f"{where} lacks the loopmath skill: run `{_install_cmd(p)}`")
207
222
  elif not p["current"]:
208
- problems.append(f"{where} is older than this loopmath: run `{_install_cmd(p)}`")
223
+ problems.append(f"{where} has a loopmath skill that differs from the one loopmath {__version__} writes: "
224
+ f"run `{_install_cmd(p)}`")
225
+ if retired["owned"]:
226
+ problems.append(f"{where} still has the job skills 0.3.3 and older installed "
227
+ f"({_folders(retired['owned'])}): run `{_install_cmd(p)}` to remove them")
228
+ if retired["changed"]:
229
+ problems.append(f"{where} kept {', '.join(retired['changed'])}: changed since loopmath wrote "
230
+ f"{'them' if len(retired['changed']) > 1 else 'it'}; move "
231
+ f"{'them' if len(retired['changed']) > 1 else 'it'} aside when no longer needed")
232
+ if retired["foreign"]:
233
+ problems.append(f"{where} has {', '.join(retired['foreign'])}, where 0.3.3 and older put job skills, "
234
+ "but loopmath did not write "
235
+ f"{'them' if len(retired['foreign']) > 1 else 'it'}: left alone")
209
236
  if problems:
210
237
  return _check("skill", "warn", "; ".join(problems), places=places)
211
238
  parts = [f"{p['target']} {p['scope']} ({'AGENTS.md block' if p['method'] == 'agents_block' else 'skills'})"
212
239
  for p in seen]
213
- return _check("skill", "ok", f"{n} skills: " + ", ".join(parts), places=places)
240
+ return _check("skill", "ok", "the loopmath skill: " + ", ".join(parts), places=places)
214
241
 
215
242
 
216
243
  def run_checks(home: Path, *, env: Mapping[str, str] | None = None, cwd: Path | None = None,
@@ -0,0 +1,52 @@
1
+ """`loopmath guide [TOPIC]`: the instructions for each job, for the agent to read and follow.
2
+
3
+ The one installed skill (`skills/loopmath/SKILL.md`) sends the agent here, so a job's
4
+ instructions always match the installed loopmath. Each topic is a packaged file in `guides/`:
5
+ the five jobs, then the command reference they share. Read only: it needs no store and writes
6
+ nothing, so this module imports nothing from the rest of loopmath.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+ import sys
13
+ from importlib import resources
14
+
15
+ # Each topic, with one line on when to use it, in the order `loopmath guide` lists them.
16
+ TOPICS = {
17
+ "onboard": "set up, start or try loopmath from the user's Claude Code and Codex history, or loopmath has no runs yet",
18
+ "import": "OCP files or a folder of finished runs to bring into loopmath",
19
+ "plan": "a task to do: pick its workflow, models and effort, then start the run",
20
+ "record": "a task is done: record the run and show its receipt, or judge a pair blind",
21
+ "fit": "update the fit, say what loopmath learned, or the fit is not usable",
22
+ "reference": "every command, flag, JSON field and exit code the guides use",
23
+ }
24
+ FOLLOW = "Run `loopmath guide <topic>` and follow it."
25
+ EXIT_UNKNOWN = 2 # the CLI's "not found"
26
+
27
+
28
+ def text(topic: str) -> str:
29
+ """One topic's text, as packaged. KeyError on another name."""
30
+ if topic not in TOPICS:
31
+ raise KeyError(topic)
32
+ return resources.files("loopmath.skill").joinpath("guides", f"{topic}.md").read_text(encoding="utf-8")
33
+
34
+
35
+ def listing() -> str:
36
+ """What `loopmath guide` alone prints: each topic with when to use it, then how to read one."""
37
+ width = max(map(len, TOPICS))
38
+ rows = [f" {name:<{width}} {when}" for name, when in TOPICS.items()]
39
+ return "loopmath guides, one per job, and the command reference:\n\n" + "\n".join(rows) + f"\n\n{FOLLOW}\n"
40
+
41
+
42
+ def command(args: argparse.Namespace) -> int:
43
+ topic = getattr(args, "topic", None)
44
+ if topic is None:
45
+ sys.stdout.write(listing())
46
+ return 0
47
+ try:
48
+ sys.stdout.write(text(topic))
49
+ except KeyError:
50
+ print(f"error: no guide {topic!r}; the topics are {', '.join(TOPICS)}. {FOLLOW}", file=sys.stderr)
51
+ return EXIT_UNKNOWN
52
+ return 0
@@ -1,14 +1,8 @@
1
- ---
2
- name: loopmath-update-fit
3
- description: "Refit loopmath on every run recorded so far and show the results page. Use when the user asks to update, refresh or rerun the loopmath fit, asks what loopmath learned or believes about models, efforts or workflows, or after runs were imported or recorded without a refit."
4
- allowed-tools: Bash(loopmath:*), Bash(open:*), Bash(xdg-open:*)
5
- ---
6
-
7
1
  # Update the loopmath fit
8
2
 
9
3
  Refit on everything in the store, then show the results page. No question.
10
4
 
11
- Use exactly the commands below. Flags and fields are in `reference.md` next to this file. Never run `--help`.
5
+ Use exactly the commands below. Flags and fields are in `loopmath guide reference`. Never run `--help`.
12
6
 
13
7
  ## 1. Fit
14
8
 
@@ -24,7 +18,7 @@ A new fit replaces the one `recommend` and the pages read. Read `fit.id`, `fit.n
24
18
 
25
19
  `shipped_overlap` counts, per shipped source, the user's runs that the shipped prior also holds (the same runs); the fit uses the user's copies. When it has counts, the summary says one line, once: "N of your runs are also in the shipped SOURCE prior (same runs): fits use your copies", with the total for N ("1 of your runs is also in the shipped SOURCE prior (same run): fits use your copy" for one run), and with several sources "the shipped prior (rq1 40, e0 4)" for "the shipped SOURCE prior". Its `dropped` reason, "shipped copy of a stored run", is that same overlap: do not name it again.
26
20
 
27
- If it exits 4 (another fit holds the lock), wait 30 seconds and run it once more. If `fit.n_runs.user` is 0 and the user expected runs, say so and suggest `loopmath-onboard` or `loopmath-import-runs`.
21
+ If it exits 4 (another fit holds the lock), wait 30 seconds and run it once more. If `fit.n_runs.user` is 0 and the user expected runs, say so and suggest onboarding (`loopmath guide onboard`) or bringing existing runs (`loopmath guide import`).
28
22
 
29
23
  ## 2. Show the results page
30
24
 
@@ -1,14 +1,8 @@
1
- ---
2
- name: loopmath-import-runs
3
- description: "Bring agent runs the user already has as OCP files (*.ocp.json) into loopmath in one pass: validate all, import all, fit once, show the results page. Use when the user points at OCP files or a folder of finished runs, or at the output of an orchestrator or experiment harness that writes OCP, and wants loopmath to learn from them."
4
- allowed-tools: Bash(loopmath:*), Bash(open:*), Bash(xdg-open:*)
5
- ---
6
-
7
1
  # Bring existing runs into loopmath
8
2
 
9
3
  The user has finished runs written as OCP v0.3 (or v0.1, v0.2) documents. Validate them all, import them all without refitting after each, fit once, and show the results page. Ask nothing unless the location of the files is unknown.
10
4
 
11
- Use exactly the commands below. Flags and fields are in `reference.md` next to this file. Never run `--help`.
5
+ Use exactly the commands below. Flags and fields are in `loopmath guide reference`. Never run `--help`.
12
6
 
13
7
  ## 1. Find the files
14
8
 
@@ -1,14 +1,8 @@
1
- ---
2
- name: loopmath-onboard
3
- description: "Set the user up with loopmath from their own Claude Code and Codex history, in one pass: one question (which model labels their sessions, with its cost), then onboarding, the first fit and the results page. Use when the user asks to onboard, set up, start or try loopmath, or when loopmath has no runs yet."
4
- allowed-tools: Bash(loopmath:*), Bash(open:*), Bash(xdg-open:*)
5
- ---
6
-
7
1
  # Onboard the user with loopmath
8
2
 
9
3
  Onboarding reads the user's past Claude Code and Codex sessions (read only), groups them into tasks, has a model the user chooses name each task's type, records one run per task, finds the usual workflow per task type and repo, and fits. You ask one question, the labeller with its cost, and do the rest without stopping.
10
4
 
11
- Use exactly the commands below. Flags and fields are in `reference.md` next to this file. Never run `--help`.
5
+ Use exactly the commands below. Flags and fields are in `loopmath guide reference`. Never run `--help`.
12
6
 
13
7
  ## 1. Look first (no question yet)
14
8
 
@@ -22,7 +16,7 @@ Read `prior.line`, `groups.total`, `groups.to_label`, `window.from`, `window.to`
22
16
 
23
17
  Show the user `prior.line` once, word for word. It says what the answers start from before any of their runs, the prior that ships inside loopmath: its version, its runs per source, the published benchmarks it holds and the date it was built. Do not repeat it later, and do not write the numbers yourself: they change with each release. `loopmath prior show` lists the same prior source by source.
24
18
 
25
- If `groups.to_label` is 0, there is nothing to label. Do not ask anything. Say what was found (`groups.total` groups, none with a prompt to label, or no sessions in the window), run `loopmath fit --json`, and go to step 4. Suggest `loopmath-import-runs` if the user has OCP files.
19
+ If `groups.to_label` is 0, there is nothing to label. Do not ask anything. Say what was found (`groups.total` groups, none with a prompt to label, or no sessions in the window), run `loopmath fit --json`, and go to step 4. If the user has OCP files, offer to bring them in (`loopmath guide import`).
26
20
 
27
21
  ## 2. Ask one question
28
22
 
@@ -1,21 +1,15 @@
1
- ---
2
- name: loopmath-plan-task
3
- description: "Choose the workflow, models and effort for one coding task with loopmath, then start it: recommend, show the ready choices with chance and cost, ask one question, open the run. Use when the user asks to plan a task or an implementation with loopmath, asks which workflow, model or effort to use, pastes an option from a loopmath planning page (option 2: ...), or starts a coding task of more than a few minutes of agent work in a repo where they use loopmath."
4
- allowed-tools: Bash(loopmath:*), Bash(git rev-parse:*), Bash(git remote get-url:*), Bash(open:*), Bash(xdg-open:*)
5
- ---
6
-
7
1
  # Plan a task with loopmath
8
2
 
9
3
  One pass: classify the task, ask loopmath, show its choices, ask one question, start the chosen run, then do the work. The user makes one choice; you type everything else.
10
4
 
11
- Use exactly the commands below. Flags and fields are in `reference.md` next to this file. Never run `--help`.
5
+ Use exactly the commands below. Flags and fields are in `loopmath guide reference`. Never run `--help`.
12
6
 
13
7
  ## 1. Classify the task (no question)
14
8
 
15
9
  From the user's words and the repo, decide:
16
10
  - `TYPE`: one of `bug_fix`, `feature`, `refactor`, `tests`, `docs`, `research`, `infra`, `data`;
17
11
  - `TITLE`: the task in at most 60 characters;
18
- - features you can tell: `size`, `lang`, `has_tests`, `spec_clarity`, `needs_design`, `touches` (values in `reference.md`). Leave out the rest;
12
+ - features you can tell: `size`, `lang`, `has_tests`, `spec_clarity`, `needs_design`, `touches` (values in `loopmath guide reference`). Leave out the rest;
19
13
  - a target, only when the user states a score or runtime goal: `--target 'heldout_perf>=2400'`.
20
14
 
21
15
  Then the repo and the base commit. When the user names the repo ("in ale-bench", "for acme/api"), `REPO` is that name, lowercased. In the folder you work in:
@@ -111,7 +105,7 @@ Run the pieces in order, each with its setting from `piece_settings`. Note every
111
105
  - **Width above 1:** launch that many agents for the piece, each with its own session.
112
106
  - **Pair:** both runs start from `SHA` in separate git worktrees (`git worktree add ../TASK-a SHA`, `../TASK-b SHA`; with no git checkout, two copies of the folder), and both finish before any judging.
113
107
 
114
- When the work is done, follow `loopmath-record-run`.
108
+ When the work is done, run `loopmath guide record` and follow it.
115
109
 
116
110
  ## Never
117
111
 
@@ -1,14 +1,8 @@
1
- ---
2
- name: loopmath-record-run
3
- description: "Record a finished agent run in loopmath with one command, from the session ids noted while the work ran, with test results and scores, then show the receipt: predicted against actual cost, and the outcome. Use when a task planned with loopmath is done, when the user asks to record, log or save a run in loopmath, or when both runs of a loopmath pair are done and need a blind judge."
4
- allowed-tools: Bash(loopmath:*), Bash(open:*), Bash(xdg-open:*)
5
- ---
6
-
7
1
  # Record a run with loopmath
8
2
 
9
3
  One command records the whole run: one attempt per session (a Claude Code session counts its sub-agents), the commits made since the base commit, the verdicts and scores, the cost from the logs, the receipt and a background refit. Ask nothing unless you cannot tell which sessions did the work.
10
4
 
11
- Use exactly the commands below, and read their JSON as printed. Flags and fields are in `reference.md` next to this file. Never run `--help`.
5
+ Use exactly the commands below, and read their JSON as printed. Flags and fields are in `loopmath guide reference`. Never run `--help`.
12
6
 
13
7
  ## 1. Gather what the command needs (no question)
14
8
 
@@ -56,7 +50,7 @@ The second line is `receipt.line`. Report every `unmatched` entry and every note
56
50
 
57
51
  ## 4. Pairs: judge blind, after both runs are recorded
58
52
 
59
- When the run belongs to a slate (a pair from `loopmath-plan-task`) and both runs are recorded:
53
+ When the run belongs to a slate (a pair started as `loopmath guide plan` says) and both runs are recorded:
60
54
 
61
55
  1. `loopmath config get referee.model --json`: launch a fresh agent of that family (a family other than both runs' implementers when `value` is null).
62
56
  2. Give it the task and the two diffs in random order as A and B, without run ids, workflow names or models, with this prompt:
@@ -1,6 +1,6 @@
1
1
  # loopmath reference for agents
2
2
 
3
- Shared by every loopmath skill; `loopmath skill install` puts a copy next to each `SKILL.md`, and `loopmath skill show reference` prints it. Every command, flag and JSON field the skills use is here. Never run loopmath or any of its commands with `--help`: if something is missing here, run `loopmath doctor --json` and tell the user.
3
+ Shared by every loopmath guide; `loopmath guide reference` prints it. Every command, flag and JSON field the guides use is here. Never run loopmath or any of its commands with `--help`: if something is missing here, run `loopmath doctor --json` and tell the user.
4
4
 
5
5
  ## Conventions
6
6
 
@@ -35,7 +35,7 @@ Workflow shapes (`--workflow`): `solo`, `best_of_n`, `plan_implement`, `implemen
35
35
  ## Commands
36
36
 
37
37
  ### Status
38
- `loopmath status --json`. Read `exists` (the store exists), `fit.latest` (fit id or null), `fit.usable` (false with no fit, or with a fit an older loopmath made: refit), `fit.problem` (why not, or null), `fit.running`, `counts.runs`, `open_runs[]` (`run`, `type`, `repo`, `started_at`, `slate`), `budget.cap_usd`, `budget.spent.usd`.
38
+ `loopmath status --json`. Read `exists` (the store exists), `fit.latest` (fit id or null), `fit.usable` (false with no fit, or with a fit an older loopmath made: refit), `fit.problem` (why not, or null), `fit.running`, `counts.runs`, `open_runs[]` (`run`, `type`, `repo`, `started_at`, `slate`), `budget.cap_usd`, `budget.spent.usd`, `update` (null when the update check is off or pypi.org has not answered yet; else `latest`, `installed`, `available` (true when a newer loopmath is out), `command` (the upgrade command: offer it when a newer loopmath is out, and run it only if the user agrees), `checked_at` (when loopmath last asked pypi.org)).
39
39
 
40
40
  ### Onboard
41
41
  - `loopmath onboard --dry-run --json`: reads the history, writes nothing. Read `prior.line` (the starting prior, in one line: show it once), `groups.total`, `groups.to_label`, `window.from`, `window.to`, `sessions`, `cost_in_logs.usd`, `labeler.chosen`, `labeler.spec`, `labeler.expected.usd`, `labeler.options[]` (`spec`, `title`, `expected.usd`): one entry per labeller this machine can run, plus `none`.
@@ -70,7 +70,7 @@ loopmath recommend --type TYPE --repo REPO --title "TEXT" --feature size=m --bas
70
70
  - Up to 5 choices. Their order in `choices[]` is the order to number them in: each has `option`, its number from 1, the same number the planning page shows. The page's "Copy option" button copies `option N: LABEL`; a user who pastes it means the choice with that `label`; when no choice has that label (a page from another recommendation), show the current choices and ask, and never start another workflow in its place. For a row that is not a numbered option it copies `workflow CFG: LABEL`: start that configuration with `--config CFG` (Run start, below).
71
71
  - `most_likely` (with a score target): the workflow with the highest chance to reach the target. Left out when it is already another choice.
72
72
  - `p_accepted_within` on each choice (and in each `numbers` object): `mean`, `lo`, `hi`, `attempts`: the chance of an accepted result within `attempts` attempts, the first run and its retries (a ceiling: retries have less and less chance). Show it apart from `chance`, the chance of one run.
73
- - `bands` on each choice (and in each `numbers` object) in the full `--json`, the stored recommendation and the page data, not in `--brief`: central intervals, `chance`, `run_cost_usd` and `cost_per_accepted_usd`, each `{"50": [lo, hi], "80": [...], "90": [...], "95": [...]}`; a missing level is an absent key. For the pages; the skills show the 80% range from `lo` and `hi`.
73
+ - `bands` on each choice (and in each `numbers` object) in the full `--json`, the stored recommendation and the page data, not in `--brief`: central intervals, `chance`, `run_cost_usd` and `cost_per_accepted_usd`, each `{"50": [lo, hi], "80": [...], "90": [...], "95": [...]}`; a missing level is an absent key. For the pages; the guides show the 80% range from `lo` and `hi`.
74
74
  - There is a `pair` choice only when a second workflow is worth trying beside the goal; without one, `message` says so, and `run start --choice` takes only the keys in `choices[]`. The `pair` choice adds `explore_config` (the second member), `price_now_usd` (the extra run's cost now), `gain_per_future_run_usd` (the expected saving on each future similar run), `payback_runs` (similar runs until the extra run pays for itself: `price_now_usd` divided by `gain_per_future_run_usd`, rounded up, at least 1; null when the gain is 0; the number `message` says) and `p_beats_goal`.
75
75
  - `rescue`: how a missed run is fixed, which cost per accepted result counts. `kind` `retry` (the default): retry with another workflow, `of` (its label) and `config` (its id), chosen as the cheapest per run with at least `min_chance` (0.7) chance, else the most likely; `chance` (`mean`, `lo`, `hi`) and `run_cost_usd` are its own; each extra attempt has `decay` (0.5) times the chance of the one before, up to `max_attempts` (3) attempts in all, counting the first run; `p_accepted` is the chance the retries fix a miss; `usd` and `tokens` are the expected cost of fixing a miss; `basis` says how it was chosen; `text` is one plain sentence about it: quote it word for word. Older kinds: `redo_usual` (the reference repeated until accepted), `person` (a person's time), `none`. Without `text`, run cost is what the agents cost for one run, and cost per accepted result adds `expected_rescue_usd`, the expected cost of fixing a miss.
76
76
  - The `goal` choice adds `strategy`: null, or the try-then-rescue plan when the pick is less likely than the reference. Show `strategy.text` word for word. Its numbers are in `chance`, `misses`, `rescue`, `cost_per_accepted_usd` and `reference_cost_per_accepted_usd`. The same object is `goal.strategy`.