fix: keep report evidence consistent across collectors

CHANGELOG.md

@@ -40,6 +40,26 @@ observable behavior and compatibility, not every internal refactor.
   (`qoder, codex, claude, cursor, qwen, copilot, pi`) when it rejects an
   unsupported `--platform`, matching the session-analysis and asset-baseline
   gates. The existing error prefix and exit behavior are unchanged.
+- Core Change Watch now requires framework-specific evidence before labeling
+  Rails or FastAPI, exposes bounded root Just recipes as statically discovered
+  unverified argv entrypoints, and keeps historical-only files out of current
+  recommended reads and action targets.
+- Evidence bundles now discover and privacy-filter one frozen Session population
+  before either Session facts or lead analysis hydrates it. Versioned redacted
+  bindings fail closed on population, selection, or admission contradictions
+  while preserving bounded lead selection and explicit zero-signal filtering.
+- Self-contained HTML reports now expose every fluency-dimension score track as
+  a labeled progressbar with a zero-to-100 range and the displayed rounded
+  score. Report validation rejects incomplete, duplicated, invalid, or
+  score-mismatched dimension progressbar contracts.
+- Chinese self-contained HTML reports now use standards-based language
+  segmentation to keep bounded word-like phrases together while preserving
+  normal wrapping around Latin text, paths, URLs, and longer content. Runtimes
+  without segmentation support fall back to readable escaped text, and English
+  reports remain unchanged.
+- HTML Evidence cards now display machine-owned Task Episode coverage from a
+  summary-facts companion, with legacy at-a-glance coverage retained only as a
+  compatibility fallback.
 
 ## 0.3.0 - 2026-07-27
 

docs/specs/2026-07-30-core-change-watch-profile-and-current-paths.md

@@ -0,0 +1,95 @@
+# Core Change Watch Profile And Current Paths
+
+## Traceability
+
+- Spec ID: 2026-07-30-core-change-watch-profile-and-current-paths
+- Status: Implemented
+- Issue: None; focused evidence-correctness maintenance discovered by a validated Better Harness report.
+
+## Intent
+
+Keep Core Change Watch's static project profile and current-work guidance
+truthful. Framework labels must require framework-specific evidence, supported
+root Just recipes must be visible without being executed, and current reads or
+actions must not point to files that exist only in bounded Git history.
+
+## Acceptance Scenarios
+
+- AC-1: A Python project with FastAPI declared in a supported Python manifest
+  and generic `app/api` or `app/services` paths is identified as FastAPI, is not
+  identified as Rails, and receives no TypeScript-only path reason. A real
+  Rails fixture remains identified from Rails-specific evidence.
+- AC-2: Public recipes in a root `justfile`, `Justfile`, or `.justfile` are
+  represented additively as entry candidates with `kind: "just-recipe"`, an
+  argv-style `command`, the source path, and `executionStatus: "unverified"`.
+  Parsing is static, bounded, handles LF and CRLF, ignores private recipes, and
+  never runs Just or a shell.
+- AC-3: `recommendedReads` and every `followUpActions[].files` entry resolve to
+  a currently present tracked file or a currently present changed/untracked
+  file. Deleted historical paths remain available in raw history evidence but
+  are not projected as current work targets.
+- AC-4: Focused Core Change Watch tests, repository documentation checks, and
+  the full package gate pass without a new dependency.
+
+## Non-Goals
+
+- Session lane/lead population binding or source-fingerprint changes.
+- Renderer progress-track ARIA changes.
+- Agent Work Loop score changes or synthetic Task Episodes.
+- Executing Just recipes, shell-string dispatch, or proving command success.
+- Adding dependencies or a general TOML/Just parser.
+- Editing generated reports, installed plugin caches, Session content, Memory,
+  or user-home data.
+- Rewriting or deleting valid raw Git-history evidence.
+
+## Plan And Tasks
+
+Allowed files, copied verbatim from the approved Worker package:
+
+1. `docs/specs/2026-07-30-core-change-watch-profile-and-current-paths.md`
+2. `scripts/core-change-watch/project-profile.mjs`
+3. `scripts/core-change-watch/core-candidates.mjs`
+4. `scripts/core-change-watch/evidence-pack.mjs`
+5. `test/core-change-watch.test.mjs`
+6. `references/project-harness/core-change-watch.md`
+7. `CHANGELOG.md`
+8. `docs/better-harness-doc-links.mmd`
+
+Tasks:
+
+1. Add focused regression fixtures for AC-1 through AC-3 and preserve the
+   defect-specific failing run before production edits.
+2. Tighten framework/path evidence and add bounded static Just recipe
+   projection without changing existing entry-candidate meanings.
+3. Filter history-derived current-work projections through present repository
+   inventory while preserving the history profile.
+4. Update the canonical Core Change Watch guidance and changelog, regenerate
+   the Markdown routing graph, and mark this spec Implemented only after all
+   acceptance evidence passes.
+5. Run the change-traceability Review Readiness Check before commit or review.
+
+## Test And Review Evidence
+
+- The focused red run failed all three new regressions for the intended causes:
+  missing FastAPI evidence, missing Just recipe projection, and a deleted
+  historical path projected as current work. The same run passed 3/3 after the
+  implementation.
+- The real `database-caching` projection reports only `fastapi`, exposes
+  `just sync`, `just api-dev`, `just health`, and `just check` with unverified
+  status, uses no TypeScript reason for `app/api`, and emits only readable
+  recommended/action paths.
+- AC-1 to AC-3 red/green:
+  `node --test --test-name-pattern='framework-specific evidence|Just recipes|non-current historical paths' test/core-change-watch.test.mjs`
+- Focused suite: `node --test test/core-change-watch.test.mjs`
+- Real target projection: run `analyzeProjectProfile`,
+  `analyzeCoreCandidates`, and `buildEvidencePack` against `database-caching`;
+  assert FastAPI/no Rails, argv Just entries with unverified status, neutral
+  `app/api` reasons, and readable current-work paths.
+- Documentation: regenerate the routing graph and run
+  `node --test test/doc-link-graph.test.mjs`.
+- Package gate: `TMPDIR=<clean-temp-root> npm run check` passed with 884/884
+  tests plus npm-package and runtime-zip verification. The clean temp root
+  avoids unrelated `/tmp/CLAUDE.md` ancestor-instruction contamination.
+- Risk review: verify additive output fields, cross-platform path handling,
+  preserved Rails and raw-history fixtures, no shell execution, no dependency
+  changes, and an explicit AI co-author marker at commit time.

