taskops-cli 0.2.0__py3-none-any.whl

taskops/usecases/edit.py

@@ -0,0 +1,71 @@
+"""`taskops tasks edit` — rewriting the card itself: its title, its spec, its priority.
+
+Until this existed, a spec was whatever the planner typed at 9am and nothing could correct
+it: an agent that read a brief which had since turned out to be wrong had no door back, and
+the only workaround was cancelling the card and planning a new one, which threw away its
+thread and its commits.
+
+Separate from `update` on purpose. `update` moves a card through the state machine and talks
+about the WORK; this rewrites what the work IS. They record different events, they answer to
+different guards, and folding them together would put a spec rewrite behind the same lease
+and transition checks that exist to protect a status.
+
+**One event per field**, never one `edited` carrying three. Replay applies each event on its
+own merits, so a body holding three fields would make the newer-wins rule all-or-nothing —
+two people editing different fields of the same card would clobber each other instead of
+converging on both edits.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from .._errors import BadRequest
+from .._types import CLOSED_STATUSES
+from ..contracts import EditResult, Task
+from ..engine import record
+from ..storage import Store
+from ._project import caller, heartbeat, project
+
+__all__ = ["edit"]
+
+CLOSED_REFUSAL = "closed cards are history — open a new card referencing it"
+"""Why a done or cancelled card is frozen. The log is what a standup, a report and a
+teammate's clone read back; letting somebody rewrite the spec of work already delivered
+would rewrite the record of what was delivered, which is the one thing this system exists
+to keep honest."""
+
+
+def edit(start: Path | str, task_id: str, *, title: str | None = None,
+         spec: str | None = None, priority: int | None = None,
+         actor: str = "") -> EditResult:
+    """Apply whatever fields were passed, recording one `edited` event for each."""
+    asked = {"title": title, "spec": spec, "priority": priority}
+    wanted = {field: value for field, value in asked.items() if value is not None}
+    if not wanted:
+        raise BadRequest("nothing to edit — pass a `title`, a `spec` or a `priority`")
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        task = store.tasks.need(task_id)
+        if task["status"] in CLOSED_STATUSES:
+            raise BadRequest(CLOSED_REFUSAL)
+        changed = [f for f, value in wanted.items() if _apply(store, task, who, f, value)]
+        return EditResult(task=store.tasks.need(task_id), changed=changed)
+
+
+def _apply(store: Store, task: Task, who: str, field: str, value: object) -> bool:
+    """Write one field, and say so in the log. A no-op edit records NOTHING.
+
+    An event whose `from` equals its `to` is a lie about the card's history and, worse,
+    bumps `updated` — which is the arbitrator replay uses, so a redundant edit on one
+    machine would win an argument against a real edit on another.
+    """
+    before = task[field]                # type: ignore[literal-required]
+    if before == value:
+        return False
+    store.tasks.set_field(task["id"], field, value, when=now())
+    record(store, task=task["id"], actor=who, kind="edited",
+           body={"field": field, "from": before, "to": value})
+    return True

taskops/usecases/exchange.py

@@ -0,0 +1,86 @@
+"""Events over HTTP: the half of remote sync that a server performs.
+
+The git path (`storage.sync`) and this one move the SAME facts and rely on the same property —
+ids are content hashes, so importing an event twice is a primary-key no-op. Nothing here
+resolves a conflict because there is none to resolve: events are facts about the past, and the
+union of two logs is the correct log.
+
+**Seq is local, and that is the whole cursor design.** A puller's `after` is a number in the
+SERVER's sequence, so a client keeps one cursor PER remote and may never mix two. Nothing on
+the wire carries a seq inside an event for exactly that reason (`EventTable.page_after`).
+
+**Local-only kinds are filtered in BOTH directions.** Outbound because `activity` is a
+per-tool-call heartbeat and replicating it would add thousands of rows a day for nothing;
+inbound because a server does not trust a client to have remembered the rule.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .._errors import BadRequest
+from .._types import LOCAL_ONLY_KINDS
+from ..contracts import Event
+from ..engine import relay, replay, unblock
+from ..storage import event_from
+from ._project import project
+
+__all__ = ["accept_events", "pull_events", "MAX_BATCH", "MAX_PAGE"]
+
+MAX_BATCH = 500
+"""Events per POST. A cap and not a stream: the body is read into memory before anything looks
+at it, so the limit has to bind before the allocation does. A client with more sends again."""
+
+MAX_PAGE = 500
+
+
+def accept_events(start: Path | str, raw: list[Any]) -> dict[str, int]:
+    """Relay a foreign batch. Returns how many were NEW here, and this server's cursor.
+
+    `accepted` is the idempotency signal the client logs: pushing the same batch twice answers
+    0 the second time, which is how a person reading the output can tell a retry from a
+    duplicate import.
+
+    The whole batch is coerced BEFORE anything is written, so a malformed event at index 40
+    cannot leave 39 relayed and the caller unsure how far it got.
+
+    Accepted events are MATERIALISED — `replay` then `unblock` — before this returns. Without
+    that, a push landed its events and the server's board stayed empty: the exact bug the git
+    path hit once and `replay.py` tells the story of. The smoke that caught it here asked the
+    server's board for the pushed card and got eight empty columns.
+    """
+    if len(raw) > MAX_BATCH:
+        raise BadRequest(f"{len(raw)} events in one push — send at most {MAX_BATCH} per "
+                         f"request and repeat until the cursor stops moving")
+    events = [_coerce(item, index) for index, item in enumerate(raw)]
+    with project(start) as store:
+        fresh = [e for e in events if e is not None and relay(store, e)]
+        if fresh:
+            replay.apply(store, fresh)
+            unblock(store)
+        return {"accepted": len(fresh), "max_seq": store.events.max_seq()}
+
+
+def pull_events(start: Path | str, *, after: int = 0, limit: int = MAX_PAGE) -> dict[str, Any]:
+    """One page of this server's log after a cursor, plus where the cursor now stands.
+
+    `more` reports that the PAGE was full, not that events are certainly waiting — the cheap
+    answer, and the client's loop stops one request later either way.
+    """
+    size = max(1, min(limit, MAX_PAGE))
+    with project(start) as store:
+        page, cursor = store.events.page_after(after, limit=size)
+        shared = [e for e in page if e["kind"] not in LOCAL_ONLY_KINDS]
+        return {"events": shared, "max_seq": cursor, "more": len(page) == size}
+
+
+def _coerce(item: Any, index: int) -> Event | None:
+    """A wire object -> an event to relay, or None for one to drop. Raises on nonsense.
+
+    The id is NOT recomputed — see `engine.log.relay` for why rebuilding it forks history.
+    """
+    event = event_from(item)
+    if event is None:
+        raise BadRequest(f"events[{index}] is not an event — it needs at least `id` and `kind`")
+    return None if event["kind"] in LOCAL_ONLY_KINDS else event

