taskops-cli 0.2.0__py3-none-any.whl

taskops/render/_verbatim.py

@@ -0,0 +1,65 @@
+"""The two blocks a WRITTEN report carries verbatim: the card's spec, and every word said on it.
+
+Split from `_dossier` because it owns one idea — text that is quoted whole rather than
+summarised — and because the density switch lives here rather than in four `if` statements
+spread across the renderer.
+
+Why verbatim at all: a report is meant to be read INSTEAD of the git log, and a diff cannot
+say what was ASKED or what was DECIDED. The spec is the ask, the comments are the reasoning,
+and both are lost the moment they are truncated to one line. The terminal keeps the short
+form — nobody wants a screen of quoted essays — so the same projection is printed at two
+densities and never forked into two renderers.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from ..contracts import Event, Task
+from ._text import truncate
+
+__all__ = ["Detail", "spec_block", "said_block"]
+
+Detail = Literal["brief", "full"]
+"""How much of the text survives. `brief` is the terminal, `full` is the file on disk."""
+
+
+def spec_block(task: Task, detail: Detail) -> list[str]:
+    """What was ASKED, quoted whole — `full` only.
+
+    Without it the narration can only describe what was delivered, and "delivered" with
+    nothing to compare it against is a changelog, not a report. Quoted with `>` so a spec
+    that is itself markdown cannot inject headings into the dossier's own outline.
+    """
+    spec = task["spec"].strip()
+    if detail == "brief" or not spec:
+        return []
+    return ["", "  **Pedido**", "", *_quote(spec)]
+
+
+def said_block(mine: list[Event], detail: Detail) -> list[str]:
+    """The conversation on one card.
+
+    `brief`: a count and the last line, which is the hand-off note. `full`: every comment
+    in order, attributed, whole — that is where the reasoning and the surprises live, and a
+    report that drops all but the last one cannot say why anything was done.
+    """
+    if not mine:
+        return []
+    if detail == "brief":
+        text = str(mine[-1]["body"].get("text", ""))
+        return [f"  {len(mine)} comment(s) · last: {truncate(text, 120)}"]
+    out = ["", f"  **{len(mine)} comment(s)**"]
+    for event in mine:
+        out += ["", f"  **{event['actor']}**:", "", *_quote(str(event["body"].get("text", "")))]
+    return out
+
+
+def _quote(text: str) -> list[str]:
+    """Every line of `text` as an indented blockquote, blank lines included.
+
+    Blank lines carry the `>` too: a markdown blockquote broken by a bare empty line becomes
+    two quotes with a paragraph between them, and a multi-paragraph spec would stop reading
+    as one quoted thing.
+    """
+    return [f"  > {line}".rstrip() for line in text.strip().splitlines()]

taskops/render/ansi.py

@@ -0,0 +1,92 @@
+"""Markdown for a terminal, rendered as it arrives. taskops' first ansi vocabulary.
+
+A narration is streamed a delta at a time, and a delta is not a line: it splits words, and it
+splits `**bo` from `ld**`. So nothing may be styled until the line it belongs to is COMPLETE —
+`Ink.feed` buffers fragments and hands back only the lines that have ended. Anything else
+produces a `**` that never closes and an escape sequence in the middle of a word.
+
+Pure, like everything in `render/`: fragments in, rendered lines out. Nothing here prints, opens
+a file, or asks whether it is talking to a terminal — the transport that owns stdout decides
+that and passes the answer in. With `colour=False` a line comes back byte for byte as it went
+in, which is exactly what the digest used to emit, so the plain path costs nothing and a
+redirected `--digest` is unchanged.
+
+ANSI never reaches the FILE. The report on disk is written from the joined text, not from this.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ._text import STATUS_MARK
+
+__all__ = ["Ink", "BULLET"]
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+TITLE = "\033[1;4m"
+"""Bold + underline, for `#` only. A narration's one top-level heading is the report's own
+title; every deeper level is a section inside it and gets plain bold."""
+CODE = "\033[36m"
+
+BULLET = STATUS_MARK["backlog"]
+"""The glyph a `- ` becomes. Borrowed from the board's register rather than chosen here: two
+vocabularies for "a small thing in a list" is how a terminal ends up with `•` in one command
+and `·` in the next, and the reader learns neither."""
+
+_HEADING = re.compile(r"^(#{1,6})\s+(.*)$")
+_BOLD = re.compile(r"\*\*(.+?)\*\*")
+_CODE = re.compile(r"`([^`]+)`")
+_BULLET = re.compile(r"^(\s*)[-*]\s+")
+
+
+class Ink:
+    """A stream of markdown fragments, turned into finished terminal lines."""
+
+    def __init__(self, *, colour: bool) -> None:
+        self._colour = colour
+        self._held = ""
+        self._fenced = False
+
+    def feed(self, fragment: str) -> list[str]:
+        """The lines COMPLETED by this fragment. Usually none — deltas are smaller than lines."""
+        self._held += fragment
+        if "\n" not in self._held:
+            return []
+        *done, self._held = self._held.split("\n")
+        return [self._paint(line) for line in done]
+
+    def flush(self) -> list[str]:
+        """Whatever is left when the narration ends — a last line with no trailing newline is
+        still a line, and dropping it loses the final sentence."""
+        rest, self._held = self._held, ""
+        return [self._paint(rest)] if rest else []
+
+    def _paint(self, line: str) -> str:
+        """One whole line, styled. Verbatim when colour is off or a fence is open.
+
+        The fence toggles on its own line and suppresses everything inside it: `**` in a shell
+        snippet is a glob, and a `#` is a comment, not a heading.
+        """
+        if line.lstrip().startswith("```"):
+            self._fenced = not self._fenced
+            return line
+        if not self._colour or self._fenced:
+            return line
+        head = _HEADING.match(line)
+        if head:
+            # No inline pass over a heading: an inner RESET would end the heading's own style
+            # halfway through it, and the rest of the title would come out plain.
+            mark = TITLE if len(head.group(1)) == 1 else BOLD
+            return f"{mark}{head.group(2)}{RESET}"
+        return _spans(_BULLET.sub(rf"\1{BULLET} ", line))
+
+
+def _spans(text: str) -> str:
+    """Inline styling, applied only WITHIN a finished line.
+
+    Never across the buffer: a `**` whose partner is in the next fragment is not emphasis yet,
+    and treating it as one emits an opening escape that nothing ever closes.
+    """
+    text = _CODE.sub(rf"{CODE}\1{RESET}", text)
+    return _BOLD.sub(rf"{BOLD}\1{RESET}", text)

