taskproof 0.3.0__tar.gz → 0.4.0__tar.gz

{taskproof-0.3.0 → taskproof-0.4.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: taskproof
-Version: 0.3.0
+Version: 0.4.0
 Summary: A conveyor belt for AI coding agents: dispatch, independently verify, record.
 Author-email: HaoHaoP <HaoHaoP@HaoHaoP.com>
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/HaoHaoP/taskproof
+Project-URL: Documentation, https://taskproof.haohaop.com/
 Project-URL: Issues, https://github.com/HaoHaoP/taskproof/issues
 Keywords: ai-agents,orchestration,verification,codex,claude-code,cli
 Classifier: Development Status :: 2 - Pre-Alpha
@@ -70,28 +71,34 @@ else keeps working.
 
 ### Command line
 
+```bash
+pipx install taskproof
+```
+
+`uv tool install taskproof` does the same thing. Python **3.11+**, and the package
+is pure standard-library Python — there is no dependency tree to resolve.
+
+The latest development version, straight from the repository:
+
 ```bash
 pipx install git+https://github.com/HaoHaoP/taskproof
 ```
 
-Or download the wheel from the same Release and install the local file:
+Offline, or pinned to one build: download the wheel (or the sdist) from the
+[Releases](https://github.com/HaoHaoP/taskproof/releases) page and install the
+file. Its name carries the version, so take it from the release you downloaded —
+there is no unpinned wheel name to copy.
 
 ```bash
 pipx install ./taskproof-<version>-py3-none-any.whl
 ```
 
-The wheel's filename carries the version — take it from the Release you just
-downloaded; there is no unpinned wheel name to copy.
-
 Or run from a source checkout:
 
 ```bash
 pip install -e .
 ```
 
-**There is no `taskproof` package on PyPI.** Do not look for it there; use one of
-the three installs above.
-
 ## Run a task
 
 ```bash

{taskproof-0.3.0 → taskproof-0.4.0}/README.md

@@ -50,28 +50,34 @@ else keeps working.
 
 ### Command line
 
+```bash
+pipx install taskproof
+```
+
+`uv tool install taskproof` does the same thing. Python **3.11+**, and the package
+is pure standard-library Python — there is no dependency tree to resolve.
+
+The latest development version, straight from the repository:
+
 ```bash
 pipx install git+https://github.com/HaoHaoP/taskproof
 ```
 
-Or download the wheel from the same Release and install the local file:
+Offline, or pinned to one build: download the wheel (or the sdist) from the
+[Releases](https://github.com/HaoHaoP/taskproof/releases) page and install the
+file. Its name carries the version, so take it from the release you downloaded —
+there is no unpinned wheel name to copy.
 
 ```bash
 pipx install ./taskproof-<version>-py3-none-any.whl
 ```
 
-The wheel's filename carries the version — take it from the Release you just
-downloaded; there is no unpinned wheel name to copy.
-
 Or run from a source checkout:
 
 ```bash
 pip install -e .
 ```
 
-**There is no `taskproof` package on PyPI.** Do not look for it there; use one of
-the three installs above.
-
 ## Run a task
 
 ```bash

{taskproof-0.3.0 → taskproof-0.4.0}/pyproject.toml

@@ -26,6 +26,7 @@ dependencies = []
 
 [project.urls]
 Homepage = "https://github.com/HaoHaoP/taskproof"
+Documentation = "https://taskproof.haohaop.com/"
 Issues = "https://github.com/HaoHaoP/taskproof/issues"
 
 [project.scripts]

{taskproof-0.3.0 → taskproof-0.4.0}/src/taskproof/__init__.py

@@ -8,7 +8,7 @@ import sys
 
 # The single source of the version: `pyproject.toml` reads it from here
 # (`[tool.setuptools.dynamic]`), so cutting a release bumps exactly one string.
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 # Fail early and in plain language. Without this, running from a source checkout
 # under an older interpreter surfaces as `ModuleNotFoundError: No module named

{taskproof-0.3.0 → taskproof-0.4.0}/src/taskproof/cli.py

@@ -159,15 +159,16 @@ def build_parser() -> argparse.ArgumentParser:
     p = sub.add_parser(
         "accept",
         help=(
-            "clear a blocked or failed task: done if acceptance passed (a failed "
-            "card needs --note), else failed"
+            "clear a blocked, failed or timed-out task: done if acceptance passed "
+            "(failed and timeout cards need --note; a timeout stays timeout)"
         ),
     )
     p.add_argument("task_id")
     p.add_argument(
         "--note",
         help=(
-            "why a failed card is being cleared; required for failed "
+            "why a failed or timed-out card is being cleared; required for failed "
+            "(false red) and timeout (keeping half-finished work) "
             "(人工收尾必须留说明)"
         ),
     )
@@ -375,6 +376,22 @@ def _read_probe_flags(reg_path) -> dict:
     return registry.read_probe_flags(reg_path)
 
 
+def _warn_unknown_keys(reg) -> None:
+    """Print one stderr warning per key a block declares that nothing reads.
+
+    Card 88. An unknown key is not an error — the registry stays loadable and
+    the exit code stays 0 — but it is never silent either: this is how a
+    declaration that does nothing announces itself instead of waiting for a
+    human to notice months later (card 81's 22 dangling `timeout`s).
+
+    Only the two *listing* commands warn, and only on stderr, so `--json` keeps
+    the exact shape it had and `run` keeps its machine-readable stream clean.
+    """
+    for block, key in reg.unknown_keys:
+        where = "[defaults]" if block == "[defaults]" else f"lane '{block}'"
+        print(f"warning: unknown key '{key}' in {where}", file=sys.stderr)
+
+
 def _lane_overview(reg, stats, probes):
     """Project rows: one per project, each carrying its lanes and totals."""
     projects = []
@@ -465,6 +482,7 @@ def cmd_projects(args):
     """
     reg_path = registry.workspace_registry_path(args.workspace)
     reg = registry.load(reg_path)
+    _warn_unknown_keys(reg)
     probes = _read_probe_flags(reg_path)
 
     overview = []
@@ -511,6 +529,7 @@ def cmd_taskgroups(args):
     """List every taskgroup (lane): id, owning project, path and verify command."""
     reg_path = registry.workspace_registry_path(args.workspace)
     reg = registry.load(reg_path)
+    _warn_unknown_keys(reg)
     probes = _read_probe_flags(reg_path)
 
     taskgroups = [registry.taskgroup_record(tg, probes) for tg in reg.taskgroups]

{taskproof-0.3.0 → taskproof-0.4.0}/src/taskproof/dispatch.py

@@ -33,7 +33,14 @@ from typing import Optional
 from . import concurrency, registry, storage, verify
 from .adapters import get as get_adapter
 from .adapters.base import ResultParseError
-from .errors import EXIT_VERIFY, AdapterError, ConcurrencyError, UsageError, VerifyError
+from .errors import (
+    EXIT_VERIFY,
+    AdapterError,
+    ConcurrencyError,
+    PreconditionError,
+    UsageError,
+    VerifyError,
+)
 from .models import (
     STATUS_BLOCKED,
     STATUS_CANCELLED,
@@ -77,6 +84,13 @@ _ALL_STATUSES = (
 VERIFY_SKIPPED = "SKIPPED"
 
 
+#: Who ran a `verify` event: the dispatch pipeline's step ⑦ does it as the card
+#: winds down, a human re-checks afterwards (`taskproof verify <id>`). Recorded
+#: as a fact the ledger can read back, so the two cases stop looking alike.
+VERIFY_BY_RUN = "run"
+VERIFY_BY_CLI = "cli"
+
+
 #: Ceiling on the number of paths a single `changes` event carries. The audit
 #: stream is read by humans (`show`) as well as machines, so a card that sweeps
 #: thousands of files must not bloat the payload. The cut is not silent: the
@@ -159,6 +173,97 @@ def _cap_aware_refusal(exc: ConcurrencyError, setting) -> ConcurrencyError:
     return exc
 
 
+def _head_branch(path: str) -> str:
+    """``git -C <path> rev-parse --abbrev-ref HEAD``; empty on any failure.
+
+    Read-only. A detached HEAD reports the literal ``HEAD`` — that is exactly
+    what the refusal message has to show, because a lane that wants a branch and
+    finds a detached checkout is looking at the same mistake as one that wants
+    `main` and finds `other`.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=path,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    if proc.returncode != 0:
+        return ""
+    return proc.stdout.strip()
+
+
+def _has_branch_commit(path: str, branch: str) -> bool:
+    """Does ``refs/heads/<branch>`` resolve to a commit in ``path``?
+
+    Read-only, and deliberately the same question `git worktree add <branch>`
+    will ask a moment later: a name that no commit backs would otherwise turn
+    into a failed workspace creation AFTER a slot has been taken.
+    """
+    revision = f"refs/heads/{branch}^{{commit}}"
+    try:
+        proc = subprocess.run(
+            ["git", "rev-parse", "--verify", "--quiet", revision],
+            cwd=path,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return proc.returncode == 0
+
+
+def _check_branch_precondition(taskgroup) -> None:
+    """Refuse a dispatch the repository cannot honour (card 88), before any slot.
+
+    A lane that declares ``branch = X`` is stating which checkout it may run on.
+    Nothing checked that before: the card landed on whatever HEAD the tree
+    happened to be on, and the only guard was a shell assertion hand-written at
+    the head of some lanes' `verify` command — which a `workspace = "worktree"`
+    lane cannot even use, because its long-lived checkout is created from the
+    main tree's HEAD and detached from any branch.
+
+    * ``workspace = "none"``: the tree must actually be ON that branch, so the
+      check is ``rev-parse --abbrev-ref HEAD`` == X (a detached checkout
+      reports ``HEAD``, and is refused).
+    * ``workspace = "worktree"``: the branch must exist, because that is the
+      commit the lane workspace is built from; the main tree may be anywhere.
+
+    A lane without the key is not gated at all — today's behaviour, unchanged.
+    Runs before the task row and before the concurrency claim, so a refusal
+    leaves the ledger empty and takes no cap slot (exit 78).
+    """
+    branch = getattr(taskgroup, "branch", None)
+    if not branch:
+        return
+    path = taskgroup.path
+    if not os.path.isdir(path) or not _is_git_repo(path):
+        raise PreconditionError(
+            f"lane '{taskgroup.id}' declares branch '{branch}', but {path} "
+            "is not a git repository",
+            hint="check the lane's path, or drop the branch key",
+        )
+    if taskgroup.workspace == "worktree":
+        if not _has_branch_commit(path, branch):
+            raise PreconditionError(
+                f"lane '{taskgroup.id}' wants branch '{branch}', but {path} "
+                "has no such branch",
+                hint="fetch the branch, fix the name, or drop the branch key",
+            )
+        return
+    current = _head_branch(path)
+    if current != branch:
+        raise PreconditionError(
+            f"lane '{taskgroup.id}' wants branch '{branch}', the tree at "
+            f"{path} is on '{current}'",
+            hint="switch the tree to the declared branch, or drop the branch key",
+        )
+
+
 def dispatch(
     workspace: str,
     project_key: str,
@@ -183,7 +288,8 @@ def dispatch(
     link survives even a failed rerun. ``taskproof rerun`` is the only caller.
 
     Raises the typed errors in `errors.py` so the CLI can map them to exit codes:
-      ConcurrencyError -> 75, AdapterError -> 70, VerifyError -> 71, RegistryError -> 2
+      ConcurrencyError -> 75, AdapterError -> 70, VerifyError -> 71,
+      RegistryError -> 2, PreconditionError -> 78
 
     Rules that must survive any refactor:
       * the acceptance command runs in the PROJECT workdir, never the workspace
@@ -199,6 +305,12 @@ def dispatch(
     reg = registry.load(registry.workspace_registry_path(workspace))
     taskgroup = reg.require(project_key)
 
+    # ①′ the branch gate (card 88): a lane that declares `branch = X` must find
+    # a repository that can honour it. Before the adapter is chosen, before a
+    # task id or a slot exists, so a refusal is a PreconditionError (exit 78)
+    # with no ledger trace and no cap slot taken.
+    _check_branch_precondition(taskgroup)
+
     # The effective per-run timeout and where it came from (card 81): a
     # `--timeout` wins over the lane's own `timeout`, which wins over
     # `[defaults] timeout`, which wins over the built-in fallback.
@@ -808,6 +920,7 @@ def _execute(
             "exit_code": verify_exit_field,
             "note": note,
             "output_tail": outcome.output_tail if outcome is not None else "",
+            "by": VERIFY_BY_RUN,
         },
     )
 
@@ -1589,9 +1702,22 @@ def _ensure_links(repo_root: str, workspace_root: str, links) -> list:
 
 
 def _worktree_add(repo_root: str, path: str, lane) -> None:
-    """``git worktree add --detach`` a fresh, long-lived lane workspace."""
+    """``git worktree add --detach`` a fresh, long-lived lane workspace.
+
+    A lane that declares `branch` gets its workspace built from that branch
+    (card 88), so the checkout it runs in for the rest of its life is the one
+    the registry names rather than whatever the main tree's HEAD happened to be
+    on the day it was first used. `--detach` is not decoration: a branch can be
+    checked out by only one worktree at a time and the main tree normally holds
+    it, so a plain checkout of the same branch fails outright. A lane without
+    the key is created exactly as before — detached at the main tree's HEAD —
+    because the argument list is left untouched.
+    """
+    argv = ["git", "worktree", "add", "--detach", path]
+    if getattr(lane, "branch", None):
+        argv.append(lane.branch)
     proc = subprocess.run(
-        ["git", "worktree", "add", "--detach", path],
+        argv,
         cwd=repo_root,
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
@@ -1615,6 +1741,12 @@ def _ensure_lane_workspace(conn, task_id: str, lane, *, worktree_flag: bool = Fa
     same repo is a hard error with the `workspace-rm` remedy. ``worktree_flag``
     is the one-time ``--worktree`` argument: when set it is ignored, because the
     lane workspace already is the long-lived checkout.
+
+    A lane that declares `branch` is created from that branch; an existing
+    workspace is never re-created or moved onto a newly declared one, exactly
+    like every other edit to a lane's configuration: what runs next changes,
+    the checked-out tree on disk does not. Switch it with `workspace-rm` plus a
+    new run if that is what you want.
     """
     if not _is_git_repo(lane.path):
         raise UsageError(
@@ -1901,6 +2033,7 @@ def verify_task(workspace: str, task_id: str) -> verify.VerifyOutcome:
                 "exit_code": outcome.exit_code,
                 "note": outcome.note,
                 "violations": outcome.violations,
+                "by": VERIFY_BY_CLI,
             },
         )
         return outcome
@@ -2072,25 +2205,33 @@ def _last_summary(conn, task_id: str) -> Optional[str]:
 def accept_task(
     workspace: str, task_id: str, *, by: str = "cli", note: Optional[str] = None
 ) -> dict:
-    """Clear a `blocked` or `failed` card — the human disposition of one run.
+    """Clear a `blocked`, `failed` or `timeout` card — the human disposition of
+    one run.
 
     `blocked` (a boundary breach) is accepted with or without a note, exactly as
     it always has been: a green acceptance earns `done`, a red or skipped one
     earns `failed`. `failed` (the adapter failed, or acceptance ran and went red)
     may also be accepted, but ONLY with a non-empty ``note``: closing a failed
-    card is a human sign-off, and the reason must survive in the ledger.
+    card is a human sign-off that the recorded red was a false one, and the
+    reason must survive in the ledger. `timeout` (the adapter hit the hard
+    timeout) is accepted the same way — also ONLY with a non-empty ``note`` —
+    because a timed-out run's artefacts are half-finished by definition and the
+    sign-off means "a human has looked at this and kept the work", never "done".
 
     `accept` is a human **registration**, not a verdict: it never re-runs
     acceptance and never rewrites `verify_*`. Whatever the run recorded when it
     stopped stays authoritative; a failed card is promoted to `done` only because
-    a human judged the recorded failure a false red, and that judgement is kept
-    in the `accepted` event alongside the evidence the human saw.
-
-    Every other status (running / verifying / done / timeout /
-    cancelled) is refused with a readable `TaskStateError`, so `accept` can never
-    silently re-close a card. The card's `verify_*` columns and `finished_at` are
-    left untouched — the run's own facts do not change because a human later
-    signed off. Returns the updated task row.
+    a human judged the recorded failure a false red. A `timeout` card is not
+    promoted at all: it stays `timeout` and the ledger simply gains one
+    `accepted` event whose `from` and `to` are both `"timeout"` — from == to is
+    how "registered, not re-judged" is written. Either judgement is kept in the
+    `accepted` event alongside the evidence the human saw.
+
+    Every other status (running / verifying / done / cancelled) is refused with a
+    readable `TaskStateError`, so `accept` can never silently re-close a card.
+    The card's `verify_*` columns and `finished_at` are left untouched — the
+    run's own facts do not change because a human later signed off. Returns the
+    updated task row.
     """
     note_text = note if isinstance(note, str) else None
     note_present = bool(note_text and note_text.strip())
@@ -2101,20 +2242,23 @@ def accept_task(
         if row is None:
             raise TaskNotFoundError(f"no such task: {task_id}")
         status = row["status"]
-        if status not in (STATUS_BLOCKED, STATUS_FAILED):
+        if status not in (STATUS_BLOCKED, STATUS_FAILED, STATUS_TIMEOUT):
             raise TaskStateError(
                 f"task {task_id} is {status}; "
-                "only a blocked or failed task can be accepted"
+                "only a blocked, failed or timed-out task can be accepted"
             )
-        if status == STATUS_FAILED and not note_present:
-            # A failed card is closed by human judgement, not by a fresh verdict,
-            # so the reason MUST be on the record. Refuse before touching the row.
+        if status in (STATUS_FAILED, STATUS_TIMEOUT) and not note_present:
+            # A failed or timed-out card is closed by human judgement, not by a
+            # fresh verdict, so the reason MUST be on the record: a failed card's
+            # sign-off says the red was false, a timed-out card's says the
+            # half-finished work is being kept. Refuse before touching the row.
+            what = "failed" if status == STATUS_FAILED else "timed-out"
             raise UsageError(
-                "accepting a failed task requires a note: "
+                f"accepting a {what} task requires a note: "
                 "人工收尾必须留说明",
                 hint=(
                     "accept is a human registration, not a verdict; pass "
-                    '--note "why this failure is being cleared"'
+                    '--note "why this false red / timed-out result is kept"'
                 ),
             )
 
@@ -2129,6 +2273,11 @@ def accept_task(
             # A human signed the red off as a false negative: the recorded facts
             # stay, the terminal state becomes `done`.
             new_status = STATUS_DONE
+        elif status == STATUS_TIMEOUT:
+            # Registration only: a timed-out card is not re-judged. Its terminal
+            # state stays `timeout` and `finished_at` is left alone — the run's
+            # own facts stand; the `accepted` event is the only thing added.
+            new_status = status
         else:
             # `blocked` keeps following its acceptance result, exactly as before.
             new_status = STATUS_DONE if verify_exit == 0 else STATUS_FAILED
@@ -2154,7 +2303,10 @@ def accept_task(
             if agent_summary:
                 payload["summary"] = agent_summary[:_SUMMARY_TAIL_CHARS]
 
-        storage.update_task(conn, task_id, status=new_status)
+        # A timeout is never promoted, so its row is not written at all; every
+        # other path moves `status` (and only `status`).
+        if new_status != status:
+            storage.update_task(conn, task_id, status=new_status)
         storage.append_event(conn, task_id, "accepted", payload)
         return dict(storage.get_task(conn, task_id))
     finally:

{taskproof-0.3.0 → taskproof-0.4.0}/src/taskproof/errors.py

@@ -13,6 +13,9 @@ EXIT_USAGE = 64
 EXIT_ADAPTER = 70
 EXIT_VERIFY = 71
 EXIT_CONCURRENCY = 75
+#: sysexits' EX_CONFIG: the declaration is understood, the environment cannot
+#: satisfy it. Here: the registry and the repository disagree about reality.
+EXIT_PRECONDITION = 78
 
 
 class TaskproofError(Exception):
@@ -53,3 +56,17 @@ class ConcurrencyError(TaskproofError):
     """Same-group serialisation or the global cap blocked this dispatch. -> 75"""
 
     exit_code = EXIT_CONCURRENCY
+
+
+class PreconditionError(TaskproofError):
+    """What the registry declares and what the repository really is disagree.
+
+    Raised before the card exists — before a task row, before a concurrency
+    slot — so a refusal leaves no ledger trace at all. The same idea as
+    sysexits' ``EX_CONFIG`` (78): the configuration is readable and well formed,
+    but it cannot be honoured right now. Concretely, a lane that declares
+    ``branch = X`` and finds a different branch checked out, a missing branch,
+    or no repository at all. -> 78
+    """
+
+    exit_code = EXIT_PRECONDITION

{taskproof-0.3.0 → taskproof-0.4.0}/src/taskproof/models.py

@@ -68,6 +68,13 @@ class Taskgroup:
     #: (for example ``desktop/node_modules``). Empty means the dispatcher may
     #: probe for package-manager dependency directories.
     link: List[str] = field(default_factory=list)
+    #: Branch this lane declares as its home (card 88). ``None`` — the default —
+    #: means the lane says nothing, so no gate runs and a ``workspace =
+    #: "worktree"`` lane is still built from the main tree's current HEAD, byte
+    #: for byte as before. A declared name is checked against the repository at
+    #: dispatch time (a mismatch raises a precondition error, exit 78) and is
+    #: the commit a lane workspace is created from. See `dispatch`.
+    branch: Optional[str] = None
     #: Concurrency lock name. Empty means this lane's own id; loading fills the
     #: default in so callers never need to special-case an unset value.
     group: str = ""

{taskproof-0.3.0 → taskproof-0.4.0}/src/taskproof/registry.py

@@ -125,6 +125,41 @@ _LANE_FIELDS = (
     "link",
 )
 
+#: Every key `_load_lane_fields` reads, i.e. every key that is a lane *setting*.
+#: Deliberately NOT the same tuple as `_LANE_FIELDS` above: that one decides
+#: whether a `[[project]]` block *is* a lane, so a setting that does not settle
+#: that question (`timeout`, `branch`, `group`, ...) must stay out of it or a
+#: bare project block would silently become a lane. This tuple is the other
+#: direction — it is what the unknown-key warning uses, so adding a key to the
+#: loader means adding it here too.
+_LANE_SETTING_KEYS = (
+    "group",
+    "verify",
+    "verify_kind",
+    "forbidden_paths",
+    "auto_registered",
+    "result_schema",
+    "workspace",
+    "link",
+    "timeout",
+    "idle_timeout",
+    "branch",
+)
+
+#: Keys a `[[project]]` block may carry without a warning: its own identity
+#: plus every lane setting (the compat path reads a lane off exactly those).
+_PROJECT_KEYS = frozenset(("id", "path", "aliases") + _LANE_SETTING_KEYS)
+
+#: A `[[taskgroup]]` block is the same shape plus its owning project.
+_TASKGROUP_KEYS = _PROJECT_KEYS | {"project"}
+
+#: Keys `[defaults]` is actually read for — `Registry.concurrency`,
+#: `Registry.timeout` / `registry.resolve_timeout`. `idle_timeout` is
+#: deliberately absent: card 83 gave the idle watchdog no `[defaults]` rung
+#: (`registry.resolve_idle_timeout`), so writing one there is ignored like any
+#: typo and has to be warned about, not blessed.
+_DEFAULTS_KEYS = frozenset(("concurrency", "timeout"))
+
 
 class RegistryConflictError(RegistryError):
     """The caller's expected hash no longer matches the registry on disk."""
@@ -266,11 +301,19 @@ class Registry:
         taskgroups: List[Taskgroup],
         defaults: dict,
         source: Optional[str] = None,
+        unknown_keys=None,
     ):
         self.projects = projects
         self.taskgroups = taskgroups
         self.defaults = defaults or {}
         self.source = source
+        #: `(block id, key)` for every key a block carried that its kind cannot
+        #: read, in file order and deduplicated. `[defaults]` names itself as
+        #: `"[defaults]"`. Empty is the normal case. Loading never fails on
+        #: these — `taskproof projects` / `taskgroups` warn on stderr instead,
+        #: which is how a silently dropped `timeout` (card 81's bug) would have
+        #: announced itself.
+        self.unknown_keys = list(unknown_keys or [])
 
     # -- lookup -----------------------------------------------------------
 
@@ -674,6 +717,31 @@ def _load_lane_fields(
             "workspace = 'worktree'"
         )
 
+    # A lane's `branch` (card 88) is only a NAME here. Whether the repository
+    # actually has it is a question for dispatch time (the repo may not be on
+    # the machine yet, and a check at load time would make `projects` fail for a
+    # lane nobody is running). The shape, though, is settled now: a string that
+    # still has something in it once trimmed, and no whitespace inside — a
+    # `branch = "george main"` would otherwise be handed to `git`, which reads
+    # it as a revision range, not a branch.
+    branch = entry.get("branch")
+    if branch is not None:
+        if not isinstance(branch, str):
+            raise RegistryError(
+                f"{source}: {label} field 'branch' must be a string "
+                f"(got {type(branch).__name__})"
+            )
+        branch = branch.strip()
+        if not branch:
+            raise RegistryError(
+                f"{source}: {label} field 'branch' must not be empty"
+            )
+        if any(character.isspace() for character in branch):
+            raise RegistryError(
+                f"{source}: {label} field 'branch' must not contain "
+                f"whitespace: {branch!r}"
+            )
+
     # A lane timeout, when written, must be a positive integer. TOML gives us
     # bool/int/float here, so reject every wrong type up front rather than
     # letting a truthy `true` masquerade as 1 second. Missing stays `None`:
@@ -704,6 +772,7 @@ def _load_lane_fields(
         "result_schema": result_schema,
         "workspace": workspace,
         "link": link,
+        "branch": branch,
         "timeout": timeout,
         "idle_timeout": idle_timeout,
     }
@@ -851,7 +920,35 @@ def load(path: str) -> Registry:
     defaults = data.get("defaults", {})
     if not isinstance(defaults, dict):
         raise RegistryError(f"{path}: 'defaults' must be a table")
-    return Registry(projects, taskgroups, defaults, source=path)
+
+    # Card 88: every key a block carries that its kind has no reader for. The
+    # ids are guaranteed non-empty strings by here (both loops above refuse a
+    # block without one first), so this pass only has to walk the blocks.
+    # `data` keeps keys in the order they first appear in the document, which is
+    # what "in order of appearance" means for a reader looking at the file.
+    unknown_keys: List[tuple] = []
+    recorded = set()
+
+    def note(block: str, entry: dict, known) -> None:
+        for key in entry:
+            if key in known or (block, key) in recorded:
+                continue
+            recorded.add((block, key))
+            unknown_keys.append((block, key))
+
+    for name, value in data.items():
+        if name == "defaults" and isinstance(value, dict):
+            note("[defaults]", value, _DEFAULTS_KEYS)
+        elif name == "project" and isinstance(value, list):
+            for entry in value:
+                note(entry["id"], entry, _PROJECT_KEYS)
+        elif name == "taskgroup" and isinstance(value, list):
+            for entry in value:
+                note(entry["id"], entry, _TASKGROUP_KEYS)
+
+    return Registry(
+        projects, taskgroups, defaults, source=path, unknown_keys=unknown_keys
+    )
 
 
 def workspace_registry_path(workspace: str) -> str:
@@ -917,6 +1014,9 @@ def taskgroup_record(taskgroup: Taskgroup, probe_flags: Optional[dict] = None) -
         "result_schema": taskgroup.result_schema,
         "timeout": taskgroup.timeout,
         "idle_timeout": taskgroup.idle_timeout,
+        # Card 88: the declared branch, or null when the lane declares none
+        # (the shape `timeout` beside it uses for "not declared").
+        "branch": taskgroup.branch,
         "auto_registered": bool(taskgroup.auto_registered),
         "probe": probe,
         "probe_exit": probe_exit,