Skip to content

mattvideoproductions/MVP-Prompts / skills/foreman

foreman

Verified

Be the foreman on a big job. One lead model plans the work, hands pieces to helper agents in lanes that never share files, checks everything before accepting it and reports the cost; or runs a long solo build with an owner in the loop. Covers the North Star plan of record, briefs that carry the lead's reasoning, measured gates plus the owner's judgement, strike-based promotion between model tiers, a cost ledger and a mistake register every pass is checked against. Use it when the user types /foreman, says "be the foreman", "be the lead" or "orchestrate this", asks to delegate to subagents or run lanes or passes, or mentions a North Star, three strikes, tiers or promotion between models. Also load it when a task looks too big for one context or needs several agents or days, even if not asked by name; the skill then has you offer it and wait for a yes. Also use it to resume such a project, close a pass, report a session's cost or record a mistake. Not for a change one agent can finish in one sitting.

scripts/orch.py

View on GitHub
#!/usr/bin/env python3
"""orch.py - bookkeeping for the foreman skill. Standard library only.

  init                          set up .orchestration/ and NORTH_STAR.md in a project
  pass-end --pass N             close a pass: cost, North Star checks, mistake diff, snapshot
  cost now|record|add|report|lanes   API-equivalent cost by tier, per pass, per lane, over time
  northstar check|snapshot      check the North Star and diff it against the last snapshot
  mistakes check|answer|add|report|promote|export

Run from the project root, or pass --root. Exit codes: 0 clear, 1 a past mistake
repeated or a check failed, 2 questions still need the lead's answer.
"""
import argparse
import json
import re
import shutil
import sys
from collections import Counter, defaultdict
from datetime import datetime, timezone
from pathlib import Path

SKILL = Path(__file__).resolve().parent.parent
ASSETS = SKILL / "assets"
GLOBAL_REGISTER = Path.home() / ".claude" / "foreman" / "mistakes.jsonl"
TIER_ORDER = ["lead", "senior", "standard", "light"]
RANK = {"CLEAR": 0, "ASK": 1, "REPEAT": 2}


# ---------- small helpers ----------

def now_iso():
    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")


def today():
    return datetime.now(timezone.utc).strftime("%Y-%m-%d")


def parse_ts(s):
    try:
        t = datetime.fromisoformat(str(s).replace("Z", "+00:00"))
        return t if t.tzinfo else t.replace(tzinfo=timezone.utc)
    except (ValueError, TypeError):
        return None


def read_jsonl(path):
    out = []
    if Path(path).exists():
        for line in Path(path).read_text(encoding="utf-8").splitlines():
            line = line.strip()
            if line:
                out.append(json.loads(line))
    return out


def append_jsonl(path, obj):
    with open(path, "a", encoding="utf-8") as f:
        f.write(json.dumps(obj, ensure_ascii=False) + "\n")


def write_jsonl(path, rows):
    Path(path).write_text("".join(json.dumps(r, ensure_ascii=False) + "\n" for r in rows), encoding="utf-8")


def money(x):
    return f"${x:,.2f}"


def pct(x):
    return f"{100 * x:.0f}%"


def table(headers, rows):
    rows = [[str(c) for c in r] for r in rows]
    widths = [max(len(h), *(len(r[i]) for r in rows)) if rows else len(h) for i, h in enumerate(headers)]
    line = lambda cells: "  ".join(c.ljust(w) for c, w in zip(cells, widths)).rstrip()
    return "\n".join([line(headers), line(["-" * w for w in widths])] + [line(r) for r in rows])


def die(msg):
    print(f"orch: {msg}", file=sys.stderr)
    sys.exit(1)


class Ctx:
    def __init__(self, root):
        self.root = Path(root).resolve()
        self.state = self.root / ".orchestration"
        self.north = self.root / "NORTH_STAR.md"
        self.ledger = self.state / "cost_ledger.jsonl"
        self.register = self.state / "mistakes.jsonl"
        self.mlog = self.state / "mistake_log.jsonl"
        self.snaps = self.state / "snapshots"

    def need_state(self):
        if not self.state.exists():
            die(f"no .orchestration/ in {self.root}. Run: orch.py init")

    def cfg(self):
        cfg = json.loads((ASSETS / "config.default.json").read_text(encoding="utf-8"))
        p = self.state / "config.json"
        if p.exists():
            cfg.update(json.loads(p.read_text(encoding="utf-8")))
        return cfg

    def prices(self):
        p = self.state / "prices.json"
        return json.loads((p if p.exists() else ASSETS / "prices.json").read_text(encoding="utf-8"))


# ---------- cost: reading transcripts ----------

def transcript_files(ctx, extra=None):
    paths = list(extra or []) + list(ctx.cfg().get("transcripts") or [])
    if not paths:
        slug = re.sub(r"[^A-Za-z0-9]", "-", str(ctx.root))
        paths = [Path.home() / ".claude" / "projects" / slug]
    files = []
    for p in paths:
        p = Path(p).expanduser()
        if p.is_dir():
            files += sorted(p.rglob("*.jsonl"))
        elif p.is_file():
            files.append(p)
    return files


def load_transcripts(files):
    """Returns (responses, owner_message_times). One record per model response:
    streaming writes a response on several lines with the same message id, and a
    continued session carries its history, so keep one per id (the fullest)."""
    seen, owner = {}, {}
    for f in files:
        try:
            handle = open(f, encoding="utf-8", errors="replace")
        except OSError:
            continue
        with handle:
            for line in handle:
                if '"usage"' not in line and '"user"' not in line:
                    continue
                try:
                    d = json.loads(line)
                except json.JSONDecodeError:
                    continue
                if not isinstance(d, dict):
                    continue
                m = d.get("message") if isinstance(d.get("message"), dict) else {}
                if d.get("type") == "user":
                    origin = d.get("origin") if isinstance(d.get("origin"), dict) else {}
                    typed = origin.get("kind") == "human" or (not origin and isinstance(m.get("content"), str))
                    if typed and not d.get("isSidechain") and not d.get("isMeta") and "toolUseResult" not in d:
                        owner[d.get("uuid") or len(owner)] = parse_ts(d.get("timestamp"))
                    continue
                u = m.get("usage")
                model = m.get("model") or ""
                if d.get("type") != "assistant" or not isinstance(u, dict) or not model or model.startswith("<"):
                    continue
                worker = bool(d.get("agentId")) or bool(d.get("isSidechain"))
                agent = d.get("agentId") or (f.stem if worker else "main:" + str(d.get("sessionId") or f.stem)[:8])
                mid = m.get("id") or d.get("uuid") or f"{f}:{len(seen)}"
                rec = {"id": mid, "ts": parse_ts(d.get("timestamp")), "model": model, "agent": agent,
                       "worker": worker, "usage": u}
                old = seen.get(mid)
                if old is None or (u.get("output_tokens") or 0) >= (old["usage"].get("output_tokens") or 0):
                    if old is not None and old["ts"] and (rec["ts"] is None or old["ts"] < rec["ts"]):
                        rec["ts"] = old["ts"]
                    seen[mid] = rec
    return list(seen.values()), [t for t in owner.values() if t]


def mark_rewrites(responses, cfg):
    """Flag responses where an agent wrote its context to the cache again instead
    of reading it: 'start' for an agent's first response, 'idle' after a gap long
    enough for the cache to expire, 'other' for compaction or a broken cache."""
    by_agent = defaultdict(list)
    for r in responses:
        by_agent[r["agent"]].append(r)
    floor = datetime.min.replace(tzinfo=timezone.utc)
    for seq in by_agent.values():
        seq.sort(key=lambda r: r["ts"] or floor)
        prev = None
        for r in seq:
            parts = usage_parts(r["usage"], r["model"])
            prompt = max((x["input"] + x["cache_read"] + x["w5"] + x["w1"] for x in parts), default=0)
            written = max((x["w5"] + x["w1"] for x in parts), default=0)
            r["rewrite"] = None
            if prev is None:
                r["rewrite"] = "start"
            elif prompt >= cfg["rewrite_min_tokens"] and written >= 0.5 * prompt:
                gap = (r["ts"] - prev["ts"]).total_seconds() / 60 if r["ts"] and prev["ts"] else 0
                r["rewrite"] = "idle" if gap >= cfg["idle_gap_minutes"] else "other"
            prev = r


