rebind-html

Skill: rebind-html

What this is

The HTML surgical output engine for report-regeneration — pipeline stage 3. Given a template HTML file, a Binding Manifest (../../knowledge/binding-manifest.schema.json), and resolved new-source data, it produces a same-format review-ready draft by performing schema-validated surgery on a copy of the template — never by re-rendering from an abstract model. This is the "surgeon, not a renderer" model from ../../knowledge/core-architecture-spec.md §1, applied to the HTML/web→PDF output format.

The engine consumes a manifest; it does not infer structure or propose bindings (that is an earlier pipeline stage) and it does not run the fidelity harness (V1-V6 + period-coherence — a separate, downstream track). Its one job is: apply exactly what the manifest says, per node class, and prove the frozen ones didn't move.

The four node classes (§4 of the architecture spec)

Class	What this engine does
frozen	No mutation. After every other binding is applied, the engine re-checks that the node's exact byte span is identical between template and output (_assert_frozen_unchanged) — a defensive proof, not an assumption.
surgical	Strip, then write — two separate mutations, in that order. strip_inner_by_id (or strip_attr_by_id for a void element) empties the old value; write_inner_by_id/write_attr_by_id writes the new one. At the instant between the two calls the node provably carries no old instance value — by construction, not a downstream check.
regenerate	Same strip-then-write invariant, but the new value is rendered from a template string against the new-data JSON (stdlib string.Template, dotted-placeholder subclass — jinja2 is optional acceleration for templates that use native {{ }}/{% %} control syntax). A raster/void node (an <img>) is rebound by attribute (src, + alt if provided) — never by transplanting the old binary, per the spec's construction rule: "a transplanted binary blob cannot be proven data-free."
needs-review	Left completely untouched — content and attributes unchanged — but flagged: a machine-readable data-rebind-flag="needs-review" (+confidence) attribute on the opening tag, plus a visible on-page badge (⚠ NEEDS REVIEW — human sign-off required (...)) inserted as the node's first child (or as a sibling for a void element). Logged in the printed change-manifest. Never ships silently — this is guarantee #2 made mechanical.

Usage

python3 plugins/report-regeneration/skills/rebind-html/rebind_html.py \
    --template  tests/fixtures/report-regeneration/sample-report.html \
    --manifest  path/to/binding-manifest.json \
    --new-data  path/to/new-data.json \
    --out       tests/fixtures/report-regeneration/_out/regenerated.html

Add --pretty to pretty-print the printed JSON change-manifest. Every invocation prints a JSON object to stdout: {"schema": "report-regeneration/rebind-html@1", "ok": true|false, ..., "changes": [...]}. Exit code 0 = success; 2 = usage / path-guard / manifest-schema / anchor-not-found / missing-data-query / missing-new-data-key error (never a silent partial write — a failure aborts the whole run and touches --out not at all).

--template/--manifest/--new-data/--out are relative paths, path-guarded (mirrors ../../scripts/seed_defects.py and ravenclaude-core's skills/svg-report-lint/lint.py _repo_root()/_safe_path() convention): no absolute paths, no .. traversal, must resolve inside the repo root. --out may never equal --template — this script works on a copy; the template file on disk is never mutated (verified in tests/test_rebind.py's CLI suite via a before/after SHA-256 hash of the template file).

The new-data lookup + template contract

A binding's data_query.expression is a dot-path into the --new-data JSON (e.g. "revenue.total" looks up {"revenue": {"total": ...}}). surgical writes the resolved value directly. regenerate treats the resolved value as either:

• a plain string — a template, rendered with ${dotted.path} placeholders resolved against the SAME new-data object (stdlib-only, always works); or a native Jinja template ({{ }}/{% %}) — rendered via jinja2 if it's importable, else a loud RebindError (never a silent stdlib mis-render of control-flow syntax that stdlib templating cannot express); or
• an object — for a raster/void node, {"src": "...", "alt": "..."} (alt optional); for a text node with an explicit template key, {"template": "..."}.

A missing dot-path segment, an unresolvable anchor, or a class/data_query mismatch against the schema's allOf rule (frozen carries no data_query; every other class must) is a loud RebindError → exit 2 — never a guess.

Anchor support (this is an HTML-only engine)

Only anchor.kind == "element_id" and a simple anchor.kind == "css_selector" of the shape "#element-id" are resolvable (both reduce to the same id-attribute lookup, via regex — deliberately not a full DOM rebuild, matching seed_defects.py's convention). json_pointer and ooxml_path anchors are Office/docx-format anchors from the same manifest schema; this engine rejects them loudly (RebindError) rather than guessing — Office output is a later release lane (v0.2.0 per the plugin's CLAUDE.md).

Tests

tests/test_rebind.py — stdlib unittest, no pytest required:

• TestCoreMechanics — a small synthetic fixture exercising all four classes: frozen byte-identity (+ a must-fail check that a genuinely mutated frozen node IS caught), surgical strip-then-write with the old value asserted absent at both the strip midpoint and the final node, regenerate text + regenerate raster (both asserting the old value/asset is gone), needs-review flagging + untouched content, html.parser parseability, the stdlib ${dotted.path} template renderer, the jinja2-absent loud-failure path, and three manifest-schema-violation rejections.
• TestSampleReportCorpus — end-to-end against the real tests/fixtures/report-regeneration/sample-report.html corpus fixture: a hand-built manifest covering a frozen void element (#logo-header), two surgical text nodes (#kpi-revenue, #hdr-period), a regenerate narrative (#exec-summary-narrative), a regenerate raster (#chart-region-mix), and the fixture's own deliberately-tricky needs-review case (#tagline-text, the percent-shaped marketing literal called out in the corpus README) — asserting new values present / old values absent at each node, the template file untouched on disk, and the whole output still parses.
• TestCLI — process-boundary tests: happy path (exit 0, output written, template SHA-256 unchanged), --out == --template rejection, path-traversal rejection, and absolute-path rejection (all exit 2).

Run: python3 plugins/report-regeneration/skills/rebind-html/tests/test_rebind.py -v

Purity contract

• Stdlib-only — argparse, html.parser, json, re, string, pathlib, sys. No pip installs required. jinja2 is imported via a graceful try/except and is optional acceleration only — every ${dotted.path}-only template (which is what this skill's whole test suite exercises) works with jinja2 absent.
• Runs unmodified on Python 3.9.6 — from __future__ import annotations; no PEP 604 union syntax (X | Y), no match statement.
• No network, no subprocess inside the engine itself.
• Path-guarded — see Usage above.
• Exit-coded — deterministic 0/2; no partial write on failure.
• Zero-literal construction, by construction — every surgical/regenerate mutation is a strip call followed by a write call; there is no code path that writes a new value without first stripping the old one at that anchor.