docs/specs/2026-07-30-html-cjk-line-breaking.md

@@ -0,0 +1,95 @@
+# Keep Chinese phrases together in HTML reports
+
+## Traceability
+
+- Spec ID: 2026-07-30-html-cjk-line-breaking
+- Status: Implemented
+- Issue: None; focused follow-up to the reviewed HTML progressbar visual QA.
+
+## Intent
+
+Keep ordinary Chinese word-like phrases together when the self-contained HTML
+report wraps headings and card copy. Segment visible `zh-CN` text with the
+standards-based `Intl.Segmenter` API and emit bounded, nonvisual keep-together
+spans so the result is deterministic across supported browsers. The generic
+renderer must improve reviewed Chinese content without hardcoded phrases,
+report-data mutation, runtime measurement, or a visual redesign.
+
+## Acceptance Scenarios
+
+- AC-1: A `zh-CN` HTML report uses `Intl.Segmenter` word segmentation for
+  visible text and wraps each ordinary all-Han word-like segment of at most
+  eight code points in `<span class="cjk-phrase">`. Representative phrases
+  including `口径`, `入口`, `结论`, and `命令` receive that deterministic markup.
+- AC-2: Phrase markup remains scoped to visible Chinese report text. English
+  reports retain their current markup, wrapping behavior, and visible copy;
+  attributes, accessibility labels, copied prompts, and embedded report JSON
+  remain plain escaped text without phrase spans or invisible joiners.
+- AC-3: Chinese headings, card titles, summaries, reasons, and ordinary
+  paragraphs continue to wrap between marked segments. Each keep-together span
+  is bounded to eight Han code points. Long tokens, paths, URLs, mixed Latin
+  text, and unrecognized segments remain escaped readable text and cannot gain
+  an unbounded no-wrap container.
+- AC-4: The existing dimension progressbar role, label, range, rounded value,
+  count validation, CSS, score computation, report data, and artifact set remain
+  unchanged.
+- AC-5: Focused HTML tests, the full package check, whitespace validation, and
+  the allowed-file audit pass. Before review completion, an environment with a
+  browser runtime inspects the same report at all three target widths.
+
+## Compatibility Boundary
+
+`Intl.Segmenter` is used only while generating the self-contained report. The
+renderer accepts only `isWordLike` segments that consist entirely of Han code
+points and are between two and eight code points long. All other segments use
+the existing HTML escaping path. If `Intl.Segmenter` is absent or throws, the
+entire value falls back to the same escaped readable text. CSS applies
+`white-space: nowrap` only to the bounded phrase spans, leaving normal wrapping
+available between spans and around Latin tokens, punctuation, paths, and URLs.
+
+## Non-goals
+
+- Hardcoding known report phrases or inserting word-joiner characters into
+  report data, visible copy, accessibility text, or copied prompts.
+- Preventing ordinary Chinese paragraphs from wrapping or forcing a complete
+  sentence, heading, or card onto one line.
+- Adding overflow, clipping, ellipsis, hidden content, fixed widths, custom
+  fonts, browser-specific JavaScript, dependencies, or generated artifacts.
+- Changing English layout, scores, findings, dimensions, report schemas,
+  progressbar semantics, interactions, or artifact names.
+
+## Plan and Tasks
+
+1. Add a focused renderer regression for deterministic markup, escaping,
+   bounded long-token handling, mixed Latin/path/URL preservation, English
+   preservation, unavailable-segmenter fallback, and the four reviewed phrases.
+   Record the missing-markup failure before renderer implementation. (AC-1..AC-4)
+2. Add one visible-text renderer using `Intl.Segmenter` and a bounded
+   `.cjk-phrase` keep-together rule. Route visible report copy through it while
+   leaving attributes, copied prompts, and serialized data unchanged. Remove
+   the insufficient browser-dependent `auto-phrase` contract. (AC-1..AC-4)
+3. Update the public changelog and verify the exact reviewed Chinese report at
+   375, 768, and 1280 pixels, including wrapping, overflow, clipping, console,
+   and preserved progressbar semantics. (AC-3..AC-5)
+
+## Test and Review Evidence
+
+- The initial focused test failed for the intended reason: the reviewed Chinese
+  phrases had no deterministic keep-together markup. It passed after the
+  standards-based segment renderer and bounded phrase span were added.
+- Browser QA then exposed descendant-selector leakage: nested phrase spans in
+  the score orbit, metrics, and evidence grid inherited block, width, and label
+  typography rules. A focused regression failed on the missing direct-child
+  selector contract before those existing rules were scoped to their direct
+  label and value children; nested phrase spans now remain inline.
+- The combined CJK and preserved progressbar suite passed 2/2:
+  `node --test --test-name-pattern='HTML CJK phrase|HTML dimension progressbar' test/harness-report-render-cli.test.mjs`.
+- The target-owned HTML suite passed 6/6:
+  `node --test --test-name-pattern='HTML' test/harness-report-render-cli.test.mjs`.
+- The coordinating PM ran the complete test suite serially with an isolated
+  temporary root: all 894 tests passed, followed by successful npm and runtime
+  zip package verification. This resolved the parallel temporary-ancestor
+  interference observed in two earlier Worker runs.
+- The exact reviewed Chinese report retains its source scores, finding count,
+  progressbar count, embedded report data, and artifact set. Post-fix browser
+  review at 375, 768, and 1280 pixels remains the final visual gate.