taskops/render/board.py

@@ -0,0 +1,55 @@
+"""The board as text — the state of the work, column by column.
+
+Read by BOTH a human in a terminal and a model in a context window, which settles most
+of the formatting questions: no colour, no box drawing, one glyph per status, counts
+rather than bars. What an ACTION returns lives in `results`; the time-window reports live
+in `reports`.
+"""
+
+from __future__ import annotations
+
+from ..contracts import Board
+from ._text import STATUS_MARK, table, truncate
+
+__all__ = ["render_board"]
+
+
+def render_board(board: Board) -> str:
+    """EVERY column, always, with a line where one is empty.
+
+    Hiding empty columns was the first version, on the theory that four of eight are usually empty and
+    showing them is noise. It reads as a bug instead: a reader who cannot see a `done` column cannot
+    tell whether nothing is finished or whether the board has no such state — and "where are my done
+    cards" is the question it produced. An empty column that says it is empty answers that in place.
+    """
+    parts = [f"# board — {board['total']} task(s), {board['ready']} ready", ""]
+    for column in board["columns"]:
+        parts += [f"## {STATUS_MARK.get(column['status'], '?')} {column['status']} "
+                  f"({len(column['cards'])})", ""]
+        if not column["cards"]:
+            parts += ["_none_", ""]
+            continue
+        rows = [[card["task"]["id"], truncate(card["task"]["title"], 46),
+                 str(card["task"]["priority"]),
+                 card["lease"]["actor"] if card["lease"] else "—",
+                 _counts(card["blocked_by"], card["blocks"], card["commits"])]
+                for card in column["cards"]]
+        parts += [table(["id", "title", "pri", "who", "deps/commits"], rows), ""]
+    return "\n".join(parts)
+
+
+def _counts(blocked_by: int, blocks: int, commits: int) -> str:
+    """`↑2 ↓1 ◆3` — waiting on, blocking, commits. "—" when there is nothing.
+
+    Three zeroes read as data a reader has to parse; one dash reads as "nothing to see",
+    which is what it means. The arrows are directional so the two dependency counts cannot
+    be mistaken for each other, which numbers alone always are.
+    """
+    bits: list[str] = []
+    if blocked_by:
+        bits.append(f"↑{blocked_by}")
+    if blocks:
+        bits.append(f"↓{blocks}")
+    if commits:
+        bits.append(f"◆{commits}")
+    return " ".join(bits) if bits else "—"