def usage_parts(u, model):
    """Split a usage block into billable parts. When 'iterations' is present it
    is the complete account (it includes compaction and advisor calls)."""
    its = u.get("iterations")
    parts = its if isinstance(its, list) and its else [u]
    out = []
    for it in parts:
        if not isinstance(it, dict):
            continue
        cc = it.get("cache_creation") if isinstance(it.get("cache_creation"), dict) else {}
        w5, w1 = cc.get("ephemeral_5m_input_tokens"), cc.get("ephemeral_1h_input_tokens")
        if w5 is None and w1 is None:
            w5, w1 = it.get("cache_creation_input_tokens") or 0, 0
        out.append({"model": it.get("model") or model, "input": it.get("input_tokens") or 0,
                    "output": it.get("output_tokens") or 0, "cache_read": it.get("cache_read_input_tokens") or 0,
                    "w5": w5 or 0, "w1": w1 or 0})
    return out


def find_price(model, prices):
    for key in sorted(prices["models"], key=len, reverse=True):
        if key in model:
            return prices["models"][key]
    return None


def part_cost(part, p, fast):
    prompt = part["input"] + part["cache_read"] + part["w5"] + part["w1"]
    r = dict(p)
    lp = p.get("long_prompt")
    if lp and prompt > lp["above_tokens"]:
        r.update(lp)
    mult = p.get("fast_multiplier", 1) if fast else 1
    reread = part["cache_read"] * r["cache_read"] / 1e6 * mult
    write = (part["w5"] * r["cache_write_5m"] + part["w1"] * r["cache_write_1h"]) / 1e6 * mult
    rest = (part["input"] * r["input"] + part["output"] * r["output"]) / 1e6 * mult
    return {"cost": rest + reread + write, "reread": reread, "write": write, "prompt": prompt}


def summarise(responses, prices, cfg, owner_messages=0):
    tiers = defaultdict(lambda: {"responses": 0, "cost": 0.0, "cache_read_cost": 0.0, "cache_write_cost": 0.0,
                                 "input": 0, "output": 0, "cache_read": 0, "cache_write": 0, "models": Counter()})
    agents = {}
    unpriced, notes = Counter(), set()
    rw = {"start": 0.0, "idle": 0.0, "other": 0.0}
    rw_n = Counter()
    worker_prompt = 0
    for r in responses:
        fast = r["usage"].get("speed") == "fast"
        own = find_price(r["model"], prices)
        own_tier = own["tier"] if own else "unpriced"
        a = agents.setdefault(r["agent"], {"id": r["agent"], "worker": r["worker"], "responses": 0, "cost": 0.0,
                                           "peak_context": 0, "tiers": Counter()})
        a["responses"] += 1
        a["tiers"][own_tier] += 1
        tiers[own_tier]["responses"] += 1
        tiers[own_tier]["models"][r["model"]] += 1
        if not own:
            unpriced[r["model"]] += 1
        biggest = 0
        for part in usage_parts(r["usage"], r["model"]):
            p = find_price(part["model"], prices)
            if not p:
                if part["model"] != r["model"]:
                    unpriced[part["model"]] += 1
                continue
            if fast and "fast_multiplier" not in p:
                notes.add(f"fast-mode responses on {part['model']} priced at the standard rate (no fast price on file)")
            c = part_cost(part, p, fast)
            t = tiers[p["tier"]]
            t["cost"] += c["cost"]
            t["cache_read_cost"] += c["reread"]
            t["cache_write_cost"] += c["write"]
            t["input"] += part["input"]
            t["output"] += part["output"]
            t["cache_read"] += part["cache_read"]
            t["cache_write"] += part["w5"] + part["w1"]
            a["cost"] += c["cost"]
            biggest = max(biggest, c["prompt"])
            if r.get("rewrite"):
                rw[r["rewrite"]] += c["write"]
        a["peak_context"] = max(a["peak_context"], biggest)
        if r.get("rewrite"):
            rw_n[r["rewrite"]] += 1
        if r["worker"]:
            worker_prompt += biggest
    total = sum(t["cost"] for t in tiers.values())
    reread = sum(t["cache_read_cost"] for t in tiers.values())
    written = sum(t["cache_write_cost"] for t in tiers.values())
    workers = [a for a in agents.values() if a["worker"]]
    mains = [a for a in agents.values() if not a["worker"]]
    wresp = sum(a["responses"] for a in workers)
    senior = sum(a["tiers"].get("lead", 0) + a["tiers"].get("senior", 0) for a in workers)
    share = lambda x: round(x / total, 4) if total else 0.0
    metrics = {
        "workers": len(workers),
        "worker_responses": wresp,
        "senior_share_of_worker_responses": round(senior / wresp, 4) if wresp else 0.0,
        "max_responses_per_worker": max((a["responses"] for a in workers), default=0),
        "avg_responses_per_worker": round(wresp / len(workers), 1) if workers else 0.0,
        "max_context_per_worker": max((a["peak_context"] for a in workers), default=0),
        "avg_context_per_worker_response": round(worker_prompt / wresp) if wresp else 0,
        "workers_over_budget": sorted(a["id"] for a in workers if a["peak_context"] > cfg["context_budget_tokens"]),
        "cache_read_cost_share": share(reread),
        "cache_write_cost_share": share(written),
        "rewrites": rw_n["idle"] + rw_n["other"],
        "idle_rewrites": rw_n["idle"],
        "rewrite_cost": round(rw["idle"] + rw["other"], 4),
        "idle_rewrite_cost": round(rw["idle"], 4),
        "rewrite_cost_share": share(rw["idle"] + rw["other"]),
        "agent_start_cost": round(rw["start"], 4),
        "main_cost_share": share(sum(a["cost"] for a in mains)),
        "main_responses": sum(a["responses"] for a in mains),
        "main_peak_context": max((a["peak_context"] for a in mains), default=0),
        "owner_messages": owner_messages,
    }
    for a in agents.values():
        a["tier"] = a["tiers"].most_common(1)[0][0] if a["tiers"] else "unpriced"
        a["cost"] = round(a["cost"], 4)
        del a["tiers"]
    for t in tiers.values():
        for k in ("cost", "cache_read_cost", "cache_write_cost"):
            t[k] = round(t[k], 4)
        t["models"] = dict(t["models"])
    return {"total_cost": round(total, 4), "tiers": dict(tiers),
            "agents": sorted(agents.values(), key=lambda a: -a["cost"]), "metrics": metrics,
            "unpriced": dict(unpriced), "notes": sorted(notes)}


def window_start(ctx, rows, pass_no=None):
    autos = [r for r in rows if r.get("kind") == "auto" and (pass_no is None or r["pass"] != pass_no)]
    if autos:
        return parse_ts(max(r["until"] for r in autos))
    return parse_ts(ctx.cfg().get("started_at"))


def measure(ctx, extra, start):
    files = transcript_files(ctx, extra)
    cfg = ctx.cfg()
    responses, owner = load_transcripts(files)
    mark_rewrites(responses, cfg)
    inside = lambda t: start is None or (t and t > start)
    s = summarise([r for r in responses if inside(r["ts"])], ctx.prices(), cfg, sum(1 for t in owner if inside(t)))
    s["files"] = len(files)
    return s


def tier_cells(tiers):
    known = [money(tiers.get(t, {}).get("cost", 0.0)) for t in TIER_ORDER]
    other = sum(v.get("cost", 0.0) for k, v in tiers.items() if k not in TIER_ORDER)
    return known + [money(other)]


def pass_groups(rows):
    groups = defaultdict(lambda: {"auto": None, "manual": []})
    for r in rows:
        if r.get("kind") == "auto":
            groups[r["pass"]]["auto"] = r
        else:
            groups[r["pass"]]["manual"].append(r)
    return dict(sorted(groups.items()))


def pass_total(g):
    return (g["auto"]["total_cost"] if g["auto"] else 0.0) + sum(m["cost"] for m in g["manual"])


