delivery-friction-analyzer 0.22.0 → 0.23.0

package/docs/contracts/friction-report.md

@@ -28,16 +28,17 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `source`: optional source-bundle provenance copied into live-generated report
   artifacts, including `kind` and a human-readable label.
 - `targetRepository`: analyzed repository identity; live analysis sample size is encoded as `targetRepository.analysisPullRequestLimit` from collection metadata.
-- `analysisFilter`: optional metadata for explicit filters applied before metrics computation, including excluded PR classes and before/after PR counts.
+- `analysisFilter`: optional metadata for explicit filters applied before metrics computation, including excluded PR classes and before/after PR counts. Live dry-run completion receipts may also include requested `analysisFilter.excludedPrClasses` with null before/after counts because dry-run coverage probes do not compute filtered metrics or report artifacts.
 - `configuredWorkflow`: optional user-configured workflow context from the repository profile. It is not observed GitHub evidence and does not change scoring, ranking, CSV exports, or PR class matching.
 - `contributorSource`: optional sanitized contributor-source metadata from the repository profile and collection path. It records source type, path, coverage status, parsed hint count, and guardrail note. It does not include raw contributor file contents or contributor rankings.
 - `collectionCoverage`: optional source collection coverage metadata copied into live-generated report JSON artifacts. `collectionCoverage.status` records aggregate coverage, and `collectionCoverage.sourceFamilies` lists source-family entries with `family`, `status`, `attempts`, `source`, `diagnostics`, and `downstreamImpact`. This uses the generic `source-bundle.v1` `coverage.sourceFamilies` name; legacy GitHub `apiFamilies` is not a live `friction-report.v1` field.
-- `summary`: repository totals and top bottleneck identifiers.
+- `summary`: repository totals, positive-signal top bottleneck identifiers, and no-signal bottleneck identifiers.
 - `coverage`: PR-open diff, workflow-run, and review-thread coverage counts plus caveats.
 - `commentSources`: total and source-grouped review comments for Copilot, human, bot, scanner, author replies, and unknown sources.
 - `surfaces`: core, low-signal, generated, support-surface, role, and functional-surface breakdowns.
 - `prClasses`: PR class distribution for the analyzed sample, including PR counts, changed lines, share of PRs, and classification source counts by class.
-- `bottlenecks`: ranked friction patterns with observed data, inferred diagnosis, and suggested action kept as separate fields. `bottlenecks[].title` is a reader-facing display label and may change for clarity while stable IDs such as `changed-file-spread` remain unchanged.
+- `bottlenecks`: ranked positive-signal friction patterns with observed data, inferred diagnosis, and suggested action kept as separate fields. `bottlenecks[].title` is a reader-facing display label and may change for clarity while stable IDs such as `changed-file-spread` remain unchanged.
+- `noSignalBottlenecks`: ranked no-signal context entries using the same item property names as `bottlenecks`. Entries move here when their raw, unrounded report-owned representative scores are zero or when no displayed representative score is positive. They are excluded from `summary.topBottleneckIds` and recommendation category counts; `summary.noSignalBottleneckIds` records their IDs in deterministic order.
 - `bottlenecks[].observedData[]`: representative PR examples with PR identity, score/value, PR class evidence, final/current additions, deletions, changed-file count, and changed-line count.
 - `bottlenecks[].observedData[].validationEvidence`: workflow-run source label, workflow-run coverage, workflow-run conclusions, failed check-run count, failed workflow-run count, and cancelled workflow-run count for representative PR examples.
 - `bottlenecks[].observedData[].reviewEvidence`: review-thread source label, thread counts, resolution/outdated counts, review decision label/source, human reviewer count, human approval / changes-requested booleans, comment-source breakdown, bot comment count, human reviewer comment count, and author reply count for representative PR examples.
@@ -49,7 +50,7 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `guardrails`: machine-readable checks that the report avoids individual ranking, separates evidence from inference, and does not use an opaque composite score.
 - `followUp`: non-automated future work suggested by the report.
 
