@appchy/jarvis 0.1.36 → 0.1.39

package/harness/harness/coverage.py

@@ -0,0 +1,199 @@
+"""`jarvis work coverage` — join what the FEATURES promise against what a test RUN
+actually proved.
+
+The gap this closes: until now a criterion was "done" because a person typed an
+`x`, and its evidence was a `// Covers:` comment nobody re-checked. A comment
+survives its test being renamed, skipped or deleted, so the spec could go on
+claiming a behaviour nothing exercised. That is the failure mode this whole task
+exists to end — a spec that lies is worse than one that is silent.
+
+So the binding is emitted by the RUNNER, never authored:
+
+    vitest      `covers("sharing/AC-01")`  → the reporter `work` ships
+    playwright  `{ tag: ["@sharing/AC-01"] }` → e2e/support/covers-reporter.ts
+
+Both write `.work/coverage/*.json` with the same shape, carrying the file's REAL
+result. Delete the test and the id stops appearing; let it fail and the id is
+reported `failed`, never as evidence.
+
+`.work/` is gitignored on purpose: evidence is a fresh run, not a file somebody
+checked in.
+
+**The denominator is what is BUILT, never what is promised.** A feature file is a
+roadmap as much as a spec: most of its criteria describe behaviour nobody has
+written yet, and dividing by all of them measures ambition instead of honesty —
+it also cannot move except by someone deleting a promise. So the headline is
+`proven / built`, and the unbuilt remainder is reported beside it rather than
+underneath it.
+"""
+import json
+from pathlib import Path
+
+from .lint import feature_ac_levels
+from .model import scan_features
+from .shard import _load_run
+from .tree import find_work_root
+
+#: `{name: command}` from the repo's `verify` config, set by `config.apply()`.
+#: Empty by default: the harness must never suggest a command it invented.
+VERIFY: dict = {}
+
+
+
+
+def _wrong_level(level: str, runners: set):
+    """The complaint when a criterion's declared level and the level it is
+    actually claimed at disagree — `None` when they agree.
+
+    This is the suite standard's rule 5, made checkable: a test may only claim
+    what it ASSERTS, never the layer below it. A test aimed one layer away still
+    passes, so nothing about a green run reveals it, and the binding makes the
+    mistake permanent.
+    """
+    if not runners:
+        return None
+    browser = "playwright" in runners
+    value = bool(runners - {"playwright"})
+    if level == "eyes-on":
+        return ("says only a person can settle it, but a test claims it — either "
+                "it is provable after all, or the test claims more than it asserts")
+    if level == "e2e" and not browser:
+        return "says it is about what is on screen, but only a vitest test claims it"
+    if level in ("unit", "integration") and browser and not value:
+        return f"says it is a {level} fact, but only a browser test claims it"
+    return None
+
+
+def cmd_coverage(args) -> int:
+    """Report each feature's promises against a real run. REPORT-ONLY, exit 0 —
+    same reasoning as `align`: with coverage partial, a blocking gate is a lint
+    nobody reads. The flip is its own task."""
+    root = find_work_root()
+    repo = root.parent
+    run, runners, shards = _load_run(repo)
+
+    if not shards:
+        # The commands come from `verify.*` in the repo's config. They used to be
+        # one repo's own package-manager invocations, hardcoded — which told every
+        # other consumer to run a command it does not have. A name-only literal
+        # scan misses this, because a toolchain command carries no repo name;
+        # that is why the scan in the suite checks command names too.
+        lines = [f"    {cmd}" + (f"        ({name})" if name else "")
+                 for name, cmd in sorted(VERIFY.items())]
+        print("\n  no run found — `.work/coverage/` is empty.\n"
+              "  Evidence is a fresh run, so produce one first:\n"
+              + ("\n".join(lines) if lines
+                 else "    (no `verify` commands configured — add them to "
+                      ".claude/work.config.json)") + "\n")
+        return 0
+
+    only = args.get("feature")
+    rows, totals = [], {"declared": 0, "built": 0, "proven": 0, "failed": 0,
+                        "todo": 0, "gap": 0, "ahead": 0, "eyes": 0, "unlevelled": 0}
+    mismatched = []
+
+    for md in sorted(scan_features(root)):
+        name = md.stem
+        if only and name != only:
+            continue
+        levels = feature_ac_levels(md.read_text())
+        declared = set(levels)
+        built = {ac for ac, (_, is_built) in levels.items() if is_built}
+        if not declared:
+            continue
+
+        passed = {ac for ac in declared if run.get(f"{name}/{ac}") == "passed"}
+        failed = {ac for ac in declared if run.get(f"{name}/{ac}") == "failed"}
+        # A criterion someone has DECLARED a test for and not yet written — an
+        # `it.todo()` / `test.fixme()` carrying the tag. Its own state on purpose:
+        # counting it as proven would be a green check over an empty body, and
+        # counting it as failing would bury a real regression under scaffolding.
+        todo = {ac for ac in declared if run.get(f"{name}/{ac}") == "todo"}
+        # A criterion whose evidence is a PERSON LOOKING is not a coverage hole:
+        # no run will ever prove it, so leaving it in the denominator makes a
+        # number that can only go up by deleting the promise. It comes out of the
+        # ratio and is reported beside it, exactly as the unbuilt roadmap is.
+        eyes = {ac for ac in built if levels[ac][0] == "eyes-on"}
+        # The two ways the spec and the evidence disagree, and they point opposite
+        # ways. `gap` is a promise claimed with nothing to show. `ahead` is a
+        # promise a passing test already keeps while the spec still says nobody
+        # built it — the doc trailing the code, which no report used to count.
+        gap = built - passed - failed - todo - eyes
+        ahead = passed - built
+        provable = built - eyes
+        proven = (built & passed) - eyes
+
+        for ac in sorted(declared):
+            level = levels[ac][0]
+            complaint = _wrong_level(level, runners.get(f"{name}/{ac}", set())) if level else None
+            if complaint:
+                mismatched.append(f"{name}/{ac}: {complaint}")
+
+        totals["declared"] += len(declared)
+        totals["built"] += len(provable)
+        totals["proven"] += len(proven)
+        totals["failed"] += len(failed)
+        totals["todo"] += len(built & todo)
+        totals["gap"] += len(gap)
+        totals["ahead"] += len(ahead)
+        totals["eyes"] += len(eyes)
+        totals["unlevelled"] += sum(1 for ac in declared if levels[ac][0] is None)
+        rows.append((name, len(built), len(proven), len(eyes),
+                     len(built & todo), len(declared - built),
+                     sorted(failed), sorted(gap), sorted(ahead)))
+
+    print(f"\n  read {len(shards)} shard(s): {', '.join(shards)}\n")
+    print(f"  {'feature':<18} {'built':>6} {'PROVEN':>7} {'eyes-on':>8} {'todo':>5} "
+          f"{'gap':>4} {'unbuilt':>8}   status")
+    print(f"  {'-' * 18} {'-' * 6} {'-' * 7} {'-' * 8} {'-' * 5} {'-' * 4} "
+          f"{'-' * 8}   {'-' * 28}")
+    for name, blt, prv, eye, td, unbuilt, failed, gap, ahead in rows:
+        note = ""
+        if failed:
+            note = f"FAILING: {', '.join(failed)}"
+        elif gap:
+            shown = ", ".join(gap[:4]) + (" …" if len(gap) > 4 else "")
+            note = f"claimed, unproven: {shown}"
+        elif ahead:
+            shown = ", ".join(ahead[:4]) + (" …" if len(ahead) > 4 else "")
+            note = f"proven, unticked: {shown}"
+        # Both disagreements can hold at once, and the second must not vanish
+        # behind the first — it is the one a reader would otherwise never see.
+        if gap and ahead:
+            note += f"  (+{len(ahead)} proven, unticked)"
+        print(f"  {name:<18} {blt:>6} {prv:>7} {eye:>8} {td:>5} {len(gap):>4} "
+              f"{unbuilt:>8}   {note}")
+
+    t = totals
+    rate = f"{100 * t['proven'] // t['built']}%" if t["built"] else "—"
+    print(f"\n  BUILT COVERAGE  {t['proven']}/{t['built']} = {rate} "
+          f"— of the RUN-PROVABLE promises this app keeps, how many a run proves\n"
+          f"  {t['gap']} claimed with nothing to show · {t['todo']} declared-but-unwritten · "
+          f"{t['failed']} failing\n")
+    print(f"  Settled by eyes, not by a run: {t['eyes']}. A look is a level, not an\n"
+          f"  excuse — no assertion is evidence about weight, colour or rhythm — so\n"
+          f"  these sit beside the ratio with the dated ✔ in the feature file as their\n"
+          f"  evidence, never inside it.\n")
+    print(f"  Not built yet: {t['declared'] - t['built']} of {t['declared']} promises. "
+          f"That is a roadmap, NOT a coverage hole —\n"
+          f"  an unticked criterion is behaviour nobody has written, so counting it\n"
+          f"  against coverage measures ambition rather than honesty.\n")
+    if t["gap"]:
+        print("  A built promise with no passing bound test is a CLAIM, not evidence.\n"
+              "  Either bind it with `covers()` / a Playwright tag, or untick it and\n"
+              "  queue the gap as work.\n")
+    if t["ahead"]:
+        print(f"  {t['ahead']} promise(s) are PROVEN but not ticked — a passing test keeps\n"
+              "  a promise the spec still says nobody built. Read each against the test\n"
+              "  that claims it, and tick the ones it genuinely asserts.\n")
+    if mismatched:
+        print(f"  {len(mismatched)} criterion(s) are proven at the WRONG LEVEL — the level\n"
+              "  each declares, and the level it is actually claimed at, differ:\n")
+        for complaint in mismatched:
+            print(f"    {complaint}")
+        print()
+    if t["unlevelled"]:
+        print(f"  {t['unlevelled']} criteria declare no level, so nothing can check the test that\n"
+              "  claims them — and they count as run-provable by default, which for a\n"
+              "  look is the wrong default.\n")
+    return 0

