# Make Claude Code reports durable by default

## Traceability

- Spec ID: claude-durable-html-default
- Status: Implemented

## Intent

Make an ordinary `/better-harness` run in Claude Code produce the same portable,
openable report experience promised by the public quick start. Claude Code
should default to the existing validated HTML renderer instead of returning an
inline-only review that leaves no reusable artifact.

## Acceptance Scenarios

- CDHD-AC-1: An ordinary Claude Code invocation selects durable HTML output by
  default. Inline output writes nothing only when the user explicitly requests
  an inline or no-files result.
- CDHD-AC-2: A durable Claude run writes exactly `findings.json`, `report.md`,
  and self-contained `report.html` below the target-local
  `.claude/better-harness` report root and succeeds only when the renderer
  returns `status: pass`.
- CDHD-AC-3: Qoder remains Canvas-first, Codex remains HTML-first, and the
  renderer's machine contract and report schemas do not change.
- CDHD-AC-4: The public README, host adapter matrix, report-routing contract,
  and canonical Better Harness Skill describe the same Claude default.
- CDHD-AC-5: Claude's native plugin manifest, isolated marketplace install,
  Skill discovery, and a real Claude routing probe pass against the updated
  source plugin.

## Non-goals

- Add a new renderer, report schema, Claude-specific findings model, or Claude
  session-evidence provider.
- Make the generated HTML depend on a server, remote asset, or Claude-only
  runtime.
- Change Qoder Canvas artifacts, Codex output, scoring, finding eligibility, or
  source-mutation authority.
- Publish the repository, package, or marketplace listing.

## Plan and Tasks

1. Update the report-routing switchboard so Claude Code and Codex select the
   existing HTML route by default, while an explicit inline request remains a
   no-write route.
2. Tighten the canonical Skill with host-specific default output roots and make
   report-artifact authority distinct from source/config mutation authority.
3. Align the README and host adapter matrix with the executable Skill contract.
4. Route standalone HTML findings through the compact Agent Work Loop validator
   instead of requiring the Qoder-only `canvas.json` sidecar.
5. Add focused contract assertions that prevent Claude from regressing to an
   undocumented inline-only default or a Canvas-only validation path.
6. Re-run Claude strict validation, isolated install/discovery, a real routing
   probe, focused renderer/docs tests, the documentation link graph, and package
   verification.

## Test and Review Evidence

- CDHD-AC-1/CDHD-AC-4: `node --test test/style-templates.test.mjs
  test/better-harness-skill.test.mjs` asserts the Claude default and explicit-inline
  exception across routing and Skill owners.
- CDHD-AC-2/CDHD-AC-3: `node --test
  test/harness-report-render-cli.test.mjs` confirms validated HTML contains the
  three named artifacts and remains self-contained while Canvas coverage stays
  green.
- CDHD-AC-4: regenerate the routing graph with `node
  scripts/doc-link-graph/cli.mjs skills/better-harness`, then run `node --test
  test/doc-link-graph.test.mjs`.
- CDHD-AC-5: run `claude plugin validate --strict .`; install the repository in
  an isolated `CLAUDE_CONFIG_DIR`; confirm `Skills (1) better-harness`; then ask
  a real Claude Code process which route an ordinary invocation selects.
- Risk: default report writes may surprise users who wanted chat-only output.
  Mitigate with an explicit inline/no-files override and keep report writes
  confined to the target-local host report root.
- Risk: Claude could hand-write HTML or leave partial artifacts after validation
  failure. Mitigate by retaining the renderer-only contract, exact artifact
  set, atomic publication, and `status: pass` gate.

## Implementation Evidence

- CDHD-AC-1/CDHD-AC-4: the canonical Skill, report routing, host matrix, README,
  architecture guide, and changelog now agree that Claude Code defaults to
  durable HTML and reserves write-free behavior for explicit inline/no-files
  requests. The Skill stays below its 12,000-byte prompt budget and passes the
  Skill Creator validator.
- CDHD-AC-2/CDHD-AC-3: standalone compact Agent Work Loop findings now use the
  compact validator for HTML/Markdown output while Qoder's split Canvas route
  still requires its sidecar. A target-local live render returned `status:
  pass`, exactly three artifacts, a passing self-contained HTML check, and no
  `canvas.json`.
- CDHD-AC-5: Claude Code 2.1.217 passed strict plugin validation. A fresh
  isolated marketplace install exposed `Skills (1) better-harness`; its copied
  Skill contained the Claude HTML route, and its copied renderer returned
  `status: pass`. A real one-turn Claude probe selected durable HTML,
  `.claude/better-harness`, and the exact three-artifact set.
- Final validation: `npm test` passed 822/822; `npm run pack:verify` passed with
  an isolated writable npm cache (290 npm entries and 324 runtime ZIP entries);
  the regenerated document graph passed all five focused integrity tests; and
  `git diff --check` passed.