taskops/render/day.py

@@ -0,0 +1,102 @@
+"""The dossier as markdown: what closed, what was planned, what is still moving, what was said.
+
+Ordered by what a person reads first at the end of a day — the finished work, then the work
+that was planned, then the work that is neither, then the conversation, then who did it. A
+reader who stops after the first section has still got the answer to "what shipped", which is
+usually the question — and on a day that shipped nothing, `## Abierto` is right underneath.
+
+EVERY open card lands in exactly one section. `in_flight` and `blocked` used to be the only
+ones drawn, so `ready` and `backlog` — all planned-but-unstarted work — were rendered nowhere
+and a freshly planned project reported that nothing had happened at all.
+
+ONE function for a day and for a month. A wider window changes exactly two things — the title
+is a label rather than a date, and the closed cards get a heading per day — and nothing else,
+so a range report is the report somebody already knows how to read.
+
+Pure like every renderer here: this is reproducible from a literal dict, with no database and
+no git in sight.
+"""
+
+from __future__ import annotations
+
+from ..contracts import Event, PeriodReport
+from ._closed_days import closed_section
+from ._opened import moving_section, opened_section
+from ._text import table, truncate
+from ._verbatim import Detail
+
+__all__ = ["render_day"]
+
+TALK_LINE = 160
+"""Characters of a comment the TERMINAL prints. `full` prints all of it — the conversation is
+where the reasoning is, and 160 characters of it is a hint that something was said."""
+
+
+def render_day(day: PeriodReport, detail: Detail = "brief") -> str:
+    """The whole window. A window with nothing in any section says so in one line rather than
+    printing empty headings — a report made of section titles reads as broken, not as quiet.
+
+    Emptiness is judged on the SECTIONS, not on `actors`. It was judged on actors, and that is
+    precisely how the silent-planning-day bug hid: four cards created means one actor with four
+    tasks, so the report was not "empty", it just had no section that could hold a `ready` card
+    and printed three headings with nothing under them. A report that draws nothing must say
+    nothing happened; a report that has something to draw must draw it.
+    """
+    body = (closed_section(day, detail) + opened_section(day, detail) + moving_section(day)
+            + _talk(day, detail))
+    if not _anything(day):
+        quiet = ("on this day" if day["from_date"] == day["to_date"]
+                 else "in this window")
+        return f"# {day['label']}\n\nNothing happened {quiet}."
+    return "\n".join([_headline(day), ""] + body + _actors(day))
+
+
+def _anything(day: PeriodReport) -> bool:
+    """Whether the window holds a single fact worth a heading.
+
+    `dropped` counts: a window that closed more cards than the cap renders has plenty to say,
+    and answering it with "nothing happened" would be the loudest possible lie.
+    """
+    return bool(day["closed"] or day["opened"] or day["in_flight"] or day["blocked"]
+                or day["waiting"] or day["conversations"] or day["commits_total"]
+                or day["dropped"])
+
+
+def _headline(day: PeriodReport) -> str:
+    """The counts, with `opened` and `waiting` shown only when they are not zero.
+
+    Conditional and not unconditional: those two numbers exist to stop the summary line
+    claiming a planning day was empty, and a window that opened nothing does not need to be
+    told so — while every dossier ever committed keeps the header it was written with.
+    """
+    counts = [f"{len(day['closed'])} closed", f"{len(day['opened'])} opened",
+              f"{len(day['in_flight'])} in flight", f"{len(day['blocked'])} blocked",
+              f"{len(day['waiting'])} waiting", f"{day['commits_total']} commit(s)",
+              f"{len(day['actors'])} actor(s)"]
+    drop = {f"0 {name}" for name in ("opened", "waiting")}
+    return f"# {day['label']} — " + " · ".join(c for c in counts if c not in drop)
+
+
+def _talk(day: PeriodReport, detail: Detail = "brief") -> list[str]:
+    """Every comment and message of the day, in the log's own order — a conversation read
+    top-down. Truncated per line in the terminal so one essay cannot push the rest of the day
+    off screen; whole in the file, where the essay is the point."""
+    if not day["conversations"]:
+        return []
+    lines = [f"**{e['actor']}** on {e['task']}: {_body(e, detail)}"
+             for e in day["conversations"]]
+    return [f"## Conversaciones ({len(lines)})", "", "\n\n".join(lines), ""]
+
+
+def _body(event: Event, detail: Detail) -> str:
+    text = str(event["body"].get("text", ""))
+    return text.strip() if detail == "full" else truncate(text, TALK_LINE)
+
+
+def _actors(day: PeriodReport) -> list[str]:
+    if not day["actors"]:
+        return []
+    rows = [[roll["actor"], str(roll["tasks"]), str(roll["commits"]),
+             str(roll["comments"]), str(roll["done"])] for roll in day["actors"]]
+    return ["## Por actor", "",
+            table(["actor", "tasks", "commits", "comments", "closed"], rows)]