package/harness/harness/epic.py

@@ -0,0 +1,220 @@
+import shutil
+from datetime import date
+
+from .tree import BUCKETS, EPIC_FM_ORDER, die, find_work_root, rel
+from .frontmatter import rewrite_file
+from .model import epic_home, locate_epic, locate_version
+from .scaffold import _check_covers_ref, _check_kebab, _check_unused, _scaffold_epic
+from .generate import _sync
+from . import events
+
+
+def cmd_epic_new(args) -> int:
+    """Scaffold an epic — in a version with `--version`, else in the backlog.
+
+    Backlog is the DEFAULT home on purpose. A version is now a release and is
+    expensive to open, so an epic is planned first and pulled into a cut when
+    its cut opens (`jarvis work place <epic> --version <v>`)."""
+    root = find_work_root()
+    name = args["name"]
+    _check_kebab("epic", name)
+    _check_unused(root, name)
+
+    covers = [c.strip() for c in (args.get("covers") or "").split(",") if c.strip()]
+    for c in covers:
+        _check_covers_ref(c)
+    owner = (args.get("owner") or "").strip()
+    title = args.get("title") or name.replace("-", " ").capitalize()
+
+    # Lineage. An epic name is globally unique, so work carried into a later cut
+    # cannot reuse the name it had — and without this it would arrive looking like
+    # a brand new goal that happens to resemble an old one. `continues:` is the one
+    # owner of the link; the earlier epic is NOT edited to point forward, because a
+    # fact with two writers is a fact that drifts, and this direction is the one
+    # that can be written at the moment the split actually happens.
+    continues = (args.get("continues") or "").strip()
+    if continues:
+        earlier = locate_epic(root, continues)
+        if not earlier:
+            die(f"--continues '{continues}': no epic by that name. It names the "
+                f"epic this one carries on from, so it has to be one that exists.")
+        if earlier.name == name:
+            die("--continues names this epic itself")
+
+    version_name = args.get("version")
+    if version_name:
+        version = locate_version(root, version_name)
+        if not version:
+            die(f"no version named '{version_name}' — create it with: "
+                f"jarvis work version-new {version_name} --outcome '…'")
+        if version.released:
+            die(f"version '{version_name}' is released — an epic is temporary "
+                f"and is removed at release; pick a planned version")
+        folder = version.folder / name
+        home = f"version '{version_name}'"
+    else:
+        folder = root / "backlog" / name
+        home = "backlog"
+
+    if folder.exists():
+        die(f"{rel(folder, root)} already exists")
+    _scaffold_epic(folder, title, covers, owner, continues)
+    events.append(root, "created", name, tier="epic", home=home)
+    print(f"created {rel(folder / 'epic.md', root)}  ({home})")
+    if continues:
+        print(f"        continues '{continues}' ({epic_home(root, earlier)}) — "
+              f"read its plan before cutting work here; what it settled still "
+              f"holds unless this one says otherwise")
+    if not covers and not owner:
+        print("        NOTE  no --covers yet — name the feature AC ids this epic "
+              "moves (`<feature>/AC-nn`), or the lint will say so. If it moves "
+              "no product criterion at all, --owner <org-domain> is the answer")
+    _sync(root)
+    return 0
+def _bucketed(epic, name: str):
+    """Where a task named `name` belongs inside `epic` — under a `queue/` bucket
+    in a version, directly under the epic in the backlog (a backlog task has no
+    status until it is pulled)."""
+    return (epic.folder / name) if epic.in_backlog else (epic.folder / "queue" / name)
+def _epic_to_backlog(root, name: str) -> int:
+    """A whole epic back out of a cut. The buckets come off on the way: status
+    exists inside a version and does not in the backlog, which is the same reason
+    `place` puts them on going the other way."""
+    epic = locate_epic(root, name)
+    if not epic:
+        die(f"no epic named '{name}' found")
+    if epic.in_backlog:
+        die(f"epic '{name}' is already in the backlog")
+    done = [t for t in epic.all_tasks() if t.status == "complete"]
+    if done:
+        die(f"epic '{name}' has {len(done)} completed task(s) — they shipped in "
+            f"'{epic.version}' and stay there, so the epic cannot move whole. "
+            f"Move its unfinished tasks out one at a time instead:\n"
+            f"  jarvis work place <task> --backlog --epic <a backlog epic>")
+
+    dest = root / "backlog" / name
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    was = epic_home(root, epic)
+    moved = epic.all_tasks()
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(epic.folder), str(dest))
+    for t in moved:
+        bucketed = dest / t.status / t.name
+        if bucketed.exists():
+            shutil.move(str(bucketed), str(dest / t.name))
+    for bucket in BUCKETS:
+        empty = dest / bucket
+        if empty.is_dir() and not any(empty.iterdir()):
+            empty.rmdir()
+    events.append(root, "moved", name, tier="epic", **{"from": was, "to": "backlog"})
+    print(f"took epic '{name}' out of the cut -> {rel(dest, root)}"
+          + (f"  ({len(moved)} task(s))" if moved else ""))
+    _sync(root)
+    return 0
+
+
+def cmd_epic_move(args) -> int:
+    """Move a whole epic into a version — the promotion path a backlog epic
+    takes when its cut opens. This is `place`'s epic form, dispatched to once
+    `place` sees the name is an epic.
+
+    Tasks are RESTRUCTURED as they go: a backlog epic's tasks sit directly under
+    it and gain a `queue/` bucket on arrival, because status exists in a version
+    and does not in the backlog."""
+    root = find_work_root()
+    name = args["name"]
+    to_backlog = str(args.get("backlog", "")).lower() == "true"
+    version_name = args.get("version")
+    if to_backlog:
+        return _epic_to_backlog(root, name)
+    if not version_name:
+        die(f"usage: jarvis work place {name} --version <v>   (or --backlog)")
+    version = locate_version(root, version_name)
+    if not version:
+        die(f"no version named '{version_name}'")
+    if version.released:
+        die(f"version '{version_name}' is released — pick a planned version")
+
+    epic = locate_epic(root, name)
+    if not epic:
+        die(f"no epic named '{name}' found")
+    if not epic.in_backlog and epic.version == version_name:
+        die(f"epic '{name}' is already in version '{version_name}'")
+
+    # An epic that has already shipped work cannot move whole: the completed tasks
+    # are the record of what THAT release delivered, and carrying them into another
+    # cut would make both versions describe work neither of them contained. Its
+    # unfinished half moves task by task into a continuation epic instead, which is
+    # what `--continues` is for.
+    done = [t for t in epic.all_tasks() if t.status == "complete"]
+    if done and not epic.in_backlog:
+        movable = [t for t in epic.all_tasks() if t.status != "complete"]
+        die(f"epic '{name}' has {len(done)} completed task(s) — they shipped in "
+            f"'{epic.version}' and stay there, so the epic cannot move whole. Make "
+            f"a continuation in the new cut and move the rest across:\n"
+            f"  jarvis work epic-new {name}-next --version {version_name} "
+            f"--continues {name}\n"
+            f"  jarvis work place <task> --version {version_name} "
+            f"--epic {name}-next\n"
+            f"  ({len(movable)} task(s) would move: "
+            f"{', '.join(t.name for t in movable[:4])}"
+            f"{' …' if len(movable) > 4 else ''})")
+
+    dest = version.folder / name
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    was = epic_home(root, epic)
+    moved = epic.all_tasks()
+    shutil.move(str(epic.folder), str(dest))
+
+    # A backlog epic's tasks were loose under it; give them the queue bucket.
+    if epic.in_backlog:
+        queue = dest / "queue"
+        queue.mkdir(exist_ok=True)
+        for t in moved:
+            shutil.move(str(dest / t.name), str(queue / t.name))
+
+    md = dest / "epic.md"
+    rewrite_file(
+        md,
+        lambda d: d.update({"updated": date.today().isoformat()}),
+        EPIC_FM_ORDER,
+    )
+    print(f"pulled epic '{name}' ({was}) -> {rel(dest, root)}  "
+          f"with {len(moved)} task(s)")
+    _sync(root)
+    return 0
+def cmd_epic_release(root, version) -> int:
+    """Remove every `epic.md` in a released version, and report it.
+
+    An epic is TEMPORARY by definition: it is the plan-it-together doc, and how
+    the work was planned stops being true the moment it ships. The folder stays
+    as the grouping of what shipped — that record is worth keeping — and git
+    holds the plan. Called from `cmd_release`, never on its own."""
+    removed = []
+    for e in version.epics:
+        e.md.unlink()
+        removed.append(e.name)
+    if removed:
+        print(f"        archived {len(removed)} epic(s) — epic.md removed, "
+              f"folders kept as the grouping: {', '.join(removed)}")
+    return len(removed)
+def epic_for_task(root, args, version_name):
+    """Resolve the `--epic` a task command names, and check it agrees with any
+    `--version` also given. Returns (epic, version_name) — the version is
+    DERIVED from the epic's home, so the two can never disagree silently."""
+    epic_name = (args.get("epic") or "").strip()
+    if not epic_name:
+        return None, version_name
+    epic = locate_epic(root, epic_name)
+    if not epic:
+        die(f"no epic named '{epic_name}' — create it with: "
+            f"jarvis work epic-new {epic_name}"
+            + (f" --version {version_name}" if version_name else ""))
+    home = None if epic.in_backlog else epic.version
+    if version_name and version_name != home:
+        die(f"--epic {epic_name} lives in {epic_home(root, epic)}, but you asked "
+            f"for version '{version_name}' — drop --version, or "
+            f"`jarvis work place {epic_name} --version {version_name}` first")
+    return epic, home

