taskops-cli 0.2.0__py3-none-any.whl

taskops/engine/_briefs.py

@@ -0,0 +1,92 @@
+"""What a worker is TOLD. Two audiences, two texts, and the difference matters.
+
+A sub-agent of the current session and a spawned process are not the same reader:
+
+- A **sub-agent** shares the parent's working directory, so it has to be told which worktree is its
+  own and told never to switch branches. Nothing else stops it editing `main` — and if two of them
+  did, they would overwrite each other in the one place no lease can protect.
+- A **process** starts in its worktree already, with `$TASKOPS_ROOT` pointing at the shared board, so
+  its brief can be short.
+
+Both end the same way, and that sentence is the most important one in either: an agent that guesses
+when the spec is wrong produces a commit somebody has to read and undo. Told to release instead, it
+hands back everything it learned.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..contracts import Task
+from .scheduler import branch_for
+
+__all__ = ["prompt_for", "brief_for"]
+
+
+def prompt_for(task: Task, actor: str = "") -> str:
+    """What the worker is told. Short on purpose — the SPEC lives in the task.
+
+    It names the claim explicitly (`task=<id>`), because a worker launched for one card must not go
+    shopping in the pool: the card is already assigned to it, and a bare `taskops_next` would hand it
+    whatever sorts first.
+
+    It NAMES the worker's actor id, and that is not cosmetic. A dispatched worker that was not told
+    who it is invents an identity — one called itself `agent:claude/worker` and claimed a card
+    assigned to a different worker, which is exactly the failure `engine.identity` warns about. The
+    id is also in `$TASKOPS_ACTOR`, so this is belt and braces on purpose: the environment is what
+    the tools read, and the prompt is what stops the model from overriding it with an argument.
+
+    The last sentence is the important one. A background agent that guesses when the spec is wrong
+    produces work nobody asked for and a commit somebody has to read; told to release instead, it
+    leaves the next agent everything it learned.
+    """
+    return (f"You are taskops worker `{actor}`. Do NOT use any other actor id — it is already "
+            f"set in your environment, so never pass `actor` to a taskops tool. "
+            f"Read .taskops/GUIDE.md, then run "
+            f"`taskops_next task={task['id']}` to claim your task and read its spec. "
+            f"Do the work, commit it on the branch the claim names, then close the task with "
+            f"`taskops_update task={task['id']} status=done` and a comment saying what you did. "
+            f"If you get stuck or the spec is wrong, do NOT guess: use "
+            f"`taskops_update status=released` with a comment explaining where you got to.")
+
+
+def brief_for(root: Path, task: Task, actor: str, tree: Path) -> str:
+    """The prompt for a SUB-AGENT of the current session. What `dispatch` hands back.
+
+    Different from `prompt_for` in the two ways that matter for a sub-agent rather than a process:
+
+    - It names the WORKTREE PATH and says to work there. A sub-agent shares the parent's working
+      directory, so nothing stops it editing `main` unless told otherwise — and if two of them did,
+      they would overwrite each other in the one place no lease can protect.
+    - It says never to `git switch`. The worktree is ALREADY on the card's branch; switching in the
+      shared checkout would move the branch under every other agent at once, which is the failure
+      that makes people conclude parallel agents cannot work on separate branches.
+
+    `$TASKOPS_ROOT` is not needed here: a sub-agent inherits the session's environment and the
+    project resolves by walking up from the worktree, which is inside the repository.
+    """
+    return (
+        f"You are taskops worker `{actor}` on card {task['id']}: {task['title']}\n\n"
+        f"YOUR WORKTREE: {tree}\n"
+        f"Work ONLY inside that directory. It is already checked out on branch "
+        f"`{branch_for(task)}` — never run `git switch`/`git checkout <branch>`, because other "
+        f"workers share this repository and switching would move their branch too.\n\n"
+        f"Steps:\n"
+        f"1. `taskops_next repo_path={root} task={task['id']} actor={actor}` — claims it and "
+        f"prints the full spec plus a warning if another worker touches your files.\n"
+        f"2. Do the work in {tree}. To RE-READ your card at any point — the spec, the thread, the "
+        f"commits, and which other workers touch your files — call "
+        f"`taskops_ask repo_path={root} task={task['id']}`. That one is read-only and safe to call as "
+        f"often as you like, unlike step 1 which claims. Read .taskops/GUIDE.md if anything about the "
+        f"process is unclear.\n"
+        f"3. Commit inside your worktree: `git -C {tree} add -A && git -C {tree} commit -m '...' "
+        f"-m 'Task: {task['id']}'`. The trailer is what binds the commit to the card.\n"
+        f"4. `taskops_update repo_path={root} task={task['id']} actor={actor} status=done "
+        f"comment='<what you did>'`.\n\n"
+        f"If you get stuck or the spec is wrong, do NOT guess: "
+        f"`taskops_update repo_path={root} task={task['id']} actor={actor} status=released "
+        f"comment='<where you got to and what blocked you>'`. That returns the card with everything "
+        f"you learned, which is worth far more than a wrong commit."
+    )
+
+

taskops/engine/_chunks.py

@@ -0,0 +1,66 @@
+"""Cutting a long dossier into slices a single reading can actually cover.
+
+A full-detail dossier for a whole project is not three paragraphs of facts: it is every card's
+spec, every comment, every file of every commit. Handed to one call it fits in the window long
+before it fits in the attention — the answer stops enumerating and starts summarising, which
+is precisely the failure this card exists to fix.
+
+So past a threshold the dossier is read in slices and the parts are stitched. The alternative
+somebody always reaches for — trimming the prompt to fit — is banned outright: a report that
+silently omits the last nine cards is worse than one that took three calls to write.
+
+Pure: given a string it returns strings. The model lives in `narrate`.
+"""
+
+from __future__ import annotations
+
+__all__ = ["CHUNK_CHARS", "slices"]
+
+CHUNK_CHARS = 60_000
+"""Roughly 15k tokens of dossier per reading.
+
+Not a context limit — the window is far larger. It is an ATTENTION budget, measured against
+what the prompt asks for: a paragraph per card, naming that card's spec, files and comments.
+Past this much input a single answer reliably starts collapsing cards into sentences, and the
+narration silently becomes the summary it was supposed to replace. Lower, and a project pays
+for stitching it does not need.
+"""
+
+_BOUNDARIES = ("### ", "✓ **")
+"""Where a slice may be cut: a day heading in a range report, or a card block. Never mid-card —
+half a card's commits under one reading and half under another produces two partial paragraphs
+about the same work, and the stitch has no way to know they are the same card.
+"""
+
+
+def slices(dossier: str, limit: int = CHUNK_CHARS) -> list[str]:
+    """The dossier as one string, or as several that each start with its title line.
+
+    The header — everything above the first card — rides along on EVERY slice, because it
+    carries the window, the counts and the language the narration must be written in.
+    """
+    if len(dossier) <= limit:
+        return [dossier]
+    head, blocks = _split(dossier)
+    out: list[str] = []
+    current = ""
+    for block in blocks:
+        if current and len(current) + len(block) > limit:
+            out.append(head + current)
+            current = ""
+        current += block
+    return [*out, head + current] if current else out or [dossier]
+
+
+def _split(dossier: str) -> tuple[str, list[str]]:
+    """`(header, blocks)`, where a block starts at a boundary line and runs to the next one."""
+    head: list[str] = []
+    blocks: list[list[str]] = []
+    for line in dossier.splitlines(keepends=True):
+        if line.startswith(_BOUNDARIES):
+            blocks.append([line])
+        elif blocks:
+            blocks[-1].append(line)
+        else:
+            head.append(line)
+    return "".join(head), ["".join(block) for block in blocks]

taskops/engine/_closed.py

@@ -0,0 +1,65 @@
+"""The cards that reached `done`, assembled with their commits and their sizes.
+
+Split from `day` because it is the expensive half: every closed card needs its whole history
+read back, and all of their commits need git. Keeping it here is what lets `day` stay a
+description of the window rather than a description of a card.
+
+The batching is the point. One `numstats` call covers every commit of every card closed that
+day, so a report of twenty cards is one subprocess — not one per card, which is how a daily
+report turns into a spinning terminal on a busy project.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from ..contracts import ClosedCard, CommitStat, Event, Task
+from ..storage import Store
+from .diffstat import numstats
+
+__all__ = ["closed_cards"]
+
+
+def closed_cards(store: Store, dones: list[Event]) -> list[ClosedCard]:
+    """One card per `done` event, oldest close first. Cards this clone does not have are
+    dropped — an event can name a task that is still in a teammate's log."""
+    histories = {done["task"]: store.events.of_task(done["task"]) for done in dones}
+    stats = numstats(store.root, [str(event["body"].get("sha", ""))
+                                  for history in histories.values() for event in history
+                                  if event["kind"] == "commit"])
+    out: list[ClosedCard] = []
+    for done in dones:
+        task = store.tasks.get(done["task"])
+        if task is not None:
+            out.append(_card(task, done, histories[done["task"]], stats))
+    return out
+
+
+def _card(task: Task, done: Event, history: list[Event],
+          stats: dict[str, tuple[int, int]]) -> ClosedCard:
+    """`claimed_ts` is the LAST claim before the close, not the first.
+
+    A card released once and picked up again by somebody else was not being worked on in
+    between, and measuring from the first claim would report a two-hour task as two days.
+    """
+    claims = [e["ts"] for e in history
+              if e["kind"] == "claimed" and e["ts"] <= done["ts"]]
+    return ClosedCard(task=task, actor=done["actor"], done_ts=done["ts"],
+                      claimed_ts=max(claims) if claims else done["ts"],
+                      commits=[_stat(e, stats) for e in history if e["kind"] == "commit"])
+
+
+def _stat(event: Event, stats: dict[str, tuple[int, int]]) -> CommitStat:
+    """A `commit` event plus what git says it weighed.
+
+    Coerced field by field, like `usecases.view._commit`: the body is an open dict written by
+    whatever taskops version ingested it, and a newer one may not have said `files` at all.
+    """
+    body = event["body"]
+    raw: object = body.get("files")
+    files = cast("list[object]", raw) if isinstance(raw, list) else []
+    sha = str(body.get("sha", ""))
+    adds, dels = stats.get(sha, (0, 0))
+    return CommitStat(sha=sha, subject=str(body.get("subject", "")),
+                      files=[str(path) for path in files], actor=event["actor"],
+                      ts=event["ts"], additions=adds, deletions=dels)

