fix(reporting): use canonical Session population in HTML

Fixes #117 by deriving the portable HTML hero and Evidence metrics from the reviewed evidence selection, preserving the legacy fallback and distinguishing unavailable data from a real zero population. Validated with focused Node 22/24 renderer suites and npm run check.

Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

Author: Cobb04

scripts/harness-analysis/renderers/html.mjs

@@ -50,6 +50,29 @@ function formatNumber(value, locale) {
   }).format(number(value));
 }
 
+function reviewedSessionPopulation(summary, language) {
+  // Usage efficiency is a separate all-eligible activity census. The visible
+  // reviewed-Session metric follows the evidence selection used by findings.
+  const selection = summary?.evidenceBoundary?.manifest?.selection
+    ?? summary?.atAGlance?.coverage?.selection;
+  const hasCounts = selection
+    && Object.hasOwn(selection, "analyzedCount")
+    && Object.hasOwn(selection, "eligibleCount");
+  const analyzed = Number(selection?.analyzedCount);
+  const eligible = Number(selection?.eligibleCount);
+  const available = hasCounts
+    && Number.isInteger(analyzed)
+    && analyzed >= 0
+    && Number.isInteger(eligible)
+    && eligible >= 0;
+  return {
+    value: available
+      ? `${formatNumber(analyzed, language)} / ${formatNumber(eligible, language)}`
+      : "N/A",
+    confidence: available ? selection.confidence ?? "" : "",
+  };
+}
+
 function copy(language, en, zh) {
   return language === "zh-CN" ? zh : en;
 }