package/harness/harness/events.py

@@ -0,0 +1,153 @@
+"""The record of what the harness DID — a file, or the commits themselves.
+
+**History, never state.** Nothing in the harness reads this record to decide what is
+true now: status is the bucket, a version's status is derived from its tasks, a
+rule lives in the domain that owns it. That line is the whole design, and blurring
+it would rebuild the central ledger `P-1` dissolved — one file that answers
+everything, which is one file to disagree with the tree.
+
+**Two backends, and which one is the repo's call.** With `git.commit` off — the
+default, and what every consumer that has not asked for anything else gets — the
+record is `work/.events.jsonl`, exactly as described below. With it on, a board
+write commits, and the commit's own trailers ARE the record: `append` hands the
+event to that commit instead of a file, and `read` asks `git log`. A repo that
+writes to git therefore has no `.events.jsonl` at all, which is the point — that
+file records a session id rather than a machine or a branch, and it appends at the
+end, so two active branches conflict on it every time.
+
+Two kinds of event never reach git. A **hold** (`claimed`, `released-claim`) is
+coordination, and coordination that replicates is two machines holding one item with
+neither knowing. A **refusal** changed nothing, so there is no commit for it to ride
+on and no board history for it to be part of; `status` loses its "refused twice"
+warning under git, which is a deliberate trade rather than an oversight.
+
+What it buys is the thing a tree cannot hold: *time*. A tree remembers only now, so
+it cannot say what shipped overnight, how long something sat blocked, or which
+questions a shift asked. Under a person those answers lived in the conversation.
+With nobody in the chair the conversation is gone by morning, and a board that looks
+identical whether the night shift did six tasks or crashed after one is a board
+nobody can trust.
+
+Committed, not gitignored: an audit trail nobody can diff is not an audit trail. It
+stays append-only in practice because a rewrite shows up as a diff that deletes
+lines — which is exactly the review this file is for.
+
+A corrupt line is skipped, never fatal. This file must not be able to break the
+board — it is a record of work, not a dependency of it.
+"""
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import git
+
+LOG = ".events.jsonl"
+
+#: Events about a hold rather than about the board. They never enter git — not as a
+#: file, not as a trailer — because a claim belongs to a machine and a moment, and a
+#: replicated one is a claim two endpoints both believe they have.
+HOLDS = ("claimed", "released-claim")
+
+#: What this command has done so far, waiting for the commit that carries it. Only
+#: used under git; a process runs one command, so one buffer is one commit.
+_PENDING: list = []
+
+#: Every event the harness appends. Closed on purpose: a typo'd event name is a
+#: line that never shows up in a digest, which is the silent failure this list
+#: exists to prevent.
+KINDS = (
+    "created",        # a task, epic, feature or version was scaffolded
+    "moved",          # bucket -> bucket
+    "blocked",        # parked, waiting on a human
+    "asked",          # a question was filed against a task
+    "answered",       # and resolved
+    "claimed",        # an instance leased a task
+    "released-claim", # ...and gave it back, or the lease expired
+    "verified",       # verify.* ran — with its exit codes
+    "observed",       # an eyes-on record against an AC
+    "gate-refused",   # completion was refused, and why
+    "completed",      # a task landed
+    "released",       # a version shipped
+    "archived",       # ...and left the board
+)
+
+
+def _now() -> str:
+    """UTC, second precision. Instances may run on different machines, so a local
+    timestamp would make the ordering of a shift unreadable."""
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def instance_id() -> str:
+    """Who is acting. `WORK_INSTANCE` names a scheduled shift; otherwise the Claude
+    Code session. Empty is fine and means a human at a terminal — recording that
+    honestly is better than inventing an id for it."""
+    return (os.environ.get("WORK_INSTANCE")
+            or os.environ.get("CLAUDE_CODE_SESSION_ID", "")).strip()
+
+
+def append(root: Path, kind: str, name: str, **fields) -> None:
+    """Append one line. Never raises: a failure to record must not fail the work
+    that was recorded — the mutation already happened, and dying here would leave
+    the tree changed and the caller told it failed."""
+    if kind not in KINDS:
+        raise ValueError(f"unknown event kind '{kind}' — one of {', '.join(KINDS)}")
+    entry = {"ts": _now(), "event": kind, "name": name}
+    who = instance_id()
+    if who:
+        entry["by"] = who
+    # Fields the caller passes are the event's own payload — never a copy of
+    # something the tree owns. A `status` here would be a second writer for a fact
+    # the bucket already states.
+    entry.update({k: v for k, v in fields.items() if v not in (None, "", [], {})})
+    if git.enabled():
+        if kind not in HOLDS:
+            _PENDING.append(entry)
+        return
+    try:
+        with (root / LOG).open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry, sort_keys=True) + "\n")
+    except OSError:
+        pass
+
+
+def pending() -> list:
+    """The events this command produced, for the commit that is about to carry them.
+    Draining is the caller's business — it runs once, at the end."""
+    return list(_PENDING)
+
+
+def read(root: Path, since: str = "", name: str = "") -> list:
+    """Every event, oldest first. A malformed line is skipped silently — a
+    half-written record from a killed process must not break `digest`."""
+    if git.enabled():
+        return git.read(root.parent, since=since, name=name)
+    p = root / LOG
+    if not p.is_file():
+        return []
+    out = []
+    for line in p.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            e = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if not isinstance(e, dict) or "event" not in e:
+            continue
+        if since and str(e.get("ts", "")) < since:
+            continue
+        if name and e.get("name") != name:
+            continue
+        out.append(e)
+    return out
+
+
+def last(root: Path, kind: str, name: str):
+    """The most recent event of one kind for one name, or None. Used by the
+    completion gate to ask 'did verify actually run, and when' — a question about
+    history, which is what this file is for."""
+    hits = [e for e in read(root, name=name) if e.get("event") == kind]
+    return hits[-1] if hits else None

