wicked-garden 12.34.0 → 12.35.0

package/.claude-plugin/components.json

@@ -2,7 +2,7 @@
   "_comment": "Issue #328: Component declarations for wicked-garden plugin. Claude Code plugin.json does not yet support inline component declarations beyond path overrides. This manifest documents all components for tooling, validation, and future schema support. When plugin.json gains a 'components' field, merge this data into plugin.json. The plugin is skills-only: former commands/ became actions of consolidated per-domain skills, and former agents/ became standalone context:fork worker skills (enumerated under fork_skills). Regenerate derived blocks with scripts/ci/sync_components.py.",
   "domains": ["agentic", "crew", "data", "engineering", "jam", "mem", "persona", "platform", "product", "qe", "search", "smaht"],
   "summary": {
-    "skills": 142,
+    "skills": 143,
     "fork_skills": 78,
     "hooks": 13,
     "specialists": 7
@@ -25,6 +25,7 @@
     "domain-coverage": ["domain-coverage"],
     "domain-extractor": ["domain-extractor"],
     "domain-modeler": ["domain-modeler"],
+    "draft": ["draft"],
     "engineering": ["architecture", "backend", "debugging", "docs", "engineering", "frontend", "integration", "large-scale-migration", "patch", "system-design", "unit-test-quality"],
     "engineering-api-documentarian": ["engineering-api-documentarian"],
     "engineering-conformance-reviewer": ["engineering-conformance-reviewer"],

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.34.0"}], "version": "12.34.0"}
+{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.35.0"}], "version": "12.35.0"}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.34.0",
+  "version": "12.35.0",
   "description": "Your coding agent's harness already plans and swarms; Wicked Garden is the curated toolkit for what it can't do alone. Proof, not claims \u2014 gates re-derive 'done' through the internal loom engine (fail-closed, independently attested via wicked-vault), so a self-asserted pass can't lie its way green. Relationships grep can't see \u2014 the wicked-estate code graph + injected bus/dispatch/capability/archetype edges power blast-radius & lineage. Plus deterministic multi-file refactor (wicked-patch), cross-session memory + knowledge (the mem domain over wicked-estate), real multi-model second opinions (jam:council), portable expertise as on-demand skill-refs, and evidence-gated testing (the in-catalog qe domain). It reads the shape of your work to apply the right rigor \u2014 steering, not a pipeline \u2014 then gets out of the way. The compiler stamps a self-contained evidence gate into any repo that runs with no wicked-garden installed. Don't fight the harness; fill its gaps. The evidence gate requires wicked-vault, a self-contained infra peer wicked-garden installs directly; wicked-bus is an opt-in layer \u2014 install what you'll use, the toolkit works without the rest.",
   "wicked_vault_version": "^0.5.0",
   "wicked_ledger_version": "^0.4.0",

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [12.35.0] — 2026-09-13
+
+### Added
+- **`wicked-garden-draft` — the quality floor for document deliverables: contrast ≥ 4.5:1, an honoured page budget, cited claims and no placeholders (F-RECON-007/008/009).** The 2026-09 recon ran a governed brochure draft end to end through the studio and the deliverable that landed was unreadable, over-long and partly invented: the hero fact strip, footer requirements and KPI label rendered `rgba(255,255,255,0.14)`-class text on a `#1a1a26` card (≈1.5:1 — invisible in the PNG and the PDF; F-RECON-007), a "two pages" brief printed as **four** A4 pages because two `.page` wrappers each overflowed their sheet (F-RECON-008), and the copy carried an invented "live instance" URL claim, a command-center mock whose figures were called illustrative only inside an HTML comment, and a visible `[PLACEHOLDER: Customer validation]` box (F-RECON-009) — while every gate auto-allowed and the run's deliverable floor proved only that the file existed. Neither garden nor crew carried a document-drafting skill (crew's `interactive-draft` phases have `skill_ref: null`; the contract was inlined prose adapted from wicked-interactive's assist skill), so nothing re-derived any of it. **New top-level skill `skills/draft/`** (user-invocable; `refs/design-floor.md`, `refs/claims.md`, `refs/self-check.md`): design guidance for the three floors — READABLE (every text/background pair ≥ 4.5:1, 3:1 for large text, judged on the COMPOSITED colours; print text ≥ 7pt — thin 6–7pt type never reaches full pixel coverage, which is why the 4.9:1 fact strip still read as grey), SIZED TO THE BRIEF (the RENDERED page count meets the budget the brief names, default = exactly as asked, any format cap disclosed, wrappers are not pages), GROUNDED (every number/URL cites a repo path via `data-source="path:line"` plus a visible Sources strip, mocks carry `data-illustrative` AND a visible label, no placeholder ever ships — gaps go to the notes) — **and one mandatory self-check** the author runs on the saved file before "done", with a `PASS` / `FAIL` / `UNVERIFIED` verdict that is pasted into the reply, never paraphrased. **Runtime (`scripts/draft/`, stdlib-only, reachable as `wicked-garden run scripts/draft/…`)**: `contrast_check.py` cascades the document's own CSS (specificity, source order, inline, `!important`, `var()` with inheritance — including `:root` tokens when the instrumented deliverable has no `<html>` element — `@media print|screen`, alpha compositing over the real background, `opacity`, every gradient stop) and judges every text-bearing element; `page_count.py` reads the rendered count from an exported PDF (page-tree `/Count`, object streams inflated) or a headless-Chrome print (`--render`; `$WICKED_CHROME`), and otherwise reports the structural estimate as **UNVERIFIED (exit 3)** — never a pass; `claims_scan.py` scans the VISIBLE text for placeholders, uncited numbers, uncited/unsourced URLs (bare domains included), hidden or missing mock labels and, with `--repo`, dangling `data-source` paths and URLs no source mentions; `self_check.py` runs all three and exits 0/1/3. Against the recon's landed v1 (kept as `tests/draft/fixtures/recon-brochure-v1.html`) the checks reproduce the findings exactly — footer `.cta-reqs` and `.mockup-kpi-label` at 1.53:1, the 6.8pt fact strip under the size floor, the accent violet at 3.7:1 on cards, 4 PDF pages vs budget 2, the placeholder, the `3 active · 1 needs you` hidden-label mock, the uncited 2 s / 3 s latencies — and pass the same document once the tokens are lifted and the claims cited (`tests/draft/`, 60+ tests: colour maths, cascade, media modes, PDF page trees incl. object streams, a fake-Chrome render path, the citation forms, CLI exit codes). Cross-CLI per the 12.33 convention (skill-relative refs, the exact `## Runtime` block, no Claude-only mechanics; `tests/portability_rules.garden.json` gains quiet/trip corpus entries for the new launcher lines). The core help overview, `components.json` and the site's honest counts move to 143 skills (`draft` folded into the product & UX group). **Hardened after the independent review (same wave):** shrink-to-fit is judged, not rewarded — `zoom`, `transform: scale()`/`matrix()` and `scale:` on any ancestor multiply into the EFFECTIVE text size the 7pt floor is applied to (the reviewer's `body{zoom:.62}` on a corrected brochure went from a full `PASS` at ≈4.3pt to `FAIL`), an unevaluable transform makes the size UNVERIFIED, and the skill text forbids scaling a page to meet a budget; unsupported colour functions (`oklch()`, `lab()`, `color-mix()`, `light-dark()`…) and image-only backgrounds are reported as `[unknown]` UNVERIFIED pairs (exit 3) instead of silently inheriting or being judged "on white"; `@media not print|screen` is evaluated correctly (it was inverted); inline `!important` sits at the top of the cascade; `--mode both` reports a pair once (`print+screen`); colour-declaring rules with selectors the matcher skips (`:nth-child`, `:is`…) leave a note instead of vanishing; the CLIs never crash on a cp1252 console (Windows piped stdout — `errors="replace"`); `page_count.py` fails (exit 1) before it reports unverified when even the estimate exceeds the budget, ignores a forced break on the last element, refuses a `--pdf` path that does not exist (no silent render), and prints offline (`--host-resolver-rules=MAP * ~NOTFOUND`); `claims_scan.py` no longer flags prose dates, numbered headings, `Step N`/`Page N of M` and lone badge numerals; the skill spells out the two "done" states (`PASS`, or `UNVERIFIED` with a disclosure naming which check, why on this seat, and what a reviewer verifies — the check prints the `DISCLOSE` lines) and that `FAIL` is never done; `refs/design-floor.md` ratios recomputed with the module (`#94a3b8` on white is 2.6:1, not 3.2). **Follow-ups (other repos):** wicked-crew's `interactive-draft` / `-edit` / `-chat` phases should set `skill_ref: 'wicked-garden-draft'` and pass the budget/snapshot to the self-check, and the deliverable floor could run `self_check.py` as a deterministic tool phase; wicked-interactive's assist skill Step 5 can point at the same floor.
+
 ## [12.34.0] — 2026-09-11
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.34.0",
+  "version": "12.35.0",
   "type": "module",
   "description": "Curated toolkit for what AI coding agents can't do alone: evidence-gated work, codegraph relationships, deterministic multi-file refactor, multi-model second opinions, and cross-session memory. Installs as a Claude Code plugin.",
   "keywords": [

package/scripts/draft/__init__.py

@@ -0,0 +1,13 @@
+"""wicked-garden `draft` runtime — the self-checks behind the `wicked-garden-draft` skill.
+
+Stdlib-only. Every module is both importable (pure functions the tests drive) and a CLI the
+skill invokes through the launcher (`wicked-garden run scripts/draft/<x>.py …`):
+
+* ``contrast_check``  — WCAG contrast (and a minimum print size) for every text-bearing element,
+                        resolved from the document's own CSS (custom properties, alpha, media).
+* ``page_count``      — rendered page count of a PDF (or a Chrome print of the HTML) against the
+                        brief's page budget; a structural estimate when nothing can render.
+* ``claims_scan``     — placeholders, uncited numbers, hidden mock labels, dangling
+                        ``data-source`` paths and unsourced URLs in the visible text.
+* ``self_check``      — the one command the worker runs before "done": all three, one verdict.
+"""

package/scripts/draft/_dom.py

@@ -0,0 +1,188 @@
+"""A tiny DOM for the draft self-checks — stdlib ``html.parser`` only.
+
+The checks need three things from a self-contained HTML deliverable: the element tree (with
+attributes), the ``<style>`` text in document order, and "which elements carry visible text".
+That is all this module does; it is deliberately not a browser. Void elements are closed
+immediately; unbalanced closing tags are tolerated (the nearest open ancestor with that tag is
+closed), so a slightly malformed draft still yields a usable tree instead of an exception.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+from typing import Iterator
+
+VOID_TAGS = frozenset(
+    "area base br col embed hr img input link meta param source track wbr".split()
+)
+# Elements whose text is never rendered to the reader.
+NON_RENDERED_TAGS = frozenset("script style template noscript title head meta link".split())
+_WS = re.compile(r"\s+")
+
+
+@dataclass(eq=False)  # identity semantics — a structural __eq__ would recurse through children
+class Node:
+    tag: str  # "" for the document root, "#text" for text, "#comment" for comments
+    attrs: dict[str, str] = field(default_factory=dict)
+    children: list["Node"] = field(default_factory=list)
+    parent: "Node | None" = None
+    text: str = ""  # #text / #comment payload
+
+    # ── tree helpers ────────────────────────────────────────────────────────────────────────
+    def ancestors(self) -> Iterator["Node"]:
+        node = self.parent
+        while node is not None and node.tag != "":
+            yield node
+            node = node.parent
+
+    def element_children(self) -> list["Node"]:
+        return [c for c in self.children if not c.tag.startswith("#")]
+
+    def classes(self) -> list[str]:
+        return self.attrs.get("class", "").split()
+
+    def direct_text(self) -> str:
+        """The element's own text (not descendants'), whitespace-collapsed."""
+        parts = [c.text for c in self.children if c.tag == "#text"]
+        return _WS.sub(" ", "".join(parts)).strip()
+
+    def all_text(self) -> str:
+        """The visible text of this element and its descendants, whitespace-collapsed."""
+        out: list[str] = []
+        for node in self.walk():
+            if node.tag == "#text":
+                out.append(node.text)
+        return _WS.sub(" ", " ".join(out)).strip()
+
+    def walk(self) -> Iterator["Node"]:
+        yield self
+        for child in self.children:
+            yield from child.walk()
+
+    def path(self) -> str:
+        """A readable locator: ``section.page.page-1 > div.fact-strip > span``."""
+        chain: list[str] = []
+        node: Node | None = self
+        while node is not None and node.tag != "":
+            if node.tag.startswith("#"):
+                node = node.parent
+                continue
+            label = node.tag
+            if "id" in node.attrs and node.attrs["id"]:
+                label += "#" + node.attrs["id"]
+            label += "".join("." + c for c in node.classes()[:3])
+            chain.append(label)
+            node = node.parent
+        return " > ".join(reversed(chain))
+
+    def preceding_comments(self) -> list[str]:
+        """Comments immediately before this element among its siblings (whitespace between
+        is fine) — where a draft tends to hide an "illustrative" label."""
+        if self.parent is None:
+            return []
+        out: list[str] = []
+        siblings = self.parent.children
+        idx = siblings.index(self)
+        for sib in reversed(siblings[:idx]):
+            if sib.tag == "#comment":
+                out.append(sib.text)
+            elif sib.tag == "#text" and not sib.text.strip():
+                continue
+            else:
+                break
+        return out
+
+
+class _Builder(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.root = Node(tag="")
+        self.cursor = self.root
+        self.styles: list[str] = []
+        self._in_style = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        node = Node(tag=tag, attrs={k.lower(): (v or "") for k, v in attrs}, parent=self.cursor)
+        self.cursor.children.append(node)
+        if tag in VOID_TAGS:
+            return
+        self.cursor = node
+        self._in_style = tag == "style"
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        node = Node(tag=tag, attrs={k.lower(): (v or "") for k, v in attrs}, parent=self.cursor)
+        self.cursor.children.append(node)
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.lower()
+        if tag in VOID_TAGS:
+            return
+        node: Node | None = self.cursor
+        while node is not None and node.tag != "":
+            if node.tag == tag:
+                self.cursor = node.parent or self.root
+                self._in_style = False
+                return
+            node = node.parent
+        # stray closing tag — ignore
+
+    def handle_data(self, data: str) -> None:
+        if self.cursor.tag == "style":
+            self.styles.append(data)
+        self.cursor.children.append(Node(tag="#text", text=data, parent=self.cursor))
+
+    def handle_comment(self, data: str) -> None:
+        self.cursor.children.append(Node(tag="#comment", text=data, parent=self.cursor))
+
+
+@dataclass
+class Document:
+    root: Node
+    styles: list[str]
+
+    def elements(self) -> Iterator[Node]:
+        for node in self.root.walk():
+            if node.tag and not node.tag.startswith("#"):
+                yield node
+
+    def find_all(self, tag: str) -> list[Node]:
+        return [n for n in self.elements() if n.tag == tag]
+
+    def inline_style_text(self) -> str:
+        return "\n".join(self.styles)
+
+
+def parse(html: str) -> Document:
+    builder = _Builder()
+    builder.feed(html)
+    builder.close()
+    return Document(root=builder.root, styles=builder.styles)
+
+
+def is_rendered(node: Node) -> bool:
+    """False when the element or an ancestor is never shown to the reader (head/script/style,
+    the ``hidden`` attribute, ``aria-hidden`` is NOT enough — sighted readers still see it)."""
+    chain = [node, *node.ancestors()]
+    for n in chain:
+        if n.tag in NON_RENDERED_TAGS:
+            return False
+        if "hidden" in n.attrs:
+            return False
+    return True
+
+
+def text_elements(doc: Document) -> Iterator[Node]:
+    """Rendered elements carrying their OWN non-blank text (the unit a contrast or claims check
+    judges — a ``<span>`` inside a ``<p>`` is its own element with its own colour)."""
+    for node in doc.elements():
+        if node.tag == "br":
+            continue
+        if not node.direct_text():
+            continue
+        if not is_rendered(node):
+            continue
+        yield node

package/scripts/draft/claims_scan.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""claims_scan.py — claims discipline for a document deliverable: no placeholders, every number
+and URL traceable to a source, every mock visibly labelled.
+
+F-RECON-009: a governed brochure shipped a visible ``[PLACEHOLDER: Customer validation]`` box, a
+"live instance" URL claim the sources contradict, and a command-center mock whose KPIs were called
+"illustrative" only inside an HTML comment. Grounding prose in the prompt did not prevent any of
+it; a scan of the *visible text* before "done" would have caught all three.
+
+What counts as CITED (the convention the `wicked-garden-draft` skill asks the author to follow):
+  * the element — or an ancestor — carries ``data-source="<repo-relative path>[:line]"``
+    (several sources: separate with spaces or commas);
+  * or the same text block names a repo path inline, e.g. ``(README.md:87)``;
+  * or the block carries a footnote marker (``[3]``, ``<sup>``) AND the document has a sources
+    block (``data-sources``, or a heading/element whose text starts with "Sources") that lists
+    repo paths.
+A MOCK/ILLUSTRATION is fine when its container carries ``data-illustrative`` AND a reader can see
+the label (the word "illustrative", "example", "mock", "sample" or "hypothetical" inside that
+container). A label that lives only in an HTML comment is the F-RECON-009 defect and is reported.
+
+Findings (all fail the floor): ``placeholder`` · ``uncited-number`` · ``mock-label-hidden`` ·
+``mock-unlabelled`` · ``dangling-source`` (``data-source`` path missing under ``--repo``) ·
+``unsourced-url`` (a URL in the visible text that no file under ``--repo`` mentions) ·
+``uncited-url`` (a URL with no ``--repo`` to check against and no ``data-source``).
+Exit: 0 clean, 1 findings, 2 usage / unreadable input. Stdlib only.
+
+CLI:
+    claims_scan.py <file.html> [--repo <dir> …] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+if __package__ in (None, ""):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from draft._dom import Document, Node, is_rendered, parse  # noqa: E402
+
+PLACEHOLDER_RE = re.compile(
+    r"\[\s*PLACEHOLDER\b|\bPLACEHOLDER\s*:|\bTODO\b|\bTBD\b|\bFIXME\b|\bTK\b(?![\w-])|"
+    r"\blorem\s+ipsum\b|\bLorem\b|\{\{[^}]*\}\}|\[\s*INSERT\b|<\s*insert\b|\[\s*(?:add|your|company|client)\s+[^\]]{0,40}(?:here|name)\s*\]",
+    re.IGNORECASE)
+# a repo path: at least one slash or a known doc/code extension, optional :line
+PATH_RE = re.compile(
+    r"(?<![\w/@:.-])((?:[\w.-]+/)*[\w.-]+\.(?:md|mdx|txt|rst|adoc|json|ya?ml|toml|ts|tsx|js|mjs|cjs|py|rs|go|java|kt|cs|rb|php|sh|html|css|sql|proto|csv|ipynb|lock)(?::\d+(?:-\d+)?)?)(?![\w/])",
+    re.IGNORECASE)
+# a URL with a scheme, or a bare domain on a common TLD (`ws.wickedagile.com`) — a file name's
+# extension (README.md, server.ts) is not a TLD in this list, so paths never match.
+URL_RE = re.compile(
+    r"https?://[^\s<>\"')\]]+|"
+    r"(?<![\w@/.-])(?:[a-z0-9-]+\.)+(?:com|org|net|io|dev|ai|app|co|cloud|sh|tech|info|biz|eu|uk|de|fr|us|ca|au)\b"
+    r"(?:/[^\s<>\"')\]]*)?",
+    re.IGNORECASE)
+NUMBER_RE = re.compile(r"(?<![\w.,:/#-])(\d+(?:[.,]\d+)*)(?![\w/:-])")
+FOOTNOTE_RE = re.compile(r"\[\d{1,3}\]|[†‡§¶]|\^\d{1,3}")
+LABEL_RE = re.compile(r"\b(illustrative|illustration|example|mock(?:-?up)?|sample|hypothetical|not (?:real|measured)|for illustration)\b", re.IGNORECASE)
+COPYRIGHT_YEAR_RE = re.compile(r"(?:©|\(c\)|copyright)\s*\d{4}", re.IGNORECASE)
+ORDINAL_RE = re.compile(r"^0\d$")  # "01", "02" — section numbering, not a claim
+# L2 — number tokens that are structure, not claims: prose dates ("September 12, 2026", "Sep 2026",
+# "2026 roadmap" → the year next to a month word), numbered headings ("1. Readable"), "Step 1",
+# page footers ("Page 1 of 2", "1 / 2"), and a lone 1–2 digit number that is an element's whole text
+_MONTH = r"(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?"
+STRUCTURE_RES = [
+    re.compile(rf"\b{_MONTH}\s+\d{{1,2}}(?:st|nd|rd|th)?,?\s+\d{{4}}\b", re.IGNORECASE),  # September 12, 2026
+    re.compile(rf"\b\d{{1,2}}(?:st|nd|rd|th)?\s+{_MONTH},?\s+\d{{4}}\b", re.IGNORECASE),   # 12 Sep 2026
+    re.compile(rf"\b{_MONTH}\s+\d{{4}}\b", re.IGNORECASE),                                # Sep 2026
+    re.compile(r"\b(?:19|20)\d{2}\s+(?:roadmap|edition|release|plan|report|review|q[1-4])\b", re.IGNORECASE),
+    re.compile(r"\b(?:q[1-4]|h[12]|fy)\s*(?:19|20)?\d{2}\b", re.IGNORECASE),               # Q3 2026 / FY26
+    re.compile(r"^\s*\d{1,3}[.)]\s+(?=\S)"),                                                # "1. Readable"
+    re.compile(r"\b(?:step|phase|part|chapter|section|figure|fig\.|table|slide|page|pg\.)\s+\d{1,3}(?:\s+of\s+\d{1,3})?\b", re.IGNORECASE),
+    re.compile(r"^\s*\d{1,3}\s*/\s*\d{1,3}\s*$"),                                            # "1 / 2" footer
+]
+LONE_ORDINAL_RE = re.compile(r"^\d{1,2}$")
+SOURCE_ATTRS = ("data-source", "data-sources", "data-src-path", "data-cite")
+SKIP_DIRS = {".git", "node_modules", ".venv", "target", "dist", "build", "__pycache__", ".next"}
+
+
+@dataclass
+class Finding:
+    kind: str
+    path: str
+    text: str
+    detail: str
+
+    def as_dict(self) -> dict:
+        return {"kind": self.kind, "path": self.path, "text": self.text, "detail": self.detail}
+
+
+def _sources_on(node: Node) -> list[str]:
+    out: list[str] = []
+    for n in [node, *node.ancestors()]:
+        for attr in SOURCE_ATTRS:
+            v = n.attrs.get(attr, "").strip()
+            if v:
+                out.extend(re.split(r"[\s,;]+", v))
+    return [s for s in out if s]
+
+
+def _illustrative_container(node: Node) -> Node | None:
+    for n in [node, *node.ancestors()]:
+        if "data-illustrative" in n.attrs or "data-mock" in n.attrs:
+            return n
+    return None
+
+
+def _has_sources_block(doc: Document) -> bool:
+    for el in doc.elements():
+        if "data-sources" in el.attrs and PATH_RE.search(el.all_text()):
+            return True
+        txt = el.direct_text()
+        if txt and re.match(r"^(sources?|references?|grounding)\b", txt, re.IGNORECASE):
+            container = el.parent if el.parent is not None else el
+            if PATH_RE.search(container.all_text()):
+                return True
+    return False
+
+
+def _claim_blocks(doc: Document) -> list[Node]:
+    """Block-level text units: the nearest element with own text whose parent is not itself a
+    text-only inline wrapper — practically: every rendered element with own text, but a span's
+    numbers are judged with its parent block's text so an inline citation counts."""
+    return [el for el in doc.elements() if el.direct_text() and is_rendered(el) and el.tag != "br"]
+
+
+_INLINE_TAGS = frozenset("span b strong i em u small sup sub code a abbr mark time s del ins q cite kbd var".split())
+
+
+def _block_of(node: Node) -> Node:
+    n = node
+    while n.parent is not None and n.parent.tag != "" and n.tag in _INLINE_TAGS:
+        n = n.parent
+    return n
+
+
+def _nearby_comments(el: Node, block: Node) -> list[str]:
+    """HTML comments a reader never sees but an author may have used as the only label of a
+    mock: comments anywhere inside the block (or its parent) and comments immediately preceding
+    the element or any of its ancestors up to three levels."""
+    out: list[str] = [n.text for n in block.walk() if n.tag == "#comment"]
+    node: Node | None = el
+    for _ in range(4):
+        if node is None or node.tag == "":
+            break
+        out.extend(node.preceding_comments())
+        node = node.parent
+    return out
+
+
+def _repo_files(repos: list[str]) -> list[Path]:
+    files: list[Path] = []
+    for repo in repos:
+        root = Path(repo)
+        if not root.is_dir():
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+            for fn in filenames:
+                p = Path(dirpath) / fn
+                try:
+                    if p.stat().st_size <= 2_000_000:
+                        files.append(p)
+                except OSError:
+                    continue
+    return files
+
+
+def _path_exists_in_repos(rel: str, repos: list[str]) -> bool:
+    rel_path = rel.split(":")[0]
+    for repo in repos:
+        if (Path(repo) / rel_path).exists():
+            return True
+    return False
+
+
+def _url_in_repos(url: str, files: list[Path]) -> bool:
+    needle = url.rstrip("/.,;").lower()
+    bare = re.sub(r"^https?://(www\.)?", "", needle)
+    for f in files:
+        try:
+            text = f.read_text(encoding="utf-8", errors="ignore").lower()
+        except OSError:
+            continue
+        if needle in text or bare in text:
+            return True
+    return False
+
+
+def scan_document(html: str, repos: list[str] | None = None) -> tuple[list[Finding], dict]:
+    repos = [r for r in (repos or []) if Path(r).is_dir()]
+    doc = parse(html)
+    findings: list[Finding] = []
+    seen: set[tuple] = set()
+    has_sources = _has_sources_block(doc)
+    repo_files = _repo_files(repos) if repos else []
+    stats = {"blocks": 0, "numbers": 0, "urls": 0, "cited_numbers": 0, "sources_block": has_sources,
+             "repos": repos}
+
+    def add(kind: str, node: Node, text: str, detail: str) -> None:
+        key = (kind, node.path(), text[:60])
+        if key in seen:
+            return
+        seen.add(key)
+        findings.append(Finding(kind, node.path(), text[:100], detail))
+
+    checked_sources: set[str] = set()
+    for el in _claim_blocks(doc):
+        stats["blocks"] += 1
+        own = el.direct_text()
+        if PLACEHOLDER_RE.search(own):
+            add("placeholder", el, own, "placeholder text is visible in the deliverable — move the gap to the notes/reply, never into the document")
+        block = _block_of(el)
+        block_text = block.all_text()
+        sources = _sources_on(el)
+        for s in sources:
+            if repos and s not in checked_sources:
+                checked_sources.add(s)
+                if not _path_exists_in_repos(s, repos):
+                    add("dangling-source", el, s, "data-source names a path that does not exist under --repo")
+        inline_paths = PATH_RE.findall(block_text)
+        cited = bool(sources) or bool(inline_paths) or (has_sources and bool(FOOTNOTE_RE.search(block_text)))
+        illustrative = _illustrative_container(el)
+        labelled = illustrative is not None and bool(LABEL_RE.search(illustrative.all_text()))
+
+        # URLs
+        for url in URL_RE.findall(own):
+            stats["urls"] += 1
+            if repos:
+                if not _url_in_repos(url, repo_files):
+                    add("unsourced-url", el, url, "no file under --repo mentions this URL — an invented or misremembered address")
+            elif not cited:
+                add("uncited-url", el, url, "URL with no data-source and no repo to check it against")
+
+        # numbers
+        text_wo_paths = PATH_RE.sub(" ", URL_RE.sub(" ", own))
+        text_wo_paths = COPYRIGHT_YEAR_RE.sub(" ", text_wo_paths)
+        for structure in STRUCTURE_RES:
+            text_wo_paths = structure.sub(" ", text_wo_paths)
+        if LONE_ORDINAL_RE.match(own.strip()):
+            text_wo_paths = ""  # a badge / list marker whose whole text is one small number
+        numbers = [n for n in NUMBER_RE.findall(text_wo_paths) if not ORDINAL_RE.match(n)]
+        if not numbers:
+            continue
+        stats["numbers"] += len(numbers)
+        if cited:
+            stats["cited_numbers"] += len(numbers)
+            continue
+        if illustrative is not None:
+            if labelled:
+                continue
+            add("mock-unlabelled", el, own, "data-illustrative container has no visible label — a reader cannot tell the figures are not real")
+            continue
+        if any(LABEL_RE.search(c) for c in _nearby_comments(el, block)):
+            add("mock-label-hidden", el, own,
+                "figures are called illustrative only in an HTML comment — label the mock visibly and mark its container data-illustrative")
+        else:
+            add("uncited-number", el, own,
+                f"number(s) {', '.join(numbers[:5])} with no data-source, inline repo path or footnote — cite the file (path:line) or remove the figure")
+    return findings, stats
+
+
+def run(path: str, repos: list[str] | None = None) -> dict:
+    html = Path(path).read_text(encoding="utf-8", errors="replace")
+    findings, stats = scan_document(html, repos)
+    by_kind: dict[str, int] = {}
+    for f in findings:
+        by_kind[f.kind] = by_kind.get(f.kind, 0) + 1
+    return {
+        "check": "claims",
+        "file": path,
+        "ok": not findings,
+        "stats": stats,
+        "by_kind": by_kind,
+        "findings": [f.as_dict() for f in findings],
+        "summary": (
+            f"claims: {stats['blocks']} text blocks, {stats['numbers']} numbers ({stats['cited_numbers']} cited), "
+            f"{stats['urls']} URLs — "
+            + ("clean" if not findings else ", ".join(f"{v} {k}" for k, v in sorted(by_kind.items())))
+        ),
+    }
+
+
+def safe_console() -> None:
+    """M1 — never crash on a code-page console (Windows piped stdout is cp1252 on Python < 3.15)."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(errors="replace")
+            except (ValueError, OSError):
+                pass
+
+
+def format_finding(f: dict) -> str:
+    return f"  [{f['kind']}] {f['path']}  \"{f['text']}\"  — {f['detail']}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    safe_console()
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("html", help="the self-contained HTML deliverable")
+    ap.add_argument("--repo", action="append", default=[],
+                    help="a repository snapshot the claims must trace to (repeatable)")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+    try:
+        report = run(args.html, args.repo)
+    except OSError as exc:
+        print(json.dumps({"check": "claims", "ok": False, "error": str(exc)}))
+        return 2
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(report["summary"])
+        for f in report["findings"]:
+            print(format_finding(f))
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())