delivery-friction-analyzer 0.22.1 → 0.23.1

package/docs/contracts/friction-report.md

@@ -32,12 +32,13 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `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;

package/package.json

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

package/release-log.md

@@ -2,6 +2,14 @@
 
 ## 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.

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;

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)