def north_limits(ctx):
    """Pass cap and cost ceiling. The North Star is the source; config is the fallback."""
    cfg = ctx.cfg()
    cap, ceiling = cfg.get("pass_cap"), cfg.get("budget_usd")
    if ctx.north.exists():
        body = split_sections(ctx.north.read_text(encoding="utf-8"))[0].get("budget", "")
        m = re.search(r"Pass cap:\s*(\d+)", body)
        if m:
            cap = int(m.group(1))
        m = re.search(r"Cost ceiling:\s*\$?\s*([\d,]+(?:\.\d+)?)", body)
        if m:
            ceiling = float(m.group(1).replace(",", ""))
    return cap, ceiling


def kilo(n):
    return f"{n / 1000:.0f}K"


def print_measure(s, title):
    print(title)
    rows = []
    for t in TIER_ORDER + sorted(k for k in s["tiers"] if k not in TIER_ORDER):
        v = s["tiers"].get(t)
        if v:
            share = v["cost"] / s["total_cost"] if s["total_cost"] else 0
            rows.append([t, ", ".join(v["models"]), v["responses"], money(v["cost"]), pct(share),
                         money(v["cache_read_cost"]), money(v.get("cache_write_cost", 0.0))])
    rows.append(["total", "", sum(v["responses"] for v in s["tiers"].values()), money(s["total_cost"]), "", "", ""])
    print(table(["tier", "model", "responses", "cost", "share", "re-reading", "cache writing"], rows))
    m = s["metrics"]
    print(f"lead's own conversation: {pct(m.get('main_cost_share', 0))} of cost, context up to {kilo(m.get('main_peak_context', 0))} tokens, "
          f"{m.get('owner_messages', 0)} owner messages")
    print(f"workers: {m['workers']}, largest context {kilo(m.get('max_context_per_worker', 0))} tokens, average "
          f"{kilo(m.get('avg_context_per_worker_response', 0))} per response, longest {m['max_responses_per_worker']} responses; "
          f"senior-or-above share of worker responses {pct(m['senior_share_of_worker_responses'])}")
    print(f"re-reading cached context {pct(m['cache_read_cost_share'])} of cost; rewriting context {money(m.get('rewrite_cost', 0))} "
          f"({m.get('rewrites', 0)} times, {m.get('idle_rewrites', 0)} after an idle gap, {money(m.get('idle_rewrite_cost', 0))}); "
          f"starting agents {money(m.get('agent_start_cost', 0))}")
    if m["workers_over_budget"]:
        print("over the context budget: " + ", ".join(m["workers_over_budget"]))
    for model, n in s["unpriced"].items():
        print(f"NOT PRICED: {n} responses from '{model}' (no entry in prices.json). The total is too low by their cost.")
    for n in s["notes"]:
        print("note: " + n)


def cmd_cost_now(ctx, a):
    ctx.need_state()
    s = measure(ctx, a.transcripts, window_start(ctx, read_jsonl(ctx.ledger)))
    print_measure(s, f"Since the last recorded pass ({s['files']} transcript files read; nothing recorded):")
    return 0


def record_cost(ctx, pass_no, extra=None, force=False):
    rows = read_jsonl(ctx.ledger)
    existing = [r for r in rows if r.get("kind") == "auto" and r["pass"] == pass_no]
    if existing and not force:
        return existing[-1], False
    if existing:
        rows = [r for r in rows if not (r.get("kind") == "auto" and r["pass"] == pass_no)]
        write_jsonl(ctx.ledger, rows)
    start = window_start(ctx, rows, pass_no)
    s = measure(ctx, extra, start)
    row = {"pass": pass_no, "kind": "auto", "recorded_at": now_iso(),
           "from": start.strftime("%Y-%m-%dT%H:%M:%SZ") if start else None, "until": now_iso(), **s}
    append_jsonl(ctx.ledger, row)
    return row, True


def cmd_cost_record(ctx, a):
    ctx.need_state()
    row, new = record_cost(ctx, a.pass_no, a.transcripts, a.force)
    print_measure(row, f"Pass {a.pass_no} cost " + ("recorded:" if new else "(already recorded; use --force to redo):"))
    return 0


def cmd_cost_add(ctx, a):
    ctx.need_state()
    append_jsonl(ctx.ledger, {"pass": a.pass_no, "kind": "manual", "recorded_at": now_iso(), "label": a.label,
                              "tier": a.tier, "cost": a.cost, "note": a.note or ""})
    print(f"added {money(a.cost)} to pass {a.pass_no} for '{a.label}' ({a.tier})")
    return 0


def cost_report(ctx):
    groups = pass_groups(read_jsonl(ctx.ledger))
    if not groups:
        return "No passes recorded yet.", 0.0, groups
    rows, cum = [], 0.0
    totals = defaultdict(lambda: {"responses": 0, "cost": 0.0})
    for n, g in groups.items():
        tiers = {k: dict(v) for k, v in (g["auto"]["tiers"] if g["auto"] else {}).items()}
        for m in g["manual"]:
            tiers.setdefault(m["tier"], {"cost": 0.0, "responses": 0})
            tiers[m["tier"]]["cost"] = tiers[m["tier"]].get("cost", 0.0) + m["cost"]
        for k, v in tiers.items():
            totals[k]["cost"] += v.get("cost", 0.0)
            totals[k]["responses"] += v.get("responses", 0)
        tot = pass_total(g)
        cum += tot
        mt = g["auto"]["metrics"] if g["auto"] else {}
        rows.append([n] + tier_cells(tiers) + [money(tot), money(cum), pct(mt.get("main_cost_share", 0)),
                    pct(mt.get("senior_share_of_worker_responses", 0)), pct(mt.get("cache_read_cost_share", 0)),
                    pct(mt.get("rewrite_cost_share", 0)), mt.get("workers", 0), kilo(mt.get("max_context_per_worker", 0)),
                    kilo(mt.get("main_peak_context", 0)), mt.get("owner_messages", 0)])
    out = [table(["pass"] + TIER_ORDER + ["other", "total", "running", "lead%", "senior%", "re-read%", "rewrite%", "workers",
                  "worker ctx", "lead ctx", "owner msgs"], rows), ""]
    trows = [[t, v["responses"], money(v["cost"]), pct(v["cost"] / cum) if cum else "0%"]
             for t, v in sorted(totals.items(), key=lambda kv: -kv[1]["cost"])]
    out.append(table(["tier", "responses", "cost", "share"], trows + [["total", sum(v["responses"] for v in totals.values()), money(cum), ""]]))
    cap, ceiling = north_limits(ctx)
    last = max(groups)
    recent = [pass_total(groups[n]) for n in sorted(groups)[-3:]]
    rate = sum(recent) / len(recent)
    out.append("")
    if cap:
        left = max(cap - last, 0)
        out.append(f"Projection: {left} of {cap} passes left at about {money(rate)} a pass (mean of the last "
                   f"{len(recent)}) -> about {money(cum + left * rate)} at the cap.")
    else:
        out.append(f"No pass cap set, so no projection. Recent passes cost about {money(rate)} each.")
    if ceiling:
        out.append(f"Cost ceiling {money(ceiling)}: {pct(cum / ceiling)} used.")
    unpriced = Counter()
    for g in groups.values():
        if g["auto"]:
            unpriced.update(g["auto"].get("unpriced") or {})
    for model, n in unpriced.items():
        out.append(f"NOT PRICED: {n} responses from '{model}'. The totals are too low by their cost.")
    not_counted = ctx.cfg().get("not_counted") or []
    out.append("Not counted: " + ("; ".join(not_counted) if not_counted else "nothing declared. Anything billed outside these transcripts is missing."))
    p = ctx.prices()
    out.append(f"API-equivalent cost at list prices as of {p.get('as_of')}. On a subscription this is what the work would have cost, not a bill.")
    return "\n".join(out), cum, groups