@@ -541,14 +564,14 @@ function renderCustomize(summary, language) {
 function renderEvidence(summary, language) {
   const boundary = summary?.evidenceBoundary ?? {};
   const coverage = boundary?.episodeCoverage ?? summary?.atAGlance?.coverage ?? {};
-  const selection = boundary?.manifest?.selection ?? coverage?.selection ?? {};
+  const population = reviewedSessionPopulation(summary, language);
   const learning = summary?.learningCapture ?? {};
   const facts = [
     [copy(language, "Evidence mode", "证据模式"), summary?.evidenceMode ?? "—"],
     [copy(language, "Task episodes", "任务 Episode"), coverage.episodeCount ?? 0],
     [copy(language, "Edited episodes", "含编辑 Episode"), coverage.editedEpisodeCount ?? 0],
-    [copy(language, "Sampling", "抽样"), `${selection.analyzedCount ?? 0} / ${selection.eligibleCount ?? 0}`],
-    [copy(language, "Confidence", "可信度"), selection.confidence ?? "—"],
+    [copy(language, "Sampling", "抽样"), population.value],
+    [copy(language, "Confidence", "可信度"), population.confidence || "—"],
     [copy(language, "Learning state", "学习状态"), learning.state ?? "—"],
   ];
   const gaps = textLines(boundary.sourceGaps);
@@ -570,10 +593,7 @@ function renderHtmlBody(reportData) {
   const high = findings.filter((row) => ["Critical", "High"].includes(row.severity)).length;
   const medium = findings.filter((row) => row.severity === "Medium").length;
   const overview = summary.overview ?? summary.strengths?.[0] ?? copy(language, "Reviewed Harness evidence is ready for inspection.", "已复核的 Harness 证据可供检查。" );
-  const coverage = summary.atAGlance?.coverage ?? {};
-  const selection = summary.usageEfficiency?.selection ?? coverage.selection ?? {};
-  const analyzed = selection.analyzedSessionCount ?? selection.analyzedCount ?? 0;
-  const eligible = selection.eligibleSessionCount ?? selection.eligibleCount ?? summary.usageActivity?.sessions?.total ?? 0;
+  const population = reviewedSessionPopulation(summary, language);
   const hasUsage = summary.usageActivity !== undefined || summary.usageEfficiency !== undefined;
   const effectiveness = loopEffectiveness(dimensions);
   const progress = repairProgress(findings);
@@ -590,7 +610,7 @@ function renderHtmlBody(reportData) {
   <div class="metrics">
     ${metric(evidenceScoreLabel(summary, language), `${effectiveness} / 100`, copy(language, "Changes after later task outcomes", "等待后续任务结果后更新"), language)}
     ${metric(copy(language, "Asset Health / Repair Progress", "资产健康 / 修复进度"), `${progress.score} / 100`, copy(language, `${progress.verified} verified · ${progress.partial} partial · ${progress.pending} pending`, `${progress.verified} 项已验证 · ${progress.partial} 项部分完成 · ${progress.pending} 项待处理`), language)}
-    ${metric(copy(language, "Sessions analyzed", "会话样本"), `${formatNumber(analyzed, language)} / ${formatNumber(eligible, language)}`, selection.confidence ?? "", language)}
+    ${metric(copy(language, "Sessions analyzed", "会话样本"), population.value, population.confidence, language)}
     ${metric(copy(language, "Findings", "待处理 Finding"), findings.length, `${high} High · ${medium} Medium`, language)}
   </div>
   ${section("fluency", copy(language, "01 · Readiness", "01 · 就绪度"), copy(language, "Five-dimension fluency", "五维流畅度"), renderDimensionGrid(summary, language), copy(language, "Scores and states come from the reviewed source.", "分数与状态来自已复核 source。"), language)}

test/reporting/harness-report-render-cli.test.mjs

@@ -1184,6 +1184,68 @@ test("portable publication and restoration failure reports PUBLISH_ROLLBACK_FAIL
   });
 });
 
+test("portable HTML Session population stays consistent across generated artifacts", async () => {
+  await withTempDir("better-harness-portable-session-population-", async (root) => {
+    // Given: reviewed portable data with a canonical 2/2 Session population and
+    // no optional usage census or legacy at-a-glance projection.
+    const reviewed = projectTaskLoopFindings(reviewedTaskLoopSource(), {
+      projectName: "render-source-project",
+      direct: true,
+    });
+    reviewed.summary.evidenceBoundary.manifest.platform = "dsh";
+    reviewed.summary.evidenceBoundary.manifest.selection = {
+      strategy: "all-eligible",
+      eligibleCount: 2,
+      analyzedCount: 2,
+      confidence: "High",
+    };
+    reviewed.summary.dimensions = reviewed.summary.dimensions.map((dimension) => {
+      const compact = { ...dimension };
+      delete compact.subdimensions;
+      return compact;
+    });
+    delete reviewed.summary.atAGlance;
+    delete reviewed.summary.usageActivity;
+    delete reviewed.summary.usageEfficiency;
+
+    const findingsPath = path.join(root, "reviewed.findings.json");
+    await writeJson(findingsPath, reviewed);
+
+    // When: every affected portable host routes the same reviewed input through
+    // the public renderer.
+    for (const host of ["dsh", "codex", "grok", "kimi", "workbuddy"]) {
+      const runDir = path.join(root, `run-${host}`);
+      const result = runNode([
+        renderPath,
+        "--findings", findingsPath,
+        "--mode", "html",
+        "--platform", host,
+        "--target", root,
+        "--run-dir", runDir,
+        "--validate",
+        "--json",
+      ], { cwd: root });
+
+      // Then: JSON, Markdown, and both visible HTML surfaces use the same
+      // canonical reviewed population without a host-specific renderer branch.
+      assert.equal(result.status, 0, `${host}: ${result.stderr || result.stdout}`);
+      const findings = JSON.parse(readFileSync(path.join(runDir, "findings.json"), "utf8"));
+      const markdown = readFileSync(path.join(runDir, "report.md"), "utf8");
+      const html = readFileSync(path.join(runDir, "report.html"), "utf8");
+      assert.deepEqual(findings.summary.evidenceBoundary.manifest.selection, {
+        strategy: "all-eligible",
+        eligibleCount: 2,
+        analyzedCount: 2,
+        confidence: "High",
+      }, host);
+      assert.match(markdown, /Session selection: all-eligible; 2 sessions analyzed of 2 eligible sessions; High confidence/u, host);
+      assert.match(html, /<span>Sessions analyzed<\/span>\s*<strong>2 \/ 2<\/strong>\s*<small>High<\/small>/u, host);
+      assert.match(html, /<span>Sampling<\/span><strong>2 \/ 2<\/strong>/u, host);
+      assert.match(html, /<span>Confidence<\/span><strong>High<\/strong>/u, host);
+    }
+  });
+});
+
 test("DSH reuses portable HTML report data, target root, and exact artifact contract", async () => {
   await withTempDir("better-harness-dsh-portable-", async (root) => {
     const target = path.join(root, "DSH target with 空格");
@@ -1622,6 +1684,38 @@ test("HTML evidence episode coverage preserves canonical summary facts and legac
   assert.match(legacyHtml, /<span>Edited episodes<\/span><strong>5<\/strong>/u);
 });
 
+test("portable HTML Session population distinguishes valid zero from unavailable data", () => {
+  const fixture = sampleFindings();
+  const reportData = {
+    ...fixture,
+    language: "en",
+    target: { name: "render-fixture", path: "/tmp/render-fixture" },
+  };
+
+  const zeroHtml = renderHtml({
+    ...reportData,
+    summary: {
+      ...reportData.summary,
+      evidenceBoundary: {
+        manifest: {
+          selection: {
+            strategy: "all-eligible",
+            eligibleCount: 0,
+            analyzedCount: 0,
+            confidence: "Low",
+          },
+        },
+      },
+    },
+  });
+  const unavailableHtml = renderHtml(reportData);
+
+  assert.match(zeroHtml, /<span>Sessions analyzed<\/span>\s*<strong>0 \/ 0<\/strong>\s*<small>Low<\/small>/u);
+  assert.match(zeroHtml, /<span>Sampling<\/span><strong>0 \/ 0<\/strong>/u);
+  assert.match(unavailableHtml, /<span>Sessions analyzed<\/span>\s*<strong>N\/A<\/strong>/u);
+  assert.match(unavailableHtml, /<span>Sampling<\/span><strong>N\/A<\/strong>/u);
+});
+
 test("HTML CJK phrase breaking emits bounded deterministic markup without changing report data", () => {
   // Given: reviewed phrases plus escaping, long-token, path, URL, and mixed-Latin boundaries.
   const fixture = sampleFindings();