taskops/engine/_entries.py

@@ -0,0 +1,126 @@
+"""One raw transcript entry -> one flat `LogEntry`. The shape-flattening, on its own.
+
+The raw format nests differently per role: an assistant entry holds `message.content`, a LIST of blocks
+each with its own type (`thinking`, `text`, `tool_use`), while a user entry's content may be a plain
+string or a list containing `tool_result`. A reader wants one flat stream in time order, so one raw
+entry can produce several `LogEntry`s.
+
+Split from `transcript` because that module answers "where is the file" and this one answers "what does
+a line mean" — and the second is the half that will need editing when the format moves.
+
+Nothing is dropped. An entry this version does not recognise becomes `other` with whatever text can be
+salvaged, because the format is not documented as stable and a silently shorter conversation is worse
+than an odd-looking line.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from ..contracts import LogEntry
+from ._blocks import result_text, summarise
+from .transcript import clip
+
+__all__ = ["flatten"]
+
+_SKIP = frozenset({"mode", "permission-mode", "ai-title", "last-prompt", "queue-operation",
+                   "file-history-snapshot", "file-history-delta", "attachment"})
+"""Entry types that are Claude Code's own bookkeeping, not conversation.
+
+Verified against a real 1018-line transcript, where these were a third of it: mode switches, the
+generated title, snapshots of files for undo. Keeping them would bury the twenty entries a person
+actually wants to read.
+"""
+
+
+def flatten(entry: dict[str, Any]) -> list[LogEntry]:
+    """Zero, one, or several readable entries from one raw line."""
+    kind = str(entry.get("type", ""))
+    if kind in _SKIP:
+        return []
+    session = str(entry.get("sessionId") or entry.get("session_id") or "")
+    ts = _time(entry)
+    message = entry.get("message")
+    if not isinstance(message, dict):
+        return _fallback(entry, session, ts)
+    return _from_message(cast("dict[str, Any]", message), kind, session, ts)
+
+
+def _from_message(message: dict[str, Any], kind: str, session: str,
+                  ts: float) -> list[LogEntry]:
+    content = message.get("content")
+    if isinstance(content, str):
+        return _entry("prompt" if kind == "user" else "text", content, "", ts, session)
+    if not isinstance(content, list):
+        return []
+    out: list[LogEntry] = []
+    for block in cast("list[object]", content):
+        if isinstance(block, dict):
+            out += _from_block(cast("dict[str, Any]", block), kind, session, ts)
+    return out
+
+
+def _from_block(block: dict[str, Any], kind: str, session: str,
+                ts: float) -> list[LogEntry]:
+    """One content block. The four shapes that actually occur, plus a catch-all."""
+    shape = str(block.get("type", ""))
+    if shape == "thinking":
+        return _entry("thinking", str(block.get("thinking", "")), "", ts, session)
+    if shape == "text":
+        return _entry("prompt" if kind == "user" else "text",
+                      str(block.get("text", "")), "", ts, session)
+    if shape == "tool_use":
+        name = str(block.get("name", "?"))
+        return _entry("tool", summarise(name, block.get("input")), name, ts, session)
+    if shape == "tool_result":
+        return _entry("result", result_text(block.get("content")), "", ts, session)
+    return _entry("other", shape, "", ts, session) if shape else []
+
+
+def _fallback(entry: dict[str, Any], session: str, ts: float) -> list[LogEntry]:
+    """An entry with no `message`: system notices and anything new.
+
+    Kept rather than dropped, because the alternative is a conversation that is quietly missing the
+    line that explained why it stopped.
+    """
+    for key in ("content", "text", "summary"):
+        found = entry.get(key)
+        if isinstance(found, str) and found.strip():
+            return _entry("other", found, "", ts, session)
+    return []
+
+
+def _entry(kind: str, text: str, tool: str, ts: float,
+           session: str) -> list[LogEntry]:
+    """One entry, or NONE when there is nothing to show.
+
+    Empty content is dropped, and `thinking` is why. Extended thinking is REDACTED in the transcript —
+    the block keeps its `signature` and its `thinking` field is the empty string — so rendering it
+    produced a blank `· thinking` line before every single assistant turn. That is not a formatting
+    nit: it doubled the length of the log with rows that say nothing, and it looked like taskops had
+    failed to read something rather than like there being nothing to read.
+
+    A `tool` entry survives an empty text, because the tool NAME is the content there.
+    """
+    body = clip(text)
+    if not body and kind != "tool":
+        return []
+    return [LogEntry(kind=kind,               # type: ignore[typeddict-item]
+                     text=body, tool=tool, ts=ts, session=session)]
+
+
+def _time(entry: dict[str, Any]) -> float:
+    """The entry's timestamp as epoch seconds, or 0.
+
+    The transcript writes ISO 8601; the rest of taskops uses epoch floats, so converting here keeps
+    every consumer on one clock.
+    """
+    from datetime import datetime
+
+    raw = entry.get("timestamp")
+    if not isinstance(raw, str):
+        return 0.0
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return 0.0

taskops/engine/_events.py

@@ -0,0 +1,55 @@
+"""The `stream-json` wire format, read. Pure: a line in, a fragment out, no process in sight.
+
+Split from `_stream` so the shape of the CLI's events can be tested from string literals, which
+is the only way to pin the one trap in them.
+
+Every stdout line of `claude --output-format stream-json --include-partial-messages` is one JSON
+object. Visible text arrives as
+`{"type": "stream_event", "event": {"delta": {"type": "text_delta", "text": "…"}}}` — but the
+THINKING deltas arrive FIRST and carry `"text": None`, so a reader that takes `delta["text"]`
+because the key is there yields `None` and crashes on the first join. Filter on the delta's TYPE.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from .._errors import NarrationFailed
+
+__all__ = ["parsed", "text_delta", "check_result"]
+
+
+def parsed(line: str) -> dict[str, Any]:
+    """One stdout line as an object, or `{}`.
+
+    A line that is not JSON is skipped rather than fatal: the CLI prints the odd warning on
+    stdout, and throwing away a finished narration over one of them would be absurd.
+    """
+    try:
+        loaded: object = json.loads(line)
+    except json.JSONDecodeError:
+        return {}
+    return cast("dict[str, Any]", loaded) if isinstance(loaded, dict) else {}
+
+
+def text_delta(event: dict[str, Any]) -> str:
+    """The visible text of a partial message, or "" for anything else — including a thinking
+    delta, whose `text` is `None` and which always arrives first."""
+    if event.get("type") != "stream_event":
+        return ""
+    inner: dict[str, Any] = event.get("event") or {}
+    delta: dict[str, Any] = inner.get("delta") or {}
+    return str(delta.get("text") or "") if delta.get("type") == "text_delta" else ""
+
+
+def check_result(event: dict[str, Any]) -> None:
+    """The `result` event ends the answer, and may end it because it failed.
+
+    A usage limit, a refused flag and a model that does not exist all arrive here with a zero
+    exit code, so a caller that only looked at the exit status would write an empty narration
+    into the report and call it done.
+    """
+    if event.get("is_error"):
+        detail = str(event.get("result") or event.get("subtype") or "no reason given")
+        raise NarrationFailed(f"claude ended the narration: {detail}")

taskops/engine/_opened.py

@@ -0,0 +1,51 @@
+"""The cards a window OPENED — planned work, with the edges that say what can start.
+
+Split from `day` for the same reason `_closed` is: assembling a card needs the graph, and the
+module that describes a window should not also know how the `deps` table is read from both
+ends.
+
+This exists because a freshly planned project reported nothing at all. `in_flight` covers
+`claimed`/`in_progress`/`review` and `blocked` covers `blocked`, so `backlog` and `ready` —
+which is ALL planned-but-unstarted work — belonged to no section, and a day spent writing four
+specs rendered as `0 closed · 0 in flight · 0 blocked` over three empty headings. The same
+class of bug as a finished project answering `tasks list` with silence: a filter that describes
+some states, and everything else falling through it.
+"""
+
+from __future__ import annotations
+
+from .._types import CLOSED_STATUSES
+from ..contracts import Event, OpenedCard, Task
+from ..storage import Store
+
+__all__ = ["opened_cards", "waiting_tasks"]
+
+
+def opened_cards(store: Store, events: list[Event]) -> list[OpenedCard]:
+    """One card per `created` event in the window, oldest first, still open.
+
+    Created AND closed inside the window means `closed` already tells the whole story with its
+    commits and its conversation; listing it here too would invite a reader to count it twice.
+    A card this clone does not have is dropped, like everywhere else — an event can name a task
+    that still lives in a teammate's log.
+    """
+    out: list[OpenedCard] = []
+    for event in events:
+        task = store.tasks.get(event["task"]) if event["kind"] == "created" else None
+        if task is not None and task["status"] not in CLOSED_STATUSES:
+            out.append(OpenedCard(task=task,
+                                  waiting_on=store.deps.open_blockers_of(task["id"]),
+                                  blocking=store.deps.dependents_of(task["id"])))
+    return out
+
+
+def waiting_tasks(touched: list[Task], opened: list[OpenedCard]) -> list[Task]:
+    """Open cards nobody has started — minus the ones this window created.
+
+    Those are in `opened`, where they carry their dependencies as well, and a card printed in
+    both sections reads as two cards to anybody scanning. So every open card the window touched
+    appears exactly once, and which section it is in says whether it is new.
+    """
+    new = {card["task"]["id"] for card in opened}
+    return [t for t in touched
+            if t["status"] in ("ready", "backlog") and t["id"] not in new]

taskops/engine/_process.py

@@ -0,0 +1,80 @@
+"""Running a detached process in a git worktree. The mechanics, not the policy.
+
+Split from `worker` by what a reader needs to know: that module decides WHAT to launch and what to
+tell it, this one knows how to get a process running somewhere it cannot damage anybody else.
+
+Two decisions carry it:
+
+**A worktree per worker.** Parallel agents editing one working tree overwrite each other, and no
+amount of lease bookkeeping fixes that — a lease coordinates who owns a TASK, not whose bytes are on
+disk. `git worktree` gives each worker its own directory on its own branch, and they merge through
+git like any two developers.
+
+**Detached, output to a file.** A dispatched worker outlives the call that launched it, so it is
+started in its own session and its stdout goes to a file. Not a pipe: nobody is reading it, and a
+full pipe buffer deadlocks the child.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+__all__ = ["make_worktree", "spawn"]
+
+
+def make_worktree(root: Path, tree: Path, branch: str) -> bool:
+    """Create the worktree; True if it is usable. Reuses the branch when it already exists.
+
+    Two `git worktree add` forms, because the branch may or may not exist yet: `-b` creates it, and
+    plain `add` attaches to one an earlier dispatch already made. Trying `-b` on an existing branch
+    fails, which would strand a re-dispatched task in the main checkout beside its siblings.
+    """
+    tree.parent.mkdir(parents=True, exist_ok=True)
+    if tree.is_dir():
+        return True
+    if _git(root, "worktree", "add", "-b", branch, str(tree)):
+        return True
+    return _git(root, "worktree", "add", str(tree), branch)
+
+
+def spawn(command: list[str], *, cwd: Path, log: Path, env: dict[str, str],
+          drop: tuple[str, ...] = ()) -> int:
+    """Start a detached process, output to `log`. Returns its pid, or 0 if it could not start.
+
+    `start_new_session` puts it in its own process group, so a ctrl-C in the terminal that ran
+    dispatch does not kill the workers it launched — they are meant to outlive it.
+
+    The environment is INHERITED and then extended, because a worker needs the developer's PATH and
+    credentials to run `claude` at all. `drop` is the other direction, and merging alone cannot
+    express it: a key set to `""` is still a key the child sees, so the names in `drop` are POPPED
+    from the merged copy and reach the child as genuinely unset. WHICH names is policy, and policy
+    lives in `worker`.
+    """
+    log.parent.mkdir(parents=True, exist_ok=True)
+    child = {**os.environ, **env}
+    for name in drop:
+        child.pop(name, None)
+    try:
+        with log.open("wb") as sink:
+            process = subprocess.Popen(command, cwd=cwd, stdout=sink,
+                                       stderr=subprocess.STDOUT,
+                                       stdin=subprocess.DEVNULL,
+                                       start_new_session=True,
+                                       env=child)
+        return process.pid
+    except OSError:
+        # 0 rather than raising: dispatching five workers where one fails to start should report
+        # four running and one that did not, never lose the four.
+        return 0
+
+
+def _git(root: Path, *args: str) -> bool:
+    """True if the command succeeded. Never raises, like everything that shells out to git here."""
+    try:
+        done = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True,
+                              timeout=30, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return done.returncode == 0

taskops/engine/_prompts.py

@@ -0,0 +1,98 @@
+"""What the model is asked for. Prose, kept out of `narrate` so the mechanism stays readable.
+
+The whole design of these three strings is one instruction: the narration is the DURABLE
+RECORD, not a summary of it. Somebody who reads this instead of the git log has to come away
+knowing what was asked, what was delivered, what was decided, and what is still owed. So the
+prompt demands a paragraph per card and says out loud that length is not the problem —
+because a model left to its own judgement writes three tidy paragraphs about twenty cards,
+which is exactly the report this replaces.
+
+"Invent NOTHING" survives from the first version and is the one rule that outranks the rest:
+an exhaustive report that is partly fiction is worse than a short true one.
+"""
+
+from __future__ import annotations
+
+__all__ = ["PROMPT", "CHUNK_PROMPT", "STITCH_PROMPT"]
+
+_RULES = """Rules:
+- EVERY closed card gets its own paragraph. Do not group cards together to save room, and do
+  not drop a card because it looks small. If the dossier lists 24 cards, 24 cards are covered.
+- Each card's paragraph says, in this order: what was ASKED (its **Pedido** block), what was
+  actually DELIVERED (the commits, the files they touched, the diff size), what was DECIDED or
+  DISCOVERED along the way (its comments — quote the phrase that matters), and what it cost
+  (how long it was held, how many commits, how big the diff).
+- Where the delivery does not match the ask — something asked for and not visible in the
+  commits, or something shipped that nobody asked for — SAY SO. That gap is the single most
+  valuable line this report can contain.
+- Name the decisions and the surprises: the thing a reader would not guess from the titles.
+- LENGTH IS NOT A PROBLEM. OMISSION IS. This document is read INSTEAD of the git log.
+- Invent NOTHING. Every claim must trace to a line in the dossier. If the dossier is silent
+  about something, the narration is silent about it too — do not fill a gap with a guess.
+- Do not flatter anybody and do not editorialise about pace.
+- Markdown. Use `###` for sub-headings; no top-level heading (the section already has one).
+"""
+
+_STRUCTURE = """Structure it in four parts, in this order:
+1. **Lo que necesita un humano** — anything blocked, anything still claimed, anything that
+   looks wrong (a card closed minutes after being claimed with no commits, a spec whose
+   delivery you cannot find). If there is nothing, one line saying so.
+2. **Por área** — one `###` section per area of the codebase the work touched (infer the areas
+   from the file paths in the commits, not from card ids), and inside it the paragraph per card.
+3. **Decisiones y sorpresas** — what was decided, what was discovered, what was reversed.
+4. **Lo que queda abierto** — what is still owed: unfinished cards, follow-ups named in a
+   comment, debts somebody wrote down and nobody closed.
+"""
+
+PROMPT = ("""You are writing the narration of an engineering report. It is the durable record of
+what was done — somebody reads it a month from now INSTEAD of the git log, and it has to leave
+them knowing what happened.
+
+Below is the dossier: what closed, each card's spec, its commits with their files and diff
+sizes, the whole conversation, and a roll-up per actor. It was generated from an append-only
+event log, so every fact in it is true.
+
+Write the narration in the SAME LANGUAGE the cards and comments are written in.
+
+"""
+          + _STRUCTURE + "\n" + _RULES + """
+Output ONLY the narration text.
+
+--- DOSSIER ---
+""")
+
+CHUNK_PROMPT = ("""You are writing PART of the narration of an engineering report. The dossier was
+too long for one reading, so you are given one slice of it; another pass will stitch the parts
+together. Cover YOUR slice completely and say nothing about what is not in it.
+
+Write in the SAME LANGUAGE the cards and comments are written in.
+
+"""
+                + _RULES + """
+Do not write an introduction, a conclusion, or a "lo que queda abierto" section — this is a
+middle of a document. Start straight at the `###` sections.
+
+Output ONLY the narration text for this slice.
+
+--- DOSSIER SLICE ---
+""")
+
+STITCH_PROMPT = ("""Below are the parts of one engineering report's narration, written from
+consecutive slices of the same dossier, in order.
+
+Assemble them into ONE document with the structure below. KEEP EVERY CARD PARAGRAPH — merge the
+`###` sections that describe the same area of the codebase, reorder them, and rewrite the
+connecting sentences, but do not delete, shorten or summarise a card's paragraph. Dropping a
+card here would defeat the reason the dossier was read in slices at all.
+
+Add the parts a slice could not write: the opening "lo que necesita un humano", and the closing
+"lo que queda abierto". Both must come from what the parts actually say — invent nothing.
+
+"""
+                 + _STRUCTURE + """
+Write in the SAME LANGUAGE the parts are written in. Markdown, no top-level heading.
+
+Output ONLY the assembled narration.
+
+--- PARTS ---
+""")