git-worklog 1.6.0__py3-none-any.whl

git_worklog/analysis/results.py

@@ -0,0 +1,871 @@
+"""Exchange Day Subagent results through files, and validate them.
+
+Why files rather than return values
+-----------------------------------
+A Day Subagent's result is the whole point of the expensive part of a run: it
+represents real patches read and real code understood. Passing it back as the
+subagent's *reply text* makes that result hostage to the host's return channel,
+which is the weakest link in the pipeline:
+
+* it can drop or truncate content (observed in practice — a subagent that did
+  63k tokens of correct analysis returned nothing),
+* a day's object is routinely 15KB+ and a large day is far bigger,
+* the skill targets several hosts (Claude Code / Codex / Gemini) whose return
+  semantics and size limits all differ,
+* a dropped reply loses the analysis outright, forcing a full re-run.
+
+A file has none of those properties. It also survives the run, so a failure
+downstream (rendering, preview, apply) never costs the analysis again, and a
+human can read exactly what a subagent concluded.
+
+So: the orchestrator mints a run directory with :func:`mint_run`, hands each
+subagent its own output path, and collects the lot with :func:`read_run`.
+Results live outside the repository, under
+``~/.git-worklog/analysis/<run_id>/<date>.json``, alongside the preview state —
+the worklog directory is for the worklog, not for scratch.
+
+What :func:`read_run` guarantees
+--------------------------------
+A missing or malformed file is reported as **that day failing**, explicitly. This
+is the deterministic half of the orchestrator's completeness check
+(`references/subagent-contract.md` §1): a day whose result never arrived must
+never be silently skipped, and must never be back-filled from commit messages.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+from datetime import datetime
+
+from git_worklog import language, markers as wm, paths
+from git_worklog.analysis import AnalysisError
+
+# Top-level keys required by the Day Subagent return schema
+# (references/subagent-contract.md §6). All must be present even when empty.
+REQUIRED_KEYS = [
+    "date", "timezone", "language", "status", "confidence",
+    "escalation_recommended", "escalation_reasons", "has_changes", "commits",
+    "work_items", "fixes", "refactors", "tests", "database_changes",
+    "configuration_changes", "deployment_changes", "uncommitted_changes",
+    "handoff_notes", "uncertainties", "evidence",
+]
+
+# Keys required on each work_items[] entry (§6).
+REQUIRED_WORK_ITEM_KEYS = [
+    "title", "summary", "behavior_change", "implementation", "impact", "files",
+    "commits", "tests", "risks", "maintenance_notes", "follow_ups",
+    "confidence", "evidence",
+]
+
+VALID_STATUS = {"complete", "partial", "failed"}
+VALID_CONFIDENCE = {"verified", "inferred", "unknown"}
+
+# Evidence entries are objects, not sentences (subagent-contract.md §8). commit
+# and file are required because they are the two facts always knowable and always
+# checkable against the repository. Left as free text, the field reliably decays
+# into a restatement of the commit subject -- observed in a real run:
+# "commit 4d08ee4: 完整改造" cites nothing a reader can open.
+REQUIRED_EVIDENCE_KEYS = ["commit", "file"]
+
+# An identifier inside a `symbol` field. Short tokens are ignored: `get` in
+# `CacheLayer.get` says nothing, and a qualified name never appears verbatim in
+# source anyway (the file holds `class CacheLayer:` and `def get`), so the field
+# is checked token by token rather than as one string.
+_SYMBOL_TOKEN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]{2,}")
+
+# A `code span` in the prose. The worklog is written from these fields, and
+# nothing checked them: evidence[] was validated while `implementation` was free
+# to invent `PreviewStore` and `read_config()`, and did (#19, #22). A check is
+# only worth the surface it measures, and this was the surface the reader sees.
+_CODE_SPAN_RE = re.compile(r"`([^`\n]+)`")
+
+# The work_item fields a reader actually reads. `files` and `commits` are paths
+# and hashes (coverage's job), and `evidence` gets the stronger commit+file check
+# above -- checking them here would only report the same fault twice.
+PROSE_KEYS = ["title", "summary", "behavior_change", "implementation", "impact",
+              "risks", "maintenance_notes", "follow_ups"]
+
+# Prose fields outside work_items, same reasoning.
+TOP_LEVEL_PROSE_KEYS = ["handoff_notes", "uncertainties"]
+
+
+def analysis_dir() -> str:
+    """Where runs live. Resolved per call so ``GIT_WORKLOG_HOME`` stays live."""
+    return paths.analysis_dir()
+
+
+def result_path(run_dir: str, date: str) -> str:
+    return os.path.join(run_dir, f"{date}.json")
+
+
+def parse_dates(raw: str) -> "list[str]":
+    """Split and validate a comma-separated date list, preserving caller order."""
+    dates = [d.strip() for d in raw.split(",") if d.strip()]
+    if not dates:
+        raise AnalysisError("NO_DATES", "Provide at least one date via --dates.")
+    for d in dates:
+        if not wm.is_valid_date(d):
+            raise AnalysisError("INVALID_DATE", f"Not an ISO YYYY-MM-DD date: {d}.",
+                                date=d)
+    return list(dict.fromkeys(dates))
+
+
+def mint_run(dates: "list[str]", run_dir: "str | None" = None) -> dict:
+    """Create a run directory and one output path per date."""
+    now = datetime.now()
+    basis = hashlib.sha256(
+        f"{now.isoformat()}|{','.join(dates)}".encode("utf-8")).hexdigest()[:6]
+    run_id = f"rw-{now.strftime('%Y%m%d')}-{basis}"
+    run_dir = run_dir or os.path.join(analysis_dir(), run_id)
+    paths.ensure_dir(run_dir)
+    return {
+        "ok": True,
+        "run_id": run_id,
+        "run_dir": run_dir,
+        "dates": dates,
+        # One path per date: hand each Day Subagent exactly its own, so two days
+        # can never race on one file.
+        "paths": {d: result_path(run_dir, d) for d in dates},
+    }
+
+
+# Issues that mean "this could not be checked", not "this was found to be
+# false". They are reported but never fail a day: `analysis-pipeline.md` has
+# promised exactly that for EVIDENCE_UNVERIFIABLE since it was written, while
+# the code failed the day anyway.
+UNVERIFIED_CODES = {
+    "EVIDENCE_UNVERIFIABLE",
+    "EVIDENCE_FILE_NOT_TEXT",
+    "PROSE_SCOPE_TRUNCATED",
+}
+
+# `file_at` has three answers, not two: the file was there, it was not there, or
+# it was there but is not UTF-8 text. The third needs a value of its own --
+# returning ``None`` would report a real binary file as "no such file", and
+# decoding it strictly used to take the whole of `collect` down without naming
+# the commit or the path it died on.
+NOT_TEXT = object()
+
+# Above this many trees, `day_scope` stops searching every state the day passed
+# through and searches only its boundaries. One grep over 27 trees costs ~25s on
+# a 250k-line repository; the cost is linear in the tree count, and a day large
+# enough to pass this is a day where the answer is worth less than the wait.
+MAX_DAY_TREES = 50
+
+
+class Tree:
+    """Reads files as they were at a commit, and remembers what it read.
+
+    Evidence must be checked against the day's tree, never the checkout: the
+    working tree holds every change made since, so a symbol that exists today
+    proves nothing about the day being described. One subprocess per distinct
+    (commit, file) — a day's evidence cites the same few files repeatedly.
+    """
+
+    def __init__(self, repo: str):
+        self.repo = repo
+        self._files: dict = {}
+        self._commits: dict = {}
+        self._greps: dict = {}
+        self._shallow = None
+
+    def _git_bytes(self, *args) -> "tuple[int, bytes]":
+        p = subprocess.run(["git", "-C", self.repo, *args], capture_output=True)
+        return p.returncode, p.stdout
+
+    def _git(self, *args) -> "tuple[int, str]":
+        code, out = self._git_bytes(*args)
+        # Replacement rather than strict decoding: every caller here reads Git's
+        # own control output -- hashes, exit codes, matched tokens -- where one
+        # undecodable byte must not end the run. `file_at` is the single caller
+        # that reads *file content*, and it decodes strictly itself, because
+        # there "not text" is an answer rather than an accident.
+        return code, out.decode("utf-8", "replace")
+
+    def is_shallow(self) -> bool:
+        if self._shallow is None:
+            _, out = self._git("rev-parse", "--is-shallow-repository")
+            self._shallow = out.strip() == "true"
+        return self._shallow
+
+    def has_commit(self, commit: str) -> bool:
+        if commit not in self._commits:
+            code, _ = self._git("cat-file", "-e", f"{commit}^{{commit}}")
+            self._commits[commit] = code == 0
+        return self._commits[commit]
+
+    def file_at(self, commit: str, path: str):
+        """The file's text at that commit, ``None`` if absent, ``NOT_TEXT`` if
+        it is there but not UTF-8."""
+        key = (commit, path)
+        if key not in self._files:
+            code, out = self._git_bytes("show", f"{commit}:{path}")
+            if code != 0:
+                self._files[key] = None
+            else:
+                try:
+                    self._files[key] = out.decode("utf-8")
+                except UnicodeDecodeError:
+                    self._files[key] = NOT_TEXT
+        return self._files[key]
+
+    def names_anything(self, token: str, trees: "tuple[str, ...]") -> bool:
+        """Does ``token`` appear anywhere in these trees?
+
+        Prose has no ``file`` to check a symbol against the way evidence does --
+        "PreviewStore stores the payload" names no location -- so the question a
+        prose symbol can answer is the weaker one: does this identifier exist in
+        the project at all, on the day being described. That is enough to catch
+        the fabrication this exists for, because an invented name exists nowhere.
+
+        ``git grep`` over whole trees rather than the cached file contents:
+        prose legitimately refers to code the day did not change ("consistent
+        with `detect_timezone`"), and checking only the day's own files would
+        report those as invented.
+
+        ``-w`` matches whole words, so a fabricated ``Cache`` is not masked by a
+        real ``CacheLayer`` -- ``-F`` alone is a substring match, and that
+        substring is exactly how a plausible-but-wrong name hides. Every token
+        reaching here is a single identifier (a dotted ``Tree.file_at`` was split
+        upstream), and an underscore is a word character, so ``_verify`` still
+        will not match inside ``_verify_against_tree`` -- which is correct, since
+        that is a different name.
+        """
+        key = (token, trees)
+        if key not in self._greps:
+            code, _ = self._git("grep", "-qwFI", "--", token, *trees)
+            self._greps[key] = code == 0
+        return self._greps[key]
+
+    def prime(self, tokens, trees: "tuple[str, ...]") -> None:
+        """Answer many tokens with one grep instead of one grep each.
+
+        `names_anything` asks the right question; asking it one token at a time
+        was the expense. ``-q`` makes a token that *is* present cheap (Git stops
+        at the first hit) and a token that is *absent* expensive (it scans
+        everything) -- so the loop paid most for exactly the tokens a false
+        report is made of. Measured on a 250k-line repository, one day of 27
+        commits and 128 tokens: 128 greps over 2 trees took 35s and missed 20
+        real names; one grep over all 28 trees took 25s and missed none.
+        Batching is what makes searching every state the day passed through
+        cheaper than searching two.
+
+        ``-o`` prints the matched text, and under ``-w -F`` that text is the
+        token itself, so Git's reply is simply the set of tokens that exist.
+        """
+        if not trees:
+            return
+        pending = [t for t in dict.fromkeys(tokens)
+                   if (t, trees) not in self._greps]
+        if not pending:
+            return
+        patterns = [arg for t in pending for arg in ("-e", t)]
+        code, out = self._git("grep", "-howFI", *patterns, *trees)
+        # 0 = matched, 1 = nothing matched, anything higher = Git refused. Only
+        # the first two are answers. On a refusal, leave the cache untouched so
+        # `names_anything` falls back to its own grep per token: recording
+        # "absent" here would turn one bad invocation into a page of
+        # fabrication reports against real code.
+        if code > 1:
+            return
+        present = set(out.split())
+        for token in pending:
+            self._greps[(token, trees)] = token in present
+
+    def _boundary_parents(self, commits: "list[str]") -> "list[str]":
+        """The day's starting states: parents of the day that the day excludes.
+
+        Plural, because a day can begin in more than one place. A day that
+        *deletes* `parse_legacy` describes it correctly and it is gone from
+        every tree the day ends in, so without the state before, every removal
+        reads as a fabrication.
+
+        Each output line begins with the commit's own full hash, so the set of
+        "inside" hashes is built from Git's own normalisation -- the caller's
+        list may be abbreviated, and comparing those against full parent hashes
+        would call every parent a boundary.
+        """
+        code, out = self._git("rev-list", "--no-walk", "--parents", *commits)
+        if code != 0:
+            return []
+        inside, parents = set(), []
+        for line in out.splitlines():
+            fields = line.split()
+            if fields:
+                inside.add(fields[0])
+                parents.extend(fields[1:])
+        return sorted({p for p in parents if p not in inside})
+
+    def _tips(self, commits: "list[str]") -> "list[str]":
+        """The day's end states: the commits no other day commit reaches."""
+        code, out = self._git("merge-base", "--independent", *commits)
+        return out.split() if code == 0 else list(commits)
+
+    def day_scope(self, commits: "list[str]") -> dict:
+        """Every tree the day's prose may be checked against.
+
+        The day's own commits plus the parents it started from -- *all* of its
+        commits, not its first and its last. Taking only the ends assumes the
+        day is one straight line of history, and a day that lands a branch is
+        not: in a real repository on 2026-08-27 two tips existed that were not
+        ancestors of one another, the later-committed one took the "last" slot,
+        and all 26 real symbols living on the other line were reported as
+        invented (issue #36).
+
+        Searching every state also closes the hole this used to document as
+        acceptable: a symbol created and deleted within the same day lives only
+        in a middle state, and middle states are now searched.
+
+        Past :data:`MAX_DAY_TREES` the scope narrows to the day's boundaries --
+        its starting states and its tips -- which is the old shape generalised
+        to every line rather than assumed to be one. That is reported, never
+        silent: a check that quietly stopped looking is how this began.
+        """
+        usable = [c for c in commits if c and self.has_commit(c)]
+        if not usable:
+            return {"trees": (), "truncated": False, "commits": 0}
+        boundary = self._boundary_parents(usable)
+        full = tuple(boundary) + tuple(usable)
+        if len(full) <= MAX_DAY_TREES:
+            return {"trees": full, "truncated": False, "commits": len(usable)}
+        ends = tuple(boundary) + tuple(self._tips(usable))
+        return {"trees": ends, "truncated": True, "commits": len(usable)}
+
+
+def validate_evidence(entries, where: str, tree: "Tree | None" = None) -> "list[dict]":
+    """Evidence must be checkable citations, not prose — and must check out.
+
+    Presence of ``commit`` and ``file`` was all this ever enforced, which left
+    ``symbol`` and ``lines`` decorative: a real run cited `migrate_directory`
+    for a function actually called `parse_legacy`, `preview_dir` for
+    `previews_dir`, and a line range past the end of the file — and all of it
+    passed (issue #15). Every fabrication was a *plausible* name, which is
+    precisely why reading cannot catch them and why this has to be mechanical.
+    """
+    if entries is None:
+        return []
+    if not isinstance(entries, list):
+        return [{"code": "EVIDENCE_INVALID",
+                 "message": f"{where} must be an array."}]
+    issues: "list[dict]" = []
+    for idx, e in enumerate(entries):
+        at = f"{where}[{idx}]"
+        if not isinstance(e, dict):
+            issues.append({
+                "code": "EVIDENCE_INVALID",
+                "message": f"{at} must be an object with at least "
+                           f"{REQUIRED_EVIDENCE_KEYS}; prose is not evidence "
+                           f"(got {type(e).__name__}).",
+                "path": at,
+            })
+            continue
+        missing = [k for k in REQUIRED_EVIDENCE_KEYS
+                   if not str(e.get(k) or "").strip()]
+        if missing:
+            issues.append({
+                "code": "EVIDENCE_INVALID",
+                "message": f"{at} is missing: {', '.join(missing)}.",
+                "path": at,
+                "missing_keys": missing,
+            })
+            continue
+        if tree is not None:
+            issues.extend(_verify_against_tree(e, at, tree))
+    return issues
+
+
+def _verify_against_tree(e: dict, at: str, tree: Tree) -> "list[dict]":
+    """Check one evidence entry against the repository it cites."""
+    commit = str(e["commit"]).strip()
+    path = str(e["file"]).strip()
+
+    if not tree.has_commit(commit):
+        # A missing commit in a shallow clone is the environment's doing, not
+        # the subagent's, and failing the day for it would punish the wrong
+        # party. In a full clone there is no such excuse: the hash is invented.
+        if tree.is_shallow():
+            return [{
+                "code": "EVIDENCE_UNVERIFIABLE",
+                "message": f"{at} cites commit {commit}, which this shallow "
+                           f"clone does not have, so its evidence could not be "
+                           f"checked. `git fetch --unshallow` to verify it.",
+                "path": at, "commit": commit,
+            }]
+        return [{
+            "code": "EVIDENCE_COMMIT_UNKNOWN",
+            "message": f"{at} cites commit {commit}, which is not in this "
+                       f"repository.",
+            "path": at, "commit": commit,
+        }]
+
+    src = tree.file_at(commit, path)
+    if src is NOT_TEXT:
+        return [{
+            "code": "EVIDENCE_FILE_NOT_TEXT",
+            "message": f"{at} cites {path} at commit {commit}, which is there "
+                       f"but is not text, so its symbol and line range could "
+                       f"not be checked. Citing it is not an error; it simply "
+                       f"proves nothing.",
+            "path": at, "commit": commit, "file": path,
+        }]
+    if src is None:
+        return [{
+            "code": "EVIDENCE_FILE_NOT_IN_COMMIT",
+            "message": f"{at} cites {path} at commit {commit}, but that commit's "
+                       f"tree has no such file. A file that exists today may not "
+                       f"have existed then.",
+            "path": at, "commit": commit, "file": path,
+        }]
+
+    issues: "list[dict]" = []
+    symbol = str(e.get("symbol") or "").strip()
+    if symbol:
+        absent = [t for t in _SYMBOL_TOKEN_RE.findall(symbol) if t not in src]
+        if absent:
+            issues.append({
+                "code": "EVIDENCE_SYMBOL_NOT_FOUND",
+                "message": f"{at} cites symbol {symbol!r} in {path} at {commit}, "
+                           f"but {', '.join(repr(a) for a in absent)} does not "
+                           f"appear there. Cite what the code is actually called.",
+                "path": at, "commit": commit, "file": path,
+                "symbol": symbol, "absent": absent,
+            })
+
+    lines = str(e.get("lines") or "").strip()
+    m = re.match(r"^(\d+)\s*-\s*(\d+)$", lines) if lines else None
+    if m:
+        lo, hi = int(m.group(1)), int(m.group(2))
+        total = len(src.splitlines())
+        if lo < 1 or hi > total or lo > hi:
+            issues.append({
+                "code": "EVIDENCE_LINES_OUT_OF_RANGE",
+                "message": f"{at} cites lines {lines} of {path} at {commit}, "
+                           f"which has {total} line(s).",
+                "path": at, "commit": commit, "file": path,
+                "lines": lines, "file_lines": total,
+            })
+    return issues
+
+
+def _prose_strings(obj, keys: "list[str]") -> "list[str]":
+    """The prose under ``keys``, flattened. A field may be a string or a list."""
+    out: "list[str]" = []
+    for k in keys:
+        v = obj.get(k)
+        if isinstance(v, str):
+            out.append(v)
+        elif isinstance(v, list):
+            out.extend(x for x in v if isinstance(x, str))
+    return out
+
+
+def cited_symbols(text: str) -> "list[str]":
+    """Identifier-shaped code spans in prose, in order, without duplicates.
+
+    Only spans that are *entirely* an identifier (optionally dotted, optionally
+    with a trailing call) are returned. A span is not a symbol when it holds a
+    path (`.git-worklog/days/`), a flag (`--language`), a tag (`zh-TW`), a date,
+    or a phrase -- all of which are legitimately backticked and none of which
+    Git's index would find. Being strict here is what keeps the check quiet
+    enough that its output means something.
+    """
+    seen, out = set(), []
+    for span in _CODE_SPAN_RE.findall(text):
+        name = span.strip()
+        if name.endswith("()"):
+            name = name[:-2]
+        if not name or not all(
+                _SYMBOL_TOKEN_RE.fullmatch(part) for part in name.split(".") if part):
+            continue
+        for token in _SYMBOL_TOKEN_RE.findall(name):
+            if token not in seen:
+                seen.add(token)
+                out.append(token)
+    return out
+
+
+def _all_prose_tokens(obj) -> "list[str]":
+    """Every symbol the whole result names, so one grep can answer them all.
+
+    Deliberately the same two functions `validate_prose` uses over the same two
+    key sets: a priming pass that asked a different question would leave the
+    tokens it missed to be greped one at a time, quietly restoring the cost it
+    exists to remove.
+    """
+    tokens: "list[str]" = []
+    for text in _prose_strings(obj, TOP_LEVEL_PROSE_KEYS):
+        tokens.extend(cited_symbols(text))
+    for item in obj.get("work_items") or []:
+        if isinstance(item, dict):
+            for text in _prose_strings(item, PROSE_KEYS):
+                tokens.extend(cited_symbols(text))
+    return tokens
+
+
+def _stamp(issues: "list[dict]") -> "list[dict]":
+    """Mark each issue blocking or unverified.
+
+    The line is "found to be false" against "could not be checked", and only
+    the first should stop a run. Failing a day because the clone was shallow,
+    or because a cited file is a `.docx`, punishes the subagent for the
+    environment -- and a day held back for a reason no re-analysis can fix is a
+    day whose correct work is thrown away and paid for again.
+    """
+    for issue in issues:
+        issue.setdefault("severity",
+                         "unverified" if issue.get("code") in UNVERIFIED_CODES
+                         else "blocking")
+    return issues
+
+
+def validate_prose(obj, keys: "list[str]", where: str, tree: "Tree | None",
+                   trees: "tuple[str, ...]") -> "list[dict]":
+    """Every symbol the prose names must exist in the day it describes.
+
+    The weaker half of the evidence check, and the one that guards what the
+    worklog is actually written from. It asks only "does this name exist here",
+    because prose names no file -- but every fabrication observed so far was a
+    plausible name for code that does not exist at all, which this catches.
+    """
+    if tree is None or not trees:
+        return []
+    issues: "list[dict]" = []
+    for text in _prose_strings(obj, keys):
+        for token in cited_symbols(text):
+            if not tree.names_anything(token, trees):
+                issues.append({
+                    "code": "PROSE_SYMBOL_NOT_FOUND",
+                    "message": f"{where} names `{token}`, which appears nowhere "
+                               f"in the project on this day. The worklog is "
+                               f"written from this prose, so cite what the code "
+                               f"is actually called.",
+                    "path": where, "symbol": token,
+                })
+    return issues
+
+
+def mentioned_files(obj) -> "set[str]":
+    """Every file path the analysis refers to, anywhere in the result.
+
+    Both `files[]` lists and `evidence[].file` count. They do different jobs --
+    `files[]` inventories what a work item touched, `evidence[]` cites proof of
+    a specific claim -- and coverage asks the weaker question: was this file
+    accounted for at all?
+
+    The walk is deliberately structure-agnostic. The contract pins `files[]` only
+    on `work_items[]`, but leaves the shape of `fixes[]`, `refactors[]`,
+    `configuration_changes[]` and friends open, and a real run put `files[]` on
+    those too. Reading only the specified location would count an honestly
+    recorded config change as an omission.
+    """
+    found: "set[str]" = set()
+
+    def add(value):
+        if isinstance(value, str) and value.strip():
+            found.add(value.strip())
+        elif isinstance(value, dict) and value.get("path"):
+            found.add(str(value["path"]).strip())
+
+    def walk(node):
+        if isinstance(node, dict):
+            for key, value in node.items():
+                if key == "files" and isinstance(value, list):
+                    for item in value:
+                        add(item)
+                elif key == "evidence" and isinstance(value, list):
+                    for e in value:
+                        if isinstance(e, dict) and e.get("file"):
+                            add(str(e["file"]))
+                walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(obj)
+    return found
+
+
+def validate_coverage(obj, required: "set[str] | None") -> "list[dict]":
+    """Every source file the manifest required must be accounted for.
+
+    This is the other half of the evidence problem. #15 fixed *accuracy* -- a
+    citation now has to resolve against the tree it names. Accuracy says nothing
+    about *completeness*: a day can cite three real files perfectly and never
+    mention the other twenty it changed, and read as confident, verified work.
+
+    The bar is what measurement supports rather than what the roadmap's wording
+    suggests. Requiring every changed file to appear in `evidence[]` sounds
+    stricter and is: measured against a real, good run it would have rejected it
+    (31% cited). Measured the same way, this rule passes that run at 91% while
+    still naming the two files its analysis genuinely never reached.
+    """
+    if not required:
+        return []
+    missing = sorted(required - mentioned_files(obj))
+    if not missing:
+        return []
+    return [{
+        "code": "COVERAGE_INCOMPLETE",
+        "message": f"{len(missing)} source file(s) the day changed are not "
+                   f"mentioned anywhere in the analysis: "
+                   f"{', '.join(missing[:5])}"
+                   f"{f' (+{len(missing) - 5} more)' if len(missing) > 5 else ''}. "
+                   f"A file that was changed but never described may not have "
+                   f"been read.",
+        "missing_files": missing,
+        "required_count": len(required),
+        "covered_count": len(required) - len(missing),
+    }]
+
+
+def _validate_language(obj, expected: "str | None") -> "list[dict]":
+    """Check the result's language field against the manifest's (§6.2.9).
+
+    Structural only, on purpose. The roadmap is explicit that a natural-language
+    detector must not decide this: engineering prose is full of English
+    identifiers, paths and API names by contract, so a detector reading a
+    correct zh-TW work item would see enough English to doubt it. What is
+    checkable is that the subagent declared a language, that the tag is
+    well-formed, and that it is the one it was asked for.
+    """
+    issues: "list[dict]" = []
+    raw = obj.get("language")
+    if raw is None:
+        return issues  # absence is already reported by the required-keys check
+
+    try:
+        tag = language.normalize(raw)
+    except language.LanguageError as exc:
+        return [{"code": "RESULT_BAD_LANGUAGE", "message": exc.message,
+                 "language": raw}]
+
+    if expected is not None and tag != expected:
+        issues.append({
+            "code": "RESULT_LANGUAGE_MISMATCH",
+            "message": f"Result is in {tag!r} but the manifest asked for "
+                       f"{expected!r}.",
+            "language": tag,
+            "expected_language": expected,
+        })
+    return issues
+
+
+def validate(obj, date: str, expected_language: "str | None" = None,
+             tree: "Tree | None" = None,
+             required: "set[str] | None" = None,
+             commits: "list[str] | None" = None) -> "list[dict]":
+    """Structural check against the §6 return schema. Returns issue dicts.
+
+    ``required`` is the manifest's required file set. It is optional because a
+    caller without a manifest genuinely cannot know it -- `collect_day_results.py`
+    is handed a run directory and nothing else, so it checks what it can and does
+    not pretend to check coverage. `analyze collect` reads the manifests, so it
+    can, and does.
+
+    ``commits`` is the day's commit list **from the manifest**, and bounds the
+    trees the prose check searches. Deliberately not ``obj["commits"]``: that is
+    written by the subagent being checked, and a check whose scope its subject
+    chooses is not a check.
+    """
+    issues: "list[dict]" = []
+    if not isinstance(obj, dict):
+        return _stamp([{"code": "RESULT_NOT_OBJECT",
+                        "message": "The result file must contain a JSON "
+                                   "object."}])
+
+    scope = tree.day_scope(commits) if (tree and commits) else None
+    trees = scope["trees"] if scope else ()
+    if trees:
+        # One grep for the whole result, before anything asks about a token.
+        tree.prime(_all_prose_tokens(obj), trees)
+    if scope and scope["truncated"]:
+        issues.append({
+            "code": "PROSE_SCOPE_TRUNCATED",
+            "message": f"This day has {scope['commits']} commits, past the "
+                       f"{MAX_DAY_TREES}-tree limit, so only its starting "
+                       f"states and its tips were searched. A symbol that "
+                       f"existed only part-way through the day is neither "
+                       f"reported as missing nor confirmed.",
+            "commits": scope["commits"], "trees_searched": len(trees),
+        })
+
+    issues.extend(_validate_language(obj, expected_language))
+    issues.extend(validate_coverage(obj, required))
+
+    missing = [k for k in REQUIRED_KEYS if k not in obj]
+    if missing:
+        issues.append({
+            "code": "RESULT_SCHEMA_INVALID",
+            "message": f"Missing required keys: {', '.join(missing)}.",
+            "missing_keys": missing,
+        })
+
+    if obj.get("date") != date:
+        issues.append({
+            "code": "RESULT_DATE_MISMATCH",
+            "message": f"Result says date={obj.get('date')!r} but it was "
+                       f"produced for {date!r}.",
+        })
+
+    status = obj.get("status")
+    if status is not None and status not in VALID_STATUS:
+        issues.append({
+            "code": "RESULT_BAD_STATUS",
+            "message": f"status must be one of {sorted(VALID_STATUS)} (got {status!r}).",
+        })
+
+    confidence = obj.get("confidence")
+    if confidence is not None and confidence not in VALID_CONFIDENCE:
+        issues.append({
+            "code": "RESULT_BAD_CONFIDENCE",
+            "message": f"confidence must be one of {sorted(VALID_CONFIDENCE)} "
+                       f"(got {confidence!r}).",
+        })
+
+    issues.extend(validate_evidence(obj.get("evidence"), "evidence", tree))
+    issues.extend(validate_prose(obj, TOP_LEVEL_PROSE_KEYS, "handoff_notes/"
+                                 "uncertainties", tree, trees))
+
+    work_items = obj.get("work_items")
+    if work_items is not None and not isinstance(work_items, list):
+        issues.append({"code": "RESULT_SCHEMA_INVALID",
+                       "message": "work_items must be an array."})
+    elif isinstance(work_items, list):
+        for idx, item in enumerate(work_items):
+            if not isinstance(item, dict):
+                issues.append({
+                    "code": "WORK_ITEM_INVALID",
+                    "message": f"work_items[{idx}] must be an object.",
+                })
+                continue
+            item_missing = [k for k in REQUIRED_WORK_ITEM_KEYS if k not in item]
+            if item_missing:
+                issues.append({
+                    "code": "WORK_ITEM_SCHEMA_INVALID",
+                    "message": f"work_items[{idx}] is missing: "
+                               f"{', '.join(item_missing)}.",
+                    "index": idx,
+                    "missing_keys": item_missing,
+                })
+            issues.extend(
+                validate_evidence(item.get("evidence"),
+                                  f"work_items[{idx}].evidence", tree))
+            issues.extend(
+                validate_prose(item, PROSE_KEYS, f"work_items[{idx}]",
+                               tree, trees))
+    return _stamp(issues)
+
+
+def read_run(run_dir: str, dates: "list[str]", repo: str,
+             expected_language: "str | None" = None,
+             required_by_date: "dict[str, set[str]] | None" = None,
+             commits_by_date: "dict[str, list[str]] | None" = None) -> dict:
+    """Read every dispatched day's result file and validate it.
+
+    ``required_by_date`` maps a date to the source files its manifest requires
+    the analysis to account for. ``commits_by_date`` maps a date to the commits
+    its manifest dispatched, which bound the prose check's search. Both are
+    omitted by callers that never saw a manifest, which then check what they can
+    rather than pretend.
+    """
+    if not os.path.isdir(run_dir):
+        raise AnalysisError("RUN_DIR_MISSING",
+                            f"No such analysis run directory: {run_dir}.",
+                            run_dir=run_dir)
+
+    tree = Tree(repo)
+    if not tree.has_commit("HEAD"):
+        raise AnalysisError(
+            "NOT_A_GIT_REPO",
+            f"{repo} is not a readable Git repository, so evidence cannot be "
+            f"checked against the commits it cites.",
+            repo=repo)
+
+    results: "dict[str, dict]" = {}
+    missing: "list[str]" = []
+    invalid: "list[dict]" = []
+    unverified: "list[dict]" = []
+
+    for date in dates:
+        path = result_path(run_dir, date)
+        if not os.path.isfile(path):
+            # The subagent never delivered. This is a failed day, not an empty
+            # one -- the caller must not treat it as "nothing happened".
+            missing.append(date)
+            continue
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                obj = json.load(fh)
+        except json.JSONDecodeError as exc:
+            invalid.append({"date": date, "path": path,
+                            "code": "RESULT_NOT_JSON",
+                            "message": f"Result file is not valid JSON: {exc}"})
+            continue
+        except (OSError, UnicodeDecodeError) as exc:
+            invalid.append({"date": date, "path": path,
+                            "code": "RESULT_UNREADABLE",
+                            "message": f"Could not read result file: {exc}"})
+            continue
+
+        issues = validate(obj, date, expected_language, tree,
+                          (required_by_date or {}).get(date),
+                          (commits_by_date or {}).get(date))
+        blocking = [i for i in issues if i["severity"] == "blocking"]
+        if blocking:
+            invalid.append({"date": date, "path": path,
+                            "code": blocking[0]["code"],
+                            "message": blocking[0]["message"],
+                            "issues": issues})
+            continue
+        if issues:
+            # Checks that could not be run. The day stands, but silence here is
+            # how a validator starts lying about what it verified.
+            unverified.append({"date": date, "path": path, "issues": issues})
+        results[date] = obj
+
+    # Every day in a run must be written in one language (§6.2.8). When the
+    # manifest's language was passed in, each day was already checked against
+    # it, so this can only fire for a run collected without one -- but it fires
+    # then, because a worklog whose days silently switch language mid-run is not
+    # something to discover after apply.
+    languages = sorted({results[d]["language"] for d in results
+                        if isinstance(results[d].get("language"), str)})
+    run_language = languages[0] if len(languages) == 1 else None
+    language_inconsistent = len(languages) > 1
+
+    complete = [d for d in dates if d in results
+                and results[d].get("status") == "complete"]
+    degraded = [d for d in dates if d in results
+                and results[d].get("status") in ("partial", "failed")]
+    failed_dates = missing + [i["date"] for i in invalid]
+
+    return {
+        "ok": True,
+        "run_dir": run_dir,
+        "dates": dates,
+        "language": run_language,
+        "language_inconsistent": language_inconsistent,
+        "languages_seen": languages,
+        "results": results,
+        "complete": complete,
+        "degraded": degraded,
+        "missing": missing,
+        "invalid": invalid,
+        "unverified": unverified,
+        "failed_dates": failed_dates,
+        # A run is partial if any day failed to arrive, arrived malformed, or
+        # reported its own status as partial/failed. Apply is blocked by default
+        # for a partial run (subagent-contract.md §11) -- which is also the lever
+        # that stops a mixed-language run from reaching the worklog, since a day
+        # in the wrong language is wrong in a way no amount of retrying the
+        # other days fixes.
+        "partial_run": bool(failed_dates or degraded or language_inconsistent),
+        "escalation_suggested_dates": [
+            d for d in dates
+            if d in results and results[d].get("escalation_recommended")
+        ],
+    }