def lane_costs(ctx):
    """Cost of each lane-ledger row, by matching the ids in its Agent column to
    worker transcripts across every recorded pass."""
    sec = split_sections(ctx.north.read_text(encoding="utf-8"))[0] if ctx.north.exists() else {}
    lanes = parse_table(sec.get("lane ledger", ""))
    spend = defaultdict(lambda: {"cost": 0.0, "responses": 0})
    for r in read_jsonl(ctx.ledger):
        for ag in r.get("agents", []) if r.get("kind") == "auto" else []:
            if ag.get("worker"):
                spend[ag["id"]]["cost"] += ag["cost"]
                spend[ag["id"]]["responses"] += ag["responses"]
    claimed, rows = set(), []
    for l in lanes:
        tokens = [t for t in re.split(r"[\s,;]+", l.get("agent", "").lower()) if len(t) >= 2 and not blank(t)]
        mine = [i for i in spend if any(i.lower() == t or i.lower().startswith(t) or i.lower().replace("agent-", "").startswith(t) for t in tokens)]
        claimed.update(mine)
        rows.append({"lane": l.get("lane", "?"), "tier": l.get("tier", "").strip().lower(), "status": l.get("status", "").strip().lower(),
                     "strikes": l.get("strikes", "").strip(), "agents": len(mine),
                     "responses": sum(spend[i]["responses"] for i in mine), "cost": sum(spend[i]["cost"] for i in mine)})
    loose = [i for i in spend if i not in claimed]
    return rows, loose, sum(spend[i]["cost"] for i in loose)


def cmd_cost_lanes(ctx, a):
    ctx.need_state()
    rows, loose, loose_cost = lane_costs(ctx)
    if not rows:
        print("The lane ledger has no rows.")
        return 0
    print(table(["lane", "tier", "status", "strikes", "agents", "responses", "cost"],
                [[r["lane"], r["tier"], r["status"], r["strikes"], r["agents"], r["responses"], money(r["cost"])] for r in rows]))
    if loose:
        print(f"{len(loose)} worker transcripts ({money(loose_cost)}) match no row: " + ", ".join(loose[:8]))
    by = defaultdict(lambda: {"rows": 0, "done": 0, "promoted": 0, "dropped": 0, "cost": 0.0})
    for r in rows:
        b = by[r["tier"] or "?"]
        b["rows"] += 1
        b["cost"] += r["cost"]
        for st in ("done", "promoted", "dropped"):
            b[st] += r["status"] == st
    trows = []
    for t in TIER_ORDER + sorted(x for x in by if x not in TIER_ORDER):
        if t in by:
            b = by[t]
            closed = b["done"] + b["promoted"] + b["dropped"]
            trows.append([t, b["rows"], b["done"], b["promoted"], b["dropped"],
                          pct(b["done"] / closed) if closed else "-", money(b["cost"]),
                          money(b["cost"] / b["done"]) if b["done"] else "-"])
    print()
    print(table(["tier", "rows", "done", "promoted", "dropped", "finished here", "cost", "cost per finished row"], trows))
    done_lanes = defaultdict(float)
    final = {}
    for r in rows:
        done_lanes[r["lane"]] += r["cost"]
        final[r["lane"]] = r["status"]
    fin = [c for l, c in done_lanes.items() if final[l] == "done"]
    if fin:
        print(f"Finished tasks: {len(fin)}, {money(sum(fin) / len(fin))} each on average, counting every tier they passed through.")
    print("'finished here' is the share of closed rows at a tier that ended done rather than promoted or dropped. "
          "Starting a tier below is worth it when this is above that tier's price as a fraction of the next one.")
    return 0


def cmd_cost_report(ctx, a):
    ctx.need_state()
    print(cost_report(ctx)[0])
    return 0


# ---------- North Star: parsing and checks ----------

def norm_title(t):
    return re.sub(r"\s*\(.*\)\s*$", "", t).strip().lower()


def split_sections(text):
    """Returns (sections, subsections, order). A section runs to the next '## '
    and includes its '### ' parts; a subsection runs to the next heading."""
    sec, sub, order = {}, {}, []
    cur = cursub = None
    for line in text.splitlines():
        m = re.match(r"^(#{2,3})\s+(.*)$", line)
        if m and m.group(1) == "##":
            cur, cursub = norm_title(m.group(2)), None
            sec[cur] = []
            order.append(cur)
            continue
        if m and cur:
            cursub = norm_title(m.group(2))
            sub[cursub] = []
            sec[cur].append(line)
            continue
        if cur:
            sec[cur].append(line)
        if cursub:
            sub[cursub].append(line)
    return {k: "\n".join(v) for k, v in sec.items()}, {k: "\n".join(v) for k, v in sub.items()}, order


def blank(s):
    s = (s or "").strip()
    return not s or s in ("-", "...", "n/a", "N/A", "none") or bool(re.search(r"<[^<>\n]+>", s))


def parse_table(text):
    rows, started = [], False
    for line in text.splitlines():
        if line.strip().startswith("|"):
            started = True
            rows.append([c.strip() for c in line.strip().strip("|").split("|")])
        elif started:
            break
    if len(rows) < 2:
        return []
    head = [h.lower() for h in rows[0]]
    out = []
    for cells in rows[1:]:
        if all(re.fullmatch(r":?-*:?", c) for c in cells):
            continue
        d = dict(zip(head, cells))
        if not blank(cells[0]):
            out.append(d)
    return out


def real_lines(text):
    return [l.strip() for l in text.splitlines() if l.strip() and not l.strip().startswith("#")]


def latest_snapshot(ctx, before_pass=None):
    best = None
    if ctx.snaps.exists():
        for p in ctx.snaps.glob("pass-*.md"):
            m = re.fullmatch(r"pass-(\d+)", p.stem)
            if m and (before_pass is None or int(m.group(1)) < before_pass):
                if best is None or int(m.group(1)) > best[0]:
                    best = (int(m.group(1)), p)
    return best