package/harness/harness/extend.py

@@ -0,0 +1,99 @@
+"""Hook extension — how a repo says something at a point the harness owns.
+
+The plugin owns two hook points: what a fresh session is told (`SessionStart`)
+and when a session is told to finish (`Stop`). Both are declared in the plugin's
+own `hooks.json`, so a consumer cannot change the declaration — and should not
+have to. What a consumer needs is to change what is SAID there, and that is what
+this is: a repo names commands, the harness runs them, and their lines are folded
+into its own message.
+
+**Extend, replace and off are one mechanic, not three.** `enabled: false` silences
+the harness's own lines; `extend` adds the repo's. Together they are a replacement,
+`extend` alone is an addition, and `enabled: false` alone is off. A separate
+`replace:` key would be a third spelling of the same two facts.
+
+**These commands are EXECUTED, so this file is a security surface.** The rules are
+`verify.*`'s, for the same reason: split with `shlex`, run with `shell=False`, and
+never interpolated — a repo may run anything it likes, but what it may not do is
+get a `;` to mean `;`. The config loader refuses shell metacharacters at load,
+where it is one message, rather than here at the end of somebody's turn.
+
+**A broken extension is reported, never silent.** A hook that swallows a failure
+teaches its owner that it is working. One line saying which command failed costs
+nothing and is the only way anybody finds out.
+"""
+import shlex
+import subprocess
+from pathlib import Path
+
+#: How long an extension may take. A `SessionStart` hook runs BEFORE the user can
+#: type, so this is a budget for somebody's first impression of the repo, not for
+#: the command's convenience. Short, fixed, and not configurable: a repo that
+#: needs longer than this at session start needs a different design, and a config
+#: key would only let one land in the tree and make every session pay for it.
+TIMEOUT_SECONDS = 5
+
+#: A runaway extension must not become the session's whole context. Anything past
+#: this is dropped, and the drop is announced — a truncated list that says it is
+#: truncated is usable, one that pretends to be complete is not.
+MAX_LINES = 40
+MAX_CHARS = 4000
+
+
+def run(commands, repo) -> list:
+    """Run each command in `repo` and return the lines they printed.
+
+    Every failure path yields a line SAYING what failed rather than raising: this
+    is called from hooks, and a hook that raises greets somebody with a traceback
+    at the moment they were trying to start work.
+    """
+    out = []
+    for command in commands or []:
+        try:
+            argv = shlex.split(command)
+        except ValueError:
+            out.append(f"extension {command!r} is not a runnable command line — "
+                       f"unbalanced quotes; nothing was run.")
+            continue
+        if not argv:
+            continue
+        if not Path(repo).is_dir():
+            out.append(f"extension `{argv[0]}` was not run — {repo} is not a "
+                       f"directory to run it in.")
+            continue
+        try:
+            done = subprocess.run(argv, cwd=str(repo), capture_output=True,
+                                  text=True, timeout=TIMEOUT_SECONDS)
+        except FileNotFoundError:
+            out.append(f"extension `{argv[0]}` is not installed here — its lines "
+                       f"are missing from this list.")
+            continue
+        except subprocess.TimeoutExpired:
+            out.append(f"extension `{argv[0]}` took longer than "
+                       f"{TIMEOUT_SECONDS}s and was stopped — its lines are "
+                       f"missing from this list.")
+            continue
+        except OSError as e:
+            out.append(f"extension `{argv[0]}` could not run ({e.strerror}) — its "
+                       f"lines are missing from this list.")
+            continue
+        if done.returncode != 0:
+            # The command's own stderr, first line only. It knows why it failed
+            # and this hook does not, so quoting it beats paraphrasing it — and a
+            # whole stack trace at session start helps nobody.
+            why = (done.stderr or "").strip().splitlines()
+            out.append(f"extension `{argv[0]}` failed (exit {done.returncode})"
+                       + (f": {why[0]}" if why else "")
+                       + " — its lines are missing from this list.")
+            continue
+        lines = [ln.strip() for ln in (done.stdout or "").splitlines() if ln.strip()]
+        kept, chars = [], 0
+        for line in lines:
+            if len(kept) >= MAX_LINES or chars + len(line) > MAX_CHARS:
+                kept.append(f"… `{argv[0]}` printed more and was cut off here "
+                            f"({len(lines)} lines).")
+                break
+            kept.append(line)
+            chars += len(line)
+        out += kept
+    return out