-Bottlenecks are ordered by their strongest observed representative metric value, with stable category order used only to break ties. Final/current PR size fields are context for comparing displayed examples against friction signals; they are not separate ordering inputs. The internal `changedFileSpread` / `changed-file-spread` signal remains the stable contract name for the metric that sums core files touched, directories touched, and functional surfaces touched. It is not a changed-line-count metric.
+Bottlenecks are ordered by their strongest observed representative metric value, with stable category order used only to break ties. `noSignalBottlenecks` preserves the same ranked-candidate ordering after positive-signal entries are removed, with stable bottleneck IDs used for no-signal ties. Final/current PR size fields are context for comparing displayed examples against friction signals; they are not separate ordering inputs. The internal `changedFileSpread` / `changed-file-spread` signal remains the stable contract name for the metric that sums core files touched, directories touched, and functional surfaces touched. It is not a changed-line-count metric.
 
 ## Markdown Output
 
@@ -71,6 +72,7 @@ The Markdown renderer presents the same report data for human review:
 - outlier and sensitivity analysis when displayed examples are dominated by one PR;
 - a prioritization explanation that describes strongest-signal ordering and how PR size is used as context, using reader-facing change-scope language while mapping back to the internal changed-file-spread signal when needed;
 - ranked bottlenecks with representative PR examples rendered as compact PR-size tables;
+- a no-signal section for zero-score or no-positive-score bottlenecks, explaining that they are future-run context rather than top findings or recommendation drivers;
 - validation, review, and source-label evidence for representative PR examples rendered as compact evidence tables;
 - text-backed status labels such as observed, partial, unavailable, configured, warning, and healthy in Markdown evidence tables where they improve scanability;
 - separately labeled inferred diagnosis, suggested action, and confidence/caveat blocks for each bottleneck;
@@ -128,7 +130,7 @@ Full live analysis writes `methodology.md` as a hybrid artifact: stable explanat
 
 The methodology artifact should stay aligned with this contract and the Markdown methodology summary, but it may be more detailed than the main report.
 
-When PR class filtering is applied, `source-bundle.json` remains the full collected sample, while `normalized.json`, `metrics-summary.json`, `friction-report.json`, `friction-report.md`, `methodology.md`, and CSV exports describe the filtered sample. The methodology and CLI completion output must name the excluded PR classes and show the filtered PR count. If filtering excludes every collected PR, the analysis must fail without writing complete-looking empty reports.
+When PR class filtering is applied to a full analysis, `source-bundle.json` remains the full collected sample, while `normalized.json`, `metrics-summary.json`, `friction-report.json`, `friction-report.md`, `methodology.md`, and CSV exports describe the filtered sample. The methodology and CLI completion output must name the excluded PR classes and show the filtered PR count. If filtering excludes every collected PR, the analysis must fail without writing complete-looking empty reports. Live dry-run receipts record requested PR class exclusions without a filtered count because dry-run does not build normalized metrics.
 
 ## CSV Evidence Exports
 
@@ -143,7 +145,7 @@ Minimum CSV column groups:
 - `comment-sources.csv`: source name, total comments, bot/scanner classification, human/author classification, and share of all comments.
 - `collection-coverage.csv`: source family, status, attempts, source label, diagnostics, and downstream impact.
 
-Empty CSV cells mean unavailable or not applicable. Numeric zero should be used only for observed or computed zero counts. Count columns that depend on optional GitHub coverage should keep source or coverage labels nearby so spreadsheet readers can tell unavailable evidence apart from observed zeroes. CSVs must not include raw comment bodies, raw workflow logs, tokens, secret-bearing environment details, or individual contributor/reviewer rankings.
+Empty CSV cells mean unavailable or not applicable. Numeric zero should be used only for observed or computed zero counts. Count columns that depend on optional GitHub or sample-bundle coverage should keep source or coverage labels nearby so spreadsheet readers can tell unavailable evidence apart from observed zeroes. `pr-metrics.csv` `review_threads` is populated when normalized review-thread source evidence is available, including synthetic sample evidence and live GraphQL review-thread evidence. CSVs must not include raw comment bodies, raw workflow logs, tokens, secret-bearing environment details, or individual contributor/reviewer rankings.
 
 Contributor-source coverage appears in `collection-coverage.csv` as the `contributor_source` source family when configured. CSVs may include aggregate comment-source counts influenced by contributor hints, but they must not include raw `.all-contributorsrc` contents, contributor names, contributor login lists, or person rankings.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",