taskops/usecases/feed.py

@@ -0,0 +1,138 @@
+"""Following the event log as it grows — what a live board (or a terminal) tails.
+
+This is a use case rather than something the HTTP layer does itself, and the architecture test
+is what said so: the feed needs a bus subscription and a cursor read, both of which are engine
+and storage. Putting it here means the transport frames SSE and nothing else, and it means the
+same feed can be tailed from the CLI without a second implementation.
+
+**Why it polls a cursor rather than only listening to the bus.** Every writer is a different
+process — MCP is stdio, so each editor session launches its own server, and each git hook is a
+fresh interpreter. An in-process bus cannot see any of them. So the source of truth is
+`events.after_seq(cursor)`, an indexed integer scan, and the bus subscription is layered on top
+purely so the studio's OWN writes (a human's comment) appear instantly rather than on the next
+tick. Both paths end at the same cursor read, so an event can never be delivered twice.
+
+**And why it also carries things that are NOT events.** A narration delta is not a fact worth
+storing — see `contracts.wire` — so it never reaches the database and there is no cursor that
+could produce it. It rides the same generator because a browser has ONE socket: the alternative
+is a second stream, a second subscription and a second lifetime to leak. A wire message is
+yielded straight through, and the consequence is documented rather than hidden: it CANNOT be
+recovered. A browser that reconnects missed whatever passed while it was away, and that is fine,
+because the file on disk is the durable copy and the socket is only the window onto it.
+"""
+
+from __future__ import annotations
+
+import queue
+from pathlib import Path
+from typing import Iterator
+
+from ..contracts import Event, WireMessage
+from ..engine import BUS, WIRE, is_wire
+from ..storage import Store, resolve_root
+
+__all__ = ["follow", "TICK", "is_wire"]
+
+TICK = 0.5
+"""Seconds between cursor polls. Under the threshold where a board feels polled rather than
+live, and two queries a second against an indexed integer column is nothing."""
+
+_SIGNAL_DEPTH = 256
+
+
+def follow(start: Path | str, after: int = -1, *,
+           tick: float = TICK) -> Iterator[Event | WireMessage | None]:
+    """Yield every event as it lands, every wire message as it is published, and `None` on
+    each quiet tick.
+
+    The `None` is not a placeholder — it is how a consumer gets control back on a schedule
+    without this module knowing what it wants to do with it. The studio emits an SSE keepalive;
+    a terminal tailer redraws a clock; a test stops. Without it, a silent hour would be an hour
+    with no way to notice the connection died.
+
+    `after < 0` means "from now": a board that opened is asking what happens NEXT, and replaying
+    the entire history into it would be a spike of thousands of frames it has no use for.
+
+    **Wire messages are filtered by ROOT, and that filter lives HERE.** `WIRE` is process-global,
+    so a server holding many projects open (`transports.http.projects`) broadcasts every narration
+    delta to every board — which is prose from one project on another project's screen, and that
+    prose names its strategies and its data. Events cannot leak: they come from each project's own
+    sqlite, through the cursor read below. A wire message has no such gate, so this generator
+    supplies one: it already resolved its own root, and it compares against the root the publisher
+    stamped with the same `resolve_root`.
+
+    It belongs to this function and not to a transport for one reason each: `live.py` sees frames
+    but would have to be told which project it is framing for (and every future consumer would
+    have to be told again), while `projects.py` mounts whole routers and never sees an individual
+    frame at all. One filter, on the only object that knows both the root and the message.
+
+    A message with NO root is DROPPED, not broadcast. It is the only safe default: an unlabelled
+    frame is exactly the pre-fix message that leaked, and delivering it everywhere to be
+    compatible with an older publisher would preserve the bug this closes. The cost of dropping
+    is a few seconds of missing animation while a mixed-version server is restarted; the cost of
+    delivering is one project's prose on another's screen.
+    """
+    root = resolve_root(start)
+    origin = str(root)
+    signal: "queue.Queue[WireMessage | None]" = queue.Queue(maxsize=_SIGNAL_DEPTH)
+    # An event enqueues `None` — the SIGNAL to read the cursor, because the row is the payload.
+    # A wire message enqueues ITSELF, because there is no row and never will be.
+    cancels = (BUS.subscribe(lambda _event: _offer(signal, None)),
+               WIRE.subscribe(lambda message: _offer(signal, message)))
+    store = Store(root, check_same_thread=False)
+    try:
+        cursor = store.events.max_seq() if after < 0 else after
+        while True:
+            messages = [m for m in _drain(signal, tick) if m.get("root") == origin]
+            yield from messages
+            fresh = store.events.after_seq(cursor)
+            yield from fresh
+            if fresh:
+                cursor = store.events.max_seq()
+            elif not messages:
+                # Only when NOTHING was delivered. A narration streaming at fifty deltas a second
+                # would otherwise emit fifty keepalive ticks a second and burn the stream's
+                # lifetime (`live.MAX_TICKS`) in the middle of the thing somebody is watching.
+                yield None
+    finally:
+        # All of them, always. A browser tab that closes leaves this generator un-advanced, and
+        # without the release every closed tab would strand a subscriber holding a sqlite
+        # connection — which on a board somebody leaves open all day IS the failure mode.
+        for cancel in cancels:
+            cancel()
+        store.close()
+
+
+def _drain(signal: "queue.Queue[WireMessage | None]", tick: float) -> list[WireMessage]:
+    """Block up to one tick, then take everything that piled up. Returns the wire messages.
+
+    The `None`s are DISCARDED on purpose: they are a wake-up signal, and the cursor read that
+    follows is what decides which events to send. Treating them as the payload would give one
+    event two delivery paths and a duplicate whenever both fired. Wire messages are the opposite
+    — they ARE the payload, since nothing else in this process knows they happened.
+    """
+    out: list[WireMessage] = []
+    try:
+        first = signal.get(timeout=tick)
+    except queue.Empty:
+        return out
+    if first is not None:
+        out.append(first)
+    while not signal.empty():
+        item = signal.get_nowait()
+        if item is not None:
+            out.append(item)
+    return out
+
+
+def _offer(signal: "queue.Queue[WireMessage | None]", item: WireMessage | None) -> None:
+    """Never block a WRITER. A full queue means a consumer is behind, and the cursor poll will
+    catch it up anyway — so dropping the signal costs half a second, where blocking here would
+    stall the use case that just recorded the event.
+
+    A dropped WIRE message is a lost fragment of prose and nothing more: the file on disk is
+    being written in parallel, so the reader loses a moment of the animation, never the text."""
+    try:
+        signal.put_nowait(item)
+    except queue.Full:
+        return