docs/specs/2026-07-30-html-dimension-progressbar-semantics.md

@@ -0,0 +1,76 @@
+# Give HTML dimension tracks progressbar semantics
+
+## Traceability
+
+- Spec ID: 2026-07-30-html-dimension-progressbar-semantics
+- Status: Implemented
+- Issue: None; focused accessibility-contract maintenance from a reviewed Better Harness finding.
+
+## Intent
+
+Make every fluency-dimension score track in the self-contained HTML report
+expose the score that sighted readers already see to assistive technology. The
+HTML validator must keep that semantic projection bound to the reviewed
+dimension count and rounded score so incomplete or stale markup cannot pass
+report validation.
+
+## Acceptance Scenarios
+
+- AC-1: Every rendered fluency-dimension card contains exactly one track with
+  `role="progressbar"`, a non-empty accessible label derived from the displayed
+  dimension label, `aria-valuemin="0"`, `aria-valuemax="100"`, and an
+  `aria-valuenow` equal to the integer score displayed beside that track.
+- AC-2: The HTML report validator passes the canonical rendered dimension
+  tracks and rejects a missing or extra dimension progressbar, a progressbar
+  with a missing or invalid role, label, minimum, maximum, or current value,
+  and a current value that differs from the reviewed rounded score.
+- AC-3: The renderer preserves existing CSS, layout, visible copy, dimension
+  ordering, score clamping and rounding, visual fill width, artifact names,
+  and generated report ownership.
+- AC-4: The focused regression, full renderer CLI suite, documentation graph,
+  doc-link suite, full package check, whitespace check, and allowed-file audit
+  pass from the assigned repository state.
+
+## Non-goals
+
+- Redesigning the dimension cards, tracks, responsive layout, color, or CSS.
+- Changing visible labels, summaries, localization, score computation,
+  clamping, rounding, or report data schemas.
+- Editing generated reports, templates, installed plugin caches, dependencies,
+  custom SVG, or any report mode other than the canonical HTML renderer.
+- Adding browser interaction, live-region announcements, or a new artifact.
+
+## Plan and Tasks
+
+1. Add one focused regression test that asserts the rendered per-dimension
+   progressbar contract and mutation-based validator rejection for missing,
+   invalid, count-mismatched, and score-mismatched semantics. Record the test
+   failing against the current renderer before implementation. (AC-1, AC-2)
+2. Reuse the renderer's existing display label and rounded score when emitting
+   the complete progressbar attributes, without changing track CSS or fill
+   width. (AC-1, AC-3)
+3. Extend `evaluateHtmlReport` to bind exactly one valid progressbar to each
+   reviewed dimension card and reject semantic count or score drift. (AC-2)
+4. Update the public changelog, regenerate the Markdown routing graph required
+   for the new spec, run every assigned verification command, and mark this
+   spec Implemented only after the evidence passes. (AC-4)
+
+## Test and Review Evidence
+
+- The required red run failed for the intended contract reason: the current
+  renderer produced zero semantic progressbars for five reviewed dimensions
+  (`0 !== 5`). The same focused command passed after implementation:
+  `node --test --test-name-pattern='dimension progressbar' test/harness-report-render-cli.test.mjs`.
+- The full renderer suite passed 15/15:
+  `node --test test/harness-report-render-cli.test.mjs`.
+- Documentation graph generation and all six doc-link checks passed:
+  `node scripts/doc-link-graph/cli.mjs skills/better-harness && node --test test/doc-link-graph.test.mjs`.
+- The complete package gate passed from a clean temporary root under
+  `/var/tmp` with 893 tests and successful npm/runtime-zip package verification:
+  `TMPDIR=/var/tmp/better-harness-t016.lxCc80 npm run check`.
+- Scope and whitespace:
+  `git diff --check -- <allowed files>` plus an allowed-file-only status audit.
+- Risk review: the focused test removes and duplicates a progressbar, mutates
+  each semantic attribute class, and changes `aria-valuenow`; all mutations
+  fail validation while canonical output passes. The CSS and existing visual
+  fill-width expression are unchanged.

