Keep Portable HTML Fix Records Consistent

Traceability

• Spec ID: html-finding-fix-recording
• Status: Implemented
• Review context: QoderAI/better-harness#39

Intent

Complete the finding-bound repair flow introduced for portable HTML reports. The fix recorder must recognize a valid HTML report without requiring Qoder's Canvas sidecar, validate the correct report contract, and publish the updated findings.json, report.md, and report.html as one consistent revision. Qoder Canvas reports must retain their stricter split-artifact validation.

Acceptance Scenarios

• HFR-AC-1 (report-family resolution): a compact findings document with report.md and report.html, and without Canvas artifacts, is recognized as an HTML report. A split Canvas report is recognized only through its Canvas artifacts. Mixed, incomplete, or otherwise ambiguous artifact sets fail closed with a stable report-context error.
• HFR-AC-2 (HTML recording): a valid result for an HTML finding records actualOutput, its AI-authored Assignment Summary, and its independent repair review without reading or creating canvas.json; the finding revision and report repair progress advance exactly once.
• HFR-AC-3 (three-artifact consistency): after a successful HTML record, findings.json, report.md, and report.html are regenerated from the same updated report data. The HTML action callback carries the new expected revision, and the report directory still contains only those three durable report artifacts.
• HFR-AC-4 (failure safety): stale revisions, invalid result payloads, invalid output paths, render-validation failures, and ambiguous report families do not change any durable report artifact and do not consume the result file.
• HFR-AC-5 (Canvas isolation): existing Qoder split reports still require and validate their Canvas sidecar, and a fabricated or missing sidecar cannot make an HTML report pass through the Canvas contract.
• HFR-AC-6 (result lifecycle): workflow guidance keeps the temporary result outside the renderer-owned report directory and consumes it only after the recorder returns status: "pass".

Non-goals

• Changing Loop Effectiveness scores or treating a repair review as delayed outcome evidence.
• Changing the callback transport contract already shipped by PR #39.
• Redesigning Qoder Canvas rendering, durable Canvas ownership, or its split report schema.
• Reconstructing or mutating historical reports without an explicit finding-bound record operation.
• Guaranteeing cross-file atomicity across an operating-system or power loss; the publish order instead keeps findings.json as the final commit marker.

Plan and Tasks

1. Resolve report family from the durable sibling artifact signature before validation: full findings, portable HTML, or Qoder Canvas. Reject mixed and incomplete compact contexts.
2. Validate portable HTML findings with the compact task-loop contract and preserve the existing full and Canvas validation paths.
3. Apply the result to an isolated clone, validate outputs, render Markdown and HTML, and run the HTML evaluator before writing durable files.
4. Publish HTML and Markdown first and findings.json last so the revision file remains the final commit marker for prepared artifacts.
5. Update the finding-bound-fix workflow to place temporary result payloads outside the report directory and consume them only on recorder success.
6. Add focused tests using an actual three-artifact HTML report, plus failure and Canvas-isolation coverage.

Test and Review Evidence

• HFR-AC-1/HFR-AC-2/HFR-AC-3: add focused tests to test/task-loop-report.test.mjs that render an HTML report, record one fix, parse the resulting findings, and verify Markdown, HTML, callback revision, repair progress, and durable artifact names.
• HFR-AC-4: snapshot all three artifacts before representative failures and assert byte identity afterward; assert the temporary result remains.
• HFR-AC-5: retain existing split-report tests and add explicit missing and mixed-sidecar rejection cases.
• HFR-AC-6: update and validate the shipped skill reference and package.
• Regression: run the focused report and CLI tests, npm run pack:verify, and the full npm test suite.
• Documentation integrity: regenerate the Better Harness doc routing graph and run node --test test/doc-link-graph.test.mjs.
• Review readiness: run git diff --check, inspect staged and unstaged changes, and record changed modules, generated files, risks, and AI evidence.
• Risk: an interrupted multi-file publish can leave prepared Markdown or HTML ahead of the old findings revision. Publishing findings.json last keeps the old callback revision authoritative until all prepared views have been installed; normal validation failures occur before any publish begins.

Observed Validation Evidence

• The 16 focused record-fix-output tests passed, including the new portable HTML success, pre-publish failure safety, and Qoder Canvas isolation cases.
• The HTML fixture proves that a successful record updates all three artifacts, increments the embedded callback revision, advances repair progress, leaves only findings.json, report.md, and report.html, and consumes an external result only after success.
• The original three-artifact Codex report was exercised without mutation by deliberately supplying a stale expected revision. The recorder returned STALE_FIX_OUTPUT_REVISION instead of ENOENT, proving that the valid compact HTML contract no longer attempts to read canvas.json.
• The combined report, renderer, Skill, CLI, and compatibility run passed 166 tests with one supported Windows symlink skip; its only failure was the same pre-existing unguarded Windows symlink-permission case reproduced on the unchanged baseline.
• The full repository run reached 1,044 passes and 6 supported skips. Its four failures were all pre-existing Windows EPERM symlink-creation cases and did not execute the changed recorder or HTML publication path.
• npm run pack:verify passed with 369 npm entries and 392 runtime-zip entries; the regenerated doc graph and all six doc-link tests passed.