taskops/usecases/guard.py

@@ -0,0 +1,122 @@
+"""The commit guard — where git-binding stops being a convention.
+
+Called from a Claude Code `PreToolUse` hook on `git commit`. It answers one question:
+may this commit happen, and with what message. The hook turns a refusal into a DENY
+that the agent reads before the commit runs, so a task-less commit never exists rather
+than being reported afterwards.
+
+Why enforce at all, when a `post-commit` hook could just record whatever happens: a
+commit with no task is a commit nobody can attribute at review time, and the moment
+one is allowed the board stops being a complete picture of what changed. The refusal is
+also cheap to satisfy — the fix is one `taskops_next` call, and the message says so.
+
+What it deliberately does NOT do is judge the CONTENT. Whether the diff matches the
+spec is a question for a model, and putting a model in the path of every commit would
+add seconds and a failure mode to the most common action in the repository.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from ..engine import commitline, gitio
+from ..storage import Store
+from ._project import caller, heartbeat, project
+
+__all__ = ["Verdict", "check_commit", "check_command"]
+
+
+class Verdict:
+    """Allowed or not, the message the commit should carry, and the command to run.
+
+    A class rather than a tuple because a caller reads all four fields, and a bare
+    `(bool, str, str, str)` at a call site is where two of them get swapped.
+    """
+
+    def __init__(self, *, allowed: bool, reason: str = "", message: str = "",
+                 task: str = "", command: str = "") -> None:
+        self.allowed = allowed
+        self.reason = reason
+        self.message = message
+        self.task = task
+        self.command = command
+        """The rewritten shell command, or "" if there is nothing to change.
+
+        Set only by `check_command`. It exists so the hook transport can hand back an
+        `updatedInput` without knowing anything about git commit syntax — deciding what a
+        command becomes is a decision, and decisions do not live in a transport.
+        """
+
+
+def check_command(start: Path | str, command: str, *, actor: str = "") -> Verdict | None:
+    """Judge a whole `git commit` shell command. None if it is not one.
+
+    The Claude Code matcher can only filter on the TOOL name, so the hook sees every Bash
+    call and something has to recognise a commit. That something is here rather than in the
+    transport, along with the rewrite: the transport passes through what it received and gets
+    back what to do.
+    """
+    if not commitline.is_commit(command):
+        return None
+    verdict = check_commit(start, commitline.message_of(command), actor=actor)
+    if verdict.allowed and verdict.message:
+        verdict.command = commitline.with_message(command, verdict.message)
+    return verdict
+
+
+def check_commit(start: Path | str, message: str, *, actor: str = "") -> Verdict:
+    """May this commit run, and what should its message say.
+
+    The task is taken from the BRANCH, not from the caller's claims. An agent holding
+    three leases and committing on one branch means exactly one of them, and asking it
+    to also state which invites the one answer that is wrong.
+    """
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        branch = gitio.current_branch(store.root)
+        return _judge(store, who, branch, message)
+
+
+def _judge(store: Store, who: str, branch: str, message: str) -> Verdict:
+    on_branch = gitio.task_of_branch(branch)
+    stated = gitio.task_of_message(message)
+    if not on_branch:
+        return _no_branch(store, who, branch, message, stated)
+    if stated and stated != on_branch:
+        return Verdict(allowed=False, task=on_branch,
+                       reason=f"the message says {stated} but the branch is for "
+                              f"{on_branch} — fix whichever is wrong, do not guess")
+    if not store.leases.held_by(on_branch, who, now()):
+        return Verdict(allowed=False, task=on_branch,
+                       reason=f"{who} holds no live lease on {on_branch}. Claim it "
+                              f"(taskops_next task={on_branch}) before committing — "
+                              f"another agent may have taken it while you worked")
+    return Verdict(allowed=True, task=on_branch,
+                   message=gitio.add_trailer(message, on_branch))
+
+
+def _no_branch(store: Store, who: str, branch: str, message: str,
+               stated: str) -> Verdict:
+    """Not on a `tk/...` branch. The one case with a genuinely useful suggestion.
+
+    A trailer alone is accepted: a developer cherry-picking onto main, or committing a
+    fix straight to a trunk-based repository, is doing something legitimate — and the
+    trailer is what actually binds the commit, since a branch name does not survive a
+    squash. Only the case with NEITHER is refused, and then the reason names the branch
+    to switch to, because "claim a task first" without the command is a puzzle.
+    """
+    if stated and store.tasks.get(stated) is not None:
+        return Verdict(allowed=True, task=stated, message=message)
+    held = store.leases.of_actor(who, now())
+    if not held:
+        return Verdict(allowed=False,
+                       reason=f"`{branch or 'HEAD'}` is not a task branch and {who} "
+                              f"holds no task. Run taskops_next, then commit on the "
+                              f"branch it names")
+    suggestions = ", ".join(f"tk/{lease['task']}/…" for lease in held[:3])
+    return Verdict(allowed=False,
+                   reason=f"`{branch}` is not a task branch. You hold "
+                          f"{len(held)} task(s) — switch to one of {suggestions} "
+                          f"(taskops_ask gives the exact branch name)")

taskops/usecases/hooks.py

@@ -0,0 +1,127 @@
+"""Installing the git hooks, without destroying the ones already there.
+
+Three decisions carry this file.
+
+**The command is the WIRING transport, not the developer's CLI.** `taskops` is what a person
+types; `python -m taskops.transports.hooks` is what git runs. They were the same binary until
+the separation the project declares turned out to be cosmetic, and a shared door is a door
+whose surface is decided by the wrong audience.
+
+**The interpreter is absolute, not `taskops` on PATH.** Git hooks run with whatever
+environment git had, and that is routinely not the shell's: a virtualenv that is not active,
+a GUI client with a minimal PATH, a `git commit` from an editor. A bare `taskops` there
+resolves to nothing and the hook does nothing — silently, because every line ends in
+`|| true`. Embedding `sys.executable -m taskops...` binds the hook to the interpreter that
+installed it, which is the one that definitely has taskops in it. (Found by the end-to-end
+test, where `git commit` could not see the venv that pytest was running from.)
+
+**Existing hooks are CHAINED, never overwritten.** A repository's `post-commit` may already
+run something somebody depends on, so an existing script is kept and our line is appended
+under a marker — which is also how a re-install finds the line it wrote last time and
+REWRITES it. That refresh is what repairs a repository initialised before the wiring moved
+out of the CLI: its hook names a command that no longer exists, and `|| true` means it says
+nothing about it. `taskops init` again is the whole repair.
+"""
+
+from __future__ import annotations
+
+import stat
+import sys
+from pathlib import Path
+
+__all__ = ["install_hooks", "HOOKS", "MARKER", "runner"]
+
+MARKER = "# >>> taskops >>>"
+
+HOOKS: dict[str, str] = {
+    "post-commit": "ingest commit HEAD",
+    "post-checkout": "ingest branch",
+    "post-merge": "sync",
+}
+"""Why these three, and why nothing else:
+
+- **post-commit** catches every commit, including the ones the PreToolUse guard never saw —
+  a human's terminal commit, a `--no-verify`, a rebase landing on a task branch.
+- **post-checkout** records the branch on the lease, so the board can show where an agent is
+  working without asking it to report that separately.
+- **post-merge** imports what a `git pull` just brought in. That is the moment another
+  developer's events become visible, and the only automatic sync point that matters.
+
+Notably NOT `pre-commit`: refusing a commit is the guard's job, and the guard runs inside
+Claude Code where a refusal reaches the agent as text it can act on. A `pre-commit` refusal
+reaches a human as a failed command with no context, and an agent as an error it will try to
+work around.
+"""
+
+
+def runner() -> str:
+    """The command prefix a hook uses: this interpreter, running the wiring transport.
+
+    Renaming this is the change that breaks in TOTAL silence — every hook line ends in
+    `|| true`, so a module that no longer exists just stops binding commits to cards and
+    nothing anywhere says so. `tests/e2e/test_hook_wiring.py` commits in a real repository and
+    asserts the binding happened; that test is the only thing standing between a rename and a
+    board that quietly loses its commits.
+    """
+    return f"{sys.executable} -m taskops.transports.hooks"
+
+
+def install_hooks(root: Path) -> tuple[list[str], list[str]]:
+    """Install into `.git/hooks`. Returns (installed, skipped-with-reason).
+
+    Skipping rather than raising: this runs inside `init`, and a directory that is not a git
+    repository yet is an ordinary state — `git init` then `taskops init` again is the fix, and
+    the report says so.
+    """
+    hooks_dir = root / ".git" / "hooks"
+    if not hooks_dir.is_dir():
+        return [], [f"{root}/.git/hooks does not exist — not a git repository yet"]
+    installed: list[str] = []
+    skipped: list[str] = []
+    for name, verb in HOOKS.items():
+        problem = _install_one(hooks_dir / name, f"{runner()} {verb} >/dev/null 2>&1 || true")
+        (skipped if problem else installed).append(f"{name}: {problem}" if problem else name)
+    return installed, skipped
+
+
+def _install_one(path: Path, command: str) -> str:
+    """"" on success, else the reason. Appends under the marker if a hook already exists."""
+    try:
+        if path.is_file() and MARKER in path.read_text(encoding="utf-8"):
+            return "" if _refresh(path, command) else "already installed"
+        if path.is_file():
+            _append(path, command)
+        else:
+            path.write_text(f"#!/bin/sh\n{MARKER}\n{command}\n", encoding="utf-8")
+        path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP)
+    except OSError as err:
+        return str(err)
+    return ""
+
+
+def _refresh(path: Path, command: str) -> bool:
+    """Rewrite OUR line when it no longer says what it should. True if anything changed.
+
+    Everything above the marker is the repository's own script and is kept byte for byte;
+    everything below it is ours, and ours is the only part that is allowed to move. Without
+    this, `init` on an already-initialised repository reports "already installed" over a hook
+    line pointing at a module that was renamed — the silent failure this file warns about,
+    reached through the command that is supposed to be the repair.
+    """
+    current = path.read_text(encoding="utf-8")
+    head, _, ours = current.partition(MARKER)
+    if ours.strip() == command:
+        return False
+    path.write_text(f"{head}{MARKER}\n{command}\n", encoding="utf-8")
+    return True
+
+
+def _append(path: Path, command: str) -> None:
+    """Add our line to an existing hook, keeping what was there.
+
+    Appended rather than prepended: the existing script is what the repository's owner put
+    there, and it gets to decide the exit code. Our line cannot fail anyway — it ends in
+    `|| true`.
+    """
+    current = path.read_text(encoding="utf-8").rstrip("\n")
+    path.write_text(f"{current}\n\n{MARKER}\n{command}\n", encoding="utf-8")

taskops/usecases/index.py

@@ -0,0 +1,62 @@
+"""What has been written up — the listing behind the Reports view.
+
+The one read here that does NOT go through `day_report`: this answers "which reports exist",
+which is a question about the directory, not about the log. It reads each file only far enough
+to answer whether it is stale and whether anybody narrated it, and never returns a body.
+
+Today is listed even when its file is missing, because the screen's main verb is generating it
+and a list that shows nothing on a fresh repository would offer nothing to press.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from ..contracts import ReportEntry
+from ..engine import date_of, missing_events, stamped_seq
+from ..render import is_pending
+from ..storage import REPORTS_DIR, Store
+from ._project import project
+from ._range import is_day
+from .dossier import report_path
+
+__all__ = ["report_index"]
+
+
+def report_index(start: Path | str) -> list[ReportEntry]:
+    """Every report on disk, newest first, with today at the top whether or not it exists."""
+    with project(start) as store:
+        today = date_of(now())
+        directory = store.root / REPORTS_DIR
+        found = sorted(directory.glob("*.md"), key=lambda path: path.stem, reverse=True) \
+            if directory.is_dir() else []
+        entries = [_entry(store, path) for path in found]
+        if not any(entry["label"] == today for entry in entries):
+            entries.insert(0, ReportEntry(label=today, path=str(report_path(store.root, today)),
+                                          exists=False, stale=False, missing_events=0,
+                                          has_narration=False, bytes=0))
+        return entries
+
+
+def _entry(store: Store, path: Path) -> ReportEntry:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    behind = _behind(store, path.stem, text)
+    return ReportEntry(label=path.stem, path=str(path), exists=True, stale=behind > 0,
+                       missing_events=behind, has_narration=not is_pending(text),
+                       bytes=len(text.encode("utf-8")))
+
+
+def _behind(store: Store, label: str, text: str) -> int:
+    """Staleness is only meaningful for a SINGLE day.
+
+    `missing_events` counts inside one calendar window, so a report named for a range — or for
+    `all` — has no window to count against. The label is opaque by contract: anything that
+    assumed it parses as a date would raise the first time somebody writes a weekly report.
+    """
+    if not is_day(label):
+        return 0
+    # Both ends are the same date: a day IS the one-day window, which is exactly why the
+    # range work could generalise `missing_events` without this call meaning something else.
+    return missing_events(store, label, label, stamped_seq(text))
+