docs/specs/2026-07-30-html-summaryfacts-episode-coverage.md

@@ -0,0 +1,60 @@
+# Preserve summary-facts Episode coverage in HTML
+
+## Traceability
+
+- Spec ID: 2026-07-30-html-summaryfacts-episode-coverage
+- Status: Implemented
+- Issue: None; focused renderer correctness repair found during final browser QA.
+
+## Intent
+
+Make the self-contained HTML Evidence section display the machine-owned Episode
+coverage already embedded in a split findings plus summary-facts companion
+render. The current renderer preserves those facts in report data but reads only
+the legacy `atAGlance.coverage` projection for its visible cards, producing a
+false zero when the canonical `evidenceBoundary.episodeCoverage` is present.
+
+## Acceptance Scenarios
+
+- AC-1: When `summary.evidenceBoundary.episodeCoverage` reports 14 total and 12
+  edited Episodes, the visible HTML Evidence cards display 14 and 12.
+- AC-2: Machine-owned `evidenceBoundary.episodeCoverage` takes precedence over
+  stale or absent legacy `atAGlance.coverage` values.
+- AC-3: A legacy report that has only `atAGlance.coverage` keeps its existing
+  visible Episode counts.
+- AC-4: No score, finding, schema, CSS, layout, CJK, interaction, or artifact
+  ownership behavior changes.
+- AC-5: Focused renderer tests, the full HTML suite, the complete serial package
+  suite, package verification, whitespace checks, and final browser QA pass.
+
+## Non-goals
+
+- Changing evidence collection, Session population binding, Episode admission,
+  report scores, findings, or summary-facts schemas.
+- Adding fallback inference from usage counts or visible prose.
+- Editing generated reports or installed plugin caches.
+- Redesigning the Evidence section or adding new UI.
+
+## Plan and Tasks
+
+1. Add a focused renderer regression for canonical summary-facts precedence and
+   legacy compatibility, and preserve its red result. (AC-1, AC-2, AC-3)
+2. Read Episode coverage from the canonical machine-facts owner with the legacy
+   projection as a compatibility fallback. (AC-1, AC-2, AC-3, AC-4)
+3. Run the assigned verification and record the evidence before marking this
+   spec Implemented. (AC-5)
+
+## Test and Review Evidence
+
+- The focused red run failed because the canonical 14/12 summary-facts values
+  rendered as the conflicting legacy 1/1 values. The unchanged focused command
+  passed after implementation:
+  `node --test --test-name-pattern='HTML evidence episode coverage' test/harness-report-render-cli.test.mjs`.
+- The complete HTML-focused renderer suite passed 7/7:
+  `node --test --test-name-pattern='HTML' test/harness-report-render-cli.test.mjs`.
+- The isolated serial package suite passed 895/895:
+  `TMPDIR=/var/tmp/better-harness-t025.dES6tD npm test -- --test-concurrency=1`.
+- Package verification passed with 324 npm entries and 348 runtime-zip entries:
+  `TMPDIR=/var/tmp/better-harness-t025.dES6tD npm run pack:verify`.
+- Final report rendering, three-width browser QA, scope, whitespace, and review
+  evidence are recorded in the contribution receipt before commit.