def lint_north(ctx, pass_no=None, cost_row=None):
    cfg = ctx.cfg()
    if not ctx.north.exists():
        return {"north_star_exists": ("REPEAT", f"{ctx.north.name} not found")}
    sec, sub, order = split_sections(ctx.north.read_text(encoding="utf-8"))
    R = {}

    need = ["one sentence", "current state", "mandate", "the one thing", "decisions and why",
            "environment contract", "gates and bars", "lane ledger", "owner notes", "budget", "status log"]
    missing = [n for n in need if n not in sec]
    R["sections_present"] = ("REPEAT", "missing: " + ", ".join(missing)) if missing else ("CLEAR", "")
    R["status_log_last"] = ("CLEAR", "") if order and order[-1] == "status log" else ("REPEAT", "Status log must be the last section")

    cs = real_lines(sec.get("current state", ""))
    problems = []
    if len(cs) > cfg["current_state_max_lines"]:
        problems.append(f"{len(cs)} lines, limit {cfg['current_state_max_lines']}")
    for label in ("Works", "Fails", "Next"):
        hit = [l for l in cs if l.startswith(label + ":")]
        if not hit or blank(hit[0].split(":", 1)[1]) and label != "Fails":
            problems.append(f"no real '{label}:' line")
    R["current_state_block"] = ("REPEAT", "; ".join(problems)) if problems else ("CLEAR", f"{len(cs)} lines")
    unv = [l for l in cs if l.lower().startswith("unverified by a person:")]
    ok = bool(unv) and bool(unv[0].split(":", 1)[1].strip()) and not re.search(r"<[^<>]+>", unv[0])
    R["unverified_line"] = ("CLEAR", unv[0][:80]) if ok else ("REPEAT", "Current state has no 'Unverified by a person:' line with content (write 'nothing' only if a person has checked everything)")

    lanes = parse_table(sec.get("lane ledger", ""))
    R["lane_ledger_has_rows"] = ("CLEAR", f"{len(lanes)} lanes") if lanes else ("REPEAT", "lane ledger is empty")
    bad = [l.get("lane", "?") for l in lanes if l.get("tier", "").strip().lower() in ("senior", "lead") and blank(l.get("why this tier", ""))]
    R["tier_justified"] = ("REPEAT", "started above standard with no reason: " + ", ".join(bad)) if bad else ("CLEAR", "")
    stuck = []
    for l in lanes:
        m = re.match(r"\d+", l.get("strikes", "").strip())
        tier = l.get("tier", "").strip().lower()
        allowed = cfg["strike_allowance"].get(tier, 3)
        if m and int(m.group()) >= allowed and l.get("status", "").strip().lower() in ("open", "running", "verify"):
            stuck.append(f"{l.get('lane', '?')} ({m.group()} strikes at {tier or '?'}, allowance {allowed})")
    R["strikes_acted"] = ("REPEAT", "struck out but not promoted: " + ", ".join(stuck)) if stuck else ("CLEAR", "")

    gates = parse_table(sec.get("gates and bars", ""))
    known = sub.get("known failures", "").lower()
    unlisted = [g["gate"] for g in gates if g.get("status", "").strip().upper().startswith("FAIL") and g.get("gate", "").lower() not in known]
    R["known_failures_listed"] = ("REPEAT", "failing but not under Known failures: " + ", ".join(unlisted)) if unlisted else ("CLEAR", f"{len(gates)} gates")
    R["tool_quirks_section"] = ("CLEAR", "") if "tool quirks" in sub else ("REPEAT", "no '### Tool quirks' section")
    excl = [l for l in real_lines(sec.get("environment contract", "")) if l.lower().startswith("exclusive resources:")]
    R["exclusive_resources_line"] = ("CLEAR", excl[0][:80]) if excl and not blank(excl[0].split(":", 1)[1]) or excl and excl[0].split(":", 1)[1].strip().lower().startswith("none") else (
        "REPEAT", "Environment contract has no 'Exclusive resources:' line. List each thing only one agent can use at a time and how turns are taken, or write 'none'")
    notes = parse_table(sec.get("owner notes", ""))
    lost = [n.get("id", "?") for n in notes if blank(n.get("routed to", "")) or blank(n.get("status", ""))]
    R["owner_notes_routed"] = ("REPEAT", "owner notes with no route or no status: " + ", ".join(lost)) if lost else ("CLEAR", f"{len(notes)} notes")
    cap = re.search(r"Pass cap:\s*(\d+)", sec.get("budget", ""))
    R["pass_cap_set"] = ("CLEAR", f"cap {cap.group(1)}") if cap else ("REPEAT", "Budget has no 'Pass cap: <number>'. Ask the owner, or propose one and record it as the lead's proposal")

    prev = latest_snapshot(ctx, pass_no)
    if prev is None:
        for k in ("bars_unmoved", "status_log_append_only", "mandate_kept"):
            R[k] = ("CLEAR", "no earlier snapshot to compare")
    else:
        psec, psub, _ = split_sections(prev[1].read_text(encoding="utf-8"))
        pgates = {g["gate"]: g.get("bar", "") for g in parse_table(psec.get("gates and bars", ""))}
        cgates = {g["gate"]: g.get("bar", "") for g in gates}
        old_changes = set(real_lines(psub.get("bar changes", "")))
        new_changes = " ".join(l for l in real_lines(sub.get("bar changes", "")) if l not in old_changes and not blank(l)).lower()
        moved = []
        for name, bar in pgates.items():
            if name not in cgates:
                if name.lower() not in new_changes:
                    moved.append(f"{name}: gate removed")
            elif cgates[name] != bar and name.lower() not in new_changes:
                moved.append(f"{name}: bar {bar} -> {cgates[name]}")
        R["bars_unmoved"] = ("REPEAT", f"changed since pass {prev[0]} with no new owner entry under Bar changes: " + "; ".join(moved)) if moved else ("CLEAR", f"compared with pass {prev[0]}")
        plog, clog = real_lines(psec.get("status log", "")), real_lines(sec.get("status log", ""))
        diff = next((i for i, l in enumerate(plog) if i >= len(clog) or clog[i] != l), None)
        R["status_log_append_only"] = ("CLEAR", f"{len(clog) - len(plog)} new lines") if diff is None else ("REPEAT", f"an earlier entry was changed or removed: '{plog[diff][:70]}'")
        quotes = [l for l in real_lines(psec.get("mandate", "")) if l.startswith('"') and not blank(l)]
        gone = [q[:60] for q in quotes if q not in sec.get("mandate", "")]
        R["mandate_kept"] = ("ASK", "owner statement no longer in Mandate: " + " | ".join(gone)) if gone else ("CLEAR", "")

    if cost_row:
        agents_col = " ".join(l.get("agent", "") for l in lanes).lower()
        workers = [a["id"] for a in cost_row.get("agents", []) if a.get("worker")]
        lost = [w for w in workers if w.lower() not in agents_col and w.lower().replace("agent-", "")[:8] not in agents_col]
        R["lane_ledger_reconciles"] = ("ASK", f"{len(lost)} of {len(workers)} worker transcripts not named in the lane ledger: " + ", ".join(lost[:8])) if lost else ("CLEAR", f"{len(workers)} worker transcripts matched")
    else:
        R["lane_ledger_reconciles"] = ("CLEAR", "no cost row to compare")
    return R


def cmd_north_check(ctx, a):
    ctx.need_state()
    R = lint_north(ctx, a.pass_no)
    print(table(["check", "result", "evidence"], [[k, v[0], v[1]] for k, v in R.items()]))
    return 1 if any(v[0] == "REPEAT" for v in R.values()) else 0


def snapshot(ctx, pass_no):
    ctx.snaps.mkdir(parents=True, exist_ok=True)
    dest = ctx.snaps / f"pass-{pass_no}.md"
    shutil.copyfile(ctx.north, dest)
    return dest


def cmd_north_snapshot(ctx, a):
    ctx.need_state()
    print(f"snapshot saved: {snapshot(ctx, a.pass_no)}")
    return 0


# ---------- briefs ----------

BRIEF_HEADS = ["STOP AND REPORT IF", "EXPECTED FAILURES", "ALREADY RULED OUT", "STANDING LIMITS", "KILL RULE", "SUSPECTS",
               "NUMBERS", "DESIGN", "REPORT", "FILES", "GOAL", "GATE"]


def parse_brief(text):
    parts, cur = {}, None
    for line in text.splitlines():
        head = next((h for h in BRIEF_HEADS if re.match(rf"^{h}(\s*\(.*\))?\s*:?\s*$", line.strip())), None)
        if head:
            cur = head
            parts[cur] = []
        elif cur:
            parts[cur].append(line)
    # Lines starting with '>' are standing guidance printed in the template, not the lead's content.
    return {k: [l.strip() for l in v if l.strip() and not l.strip().startswith(">") and not re.search(r"<[^<>\n]+>", l)]
            for k, v in parts.items()}


def lint_brief(path):
    b = parse_brief(Path(path).read_text(encoding="utf-8"))
    R = {}
    if "SUSPECTS" in b:
        thin = [h for h in ("EXPECTED FAILURES", "ALREADY RULED OUT") if not b.get(h)]
        if not any("->" in l or "rule" in l.lower() or "test" in l.lower() for l in b["SUSPECTS"]):
            thin.append("SUSPECTS (each needs the test that would rule it out)")
    else:
        thin = [h for h in ("DESIGN", "NUMBERS", "EXPECTED FAILURES", "ALREADY RULED OUT") if not b.get(h)]
    R["brief_has_reasoning"] = ("REPEAT", "empty or missing: " + ", ".join(thin)) if thin else ("CLEAR", "")
    R["brief_has_stop"] = ("CLEAR", "") if b.get("STOP AND REPORT IF") else ("REPEAT", "no stop conditions")
    R["brief_has_kill"] = ("CLEAR", "") if b.get("KILL RULE") else ("REPEAT", "no KILL RULE. Say when to abandon the task, or write 'not an experiment'")
    gate = b.get("GATE", [])
    ok = any(l.startswith("Run:") for l in gate) and any(l.startswith("Pass:") for l in gate)
    R["brief_has_gate"] = ("CLEAR", "") if ok else ("REPEAT", "GATE needs a real 'Run:' and 'Pass:' line")
    files = b.get("FILES", [])
    ok = any(l.startswith("Yours:") for l in files) and any(l.startswith("Do not touch:") for l in files)
    R["brief_has_files"] = ("CLEAR", "") if ok else ("REPEAT", "FILES needs real 'Yours:' and 'Do not touch:' lines")
    return R


# ---------- mistakes ----------