taskops/usecases/ingest.py

@@ -0,0 +1,60 @@
+"""Recording what git actually did. Called from a `post-commit` hook.
+
+This is the half of git-binding that does not need permission. The guard runs before a
+commit and can refuse; this runs after one and only records — which is why it also
+catches every commit the guard never saw: a human's `git commit` in a terminal, a
+`--no-verify`, a merge, a rebase that rewrote history onto a task branch.
+
+Recording is unconditional and idempotent. A commit whose task cannot be determined is
+skipped rather than attributed to a guess, because a wrong attribution is worse than a
+missing one: the board would show evidence for a task that has none, and the `done`
+guard would let it close.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..contracts import Event
+from ..engine import gitio, record
+from ._project import caller, project
+
+__all__ = ["ingest_commit"]
+
+
+def ingest_commit(start: Path | str, sha: str = "HEAD", *, actor: str = "") -> Event | None:
+    """Bind one commit to its task. None if there is no task to bind it to.
+
+    The task comes from the trailer FIRST and the branch second. That order matters
+    after a rebase: the branch is whatever is checked out now, the trailer is what the
+    author wrote, and when they disagree the author is right.
+    """
+    with project(start) as store:
+        resolved = gitio.head_sha(store.root) if sha == "HEAD" else sha
+        message = gitio.commit_message(store.root, resolved)
+        task = gitio.task_of_message(message) or \
+            gitio.task_of_branch(gitio.current_branch(store.root))
+        if not task or store.tasks.get(task) is None:
+            return None
+        return record(store, task=task, actor=caller(store, actor)["id"],
+                      kind="commit",
+                      body={"sha": resolved, "subject": message.splitlines()[0],
+                            "files": gitio.changed_files(store.root, resolved)})
+
+
+def ingest_branch(start: Path | str, branch: str = "", *, actor: str = "") -> Event | None:
+    """Note that a task's branch exists, and record it on the lease.
+
+    Called from `post-checkout`. The lease carries the branch so the live board can show
+    where an agent is working, and so a later `taskops_ask` can name the branch instead
+    of asking the agent to remember it.
+    """
+    with project(start) as project_store:
+        name = branch or gitio.current_branch(project_store.root)
+        task = gitio.task_of_branch(name)
+        if not task or project_store.tasks.get(task) is None:
+            return None
+        project_store.leases.set_branch(task_id=task, branch=name)
+        return record(project_store, task=task,
+                      actor=caller(project_store, actor)["id"],
+                      kind="branch", body={"branch": name})