package/release-log.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+### 2026-06-28 — Low-Signal Report Quieting
+
+- What changed: Friction report JSON and Markdown now separate zero-score or no-positive-evidence bottlenecks into no-signal context, and completion receipts expose matching `noSignalBottleneckIds` for report-generating runs while leaving coverage-only runs unranked.
+- Why it matters: Users and maintainers can distinguish observed friction from inactive checks without losing machine-readable evidence or report context.
+- Who is affected: Maintainers and users reading generated Markdown reports, `friction-report.json`, or JSON completion receipts from sample or live GitHub analysis.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/69
+
+### 2026-06-28 — CLI Artifact Truthfulness
+
+- What changed: Live dry-run JSON receipts now show requested PR-class exclusions without implying filtered metrics were computed, and `pr-metrics.csv` fills `review_threads` when sample or live review-thread evidence is available.
+- Why it matters: Maintainers and scripts can trust completion receipts and CSV evidence to reflect accepted filters and available review-thread counts.
+- Who is affected: Maintainers and users reading JSON completion receipts, CSV exports, and contract docs from sample or live GitHub analysis.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/68
+
 ### 2026-06-28 — CLI Command Help Clarity
 
 - What changed: CLI help now separates the bundled sample, live GitHub analysis, live coverage probes, output controls, interactive setup, and reusable live-run presets, with mode-specific help for `--source sample --help` and `--source github --help`.

package/src/cli/analyze-github.js

@@ -1679,6 +1679,7 @@ function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report,
     collectionCoverage: sourceBundle.coverage,
     totals: metrics?.totals ?? null,
     topBottleneckIds: report?.summary?.topBottleneckIds ?? null,
+    noSignalBottleneckIds: report?.summary?.noSignalBottleneckIds ?? null,
   };
   if (savedProfilePath) {
     summary.savedProfilePath = savedProfilePath;
@@ -1695,6 +1696,15 @@ function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report,
   return summary;
 }
 