def ledger_checks(ctx, pass_no):
    R = {}
    groups = pass_groups(read_jsonl(ctx.ledger))
    if pass_no is None:
        return {k: ("CLEAR", "no pass given") for k in ("passes_contiguous", "within_pass_cap", "within_budget", "accepted_lanes_checked")}
    gaps = [n for n in range(1, pass_no + 1) if not (groups.get(n) or {}).get("auto")]
    R["passes_contiguous"] = ("REPEAT", "no cost recorded for pass " + ", ".join(map(str, gaps))) if gaps else ("CLEAR", f"passes 1-{pass_no} recorded")
    lanes = parse_table(split_sections(ctx.north.read_text(encoding="utf-8"))[0].get("lane ledger", "")) if ctx.north.exists() else []
    checked = {e.get("brief") for e in read_jsonl(ctx.mlog) if e.get("at") == "accept"}
    unchecked = [l.get("lane", "?") for l in lanes if l.get("status", "").strip().lower() == "done" and f"lane:{l.get('lane', '?')}" not in checked]
    R["accepted_lanes_checked"] = ("REPEAT", "marked done with no accept check on record: " + ", ".join(unchecked)
                                   + ". Run: mistakes check --at accept --pass N --lane NAME") if unchecked else ("CLEAR", "")
    cap, ceiling = north_limits(ctx)
    R["within_pass_cap"] = ("REPEAT", f"pass {pass_no} is past the cap of {cap}. Stop and give the owner the known-gaps list, or get a new cap in their words") if cap and pass_no > cap else ("CLEAR", f"pass {pass_no} of {cap or 'no cap'}")
    cum = sum(pass_total(g) for g in groups.values())
    if ceiling and cum > ceiling:
        R["within_budget"] = ("REPEAT", f"{money(cum)} spent, ceiling {money(ceiling)}. This is the owner's call")
    elif ceiling and cum > 0.8 * ceiling:
        R["within_budget"] = ("ASK", f"{money(cum)} is {pct(cum / ceiling)} of the ceiling {money(ceiling)}. Tell the owner now, not at 100%")
    else:
        R["within_budget"] = ("CLEAR", money(cum) + (f" of {money(ceiling)}" if ceiling else ", no ceiling set"))
    return R


def log_key(e):
    return (e["id"], e.get("pass"), e.get("at"), e.get("brief"))


def run_mistake_checks(ctx, at, pass_no=None, brief=None, lint=None, cost_row=None, record=True, subject=None):
    subject = str(subject) if subject else None
    cfg = ctx.cfg()
    reg = [m for m in read_jsonl(ctx.register) if at in m.get("when", [])]
    log = read_jsonl(ctx.mlog)
    answers = {log_key(e): e for e in log if e.get("kind") == "answer"}
    if lint is None and any(c["kind"] == "northstar" for m in reg for c in m.get("checks", [])):
        lint = lint_north(ctx, pass_no, cost_row)
    blint = lint_brief(brief) if brief else {}
    lcheck = ledger_checks(ctx, pass_no)
    metrics = (cost_row or {}).get("metrics") or {}
    results = []
    for m in reg:
        worst, ev, asked = "CLEAR", [], False
        for c in m.get("checks") or [{"kind": "manual"}]:
            kind, name = c["kind"], c.get("name")
            if c.get("at") and at not in c["at"]:
                continue
            if kind == "manual":
                res, e, asked = "ASK", "", True
            elif kind == "northstar":
                res, e = (lint or {}).get(name, ("CLEAR", "not checked"))
            elif kind == "brief":
                res, e = blint.get(name, ("ASK", "no --brief file given"))
            elif kind == "ledger":
                res, e = lcheck.get(name, ("CLEAR", "not checked"))
            elif kind == "metric":
                if name not in metrics:
                    res, e = "CLEAR", "no cost row"
                else:
                    limit = cfg[c["config"]]
                    ok = metrics[name] <= limit
                    res = "CLEAR" if ok else ("REPEAT" if c.get("on_fail") == "repeat" else "ASK")
                    e = f"{name} {metrics[name]} against {limit}"
                    asked = asked or res == "ASK"
            else:
                res, e = "ASK", f"unknown check kind '{kind}'"
            if res != "CLEAR" and e:
                ev.append(e)
            if res == "ASK":
                asked = True
            if RANK[res] > RANK[worst]:
                worst = res
        if worst == "ASK":
            ans = answers.get((m["id"], pass_no, at, subject))
            if ans:
                worst, ev = ans["result"], ["lead's answer: " + ans.get("evidence", "")]
            elif asked and m.get("question"):
                ev.append(m["question"])
        results.append({"id": m["id"], "title": m["title"], "result": worst, "evidence": "; ".join(ev), "level": m.get("level", "prose")})
        if record:
            append_jsonl(ctx.mlog, {"ts": now_iso(), "kind": "check", "pass": pass_no, "at": at,
                                    "brief": subject, "id": m["id"], "result": worst,
                                    "evidence": "; ".join(ev)})
    return results


def print_mistake_results(results):
    for label, word in (("REPEAT", "REPEATED"), ("ASK", "ANSWER NEEDED"), ("CLEAR", "clear")):
        for r in results:
            if r["result"] == label:
                tail = f"\n        {r['evidence']}" if r["evidence"] and label != "CLEAR" else ""
                print(f"  {word:<13} {r['id']}  {r['title']}{tail}")


def lesson_stats(ctx):
    log = read_jsonl(ctx.mlog)
    by = defaultdict(lambda: {"checked": set(), "repeat_keys": set(), "latest": {}, "first": {}})
    for e in log:
        if e.get("kind") not in ("check", "answer"):
            continue
        s = by[e["id"]]
        k = log_key(e)
        s["checked"].add(k)
        if e["result"] == "REPEAT":
            s["repeat_keys"].add(k)
            s["first"].setdefault(k, e.get("ts", ""))
        s["latest"][k] = e["result"]
    return by


def lesson_strikes(m, s):
    """Strikes against a lesson at its current level. Below 'scripted' every
    repeat counts. At 'scripted' a repeat counts only if it was still failing
    when last checked: caught and fixed before the pass closed is the check working."""
    if not s:
        return 0
    since = m.get("promoted_at", "")
    keys = [k for k in s["repeat_keys"] if s["first"].get(k, "") > since]
    if m.get("level", "prose") == "scripted":
        keys = [k for k in keys if s["latest"].get(k) == "REPEAT"]
    return len(keys)


def struck_out(ctx):
    limit = ctx.cfg()["lesson_strike_limit"]
    stats = lesson_stats(ctx)
    nxt = {"prose": "write it into a template so it cannot be skipped (promote --level template)",
           "template": "turn it into a scripted check or a project gate (promote --level scripted)",
           "scripted": "the check keeps firing, so the process is wrong, not the reminder. Take it to the owner (promote --level owner)",
           "owner": "already with the owner"}
    out = []
    for m in read_jsonl(ctx.register):
        n = lesson_strikes(m, stats.get(m["id"]))
        level = m.get("level", "prose")
        if n >= limit and level != "owner":
            out.append(f"{m['id']} has {n} strikes at level '{level}': {nxt[level]}")
    return out


def exit_code(results):
    if any(r["result"] == "REPEAT" for r in results):
        return 1
    return 2 if any(r["result"] == "ASK" for r in results) else 0


def cmd_mistakes_check(ctx, a):
    ctx.need_state()
    if a.at == "brief" and not a.brief:
        die("--at brief needs --brief FILE")
    row = None
    if a.pass_no is not None:
        row = next((r for r in read_jsonl(ctx.ledger) if r.get("kind") == "auto" and r["pass"] == a.pass_no), None)
    subject = a.brief or (f"lane:{a.lane}" if a.lane else None)
    results = run_mistake_checks(ctx, a.at, a.pass_no, a.brief, cost_row=row, subject=subject)
    print(f"Diff against past mistakes, checkpoint '{a.at}'" + (f", {subject}" if subject else "") + ":")
    print_mistake_results(results)
    for s in struck_out(ctx):
        print("STRUCK OUT: " + s)
    return exit_code(results)