taskops/render/dispatch.py

@@ -0,0 +1,104 @@
+"""What a dispatch returns: the workers that started, and the cards that did not.
+
+Its own module because the reader is in a different situation from every other result — they have
+just launched processes they cannot see, so what this owes them is where to look.
+
+The Protocols are here rather than an import of `usecases.dispatch`, because that would point layer 4
+at layer 5. An architecture test enforces it, and that is how the first version got caught: a
+`TYPE_CHECKING` guard hides an import from the runtime but not from the rule, and the rule is right.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from ._text import table
+
+__all__ = ["render_dispatch", "DispatchLike", "Worker"]
+
+
+class Worker(Protocol):
+    """One launched worker, structurally.
+
+    Read-only properties rather than plain attributes: a mutable Protocol attribute is invariant, so
+    it would only match a class whose annotations are identical — and `Launched` assigns in
+    `__init__`. Rendering never writes to these anyway.
+    """
+
+    @property
+    def actor(self) -> str: ...
+    @property
+    def task(self) -> str: ...
+    @property
+    def pid(self) -> int: ...
+    @property
+    def branch(self) -> str: ...
+    @property
+    def brief(self) -> str: ...
+
+
+class DispatchLike(Protocol):
+    # `Sequence` and not `list`: list is INVARIANT, so `list[Launched]` does not satisfy
+    # `list[Worker]` even though `Launched` satisfies `Worker`. Sequence is covariant, and a renderer
+    # has no business writing to it.
+    @property
+    def launched(self) -> Sequence[Worker]: ...
+    @property
+    def skipped(self) -> Sequence[str]: ...
+    @property
+    def planned(self) -> bool: ...
+    @property
+    def spawned(self) -> bool: ...
+
+
+def render_dispatch(result: DispatchLike) -> str:
+    """The workers that were launched, and the cards that were not.
+
+    The skipped list is not an afterthought: a dispatch that quietly started three of five would leave
+    a planner believing five agents are working, and the two cards nobody started would look assigned
+    and never move. It ends with where to look, because a detached process nobody can find is a
+    process nobody trusts.
+    """
+    if not result.launched and not result.skipped:
+        return ("nothing to dispatch — no ready, unassigned card. Plan some work, or check "
+                "`taskops_report board` for what is blocked")
+    preview = result.planned
+    rows = [[w.actor, w.task, "—" if preview else str(w.pid), w.branch]
+            for w in result.launched]
+    heading = (f"# would dispatch {len(result.launched)} worker(s) — NOTHING STARTED"
+               if preview else
+               f"# dispatched {len(result.launched)} worker(s)" if result.spawned else
+               f"# prepared {len(result.launched)} worker(s) — SPAWN THEM BELOW")
+    parts = [heading, "", table(["worker", "task", "pid", "branch"], rows)]
+    if result.skipped:
+        parts += ["", f"⚠ NOT started: {', '.join(result.skipped)}",
+                  "_Not ready, already assigned, or the process failed to start._"]
+    if preview:
+        parts += ["", "A preview: no card was assigned, no worktree made, nothing started. "
+                  "Drop `dry_run` to go ahead."]
+    elif result.spawned:
+        parts += ["", "They are detached processes, running now. Watch them with "
+                  "`taskops_report fleet`; their output is in .taskops/workers/."]
+    elif result.launched:
+        parts += _handover(result)
+    return "\n".join(parts)
+
+
+def _handover(result: DispatchLike) -> list[str]:
+    """The briefs, and the instruction that the remaining half is the caller's job.
+
+    This is the part that makes the default mode work at all: the cards are assigned and their
+    worktrees exist, but nothing is DOING them until the orchestrator spawns a sub-agent per brief.
+    Saying it plainly matters — a dispatch that returned a table and stopped reads like work in
+    flight, and the cards would sit assigned to workers that were never started.
+    """
+    out = ["", f"ASSIGNED and ready. Now spawn {len(result.launched)} sub-agent(s) IN THIS SESSION "
+           f"— one per brief below, all in one message so they run in parallel. They will use this "
+           f"session's subscription rather than opening new billed ones.", ""]
+    for worker in result.launched:
+        out += [f"── brief for {worker.actor} ({worker.task}) " + "─" * 20, "",
+                worker.brief, ""]
+    out += ["If you do not spawn them, run `taskops recover` to hand the cards back rather than "
+            "leaving them assigned to workers that never existed."]
+    return out

taskops/render/inbox.py

@@ -0,0 +1,27 @@
+"""Messages addressed to one actor — the agent-to-agent channel, as text.
+
+Its own module because of WHERE it appears: at the top of a claim, and inside a session
+brief. Both are places an agent reads before doing anything, which is the whole point — a
+message read after the work is a message that cost the work.
+"""
+
+from __future__ import annotations
+
+from ..contracts import Inbox
+from ._text import ago
+
+__all__ = ["render_inbox"]
+
+
+def render_inbox(inbox: Inbox) -> str:
+    """The messages, or "" when there are none.
+
+    Empty string rather than "no messages": this gets embedded in other renders, and a
+    line saying nothing happened is a line every caller then has to decide to strip.
+    """
+    if not inbox["messages"]:
+        return ""
+    lines = [f"**{e['actor']}** on {e['task']} ({ago(e['ts'])}): "
+             f"{e['body'].get('text', '')}" for e in inbox["messages"]]
+    return "\n".join([f"### 📬 {len(inbox['messages'])} message(s) for you", "",
+                      "\n\n".join(lines)])

taskops/render/log.py

@@ -0,0 +1,47 @@
+"""An agent's conversation, rendered for a person catching up on a card.
+
+Shaped by what a reader is actually asking: not "replay everything", but "what did it decide, what did
+it touch, and how did it end". So thinking is marked as thinking, a tool call is one line naming the
+file, and the whole thing reads top-down like a transcript rather than like a data dump.
+"""
+
+from __future__ import annotations
+
+from ..contracts import LogEntry, SessionLog
+from ._text import ago
+
+__all__ = ["render_log"]
+
+_MARK = {"prompt": "▸ you", "thinking": "· thinking", "text": "◆ agent",
+         "tool": "→", "result": "  ←", "other": "·"}
+"""One marker per kind. `result` is indented because it belongs to the call above it, which is the
+only structure in the stream a reader needs to see."""
+
+_RESULT_LINES = 3
+"""Lines kept from a tool result. They are the longest entries by far and the least read — a file's
+contents came back from a Read, and the reader is looking for what the agent DID with it."""
+
+
+def render_log(log: SessionLog) -> str:
+    if not log["entries"]:
+        return f"# {log['task']} — no conversation found\n\n{log['source']}"
+    head = [f"# {log['task']} — conversation", "",
+            f"_{len(log['entries'])} entries · {len(log['sessions'])} session(s)"
+            + (" · TRUNCATED to the most recent" if log["truncated"] else "") + "_", ""]
+    return "\n".join(head + [_entry(e) for e in log["entries"]])
+
+
+def _entry(entry: LogEntry) -> str:
+    mark = _MARK.get(entry["kind"], "·")
+    when = ago(entry["ts"]) if entry["ts"] else ""
+    if entry["kind"] == "tool":
+        return f"{mark} **{entry['tool']}** `{entry['text']}`"
+    if entry["kind"] == "result":
+        return f"{mark} {_short(entry['text'])}"
+    return f"\n{mark} _{when}_\n{entry['text']}\n"
+
+
+def _short(text: str) -> str:
+    lines = [line for line in text.splitlines() if line.strip()][:_RESULT_LINES]
+    joined = " / ".join(line.strip()[:120] for line in lines)
+    return joined or "(empty)"

taskops/render/recover.py

@@ -0,0 +1,64 @@
+"""What a recovery freed, written for somebody staring at a stuck board.
+
+The leftovers are the point of this render. A card that came back with no explanation looks like a
+card nobody started, and the next agent rewrites from zero the file sitting in a directory two levels
+down — which is what nearly happened the day this was needed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from ._text import table
+
+__all__ = ["render_recover", "RecoveredLike"]
+
+
+class StuckLike(Protocol):
+    @property
+    def task(self) -> str: ...
+    @property
+    def actor(self) -> str: ...
+    @property
+    def silent_for(self) -> float: ...
+    @property
+    def commits(self) -> int: ...
+    @property
+    def leftovers(self) -> Sequence[str]: ...
+
+
+class RecoveredLike(Protocol):
+    """Structural, so `render/` never imports `usecases` — an invariant test enforces it."""
+
+    @property
+    def released(self) -> Sequence[StuckLike]: ...
+    @property
+    def alive(self) -> Sequence[str]: ...
+
+
+def render_recover(result: RecoveredLike) -> str:
+    if not result.released:
+        return _nothing(result)
+    rows = [[s.task, s.actor, f"{int(s.silent_for // 60)}m",
+             str(s.commits) if s.commits else "—",
+             f"{len(s.leftovers)} file(s)" if s.leftovers else "—"]
+            for s in result.released]
+    parts = [f"# recovered {len(result.released)} card(s)", "",
+             table(["task", "was held by", "silent", "commits", "uncommitted"], rows),
+             "", "They are `ready` and unassigned again — dispatch or claim them normally."]
+    salvage = [s for s in result.released if s.leftovers]
+    if salvage:
+        parts += ["", "⚠ UNCOMMITTED work survives — read it before redoing the task:"]
+        parts += [f"  {s.task}: {', '.join(s.leftovers)}" for s in salvage]
+    if result.alive:
+        parts += ["", f"Still reporting, left alone: {', '.join(result.alive)}"]
+    return "\n".join(parts)
+
+
+def _nothing(result: RecoveredLike) -> str:
+    """Nothing stuck is the GOOD outcome, and it has to read like one rather than like a failure."""
+    if result.alive:
+        return ("Nothing to recover — every worker is still reporting: "
+                + ", ".join(result.alive))
+    return "Nothing to recover — no live claims at all."