+function requestedAnalysisFilter(excludedPrClasses = []) {
+  if (!excludedPrClasses.length) return null;
+  return {
+    excludedPrClasses,
+    originalPullRequests: null,
+    filteredPullRequests: null,
+  };
+}
+
 function applyPrClassFilter(normalized, excludedPrClasses = []) {
   if (!excludedPrClasses.length) return normalized;
   const excluded = new Set(excludedPrClasses);
@@ -1824,7 +1834,7 @@ export async function runAnalyzeGithub(options, {
       requestedLimit: options.limit,
       sampledLimit: collectionLimit,
       csv: false,
-      analysisFilter: null,
+      analysisFilter: requestedAnalysisFilter(options.excludedPrClasses ?? []),
       savedProfilePath: options.savedProfilePath,
       savedRunPresetPath: options.savedRunPresetPath,
       prClassRulesWritten: options.prClassRulesWritten,
@@ -1988,10 +1998,13 @@ export function formatAnalyzeGithubCompletion(result) {
   }
 
   if (result.analysisFilter?.excludedPrClasses?.length) {
-    lines.push(
-      `Analysis filter: excluded PR class(es): ${result.analysisFilter.excludedPrClasses.join(", ")}.`,
-      `Filtered sample: ${result.analysisFilter.filteredPullRequests} of ${result.analysisFilter.originalPullRequests} collected pull request(s).`,
-    );
+    lines.push(`Analysis filter: excluded PR class(es): ${result.analysisFilter.excludedPrClasses.join(", ")}.`);
+    if (Number.isInteger(result.analysisFilter.filteredPullRequests)
+      && Number.isInteger(result.analysisFilter.originalPullRequests)) {
+      lines.push(`Filtered sample: ${result.analysisFilter.filteredPullRequests} of ${result.analysisFilter.originalPullRequests} collected pull request(s).`);
+    } else if (result.dryRun) {
+      lines.push("Filter application: requested only; dry-run coverage probes do not compute filtered metrics or report artifacts.");
+    }
   }
 
   if (result.savedProfilePath) {

package/src/report/evidence-artifacts.js

@@ -94,9 +94,12 @@ function hasObservedWorkflowRuns(workflowRuns = {}) {
   return (workflowRuns.coverage ?? workflowRuns.workflowRunCoverage) === "observed";
 }
 
-function hasObservedReviewThreads(reviewThreads = {}) {
+function hasObservedReviewThreads(reviewThreads = {}, coverage = {}) {
   const source = reviewThreads.source ?? reviewThreads.reviewThreadSource ?? "unavailable";
-  return String(source).startsWith("graphql");
+  if (String(source).startsWith("graphql")) return true;
+  if (String(source).startsWith("not_sampled") || source === "unavailable") return false;
+  if (String(source).includes("review_threads")) return true;
+  return coverage.status === "available";
 }
 
 function hasObservedReviewDecision(reviewDecision = {}) {
@@ -135,7 +138,7 @@ function prMetricsCsv(metricsSummary, analysisFilter) {
     ...SCORE_COLUMNS.map(([header]) => header),
   ];
   const rows = sortedPullRequests(metricsSummary).map(pr => {
-    const observedReviewThreads = hasObservedReviewThreads(pr.review?.threads);
+    const observedReviewThreads = hasObservedReviewThreads(pr.review?.threads, pr.coverage?.reviewThreads);
     const observedReviewDecision = hasObservedReviewDecision(pr.review?.decision);
     const observedWorkflowRuns = hasObservedWorkflowRuns(pr.ci?.workflowRuns);
     const row = {

package/src/report/friction-report.js

@@ -469,6 +469,32 @@ function summarizeBottlenecks(metricsSummary, prClasses = summarizePrClasses(met
     .map(({ definitionIndex, rankValue, ...bottleneck }) => bottleneck);
 }
 
+function hasPositiveRepresentativeScore(bottleneck) {
+  return (bottleneck.observedData ?? [])
+    .some(evidence => Number(evidence.value ?? 0) > 0);
+}
+
+function splitBottleneckSignals(bottlenecks) {
+  const positiveSignalBottlenecks = [];
+  const noSignalBottlenecks = [];
+
+  for (const bottleneck of bottlenecks ?? []) {
+    if (hasPositiveRepresentativeScore(bottleneck)) {
+      positiveSignalBottlenecks.push(bottleneck);
+    } else {
+      noSignalBottlenecks.push(bottleneck);
+    }
+  }
+
+  noSignalBottlenecks.sort((left, right) => {
+    const leftRank = Number(left.observedData?.[0]?.value ?? 0);
+    const rightRank = Number(right.observedData?.[0]?.value ?? 0);
+    return (rightRank - leftRank) || left.id.localeCompare(right.id);
+  });
+
+  return { positiveSignalBottlenecks, noSignalBottlenecks };
+}
+
 function summarizeEvidenceDominance(evidence) {
   const values = evidence
     .map(entry => Number(entry.value ?? 0))
@@ -866,7 +892,9 @@ function summarizeSensitivity(metricsSummary, baselineBottlenecks) {
   return {
     summaries: dominantPrNumbers.map(excludedPrNumber => {
       const excludedPr = findPullRequest(metricsSummary, excludedPrNumber);
-      const filteredBottlenecks = summarizeBottlenecks(metricsWithoutPullRequest(metricsSummary, excludedPrNumber));
+      const { positiveSignalBottlenecks: filteredBottlenecks } = splitBottleneckSignals(
+        summarizeBottlenecks(metricsWithoutPullRequest(metricsSummary, excludedPrNumber)),
+      );
       const filteredTopBottleneckIds = filteredBottlenecks.slice(0, 3).map(bottleneck => bottleneck.id);
       const affectedBottlenecks = baselineBottlenecks
         .filter(bottleneck => bottleneck.dominance?.status === "single_pr_dominates"
@@ -904,9 +932,15 @@ function summarizeSensitivity(metricsSummary, baselineBottlenecks) {
 export function generateRepositoryFrictionReport(metricsSummary, options = {}) {
   const { workflowContext, contributorSource } = options ?? {};
   const prClasses = summarizePrClasses(metricsSummary);
-  const bottlenecksWithSharedSignalKeys = summarizeBottlenecks(metricsSummary, prClasses);
+  const rankedBottlenecksWithSharedSignalKeys = summarizeBottlenecks(metricsSummary, prClasses);
+  const {
+    positiveSignalBottlenecks: bottlenecksWithSharedSignalKeys,
+    noSignalBottlenecks: noSignalBottlenecksWithSharedSignalKeys,
+  } = splitBottleneckSignals(rankedBottlenecksWithSharedSignalKeys);
   const sharedSignals = summarizeSharedSignals(bottlenecksWithSharedSignalKeys);
   const bottlenecks = bottlenecksWithSharedSignalKeys.map(({ rankingKey, ...bottleneck }) => bottleneck);
+  const noSignalBottlenecks = noSignalBottlenecksWithSharedSignalKeys
+    .map(({ rankingKey, ...bottleneck }) => bottleneck);
   const configuredWorkflow = normalizeConfiguredWorkflowContext(workflowContext);
   const contributorSourceMetadata = normalizeContributorSourceMetadata(contributorSource);
   return {
@@ -925,12 +959,14 @@ export function generateRepositoryFrictionReport(metricsSummary, options = {}) {
       failedChecks: metricsSummary.totals?.failedChecks ?? 0,
       cancelledWorkflowRuns: metricsSummary.totals?.cancelledWorkflowRuns ?? 0,
       topBottleneckIds: bottlenecks.slice(0, 3).map(bottleneck => bottleneck.id),
+      noSignalBottleneckIds: noSignalBottlenecks.map(bottleneck => bottleneck.id),
     },
     coverage: summarizeCoverage(metricsSummary),
     commentSources: summarizeCommentSources(metricsSummary),
     surfaces: summarizeSurfaces(metricsSummary),
     prClasses,
     bottlenecks,
+    noSignalBottlenecks,
     sharedSignals,
     sensitivity: summarizeSensitivity(metricsSummary, bottlenecks),
     recommendationCategories: summarizeRecommendationCategories(bottlenecks),
@@ -1263,6 +1299,7 @@ function renderPriorityExplanation() {
   return renderList([
     "Bottlenecks are ordered by their strongest displayed representative score, not by an opaque composite priority score.",
     "Each score comes from one metric family, such as review-loop drag, validation failures, change scope, planning signals, review surprise, or post-review commits.",
+    "Bottlenecks with no positive raw representative score are shown as no-signal context instead of top findings or recommendation drivers.",
     "Change scope is the internal changed-file-spread signal: core files touched plus directories touched plus functional surfaces touched. It is not a line-count metric.",
     "PR size columns show final/current additions, deletions, changed files, and changed lines so readers can compare size against the detected friction signals.",
     "PR size columns are context for interpreting displayed examples; bottleneck ordering uses each metric family's representative score and stable tie-breaks, not the PR size columns.",
@@ -1270,6 +1307,27 @@ function renderPriorityExplanation() {
   ]);
 }
 
+function renderNoSignalBottlenecks(bottlenecks) {
+  const noSignalBottlenecks = bottlenecks ?? [];
+  if (!noSignalBottlenecks.length) return "";
+
+  return [
+    "## No Signal Observed",
+    "",
+    "These bottlenecks had representative report-owned scores of zero or no positive representative score in the displayed evidence. They remain useful context for future runs when matching evidence appears, but they are not treated as top findings or recommendation drivers in this report.",
+    "",
+    renderMarkdownTable(
+      ["Bottleneck", "Metric", "Potential use when evidence exists"],
+      noSignalBottlenecks.map(bottleneck => [
+        bottleneck.title,
+        bottleneck.metricLabel,
+        recommendationActionText(bottleneck),
+      ]),
+    ),
+    "",
+  ].join("\n");
+}
+
 function topBottleneckLabels(report) {
   const bottlenecksById = new Map((report.bottlenecks ?? []).map(bottleneck => [bottleneck.id, bottleneck]));
   const ids = report.summary?.topBottleneckIds ?? [];
@@ -1712,6 +1770,11 @@ export function renderRepositoryFrictionMarkdown(report) {
     );
   }
 
+  const noSignalSection = renderNoSignalBottlenecks(report.noSignalBottlenecks);
+  if (noSignalSection) {
+    lines.push(noSignalSection);
+  }
+
   lines.push(
     "## Recommendation Categories",
     "",
@@ -1733,6 +1796,7 @@ export function renderRepositoryFrictionMarkdown(report) {
       ? "- Profile suggestions are optional interpretation improvements derived from existing report evidence; they do not change scores, rankings, CSV exports, or JSON report fields."
       : "- No profile suggestion thresholds were triggered by this report's PR class, role, functional-surface, or workflow-coverage evidence.",
     "- Bottlenecks are ranked by their strongest representative observed signal, with stable category order only used to break ties.",
+    "- Zero-score or no-positive-score bottlenecks are retained in no-signal context and excluded from top findings and recommendation category counts.",
     "- Recommendations are inferred from transparent component evidence and representative PR examples; they are not automated changes.",
     "- Missing or partial source evidence remains visible in coverage tables rather than being inferred from unrelated fields.",
     ...(hasConfiguredWorkflowContext(report.configuredWorkflow)