def cmd_mistakes_answer(ctx, a):
    ctx.need_state()
    if a.id not in {m["id"] for m in read_jsonl(ctx.register)}:
        die(f"no mistake '{a.id}' in the register")
    append_jsonl(ctx.mlog, {"ts": now_iso(), "kind": "answer", "pass": a.pass_no, "at": a.at,
                            "brief": a.brief or (f"lane:{a.lane}" if a.lane else None), "id": a.id,
                            "result": a.result.upper(), "evidence": a.note})
    print(f"recorded {a.result.upper()} for {a.id}, pass {a.pass_no}, checkpoint {a.at}")
    return 0


def cmd_mistakes_add(ctx, a):
    ctx.need_state()
    reg = read_jsonl(ctx.register)
    stem = "X-" + today().replace("-", "")
    n = 1 + sum(1 for m in reg if m["id"].startswith(stem))
    entry = {"id": f"{stem}-{n:02d}", "title": a.title, "what": a.what, "cause": a.cause, "rule": a.rule,
             "when": a.when, "checks": [{"kind": "manual"}], "question": a.question, "level": "prose",
             "source": f"{ctx.root.name}, pass {a.pass_no}" if a.pass_no else ctx.root.name, "first_seen": today()}
    append_jsonl(ctx.register, entry)
    if a.pass_no is not None:
        append_jsonl(ctx.mlog, {"ts": now_iso(), "kind": "check", "pass": a.pass_no, "at": "found", "brief": None,
                                "id": entry["id"], "result": "REPEAT", "evidence": "first occurrence: " + a.what})
    print(f"added {entry['id']}: {a.title}")
    return 0


def cmd_mistakes_report(ctx, a):
    ctx.need_state()
    stats = lesson_stats(ctx)
    rows = []
    for m in read_jsonl(ctx.register):
        s = stats.get(m["id"])
        checked = len(s["checked"]) if s else 0
        rep = len(s["repeat_keys"]) if s else 0
        still = sum(1 for k in s["repeat_keys"] if s["latest"].get(k) == "REPEAT") if s else 0
        passes = sorted({k[1] for k in s["repeat_keys"] if k[1] is not None}) if s else []
        rows.append([m["id"], m.get("level", "prose"), checked, rep, still, lesson_strikes(m, s),
                     ",".join(map(str, passes)) or "-", m["title"][:60]])
    print(table(["id", "level", "checked", "repeats", "unfixed", "strikes", "in passes", "mistake"], rows))
    for s in struck_out(ctx):
        print("STRUCK OUT: " + s)
    return 0


def cmd_mistakes_promote(ctx, a):
    ctx.need_state()
    reg = read_jsonl(ctx.register)
    hit = [m for m in reg if m["id"] == a.id]
    if not hit:
        die(f"no mistake '{a.id}' in the register")
    old = hit[0].get("level", "prose")
    hit[0]["level"] = a.level
    hit[0]["promoted_at"] = now_iso()
    write_jsonl(ctx.register, reg)
    append_jsonl(ctx.mlog, {"ts": now_iso(), "kind": "promotion", "id": a.id, "from": old, "to": a.level, "evidence": a.note})
    print(f"{a.id}: {old} -> {a.level}. Its strike count starts again at the new level.")
    return 0


def cmd_mistakes_export(ctx, a):
    ctx.need_state()
    dest = Path(a.to).expanduser() if a.to else GLOBAL_REGISTER
    dest.parent.mkdir(parents=True, exist_ok=True)
    have = read_jsonl(dest)
    ids, titles = {m["id"] for m in have}, {m["title"] for m in have}
    stats = lesson_stats(ctx)
    added = 0
    for m in read_jsonl(ctx.register):
        rep = len(stats[m["id"]]["repeat_keys"]) if m["id"] in stats else 0
        note = {"project": ctx.root.name, "date": today(), "repeats": rep, "level": m.get("level", "prose")}
        if m["id"] in ids or m["title"] in titles:
            for h in have:
                if h["id"] == m["id"] or h["title"] == m["title"]:
                    h["history"] = [x for x in h.get("history", []) if x.get("project") != ctx.root.name] + [note]
                    order = ["prose", "template", "scripted", "owner"]
                    if order.index(m.get("level", "prose")) > order.index(h.get("level", "prose")):
                        h["level"] = m.get("level", "prose")
        else:
            have.append({**{k: v for k, v in m.items() if k != "promoted_at"}, "history": [note]})
            added += 1
    write_jsonl(dest, have)
    print(f"exported to {dest}: {added} new, {len(have)} total")
    return 0


# ---------- init and pass-end ----------

def cmd_init(ctx, a):
    ctx.state.mkdir(exist_ok=True)
    ctx.snaps.mkdir(exist_ok=True)
    made = []
    cfgp = ctx.state / "config.json"
    if not cfgp.exists():
        cfg = json.loads((ASSETS / "config.default.json").read_text(encoding="utf-8"))
        cfg["started_at"] = now_iso()
        cfgp.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
        made.append("config.json")
    if not (ctx.state / "prices.json").exists():
        shutil.copyfile(ASSETS / "prices.json", ctx.state / "prices.json")
        made.append("prices.json")
    if not ctx.register.exists():
        reg = read_jsonl(ASSETS / "mistakes.seed.jsonl")
        ids, titles = {m["id"] for m in reg}, {m["title"] for m in reg}
        extra = [m for m in read_jsonl(GLOBAL_REGISTER) if m["id"] not in ids and m["title"] not in titles]
        by_id = {m["id"]: m for m in read_jsonl(GLOBAL_REGISTER)}
        order = ["prose", "template", "scripted", "owner"]
        for m in reg:
            g = by_id.get(m["id"])
            if g and order.index(g.get("level", "prose")) > order.index(m.get("level", "prose")):
                m["level"] = g["level"]
        write_jsonl(ctx.register, reg + extra)
        made.append(f"mistakes.jsonl ({len(reg)} from the skill, {len(extra)} from earlier projects)")
    for p in (ctx.ledger, ctx.mlog):
        if not p.exists():
            p.touch()
    if not ctx.north.exists():
        text = (ASSETS / "NORTH_STAR.template.md").read_text(encoding="utf-8")
        head = text.split("\n", 2)
        head[0] = head[0].replace("<PROJECT>", a.project or ctx.root.name)
        head[1] = head[1].replace("<model>", a.lead or "<model>").replace("<name>", a.owner or "<name>").replace("<date>", today())
        ctx.north.write_text("\n".join(head), encoding="utf-8")
        made.append("NORTH_STAR.md")
    print(f"Initialised {ctx.state}" + ("\n  created: " + "; ".join(made) if made else " (nothing new; existing files kept)"))
    print("Next: fill in NORTH_STAR.md, then check it with: orch.py northstar check")
    return 0


