@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/safety.py

@@ -0,0 +1,387 @@
+"""Two commands that only matter once the harness is somebody else's dependency:
+an id allocator that two sessions cannot race, and `doctor`.
+
+Both exist because centralising the harness changes who pays for its mistakes. A
+bug in one repo's copy was that repo's problem; the same bug in a plugin is every
+installer's, and neither a duplicated id nor a silently-misconfigured install
+announces itself.
+"""
+import json
+import os
+import platform
+import re
+import sys
+from datetime import date
+from pathlib import Path
+
+from . import config, events, git, ids
+from .tree import cli, die, find_work_root, rel
+from .registry import definition_sites, hosts, locate_domain, locate_system
+from .generate import _sync
+
+#: The lowest Python the harness is tested on. 3.9 is the floor for the builtin
+#: generic annotations and dict-ordering guarantees the modules rely on; below it
+#: the failure is an ImportError deep in a module, which reads as a broken plugin
+#: rather than an unsupported runtime.
+MIN_PYTHON = (3, 9)
+
+
+def _next_free(root: Path) -> int:
+    """One past the highest id anywhere in the tree.
+
+    Reads the tree rather than a counter, because the tree is the truth and a
+    counter is a second copy of it that can be wrong. That is also exactly why this
+    races: the read is cheap and two sessions doing it get the same answer.
+    """
+    seen = {ids.sort_key(i) for i in definition_sites(root)}
+    for _, _, rules, _ in hosts(root):
+        seen |= {ids.sort_key(i) for i in rules}
+    return (max(seen) + 1) if seen else 1
+
+
+def _claim(root: Path, n: int) -> bool:
+    """Try to reserve number `n`. True if this process got it.
+
+    `O_CREAT | O_EXCL` is the whole mechanism: the filesystem decides, atomically,
+    which of two racing sessions created the file. Everything else here is
+    bookkeeping.
+
+    The lock is held for microseconds and removed by the caller, because the
+    DURABLE claim is the `### <id>` heading written into the host doc. That split is
+    deliberate: a lock file is the clean way to serialise and the leaky way to
+    remember — leave one behind on a crash and the number is lost forever. Leave a
+    heading behind and the number is visibly taken by something a person can see,
+    fill in, or delete.
+    """
+    lockdir = root.parent / ".work" / "ids"
+    lockdir.mkdir(parents=True, exist_ok=True)
+    try:
+        fd = os.open(str(lockdir / f"{ids.LEDGER}-{n}"),
+                     os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except FileExistsError:
+        return False
+    os.close(fd)
+    return True
+
+
+def _release(root: Path, n: int) -> None:
+    (root.parent / ".work" / "ids" / f"{ids.LEDGER}-{n}").unlink(missing_ok=True)
+
+
+def _host_doc(root: Path, name: str) -> Path:
+    """The file that hosts rules for a domain or a system, named either way.
+
+    A caller should not have to know that a domain's rules live in its `README.md`
+    while a system's live in `architecture/<name>.md` — that is the hosting model's
+    business, and `where` already hides it on the read side.
+    """
+    md = locate_system(root, name)
+    if md:
+        return md
+    folder = locate_domain(root, name)
+    if folder:
+        return folder / "README.md"
+    die(f"no domain or system named '{name}' — `jarvis work list` shows the domains, "
+        f"`jarvis work code <region>` the systems")
+
+
+def cmd_id_new(args) -> int:
+    """Claim the next free id and write its heading into its host, atomically.
+
+    The race is ordinary, not exotic: allocation means reading "the next free
+    number" off a tree that is now spread across nine domains plus every system
+    file, and both consumer repos demonstrably run concurrent sessions — one had 56
+    uncommitted files and the other 28 during the extraction that produced this.
+    """
+    root = find_work_root()
+    host = args["host"]
+    md = _host_doc(root, host)
+    title = (args.get("title") or "").strip()
+    if not title or title == "true":
+        die("--title is required: a rule with no title is not a definition, and "
+            "`align` reports it rather than indexing a blank")
+
+    n = _next_free(root)
+    # Walk forward rather than retrying the same number: a loser in the race wants
+    # the NEXT number, and a leftover lock from a crashed session must not wedge the
+    # allocator forever.
+    for candidate in range(n, n + 1000):
+        if _claim(root, candidate):
+            n = candidate
+            break
+    else:                                             # pragma: no cover — defensive
+        die("could not claim an id after 1000 attempts — check .work/ids/")
+
+    try:
+        id_ = f"{ids.LEDGER}-{n}"
+        text = md.read_text()
+        entry = (f"\n### {id_} — {title}\n"
+                 f"enforced_by: _the check that catches a violation_\n\n"
+                 f"_Why this is true, and what it costs to break._ "
+                 f"({date.today().isoformat()})\n")
+        if re.search(r"^##\s+Rules\s*$", text, re.MULTILINE):
+            text = text.rstrip() + "\n" + entry
+        else:
+            # A host with no `## Rules` gets one. The alternative is refusing, which
+            # sends the author to hand-edit the file the tool is meant to own.
+            text = text.rstrip() + "\n\n## Rules\n" + entry
+        md.write_text(text)
+    finally:
+        # The heading is now the claim, so the lock has done its job. Released even
+        # on failure: holding it would burn the number for good.
+        _release(root, n)
+
+    print(f"claimed {id_} in {rel(md, root)}")
+    print(f"        fill in `enforced_by:` — a rule nothing can catch is a wish")
+    _sync(root)
+    return 0
+
+
+def _mcp_declared(repo: Path, server: str) -> bool:
+    """Whether any `.mcp.json` in the project declares `server`."""
+    for p in (repo / ".mcp.json", repo / ".claude" / ".mcp.json"):
+        if not p.is_file():
+            continue
+        try:
+            data = json.loads(p.read_text())
+        except json.JSONDecodeError:
+            continue
+        if server in (data.get("mcpServers") or {}):
+            return True
+    return False
+
+
+def cmd_doctor(args) -> int:
+    """Self-diagnosis, because a plugin failing in someone else's repo has no other
+    support surface.
+
+    Exits non-zero only on a GENUINE break — something that stops the harness
+    working. A degraded-but-legal install (no graph engine, no verify commands) is
+    reported and passes, because `P-3` makes those modes legal and a doctor that
+    fails on them teaches people to ignore it.
+    """
+    repo = Path(args["project_root"]).resolve()
+    checks, broken = [], 0
+
+    def ok(label, detail=""):
+        checks.append(("ok", label, detail))
+
+    def warn(label, detail=""):
+        checks.append(("warn", label, detail))
+
+    def bad(label, detail=""):
+        nonlocal broken
+        broken += 1
+        checks.append(("BROKEN", label, detail))
+
+    v = sys.version_info
+    running = f"{v.major}.{v.minor}.{v.micro} ({platform.python_implementation()})"
+    if (v.major, v.minor) >= MIN_PYTHON:
+        ok("python", running)
+    else:
+        bad("python", f"{running} — the harness needs "
+                      f">= {MIN_PYTHON[0]}.{MIN_PYTHON[1]}")
+
+    cfg = None
+    cfg_path = repo / config.CONFIG_PATH
+    try:
+        cfg = config.load(repo)
+        if cfg_path.is_file():
+            ok("config", f"{config.CONFIG_PATH} valid; ids.prefix "
+                         f"{cfg['ids']['prefix']!r}")
+        else:
+            warn("config", f"no {config.CONFIG_PATH} — running on shipped defaults "
+                           f"(ids.prefix {cfg['ids']['prefix']!r}). Fine for a new "
+                           f"repo; set one before writing rules.")
+    except config.ConfigError as e:
+        bad("config", f"{e}")
+
+    root = repo / "work"
+    if not root.is_dir():
+        bad("work tree", f"no {rel(root, root)} — run `{cli()} init`")
+    else:
+        parts = [d for d in ("versions", "backlog") if (root / d).is_dir()]
+        if (root / "README.md").is_file() and parts:
+            ok("work tree", f"{root} ({', '.join(parts)})")
+        else:
+            warn("work tree", f"{root} is incomplete — `jarvis work init` backfills "
+                              f"what is missing without touching what is there "
+                              f"(`{cli()} init`)")
+
+    if cfg is not None:
+        # The one setting here that fails SILENTLY when it cannot hold: a repo that
+        # asked for its board writes to land in git, with no repository under the
+        # tree, gets the write on disk, no complaint, and none of the guarantee it
+        # asked for. So the row says whether it holds, rather than whether it is set.
+        gc = cfg["git"]
+        # Asked once and reused: `doctor` is a diagnostic, and a diagnostic that
+        # shells out twice for one answer is one that can give two.
+        unseen = git.ignored(repo) if gc["commit"] and git.is_repo(repo) else []
+        if not gc["commit"]:
+            ok("git", f"board writes stay on disk — the record is work/{events.LOG}")
+        elif not git.is_repo(repo):
+            bad("git", f"git.commit is set but {repo} is not a git repository, so "
+                       f"every board write lands on disk only — which is the exact "
+                       f"failure that setting exists to close")
+        elif unseen:
+            # The green-but-broken case. Every command exits 0, the board looks
+            # written, and the item is in no git history anywhere — because git
+            # cannot report a change to a file it has been told to ignore.
+            bad("git", f"git.commit is set but git IGNORES "
+                       f"{', '.join(unseen)} — every board write lands on "
+                       f"disk only, silently. Un-ignore the board, or point git.paths "
+                       f"at a tree that is tracked")
+        elif not gc["push"]:
+            ok("git", f"every board write commits {', '.join(gc['paths'])} here; "
+                      f"never sent (git.push is off)")
+        elif git.has_remote(repo, gc["remote"]):
+            ok("git", f"every board write commits {', '.join(gc['paths'])} and "
+                      f"pushes to {gc['remote']}")
+        else:
+            warn("git", f"git.push is on but this repository has no remote named "
+                        f"{gc['remote']!r} — a board write will commit, then fail "
+                        f"to send, every time")
+
+        # An id matching NO configured prefix is the single highest-value thing this
+        # can report: it is exactly what an unconfigured install looks like from the
+        # inside, and it is silent otherwise — every check simply reports against a
+        # dialect the repo never chose.
+        if root.is_dir():
+            # This is the one check `align` CANNOT do: align compiles its pattern
+            # from the configured prefix, so ids in some other dialect are invisible
+            # to it by construction. That is precisely the unconfigured-install
+            # signature — a repo whose whole ledger the harness cannot see.
+            #
+            # But "is this a cross-repo citation" must have ONE answer, so the
+            # sibling-repo excuse is align's own, applied to the same left context.
+            # Otherwise doctor warns about `acme D-63` while align correctly
+            # excuses it, and the two tools disagree in front of the user.
+            from .align import _foreign_qualifier
+            foreign = _foreign_qualifier()
+            other = re.compile(r"\b([A-Z][A-Z0-9]{0,3})-\d+\b")
+            allowed = {cfg["ids"]["prefix"], *cfg["ids"]["recognised"], "AC", "B"}
+            stray = {}
+            for md in root.rglob("*.md"):
+                for line in md.read_text(errors="ignore").splitlines():
+                    for m in other.finditer(line):
+                        if m.group(1) in allowed or foreign.search(line[:m.start()]):
+                            continue
+                        stray.setdefault(m.group(1), 0)
+                        stray[m.group(1)] += 1
+            if stray:
+                top = ", ".join(f"{k}-nn x{v}" for k, v in
+                                sorted(stray.items(), key=lambda kv: -kv[1])[:4])
+                warn("ids", f"{sum(stray.values())} id(s) match no configured prefix "
+                            f"({top}). Two readings, and they are far apart: if one "
+                            f"of those IS this repo's ledger letter, set ids.prefix "
+                            f"— every check is reading the wrong dialect until you "
+                            f"do. If they are a sibling repo's ids discussed in "
+                            f"prose, add that repo to ids.foreign and they stop "
+                            f"counting here.")
+            else:
+                ok("ids", f"every id matches a configured prefix")
+
+        mcp = cfg["graph"]["mcp"]
+        if not mcp:
+            ok("graph", "none configured — the blast-radius step is grep-wide and "
+                        "says so. A fully supported mode, not a broken install.")
+        elif _mcp_declared(repo, mcp):
+            ok("graph", f"{mcp!r} declared in this project's .mcp.json")
+        else:
+            # Warn, never fail: `P-3` says degraded is legal. But a silently
+            # degraded planning loop is the thing that rule exists to prevent, so
+            # the gap between "configured" and "present" gets said out loud.
+            warn("graph", f"{mcp!r} is configured but no .mcp.json in this project "
+                          f"declares it. It may still be supplied by an installed "
+                          f"plugin — this checks declarations, it cannot probe a "
+                          f"live server from here.")
+
+        if cfg["verify"]:
+            ok("verify", ", ".join(sorted(cfg["verify"])))
+        else:
+            warn("verify", "no commands configured — `coverage` cannot tell a "
+                           "session how to produce evidence")
+
+        # A wrongly-sized window is INVISIBLE while it is wrong: the reminder simply
+        # arrives too early, every session, and reads as an over-eager feature rather
+        # than a mis-set number. It shipped that way — a 200000 default against
+        # sessions that run past 600k fired at what the config called 190%. The
+        # transcripts already know the answer, so `doctor` compares the two rather
+        # than leaving it to be inferred from irritation.
+        at = cfg["wrap"]["at_percent"]
+        if not at:
+            ok("wrap", "no reminder configured — sessions end when you end them")
+        else:
+            window = cfg["wrap"]["context_tokens"]
+            peak = _observed_peak(repo)
+            if peak and peak > window:
+                warn("wrap", f"sessions here have reached {peak:,} tokens, which is "
+                             f"MORE than wrap.context_tokens ({window:,}) — so the "
+                             f"reminder fires at {peak / window * 100:.0f}% of the "
+                             f"window it was told about, which is far too early. Set "
+                             f"context_tokens to the window you actually run.")
+            elif peak:
+                ok("wrap", f"reminds at {at}% of {window:,} tokens "
+                           f"(= {window * at // 100:,}); observed peak {peak:,}")
+            else:
+                ok("wrap", f"reminds at {at}% of {window:,} tokens "
+                           f"(= {window * at // 100:,})")
+
+    width = max(len(c[1]) for c in checks)
+    print()
+    for level, label, detail in checks:
+        mark = {"ok": "  ✓", "warn": "  ·", "BROKEN": "  ✗"}[level]
+        print(f"{mark} {label:<{width}}  {detail}")
+    print(f"\n  {broken} broken · "
+          f"{sum(1 for c in checks if c[0] == 'warn')} to look at · "
+          f"exit {1 if broken else 0}\n")
+    return 1 if broken else 0
+
+
+def _observed_peak(repo: Path):
+    """Largest context this repo's recent sessions actually reached, or None.
+
+    Read from Claude Code's own transcripts — the same `usage` record the wrap hook
+    measures — so `doctor` compares the configured window against what this machine
+    really does, rather than against an assumption. Best-effort by design: no
+    transcripts, a different client, or an unreadable file all mean "no opinion",
+    never a warning about a number it could not check.
+    """
+    home = Path.home() / ".claude" / "projects"
+    slug = str(repo).replace("/", "-")
+    d = home / slug
+    if not d.is_dir():
+        return None
+    peak = 0
+    # Newest few only: this runs inside `doctor`, and a repo can accumulate hundreds
+    # of transcripts. The window question is answered by recent behaviour.
+    try:
+        files = sorted(d.glob("*.jsonl"), key=lambda p: -p.stat().st_mtime)[:5]
+    except OSError:
+        return None
+    for f in files:
+        try:
+            # Tail only — same reasoning as the hook: the last records settle it, and
+            # these files reach tens of megabytes.
+            size = f.stat().st_size
+            with f.open("rb") as fh:
+                fh.seek(max(0, size - 256 * 1024))
+                chunk = fh.read()
+        except OSError:
+            continue
+        for raw in chunk.split(b"\n"):
+            if not raw.strip():
+                continue
+            try:
+                rec = json.loads(raw)
+            except Exception:
+                continue
+            if rec.get("isSidechain"):
+                continue
+            u = (rec.get("message") or {}).get("usage")
+            if not isinstance(u, dict):
+                continue
+            peak = max(peak, sum(u.get(k, 0) or 0 for k in
+                                 ("input_tokens", "cache_creation_input_tokens",
+                                  "cache_read_input_tokens")))
+    return peak or None

package/harness/harness/scaffold.py

@@ -0,0 +1,129 @@
+import re
+from datetime import date
+from pathlib import Path
+
+from .tree import PRIORITIES, PRODUCT_STATES, assets_dir, die
+from .model import locate, locate_epic, locate_version
+
+
+def _check_kebab(kind: str, name: str):
+    if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", name):
+        die(f"{kind} name must be kebab-case (got '{name}')")
+def _check_version_name(name: str):
+    """Version names allow dots and dashes (semver-style): v0.3, v1.0, 0.2.1-rc1."""
+    if not re.match(r"^[a-z0-9]+([._-][a-z0-9]+)*$", name):
+        die(f"version name must be kebab-case or dotted (got '{name}')")
+def _check_priority(p: str):
+    if p not in PRIORITIES:
+        die(f"priority must be one of {', '.join(PRIORITIES)}")
+def _check_state(s: str):
+    if s not in PRODUCT_STATES:
+        die(f"state must be one of {', '.join(PRODUCT_STATES)}")
+def _check_owner_ref(value: str):
+    """Format-check an `owner:` value: a bare `<domain>`, an `<app>`, or an
+    `<app>/<feature>` — each segment kebab-case. Existence is NOT checked
+    here; that's `_owner_ref_lint`'s job, non-blocking, so a task can name a
+    feature before it is scaffolded without being refused."""
+    parts = value.split("/")
+    if len(parts) not in (1, 2):
+        die(f"--owner must be '<domain>', '<app>' or '<app>/<feature>' "
+            f"(got '{value}')")
+    for p in parts:
+        _check_kebab("owner path segment", p)
+def _check_unused(root: Path, name: str):
+    """Names are globally unique across tasks, epics and versions — which is
+    what lets every command resolve a bare name without being told the tier."""
+    if locate(root, name):
+        die(f"a task named '{name}' already exists")
+    if locate_epic(root, name):
+        die(f"an epic named '{name}' already exists")
+    if locate_version(root, name):
+        die(f"a version named '{name}' already exists")
+def _check_covers_ref(value: str):
+    """Format-check an epic's `covers:` entry: `<feature>/AC-nn`.
+
+    Feature-qualified because an epic SPANS features by design — the org tier
+    touches profiles, sharing, content-trust and accounts at once — so a
+    bare `AC-01` would name four different criteria at the same time. A task's
+    `covers:` stays bare: it has exactly one `owner:` feature to resolve against."""
+    parts = value.split("/")
+    if len(parts) != 2 or not re.match(r"^AC-\d+$", parts[1]):
+        die(f"--covers entries must look like '<feature>/AC-01' (got '{value}') "
+            f"— an epic spans features, so its AC ids are feature-qualified")
+    _check_kebab("covers feature", parts[0])
+def _render_template(filename: str, **subs) -> str:
+    text = (assets_dir() / filename).read_text()
+    for k, v in subs.items():
+        text = text.replace("{{" + k + "}}", v)
+    return text
+def _scaffold_task(folder: Path, title: str, priority: str, depends: list):
+    """A queued task is a brief and nothing else — just task.md. Its plan is
+    written at pickup (not in the queue, where it'd rot); its handoff only when
+    handed to a new conversation."""
+    folder.mkdir(parents=True)
+    depends_yaml = "[" + ", ".join(depends) + "]"
+    today = date.today().isoformat()
+    (folder / "task.md").write_text(_render_template(
+        "task-template.md",
+        PRIORITY=priority, DEPENDS_ON=depends_yaml, CREATED=today, TITLE=title,
+    ))
+def _scaffold_epic(folder: Path, title: str, covers: list, owner: str = "",
+                   continues: str = ""):
+    folder.mkdir(parents=True)
+    today = date.today().isoformat()
+    (folder / "epic.md").write_text(_render_template(
+        "epic-template.md",
+        TITLE=title, CREATED=today, COVERS="[" + ", ".join(covers) + "]",
+        OWNER=owner, CONTINUES=continues,
+    ))
+def _scaffold_feature(md: Path, state: str):
+    """A feature is ONE file — `product/<feature>.md`. No directory is made:
+    that is the whole point of `AC-20`, and a `mkdir` here would quietly rebuild
+    the tier it removed the next time someone scaffolds."""
+    md.parent.mkdir(parents=True, exist_ok=True)
+    md.write_text(_render_template("feature-template.md", STATE=state,
+                                   DATE=date.today().isoformat()))
+def _scaffold_handoff(folder: Path, title: str) -> bool:
+    """Write handoff.md from the template if absent. Returns True when created."""
+    handoff = folder / "handoff.md"
+    if handoff.is_file():
+        return False
+    handoff.write_text(_render_template(
+        "handoff-template.md", TITLE=title, CREATED=date.today().isoformat(),
+    ))
+    return True
+def _scaffold_version(folder: Path, title: str, target: str, with_design: bool,
+                       with_architecture: bool = False, order: str = "",
+                       start: str = "", end: str = "", outcome: str = ""):
+    folder.mkdir(parents=True)
+    today = date.today().isoformat()
+    text = _render_template(
+        "version-template.md",
+        CREATED=today, TITLE=title, TARGET=target, OUTCOME=outcome,
+        ORDER=order, START=start, END=end,
+    )
+    # The template carries `order/start/end/target: {{...}}` placeholders;
+    # strip each line entirely when its value wasn't given, so the
+    # frontmatter stays clean (mirrors `target`'s existing strip).
+    # `outcome` is never stripped — `cmd_version_new` refuses without it.
+    for key, value in (("order", order), ("start", start), ("end", end),
+                        ("target", target)):
+        if not value:
+            text = re.sub(rf"^{key}: *\n", "", text, flags=re.MULTILINE)
+    (folder / "version.md").write_text(text)
+    # No stories.md — RETIRED 2026-07-17. Stories live per-feature in
+    # work/product/**.md (the durable owner of behaviour); version.md's
+    # Scope links the feature stories in the cut. Existing files keep a dated
+    # deprecation pointer (git holds history) and are tolerated, never scaffolded.
+    # design.md is conditional — only UI-bearing versions need a claude.ai/design
+    # UI brief; an engine-only cut never decomposes from wireframes.
+    if with_design:
+        (folder / "design.md").write_text(_render_template(
+            "design-template.md", TITLE=title,
+        ))
+    # architecture.md is conditional — the version-level TECHNICAL brief (the
+    # cross-task "plan FROM this" doc); only versions that need one scaffold it.
+    if with_architecture:
+        (folder / "architecture.md").write_text(_render_template(
+            "architecture-template.md", TITLE=title,
+        ))

package/harness/harness/shard.py

@@ -0,0 +1,63 @@
+"""Reading the coverage shards — the ONE reader, as `sdk/testing/shard.ts` is the one writer.
+
+Every runner (vitest, Playwright, the `examples/*.mjs` smokes) drops a
+`.work/coverage/<runner>-<workspace>.json` carrying what that run actually proved. Three
+checks need to read them — `coverage` reports them, `align` refuses to call a skipped
+binding evidence, and `lint`'s rollup asks whether a shipped feature has any. Each growing
+its own reader is the drift the shard format exists to prevent, and it also produced a real
+import cycle the moment the second one wanted it.
+
+`.work/` is gitignored on purpose: evidence is a fresh run, not a file somebody checked in.
+"""
+import json
+from pathlib import Path
+
+
+#: Precedence when several sites claim one criterion — the SAME rank both
+#: reporters already apply within a single runner. Anything unrecognised ranks
+#: below `passed`, so a shard that learns a new status can never silently
+#: promote a criterion.
+_RANK = {"failed": 3, "todo": 2, "passed": 1}
+
+
+def _load_run(repo: Path) -> tuple[dict, dict, list]:
+    """`{'feature/AC-nn': status}` from every shard, the RUNNERS that claimed each
+    criterion, and the shard names read.
+
+    The merge applies `failed > todo > passed` ACROSS shards, because a promise
+    is one behaviour however many runners touch it: proven here and failing
+    there is not proven, and a passing vitest suite beside a Playwright
+    `test.fixme` is half-covered, which is not proven either.
+
+    It used to be last-write-wins with only `failed` sticking — and shards are
+    read in alphabetical order, so `vitest-*.json` silently overwrote
+    `playwright.json`. A criterion bound at both levels reported whichever
+    runner sorted last, which is the one thing this file exists not to do.
+
+    The runners are kept because they say what KIND of test claimed a criterion:
+    a browser suite proves what is on screen, a unit runner proves a value. Which
+    vitest suite is `unit` and which is `integration` is not derivable here, and is
+    not guessed at — see `AC_LEVELS`. `_wrong_level` is the only caller that needs
+    them, and it is why this returns three values rather than two: a second reader
+    that tracked runners separately is exactly the drift this module ended.
+    """
+    out: dict = {}
+    runners: dict = {}
+    shards: list = []
+    d = repo / ".work" / "coverage"
+    if not d.is_dir():
+        return out, runners, shards
+    for p in sorted(d.glob("*.json")):
+        try:
+            data = json.loads(p.read_text())
+        except Exception:
+            continue
+        shards.append(p.name)
+        runner = data.get("runner") or "unknown"
+        for cid, rec in (data.get("covered") or {}).items():
+            status = rec.get("status") if isinstance(rec, dict) else str(rec)
+            runners.setdefault(cid, set()).add(runner)
+            prior = out.get(cid)
+            if prior is None or _RANK.get(status, 0) > _RANK.get(prior, 0):
+                out[cid] = status
+    return out, runners, shards