taskops/render/report.py

@@ -0,0 +1,51 @@
+"""The written report as a FILE: a fingerprint, the dossier, and a slot for a narration.
+
+Separate from `render_day` because the two have different readers. The dossier is printed to
+a terminal and posted into a reply; this is the thing that lands in `.taskops/reports/` and
+gets committed, and it carries two lines the terminal version must never have — a machine
+header, and an empty section a human or a session is expected to fill in.
+
+Pure like everything else here: given a stamp and a dossier it is a string, so the shape of a
+committed report is testable without a database, a clock or a disk.
+"""
+
+from __future__ import annotations
+
+__all__ = ["render_report", "narrated", "is_pending", "NARRATION", "PENDING"]
+
+NARRATION = "## Narración"
+"""The section `/taskops:digest` replaces. A HEADING and not a comment marker, because the
+file is read by people: an editor that hides the narration inside `<!-- -->` fences would be
+optimising for the tool that writes it over the reader it is written for."""
+
+PENDING = "_pendiente — generala con `taskops report day --digest`_"
+"""The placeholder body. It names the COMMAND, so a report opened by somebody who has never
+generated one still tells them what is missing and exactly what produces it."""
+
+
+def render_report(stamp: str, dossier: str) -> str:
+    """Header, dossier, empty narration. The narration goes LAST on purpose.
+
+    A generated report whose first screen is prose invites the reader to trust the prose; put
+    the facts first and the narration is read as a reading OF them, which is what it is.
+    """
+    return "\n".join([stamp, "", dossier.strip("\n"), "", NARRATION, "", PENDING, ""])
+
+
+def narrated(report: str, prose: str) -> str:
+    """The same report with its narration section replaced. Everything above it is untouched.
+
+    Splitting on the heading rather than rewriting the file from the dossier is what makes this
+    safe to run on a report somebody has already edited: the facts on disk stay exactly as they
+    were fingerprinted, and only the last section moves.
+    """
+    head, marker, _ = report.partition(NARRATION)
+    body = head if marker else report.rstrip("\n") + "\n\n"
+    return "\n".join([body.rstrip("\n"), "", NARRATION, "", prose.strip("\n"), ""])
+
+
+def is_pending(report: str) -> bool:
+    """True when nothing has written the narration yet. A report whose prose somebody wrote by
+    hand must not be silently replaced, so the caller checks this before regenerating."""
+    _, marker, tail = report.partition(NARRATION)
+    return not marker or not tail.strip() or PENDING in tail