def cmd_pass_end(ctx, a):
    ctx.need_state()
    if not ctx.north.exists():
        die("NORTH_STAR.md not found")
    n = a.pass_no
    row, new = record_cost(ctx, n, a.transcripts, a.force)
    print_measure(row, f"== Pass {n} cost " + ("(recorded now)" if new else "(recorded earlier)") + " ==")
    report, cum, groups = cost_report(ctx)
    print("\n== Cost over time ==\n" + report)

    cap, _ = north_limits(ctx)
    text = ctx.north.read_text(encoding="utf-8")
    spend = f"Spend:   {money(cum)} API-equivalent over {len(groups)} passes" + (f", cap {cap}" if cap else ", no cap set")
    lines = text.splitlines()
    in_cs = False
    for i, l in enumerate(lines):
        if l.startswith("## "):
            in_cs = norm_title(l[3:]) == "current state"
        elif in_cs and l.startswith("Spend:"):
            lines[i] = spend
            break
    text = "\n".join(lines) + "\n"
    ctx.north.write_text(text, encoding="utf-8")

    lint = lint_north(ctx, n, row)
    results = run_mistake_checks(ctx, "pass-end", n, lint=lint, cost_row=row)
    structural = [(k, v) for k, v in lint.items() if k in ("north_star_exists", "sections_present", "status_log_last") and v[0] == "REPEAT"]
    print(f"\n== Pass {n} diff against past mistakes ==")
    for k, v in structural:
        print(f"  NORTH STAR    {k}: {v[1]}")
    print_mistake_results(results)
    struck = struck_out(ctx)
    for s in struck:
        print("STRUCK OUT: " + s)

    tiers = {k: dict(v) for k, v in row["tiers"].items()}
    manual = groups[n]["manual"]
    for m in manual:
        tiers.setdefault(m["tier"], {"cost": 0.0})
        tiers[m["tier"]]["cost"] = tiers[m["tier"]].get("cost", 0.0) + m["cost"]
    parts = ", ".join(f"{t} {money(v['cost'])}" for t, v in sorted(tiers.items(), key=lambda kv: -kv[1].get("cost", 0)) if v.get("cost"))
    mt = row["metrics"]
    not_counted = "; ".join(ctx.cfg().get("not_counted") or []) or "nothing declared"
    cost_line = (f"- {today()} pass {n} cost: {money(pass_total(groups[n]))} ({parts or 'no priced responses'}) | running total {money(cum)} | "
                 f"lead's own {pct(mt.get('main_cost_share', 0))} | re-reading {pct(mt['cache_read_cost_share'])} | "
                 f"rewrites {money(mt.get('rewrite_cost', 0))} ({mt.get('idle_rewrites', 0)} idle) | "
                 f"workers {mt['workers']}, largest context {kilo(mt.get('max_context_per_worker', 0))} | "
                 f"lead context {kilo(mt.get('main_peak_context', 0))} | owner messages {mt.get('owner_messages', 0)} | "
                 f"not counted: {not_counted}" + ("" if not row.get("unpriced") else " | NOT PRICED: " + ", ".join(row["unpriced"])))
    rep = [r["id"] for r in results if r["result"] == "REPEAT"]
    ask = [r["id"] for r in results if r["result"] == "ASK"]
    clear = sum(1 for r in results if r["result"] == "CLEAR")
    check_line = (f"- {today()} pass {n} mistake check: {clear} clear, {len(rep)} repeated" + (f" ({', '.join(rep)})" if rep else "")
                  + f", {len(ask)} to answer" + (f" ({', '.join(ask)})" if ask else "")
                  + (f" | struck out: {', '.join(s.split()[0] for s in struck)}" if struck else ""))
    if lint.get("status_log_last", ("", ""))[0] == "CLEAR":
        body = text.rstrip("\n").splitlines()
        if not any(f"pass {n} cost:" in l for l in body) or new and a.force:
            body.append(cost_line)
        last_check = next((l for l in reversed(body) if f"pass {n} mistake check:" in l), None)
        if last_check is None or last_check.split(" ", 2)[2] != check_line.split(" ", 2)[2]:
            body.append(check_line)
        ctx.north.write_text("\n".join(body) + "\n", encoding="utf-8")
        print(f"\nAppended to the Status log:\n  {cost_line}\n  {check_line}")
        tampered = [k for k in ("bars_unmoved", "status_log_append_only") if lint[k][0] == "REPEAT"]
        if tampered:
            print("No snapshot taken: " + " and ".join(tampered) + " failed, so the last honest snapshot stays the "
                  "baseline. Restore the record, or have the owner enter the change under Bar changes, then run again.")
        else:
            print(f"Snapshot: {snapshot(ctx, n)}")
    else:
        print("\nNothing appended and no snapshot taken: the Status log is not the last section. Fix that and run again.")
        return 1
    code = 1 if structural else exit_code(results)
    print({0: "\nPass closed clean.",
           1: "\nPass closed with repeated mistakes. They are recorded as repeats. Fix what can be fixed and run pass-end again; the record of the repeat stays.",
           2: "\nAnswer the questions above with: orch.py mistakes answer --id ID --pass N --result clear|repeat --note \"evidence\", then run pass-end again."}[code])
    return code


# ---------- command line ----------

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--root", default=".", help="project root (default: current directory)")
    sp = ap.add_subparsers(dest="cmd", required=True)

    p = sp.add_parser("init", help="set up .orchestration/ and NORTH_STAR.md")
    p.add_argument("--project"), p.add_argument("--owner"), p.add_argument("--lead")
    p.set_defaults(fn=cmd_init)

    p = sp.add_parser("pass-end", help="close a pass")
    p.add_argument("--pass", dest="pass_no", type=int, required=True)
    p.add_argument("--transcripts", nargs="*"), p.add_argument("--force", action="store_true")
    p.set_defaults(fn=cmd_pass_end)

    c = sp.add_parser("cost", help="cost ledger").add_subparsers(dest="sub", required=True)
    p = c.add_parser("now", help="cost since the last recorded pass; records nothing")
    p.add_argument("--transcripts", nargs="*"), p.set_defaults(fn=cmd_cost_now)
    p = c.add_parser("record", help="record a pass's cost without the other checks")
    p.add_argument("--pass", dest="pass_no", type=int, required=True)
    p.add_argument("--transcripts", nargs="*"), p.add_argument("--force", action="store_true")
    p.set_defaults(fn=cmd_cost_record)
    p = c.add_parser("add", help="add spend the transcripts cannot show, e.g. an agent billed elsewhere")
    p.add_argument("--pass", dest="pass_no", type=int, required=True)
    p.add_argument("--label", required=True), p.add_argument("--cost", type=float, required=True)
    p.add_argument("--tier", default="independent"), p.add_argument("--note")
    p.set_defaults(fn=cmd_cost_add)
    p = c.add_parser("report", help="cost per pass and over time, with a projection")
    p.set_defaults(fn=cmd_cost_report)
    p = c.add_parser("lanes", help="cost per lane and per finished task, and how often each tier finishes its work")
    p.set_defaults(fn=cmd_cost_lanes)

    n = sp.add_parser("northstar", help="North Star checks").add_subparsers(dest="sub", required=True)
    p = n.add_parser("check")
    p.add_argument("--pass", dest="pass_no", type=int), p.set_defaults(fn=cmd_north_check)
    p = n.add_parser("snapshot")
    p.add_argument("--pass", dest="pass_no", type=int, required=True), p.set_defaults(fn=cmd_north_snapshot)

    m = sp.add_parser("mistakes", help="mistake register").add_subparsers(dest="sub", required=True)
    p = m.add_parser("check", help="diff the work against past mistakes at a checkpoint")
    p.add_argument("--at", required=True, choices=["brief", "accept", "pass-end", "owner-report"])
    p.add_argument("--pass", dest="pass_no", type=int), p.add_argument("--brief"), p.add_argument("--lane")
    p.set_defaults(fn=cmd_mistakes_check)
    p = m.add_parser("answer", help="answer a question the check asked, with evidence")
    p.add_argument("--id", required=True), p.add_argument("--pass", dest="pass_no", type=int)
    p.add_argument("--at", default="pass-end", choices=["brief", "accept", "pass-end", "owner-report"])
    p.add_argument("--brief"), p.add_argument("--lane")
    p.add_argument("--result", required=True, choices=["clear", "repeat"])
    p.add_argument("--note", required=True)
    p.set_defaults(fn=cmd_mistakes_answer)
    p = m.add_parser("add", help="register a new mistake the moment it is understood")
    p.add_argument("--title", required=True), p.add_argument("--what", required=True)
    p.add_argument("--cause", required=True), p.add_argument("--rule", required=True)
    p.add_argument("--question", required=True, help="what the lead must answer at the checkpoint, with evidence")
    p.add_argument("--when", nargs="+", default=["pass-end"], choices=["brief", "accept", "pass-end", "owner-report"])
    p.add_argument("--pass", dest="pass_no", type=int)
    p.set_defaults(fn=cmd_mistakes_add)
    p = m.add_parser("report", help="how often each mistake has repeated")
    p.set_defaults(fn=cmd_mistakes_report)
    p = m.add_parser("promote", help="move a lesson up: prose -> template -> scripted -> owner")
    p.add_argument("--id", required=True), p.add_argument("--level", required=True, choices=["template", "scripted", "owner"])
    p.add_argument("--note", required=True, help="what was changed so the lesson holds at the new level")
    p.set_defaults(fn=cmd_mistakes_promote)
    p = m.add_parser("export", help="carry this project's lessons to the cross-project register")
    p.add_argument("--to"), p.set_defaults(fn=cmd_mistakes_export)

    a = ap.parse_args()
    sys.exit(a.fn(Ctx(a.root), a))


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall