countersign-cli 0.2.0__py3-none-any.whl

countersign/jsscan.py

@@ -0,0 +1,422 @@
+# audited on 20260903
+"""Structural check for TypeScript and JavaScript: functions that do nothing.
+
+Python gets this check from the ``ast`` module. There is no parser for
+TypeScript in the standard library, and a dependency is not on the table, so
+this module does the one narrow thing the check needs without parsing the
+language: it blanks out every comment, string, template literal and regular
+expression literal (keeping line breaks), then looks for the three shapes
+an agent leaves behind when it declares a function and never writes it:
+
+  function name(...) {}            declarations, async, generators, default
+  name(...) {}                     class and object literal methods
+  export const name = (...) => {}  exported arrow and function expressions
+
+Only a body that is empty before blanking counts: a block holding nothing
+but a comment is a documented no-op, which is a decision, not unfinished
+work (and whatever the comment admits is the marker rules' business). The
+check is tuned to never fire on honest code:
+
+- constructors are skipped (parameter properties make an empty body normal),
+- Angular lifecycle hooks (``ngOnInit`` and friends) are skipped,
+- control flow keywords are never treated as a method name,
+- unexported arrow functions are skipped (callbacks and defaults are
+  legitimately empty), as is an exported ``noop``,
+- declaration files (``.d.ts``) and minified sources are skipped outright.
+
+Overloads, abstract methods and interface methods have no body and match
+nothing. Anything this cannot see is a miss, never a false positive.
+"""
+
+from __future__ import annotations
+
+import re
+
+# A line longer than this is generated or minified code, where empty
+# functions are polyfill noise rather than an agent's unfinished work.
+MINIFIED_LINE_LENGTH = 1000
+
+# Words that can precede ``(`` and a block without being a method name.
+NOT_A_METHOD = frozenset({
+    "if", "for", "while", "switch", "catch", "with", "function", "return",
+    "await", "yield", "typeof", "new", "throw", "void", "delete", "in", "of",
+    "case", "else", "do", "try", "finally", "constructor", "super", "import",
+    "export", "as", "from", "declare", "abstract", "class", "interface",
+    "namespace", "module", "enum", "type", "let", "const", "var", "instanceof",
+})
+
+# Method names whose empty body is a framework convention, not unfinished work.
+FRAMEWORK_HOOK = re.compile(r"^ng[A-Z]\w*$")
+NOOP_NAME = re.compile(r"^no[_-]?op$", re.IGNORECASE)
+
+MODIFIERS = frozenset({"public", "private", "protected", "static", "async", "override", "readonly", "get", "set", "declare", "abstract"})
+
+_IDENT = r"[A-Za-z_$][\w$]*"
+_FUNCTION_DECL = re.compile(r"\bfunction\b\s*(\*)?\s*(" + _IDENT + r")?\s*(?=[<(])")
+_METHOD_LINE = re.compile(r"^[ \t]*((?:(?:" + "|".join(sorted(MODIFIERS)) + r")\s+)*)(" + _IDENT + r")\s*(?=[<(])", re.MULTILINE)
+_EXPORTED_ARROW = re.compile(r"\bexport\s+(?:const|let|var)\s+(" + _IDENT + r")\b")
+_IDENT_AT = re.compile(_IDENT)
+
+# Characters after which a ``/`` begins a regular expression literal rather
+# than a division. Good enough for blanking; a wrong guess only affects
+# what is blanked on that line.
+_REGEX_PRECEDERS = set("(,=:[!&|?{};+-*%<>~^")
+
+
+def mask_source(source: str) -> str:
+    """Blank every comment, string, template literal and regex literal.
+
+    Every blanked character becomes a space; line breaks and everything
+    else are kept, so offsets and line numbers in the result are the
+    offsets and line numbers of the source.
+    """
+    out = list(source)
+    n = len(source)
+    i = 0
+    last_significant: str | None = None
+    # Stack of template-literal expression depths: inside ``${ ... }`` code
+    # resumes, and a ``}`` at depth zero returns to the template.
+    template_depths: list[int] = []
+
+    def blank(start: int, end: int) -> None:
+        for k in range(start, end):
+            if out[k] not in "\r\n":
+                out[k] = " "
+
+    while i < n:
+        c = source[i]
+        nxt = source[i + 1] if i + 1 < n else ""
+        if c == "/" and nxt == "/":
+            j = i
+            while j < n and source[j] not in "\r\n":
+                j += 1
+            blank(i, j)
+            i = j
+            continue
+        if c == "/" and nxt == "*":
+            j = source.find("*/", i + 2)
+            j = n if j < 0 else j + 2
+            blank(i, j)
+            i = j
+            continue
+        if c in "'\"":
+            j = i + 1
+            while j < n and source[j] != c and source[j] not in "\r\n":
+                if source[j] == "\\":
+                    j += 1
+                j += 1
+            blank(i + 1, min(j, n))
+            i = min(j + 1, n)
+            last_significant = c
+            continue
+        if c == "`":
+            i = _mask_template(source, out, i, template_depths)
+            last_significant = "`"
+            continue
+        if template_depths:
+            if c == "{":
+                template_depths[-1] += 1
+            elif c == "}":
+                if template_depths[-1] == 0:
+                    template_depths.pop()
+                    i = _mask_template(source, out, i, template_depths, resume=True)
+                    last_significant = "`"
+                    continue
+                template_depths[-1] -= 1
+        if c == "/" and (last_significant is None or last_significant in _REGEX_PRECEDERS or last_significant == "return"):
+            j = i + 1
+            in_class = False
+            while j < n and source[j] not in "\r\n":
+                ch = source[j]
+                if ch == "\\":
+                    j += 2
+                    continue
+                if in_class:
+                    if ch == "]":
+                        in_class = False
+                elif ch == "[":
+                    in_class = True
+                elif ch == "/":
+                    break
+                j += 1
+            blank(i + 1, min(j, n))
+            i = min(j + 1, n)
+            last_significant = "/"
+            continue
+        if not c.isspace():
+            if c.isalnum() or c in "_$":
+                k = i
+                while k < n and (source[k].isalnum() or source[k] in "_$"):
+                    k += 1
+                word = source[i:k]
+                last_significant = "return" if word == "return" else word[-1]
+                i = k
+                continue
+            last_significant = c
+        i += 1
+    return "".join(out)
+
+
+def _mask_template(source: str, out: list[str], start: int, depths: list[int], *, resume: bool = False) -> int:
+    """Blank a template literal from ``start`` (a backtick, or the ``}``
+    closing an expression when resuming). Returns the index after it."""
+    n = len(source)
+    i = start + 1
+    if resume:
+        out[start] = " "  # the ``}`` that closed the expression
+    while i < n:
+        c = source[i]
+        if c == "\\":
+            out[i] = " "
+            if i + 1 < n and source[i + 1] not in "\r\n":
+                out[i + 1] = " "
+            i += 2
+            continue
+        if c == "`":
+            return i + 1
+        if c == "$" and i + 1 < n and source[i + 1] == "{":
+            out[i] = " "
+            out[i + 1] = " "
+            depths.append(0)
+            return i + 2
+        if c not in "\r\n":
+            out[i] = " "
+        i += 1
+    return n
+
+
+def _matching(text: str, open_index: int) -> int:
+    """Index of the bracket closing the one at ``open_index``, or -1."""
+    pairs = {"(": ")", "[": "]", "{": "}", "<": ">"}
+    stack = [pairs[text[open_index]]]
+    i = open_index + 1
+    n = len(text)
+    while i < n:
+        c = text[i]
+        if c in pairs:
+            stack.append(pairs[c])
+        elif c in ")]}>":
+            if c == stack[-1]:
+                stack.pop()
+                if not stack:
+                    return i
+            elif c == ">":
+                pass  # an arrow or comparison inside a type; not a bracket
+            else:
+                return -1
+        i += 1
+    return -1
+
+
+def _skip_space(text: str, i: int) -> int:
+    n = len(text)
+    while i < n and text[i].isspace():
+        i += 1
+    return i
+
+
+def _body_after_signature(text: str, i: int) -> tuple[int, int] | None:
+    """Given ``i`` at ``(`` or ``<`` of a signature, find the body braces.
+
+    Returns (open_brace, close_brace) or None when there is no body (an
+    overload, an abstract method, a call).
+    """
+    if i < len(text) and text[i] == "<":
+        close = _matching(text, i)
+        if close < 0:
+            return None
+        i = _skip_space(text, close + 1)
+    if i >= len(text) or text[i] != "(":
+        return None
+    close = _matching(text, i)
+    if close < 0:
+        return None
+    i = _skip_space(text, close + 1)
+    if i < len(text) and text[i] == ":":
+        i = _skip_type(text, i + 1)
+    return _block_at(text, i)
+
+
+def _skip_type(text: str, i: int) -> int:
+    """Skip a type annotation, returning the index of the body's ``{`` or
+    ``len(text)`` when the signature has no body.
+
+    Types can contain braces (object types), so the first depth-zero ``{``
+    is not necessarily the body. What follows its matching ``}`` decides:
+    another ``{`` means the first was a type and the body comes next; a
+    type continuation (``|``, ``&``, ``[]``, ``=>``) means keep skipping;
+    a terminator (``;`` ``,`` ``)`` ``>`` ``=``) means the signature ended
+    without a body, as in an interface method returning ``{}``.
+    """
+    n = len(text)
+    depth = 0
+    while i < n:
+        c = text[i]
+        if c in "([<":
+            depth += 1
+        elif c in ")]>":
+            depth -= 1
+        elif c == "{" and depth == 0:
+            close = _matching(text, i)
+            if close < 0:
+                return n
+            after = _skip_space(text, close + 1)
+            following = text[after] if after < n else ""
+            if following == "{":
+                return after
+            if following in ("|", "&", "[") or text.startswith("=>", after):
+                i = close + 1
+                continue
+            if following in (";", ",", ")", ">", "="):
+                return n
+            return i
+        elif c == ";" and depth == 0:
+            return n
+        i += 1
+    return n
+
+
+def _block_at(text: str, i: int) -> tuple[int, int] | None:
+    if i >= len(text) or text[i] != "{":
+        return None
+    close = _matching(text, i)
+    if close < 0:
+        return None
+    return i, close
+
+
+def _is_unexplained_empty_block(original: str, masked: str, open_brace: int, close_brace: int) -> bool:
+    """Empty in the source itself, not merely empty once comments are blanked."""
+    return masked[open_brace + 1:close_brace].strip() == "" and original[open_brace + 1:close_brace].strip() == ""
+
+
+def _line_of(text: str, index: int) -> int:
+    return text.count("\n", 0, index) + 1
+
+
+def empty_functions(source: str) -> list[tuple[int, str]]:
+    """(line, name) for every function whose body does nothing."""
+    if any(len(line) > MINIFIED_LINE_LENGTH for line in source.split("\n")):
+        return []
+    original = source.replace("\r\n", "\n").replace("\r", "\n")
+    text = mask_source(original)
+    found: dict[int, tuple[int, str]] = {}
+
+    for match in _FUNCTION_DECL.finditer(text):
+        name = match.group(2) or _expression_name(text, match.start())
+        if name is None:
+            continue
+        body = _body_after_signature(text, match.end())
+        if body and _is_unexplained_empty_block(original, text, *body):
+            found.setdefault(body[0], (_line_of(text, match.start()), name))
+
+    for match in _METHOD_LINE.finditer(text):
+        name = match.group(2)
+        if name in NOT_A_METHOD or FRAMEWORK_HOOK.match(name):
+            continue
+        body = _body_after_signature(text, match.end())
+        if body and _is_unexplained_empty_block(original, text, *body):
+            found.setdefault(body[0], (_line_of(text, match.start(2)), name))
+
+    for match in _EXPORTED_ARROW.finditer(text):
+        name = match.group(1)
+        if NOOP_NAME.match(name):
+            continue
+        body = _arrow_body(text, match.end())
+        if body and _is_unexplained_empty_block(original, text, *body):
+            found.setdefault(body[0], (_line_of(text, match.start()), name))
+
+    return sorted(found.values())
+
+
+_EXPORT_DEFAULT_BEFORE = re.compile(r"export\s+default\s*$")
+_EXPORTED_BINDING_BEFORE = re.compile(r"\bexport\s+(?:const|let|var)\s+(" + _IDENT + r")\s*(?::[^=;]*)?=\s*$")
+
+
+def _expression_name(text: str, function_index: int) -> str | None:
+    """Name for an anonymous ``function`` expression, following the arrow
+    rule: ``export default`` and exported bindings count, callbacks and
+    local bindings do not, and an exported noop is exempt."""
+    before = text[max(0, function_index - 200):function_index]
+    if _EXPORT_DEFAULT_BEFORE.search(before):
+        return "default"
+    binding = _EXPORTED_BINDING_BEFORE.search(before)
+    if binding and not NOOP_NAME.match(binding.group(1)):
+        return binding.group(1)
+    return None
+
+
+def _arrow_body(text: str, i: int) -> tuple[int, int] | None:
+    """From just after an exported binding's name, the block of the arrow
+    function the binding is initialised with, or None when the initialiser
+    is not itself an arrow function (a call, a ternary, an object).
+
+    Shape accepted: ``[: type] = [async] [<generics>] (params) | ident
+    [: return type] => {``. Anything else is not this rule's business.
+    """
+    n = len(text)
+    depth = 0
+    while i < n:
+        c = text[i]
+        if c in "([{":
+            depth += 1
+        elif c in ")]}":
+            depth -= 1
+        elif c == ";" and depth == 0:
+            return None
+        elif c == "=" and depth == 0:
+            if text.startswith("=>", i):  # an arrow inside the binding's type annotation
+                i += 2
+                continue
+            break
+        i += 1
+    else:
+        return None
+    j = _skip_space(text, i + 1)
+    if text.startswith("async", j) and j + 5 < n and text[j + 5].isspace():
+        j = _skip_space(text, j + 5)
+    if j < n and text[j] == "<":
+        close = _matching(text, j)
+        if close < 0:
+            return None
+        j = _skip_space(text, close + 1)
+    if j < n and text[j] == "(":
+        close = _matching(text, j)
+        if close < 0:
+            return None
+        j = _skip_space(text, close + 1)
+    else:
+        ident = _IDENT_AT.match(text, j)
+        if not ident:
+            return None
+        j = _skip_space(text, ident.end())
+    if j < n and text[j] == ":":
+        arrow = _return_type_end(text, j + 1)
+        if arrow is None:
+            return None
+        j = arrow
+    if not text.startswith("=>", j):
+        return None
+    return _block_at(text, _skip_space(text, j + 2))
+
+
+def _return_type_end(text: str, i: int) -> int | None:
+    """Index of the ``=>`` that ends an arrow function's return type, or
+    None when the statement ends first."""
+    n = len(text)
+    depth = 0
+    while i < n:
+        c = text[i]
+        if text.startswith("=>", i):
+            if depth == 0:
+                return i
+            i += 2
+            continue
+        if c in "([{<":
+            depth += 1
+        elif c in ")]}>":
+            depth -= 1
+        elif c == ";" and depth == 0:
+            return None
+        i += 1
+    return None

countersign/pack.py

@@ -0,0 +1,243 @@
+# audited on 20260903
+"""The evidence pack: one self-contained HTML file per run.
+
+This is the artifact someone hands to someone else: a lead engineer
+reviewing an agent's pull request, an agency delivering to a client, an
+auditor asking what was actually checked. It has to say four things without
+being asked: what was checked, how, what was found, and what was not
+covered.
+
+It has no external assets, so it opens anywhere and prints to PDF from any
+browser.
+"""
+
+from __future__ import annotations
+
+import html
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__
+from .claims import PASS
+from .engine import FAIL_VERDICT, TEST_EXCLUSION_NOTE, GateResult
+from .plain import plain_sentences
+from .receipt import commit_label
+from .stubscan import RULES
+
+NOT_COVERED_ALWAYS: tuple[str, ...] = (
+    "This pack reports deterministic checks run in this repository, on this machine, at the "
+    "time stated. It is not a security audit, not a code review, and not a statement of "
+    "fitness for any purpose.",
+    "Only the claims declared in the claims file were verified. Anything nobody declared was "
+    "not checked.",
+    "Claim commands are the declaring team's own commands, run exactly as declared. Whether "
+    "they are deterministic, and whether they test what their statement says, is the team's "
+    "responsibility; Countersign records what they did.",
+    "Line exemptions are honored in the source itself and counted here. Each one is a human "
+    "decision that a finding was a false positive; audit them like any other review decision.",
+    "The register this pack cites lives on the machine that ran the checks. It proves that no "
+    "entry was altered after it was written by anyone who did not also rewrite every entry after "
+    "it. On its own that is evidence against accident and against third parties, not against "
+    "the machine's owner; evidence against the owner requires the register head to be anchored "
+    "outside the machine.",
+)
+
+NOT_COVERED_TESTS_EXCLUDED = (
+    "Test files were excluded from the marker scan by policy (exclude_tests = true): test "
+    "code legitimately fabricates data. Unfinished work inside test files was not looked for."
+)
+
+
+def _esc(value: object) -> str:
+    return html.escape(str(value))
+
+
+STYLE = """
+:root { color-scheme: light; }
+* { box-sizing: border-box; }
+body { margin: 0; padding: 48px; background: #E9E8E2; color: #121410;
+       font: 15px/1.55 "Helvetica Neue", Arial, sans-serif; }
+.sheet { max-width: 920px; margin: 0 auto; background: #F2F1EC; border: 1px solid #D3D2C8;
+         border-radius: 10px; padding: 40px; }
+h1 { font-size: 26px; letter-spacing: -0.02em; margin: 0 0 4px; }
+h2 { font-size: 13px; text-transform: uppercase; letter-spacing: 0.18em; color: #6E7168;
+     margin: 36px 0 12px; font-weight: 600; }
+.mono { font-family: "SFMono-Regular", Menlo, Consolas, monospace; font-size: 12px; }
+.faint { color: #6E7168; }
+.meta { display: grid; grid-template-columns: 210px 1fr; gap: 6px 16px; margin-top: 8px; }
+.meta span:nth-child(2n) { word-break: break-all; }
+table { width: 100%; border-collapse: collapse; margin-top: 8px; }
+th, td { text-align: left; padding: 9px 10px; border-bottom: 1px solid #D3D2C8; vertical-align: top; }
+th { font-size: 11px; text-transform: uppercase; letter-spacing: 0.14em; color: #6E7168; font-weight: 600; }
+tr:last-child td { border-bottom: none; }
+.verdict-pass { color: #1E5B41; font-weight: 700; }
+.verdict-fail { color: #C2402A; font-weight: 700; }
+.counts { display: flex; gap: 28px; margin-top: 10px; }
+.count b { display: block; font-size: 30px; letter-spacing: -0.02em; }
+.note { border-left: 3px solid #1E5B41; padding: 4px 0 4px 14px; margin-top: 10px; color: #3C3F38; }
+.chain { background: #E9E8E2; border: 1px solid #D3D2C8; border-radius: 6px; padding: 12px;
+         word-break: break-all; }
+footer { max-width: 920px; margin: 18px auto 0; color: #6E7168; font-size: 12px; }
+@media print { body { padding: 0; background: #fff; } .sheet { border: none; background: #fff; } }
+"""
+
+
+def _esc_lines(items: tuple[str, ...]) -> str:
+    return "\n".join(f"  <li>{_esc(item)}</li>" for item in items)
+
+
+def build_pack(result: GateResult, path: Path) -> Path:
+    generated = datetime.now(timezone.utc)
+    verdict_class = "verdict-pass" if result.verdict != FAIL_VERDICT else "verdict-fail"
+    verdict_word = "COUNTERSIGNED" if result.verdict != FAIL_VERDICT else "NOT COUNTERSIGNED"
+
+    finding_rows = "\n".join(
+        f"""<tr>
+              <td class="mono">{_esc(f.path)}:{_esc(f.line)}</td>
+              <td class="mono">{_esc(f.rule_id)}</td>
+              <td>{_esc(f.why)}</td>
+              <td class="mono faint">{_esc(f.evidence)}</td>
+            </tr>"""
+        for f in result.findings
+    ) or '<tr><td colspan="4" class="faint">No marker findings.</td></tr>'
+
+    if result.claim_results is None:
+        claim_rows = '<tr><td colspan="5" class="faint">The claims check was skipped, not passed. The notes below say why.</td></tr>'
+    else:
+        claim_rows = "\n".join(
+            f"""<tr>
+                  <td class="mono {_esc('verdict-pass' if c.status == PASS else 'verdict-fail')}">{_esc(c.status.upper())}</td>
+                  <td>{_esc(c.statement)}</td>
+                  <td class="mono">{_esc(c.command or 'none declared')}</td>
+                  <td class="mono">{_esc(c.exit_code if c.exit_code is not None else 'n/a')}</td>
+                  <td class="mono faint">{_esc(f"{c.duration_ms} ms")}</td>
+                </tr>"""
+            for c in result.claim_results
+        )
+
+    method_rows = "\n".join(
+        f"""<tr>
+              <td class="mono">{_esc(rule.rule_id)}</td>
+              <td>{_esc(rule.why)}</td>
+              <td class="mono">{_esc(len([f for f in result.findings if f.rule_id == rule.rule_id]))}</td>
+            </tr>"""
+        for rule in RULES
+    ) + """
+        <tr><td class="mono">empty-body</td><td>functions whose body does nothing and explains nothing: a bare pass, ellipsis or empty braces with no docstring or comment (structural: Python via ast, TypeScript and JavaScript via a comment-and-string-aware scan)</td>
+            <td class="mono">{}</td></tr>
+        <tr><td class="mono">unparseable</td><td>Python files the parser rejects (Python, structural)</td>
+            <td class="mono">{}</td></tr>
+        <tr><td class="mono">claims</td><td>each declared claim's disproof command was executed and judged as declared; a claim the config requires but the file omits counts as failed</td>
+            <td class="mono">{}</td></tr>
+        <tr><td class="mono">claims-diff</td><td>claims compared with the base revision, when one was given; weakened claims counted here</td>
+            <td class="mono">{}</td></tr>
+      """.format(
+        len([f for f in result.findings if f.rule_id == "empty-body"]),
+        len([f for f in result.findings if f.rule_id == "unparseable"]),
+        len(result.failed_claims),
+        len(result.weakened_claims) if result.claims_diff is not None else "n/a",
+    )
+
+    if result.claims_diff is None:
+        diff_section = ""
+    else:
+        diff_rows = "\n".join(
+            f"""<tr>
+                  <td class="mono">{_esc(c.claim_id)}</td>
+                  <td class="mono">{_esc(c.kind)}</td>
+                  <td class="mono {_esc('verdict-fail' if c.weakened else '')}">{_esc('YES' if c.weakened else 'no')}</td>
+                  <td class="mono faint">{_esc(c.detail)}</td>
+                </tr>"""
+            for c in result.claims_diff
+        ) or '<tr><td colspan="4" class="faint">No claim changed.</td></tr>'
+        diff_section = f"""
+<h2>Claims changed against {_esc(result.claims_base)}</h2>
+<p class="faint">The claims file was compared with the one at the base revision. A removed claim, a
+changed expectation or a changed needle is a weakening; a changed command is listed for review.</p>
+<table>
+  <tr><th>Claim</th><th>Change</th><th>Weakened</th><th>Detail</th></tr>
+  {diff_rows}
+</table>
+"""
+    plain = "\n".join(f"  <li>{_esc(sentence)}</li>" for sentence in plain_sentences(result))
+    not_covered = NOT_COVERED_ALWAYS + ((NOT_COVERED_TESTS_EXCLUDED,) if result.tests_excluded else ())
+    # The test exclusion is stated in the not-covered list above when it
+    # applies, so the run note that says the same thing is not repeated.
+    notes = "\n".join(f"  <li>{_esc(note)}</li>" for note in result.notes if note != TEST_EXCLUSION_NOTE)
+
+    document = f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>Countersign evidence pack, {_esc(result.run_id)}</title>
+<style>{STYLE}</style></head>
+<body><div class="sheet">
+
+<p class="mono faint">COUNTERSIGN · EVIDENCE PACK</p>
+<h1>Agent work verification</h1>
+<p class="{verdict_class} mono" style="font-size:18px; letter-spacing:0.08em;">{verdict_word}</p>
+
+<div class="meta mono">
+  <span class="faint">Run reference</span><span>{_esc(result.run_id)}</span>
+  <span class="faint">Git commit</span><span>{_esc(commit_label(result))}</span>
+  <span class="faint">Generated</span><span>{generated:%d %b %Y %H:%M} UTC</span>
+  <span class="faint">Countersign version</span><span>{_esc(__version__)}</span>
+  <span class="faint">Files scanned</span><span>{_esc(result.files_scanned)}</span>
+  <span class="faint">Config (SHA-256)</span><span>{_esc(result.config_sha256)}</span>
+  <span class="faint">Claims file (SHA-256)</span><span>{_esc(result.claims_sha256 or 'none read; the claims check was skipped')}</span>
+</div>
+
+<h2>In plain words</h2>
+<ul>
+{plain}
+</ul>
+
+<h2>What was found</h2>
+<div class="counts">
+  <div class="count"><b class="verdict-fail">{len(result.findings)}</b><span class="mono faint">MARKER FINDINGS</span></div>
+  <div class="count"><b>{result.exemptions}</b><span class="mono faint">EXEMPTIONS USED</span></div>
+  <div class="count"><b class="verdict-fail">{len(result.failed_claims)}</b><span class="mono faint">FAILED CLAIMS</span></div>
+</div>
+<table>
+  <tr><th>Location</th><th>Rule</th><th>Why it is a problem</th><th>Evidence</th></tr>
+  {finding_rows}
+</table>
+
+<h2>Claims, as declared and as judged</h2>
+<table>
+  <tr><th>Status</th><th>Claim</th><th>Disproof command</th><th>Exit</th><th>Duration</th></tr>
+  {claim_rows}
+</table>
+
+{diff_section}
+<h2>How it was checked</h2>
+<table>
+  <tr><th>Check</th><th>What it detects</th><th>Findings</th></tr>
+  {method_rows}
+</table>
+<p class="note">The marker scan is deterministic and re-runnable: the same files under the same
+rule versions give the same findings. Claims were run exactly as declared and judged only by
+exit code or output, as declared. No model judgement participates in any verdict on this pack.</p>
+
+<h2>What this pack does not cover</h2>
+<ul>
+{_esc_lines(not_covered)}
+</ul>
+{f'<ul>{notes}</ul>' if notes else ''}
+
+<h2>Integrity and reproducibility</h2>
+<p class="faint">Every check, finding and claim verdict was written to an append-only register,
+each entry sealed against the one before it. The run recorded the SHA-256 of the config and
+claims files it read, so the same run can be re-derived later from the same files and compared
+result for result with <span class="mono">countersign reproduce</span>.</p>
+<div class="chain mono">
+  <div>Register entry: {_esc(result.register_index)}</div>
+  <div>Head: {_esc(result.register_hash)}</div>
+</div>
+
+</div>
+<footer class="mono">Countersign {_esc(__version__)} · run inside this repository's own environment · Countersign itself made no network requests; claim commands are the declaring team's own</footer>
+</body></html>"""
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(document, encoding="utf-8")
+    return path