delivery-friction-analyzer 0.8.0 → 0.10.0

package/docs/contracts/friction-report.md

@@ -1,6 +1,6 @@
 # Friction Report Contract
 
-Milestone 3 introduces `friction-report.v1`, a deterministic report generated from a `friction-metrics.v1` repository metrics summary. The report layer does not fetch GitHub data, mutate repositories, rank individuals, or depend on services beyond the data collection path that produced the metrics summary.
+Milestone 3 introduced `friction-report.v1`, a deterministic report generated from a `friction-metrics.v1` repository metrics summary. Milestones 4 and 5 add Markdown and methodology profile suggestions without adding report JSON fields. The report layer does not fetch GitHub data, mutate repositories, rank individuals, or depend on services beyond the data collection path that produced the metrics summary.
 
 ## Outputs
 
@@ -57,9 +57,11 @@ The Markdown renderer presents the same report data for human review:
 - a compact recommendation-category snapshot before detailed bottlenecks, with the full category reference retained later in the report;
 - a short "How To Read This Report" guide that distinguishes observed evidence, interpretation, recommendations, and caveats;
 - a configured workflow context section only when repository profile workflow fields are present, labeled as user-configured profile context rather than observed GitHub evidence;
+- workflow data caveats when configured workflow context clarifies unavailable PR-open diff or workflow-run evidence;
 - evidence-quality and coverage tables before detailed recommendations;
 - key findings that highlight top bottlenecks, strongest displayed signal, outlier caveats, PR class caveats, and coverage caveats;
 - a PR class context table that shows analyzed PR counts, changed lines, sample share, and classification sources by class;
+- profile suggestions when fallback `unknown` PR classes, unknown file role/surface evidence, or omitted workflow context with relevant unavailable coverage cross deterministic thresholds;
 - a top-level shared-signal interpretation callout when multiple displayed bottlenecks share a ranking key or representative PR evidence;
 - 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;
@@ -75,6 +77,9 @@ The Markdown renderer presents the same report data for human review:
 
 Markdown output should not include individual contributor or reviewer rankings.
 Status labels are Markdown presentation helpers, not `friction-report.v1` fields. They should preserve the underlying source labels and counts rather than replacing auditable evidence.
+Profile suggestions are also presentation helpers, not `friction-report.v1` fields. They are derived from existing PR class and file-surface evidence, appear at most once per suggestion category, and do not change scores, rankings, CSV exports, filtering, or PR class matching. Because the report JSON does not carry repository-profile rule inventory, all analyzed PRs using fallback `unknown` PR class evidence is the renderer's small-sample proxy for no configured PR class rule producing usable classification evidence.
+
+Workflow-context suggestions are presentation helpers, not `friction-report.v1` fields. They render when workflow context is omitted and the report has unavailable PR-open diff coverage or workflow-run coverage that maintainer-confirmed workflow context could help explain. They are omitted when workflow context is configured or when those coverage caveats are absent.
 
 ## Recommendation Boundaries
 
@@ -92,7 +97,7 @@ The M3 report contract supports these recommendation categories:
 
 ## Coverage And Confidence
 
-Reports must label unavailable or partial GitHub data instead of inferring unavailable values from merge-time data. PR-open diff growth remains unavailable unless direct or reconstructed counts exist. Workflow coverage and review-thread sources are summarized separately.
+Reports must label unavailable or partial GitHub data instead of inferring unavailable values from merge-time data. Final/current PR metadata can come from GitHub PR data, but PR-open diff growth remains unavailable unless an open-time snapshot or equivalent captured state exists. Workflow coverage and review-thread sources are summarized separately.
 
 Representative examples should carry enough source evidence to trace a report claim back to generated artifacts. Validation examples should name the workflow-run source and conclusions. Review churn examples should name the review-thread source, review decision evidence, and comment sources. PR class evidence should be visible in representative bottleneck examples so readers can distinguish workflow populations such as release, dependency, development, or repository-specific classes. When `reviewThreads` is zero, review decision evidence should make clean human approval distinguishable from unavailable review evidence and from observed absence of human review. When displayed examples are dominated by one PR or one PR class, the report should say so instead of implying a repository-wide pattern from an outlier or workflow population.
 
@@ -109,6 +114,7 @@ Full live analysis writes `methodology.md` as a hybrid artifact: stable explanat
 - target repository and report/metric versions;
 - profile path when available;
 - configured workflow context when supplied by the repository profile, labeled as user-configured context rather than observed GitHub evidence;
+- profile suggestions when PR class, file/path, or workflow-context profile evidence crosses deterministic fallback thresholds, or an explicit no-threshold note when none were triggered;
 - requested and collected PR counts;
 - collection coverage status and API-family diagnostics;
 - scoring, ranking, dominance, sensitivity, and limitation explanations;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.8.0",
+  "version": "0.10.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-20 — Workflow Data Caveats
+
+- What changed: Markdown friction reports and methodology now explain PR-open diff and workflow-run coverage limits with configured workflow context when it is available, and suggest adding workflow context when omitted context would clarify unavailable evidence.
+- Why it matters: Maintainers can distinguish final GitHub PR metadata from unreconstructable open-time PR size without mistaking merge strategy for observed evidence or a scoring input.
+- Who is affected: Maintainers and contributors reviewing generated reports or authoring repository profiles with workflow context.
+- Action needed: Optional; add repository-profile workflow context when unavailable coverage would be easier to interpret with maintainer-confirmed merge or branch assumptions.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/46
+
+### 2026-06-20 — Profile Improvement Suggestions
+
+- What changed: Markdown friction reports and methodology now suggest PR class or file/path profile improvements when fallback `unknown` evidence dominates the analyzed sample.
+- Why it matters: Maintainers can see where repository profile rules would improve interpretation without treating the suggestions as score changes or required fixes.
+- Who is affected: Maintainers and contributors reviewing generated reports or authoring repository profiles.
+- Action needed: Optional; add or refine profile rules when the suggestions match repository conventions.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/45
+
 ### 2026-06-20 — Report Evidence Status Tables
 
 - What changed: Markdown friction reports now show representative validation, review, and source-label evidence in compact tables with text status labels for observed, partial, unavailable, configured, warning, and healthy states.

package/src/report/evidence-artifacts.js

@@ -2,6 +2,8 @@ import {
   CONFIGURED_WORKFLOW_NOTE,
   configuredWorkflowEntries,
   hasConfiguredWorkflowContext,
+  profileSuggestions,
+  workflowDataCaveats,
 } from "./friction-report.js";
 
 const BOT_OR_SCANNER_SOURCES = new Set([
@@ -345,6 +347,7 @@ function formatSensitivitySummaries(report) {
 function formatConfiguredWorkflowContext(report) {
   const configuredWorkflow = report.configuredWorkflow;
   if (!hasConfiguredWorkflowContext(configuredWorkflow)) return [];
+  const caveats = workflowDataCaveats(report);
 
   return [
     "## Configured Workflow Context",
@@ -353,6 +356,38 @@ function formatConfiguredWorkflowContext(report) {
     "",
     ...configuredWorkflowEntries(configuredWorkflow)
       .map(entry => `- ${entry.label}: ${entry.valueLabel}`),
+    ...(caveats.length
+      ? [
+          "",
+          "Workflow data caveats:",
+          "",
+          ...caveats.map(caveat => `- ${caveat}`),
+        ]
+      : []),
+    "",
+  ];
+}
+
+function formatProfileSuggestions(report) {
+  const suggestions = profileSuggestions(report);
+  if (!suggestions.length) {
+    return [
+      "## Profile Suggestions",
+      "",
+      "- No profile suggestion thresholds were triggered by this report's PR class, role, functional-surface, or workflow-coverage evidence.",
+      "",
+    ];
+  }
+
+  return [
+    "## Profile Suggestions",
+    "",
+    "Profile suggestions are optional interpretation improvements derived from existing report evidence. They do not change scores, rankings, CSV exports, or JSON report fields.",
+    "",
+    ...suggestions.map(suggestion => [
+      `- ${suggestion.area}: ${suggestion.evidence}`,
+      `  Suggested next step: ${suggestion.suggestion}`,
+    ].join("\n")),
     "",
   ];
 }
@@ -394,6 +429,7 @@ export function renderRepositoryFrictionMethodology({
     "",
     "The repository profile maps file paths to categories, roles, and functional surfaces. Those classifications drive non-generated changed-line counts, support-surface summaries, planning-document signals, and low-signal weighting.",
     "",
+    ...formatProfileSuggestions(report),
     ...formatConfiguredWorkflowContext(report),
     "## Scores And Rankings",
     "",

package/src/report/friction-report.js

@@ -83,6 +83,14 @@ const WORKFLOW_CONTEXT_VALUE_LABELS = new Map([
 
 export const CONFIGURED_WORKFLOW_NOTE = "Configured workflow context comes from the repository profile. It is user-configured context, not observed GitHub evidence, and it does not change scores, rankings, CSV exports, or PR class matching.";
 
+const PR_OPEN_DIFF_LIMITATION_NOTE = "PR-open diff growth is unavailable for PRs without an open-time snapshot or equivalent captured state; final/current PR metadata can still come from GitHub PR data, but open-time size is not reconstructed from merge-time data.";
+
+const PROFILE_SUGGESTION_THRESHOLDS = {
+  minimumPrClassSample: 3,
+  unknownPrClassShare: 0.8,
+  unknownFileShare: 0.25,
+};
+
 const BOTTLENECK_DEFINITIONS = [
   {
     id: "review-churn",
@@ -415,9 +423,7 @@ function summarizeCoverage(metricsSummary) {
 
   const notes = [];
   if (prOpenDiff.unavailable) {
-    notes.push(
-      "PR-open diff growth is unavailable for PRs without captured or reconstructed open-time snapshots; it is not inferred from merge-time data.",
-    );
+    notes.push(PR_OPEN_DIFF_LIMITATION_NOTE);
   }
   if (workflowRuns.unavailable) {
     notes.push("Workflow-run coverage is unavailable for some PRs, often because branch-based history is missing.");
@@ -585,6 +591,81 @@ function summarizeRecommendationCategories(bottlenecks) {
   }));
 }
 
+function entryValue(entries = [], name) {
+  return Number((entries ?? []).find(entry => entry.name === name)?.value ?? 0);
+}
+
+function classSourceValue(entry = {}, source) {
+  return entryValue(entry.classificationSources, source);
+}
+
+export function profileSuggestions(report = {}) {
+  const suggestions = [];
+  const summary = report.summary ?? {};
+  const prClasses = report.prClasses ?? {};
+  const classDistribution = prClasses.distribution ?? [];
+  const totalPullRequests = Number(prClasses.totalPullRequests ?? summary.pullRequests ?? 0);
+  const unknownClass = classDistribution.find(entry => entry.class === "unknown");
+  const unknownClassPullRequests = Number(unknownClass?.pullRequests ?? 0);
+  const fallbackUnknownPullRequests = classSourceValue(unknownClass, "fallback_rule");
+  const fallbackUnknownClassShare = totalPullRequests > 0
+    ? fallbackUnknownPullRequests / totalPullRequests
+    : 0;
+  const everyPrFallbackUnknown = totalPullRequests > 0
+    && unknownClassPullRequests === totalPullRequests
+    && fallbackUnknownPullRequests === unknownClassPullRequests;
+
+  if ((totalPullRequests >= PROFILE_SUGGESTION_THRESHOLDS.minimumPrClassSample
+    && fallbackUnknownClassShare >= PROFILE_SUGGESTION_THRESHOLDS.unknownPrClassShare)
+    || everyPrFallbackUnknown) {
+    suggestions.push({
+      id: "pr-class-rules",
+      area: "PR class rules",
+      evidence: `${fallbackUnknownPullRequests} of ${totalPullRequests} analyzed PRs (${percentageLabel(fallbackUnknownClassShare)}) use fallback unknown PR class evidence.`,
+      suggestion: "Add or refine repository-profile PR class title rules, or rerun interactive setup to add the Conventional Commit preset when it matches the repository.",
+    });
+  }
+
+  const nonGeneratedChangedLines = Number(summary.nonGeneratedChangedLines ?? 0);
+  const surfaces = report.surfaces ?? {};
+  const unknownRoleLines = entryValue(surfaces.byRole, "unknown");
+  const unknownSurfaceLines = entryValue(surfaces.byFunctionalSurface, "unknown");
+  const unknownRoleShare = nonGeneratedChangedLines > 0 ? unknownRoleLines / nonGeneratedChangedLines : 0;
+  const unknownSurfaceShare = nonGeneratedChangedLines > 0 ? unknownSurfaceLines / nonGeneratedChangedLines : 0;
+
+  if (unknownRoleShare >= PROFILE_SUGGESTION_THRESHOLDS.unknownFileShare
+    || unknownSurfaceShare >= PROFILE_SUGGESTION_THRESHOLDS.unknownFileShare) {
+    suggestions.push({
+      id: "file-path-rules",
+      area: "File/path rules",
+      evidence: `Unknown role lines: ${unknownRoleLines} of ${nonGeneratedChangedLines} (${percentageLabel(unknownRoleShare)}); unknown functional-surface lines: ${unknownSurfaceLines} of ${nonGeneratedChangedLines} (${percentageLabel(unknownSurfaceShare)}).`,
+      suggestion: "Add repository-profile path rules for high-volume unknown roles or functional surfaces, starting with the directories that account for the most non-generated changed lines.",
+    });
+  }
+
+  const hasWorkflowContext = hasConfiguredWorkflowContext(report.configuredWorkflow);
+  const unavailablePrOpenDiff = Number(report.coverage?.prOpenDiff?.unavailable ?? 0);
+  const unavailableWorkflowRuns = Number(report.coverage?.workflowRuns?.unavailable ?? 0);
+  if (!hasWorkflowContext && (unavailablePrOpenDiff > 0 || unavailableWorkflowRuns > 0)) {
+    const evidence = [
+      unavailablePrOpenDiff > 0
+        ? `PR-open diff coverage unavailable for ${formatCount(unavailablePrOpenDiff, "PR")}`
+        : null,
+      unavailableWorkflowRuns > 0
+        ? `workflow-run coverage unavailable for ${formatCount(unavailableWorkflowRuns, "PR")}`
+        : null,
+    ].filter(Boolean).join("; ");
+    suggestions.push({
+      id: "workflow-context",
+      area: "Workflow context",
+      evidence: `${evidence}.`,
+      suggestion: "Configure repository-profile workflow context, such as primary merge method or branch strategy, so unavailable diff-growth or workflow-run evidence is interpreted with maintainer-confirmed context instead of guesses.",
+    });
+  }
+
+  return suggestions;
+}
+
 export function normalizeConfiguredWorkflowContext(workflowContext) {
   if (!workflowContext || typeof workflowContext !== "object" || Array.isArray(workflowContext)) {
     return null;
@@ -621,6 +702,39 @@ export function hasConfiguredWorkflowContext(configuredWorkflow) {
   return configuredWorkflowEntries(configuredWorkflow).length > 0;
 }
 
+function configuredWorkflowEntry(configuredWorkflow, field) {
+  const entry = configuredWorkflowEntries(configuredWorkflow).find(candidate => candidate.field === field);
+  return entry ?? null;
+}
+
+export function workflowDataCaveats(report = {}) {
+  if (!hasConfiguredWorkflowContext(report.configuredWorkflow)) return [];
+
+  const unavailablePrOpenDiff = Number(report.coverage?.prOpenDiff?.unavailable ?? 0);
+  const unavailableWorkflowRuns = Number(report.coverage?.workflowRuns?.unavailable ?? 0);
+  if (unavailablePrOpenDiff <= 0 && unavailableWorkflowRuns <= 0) return [];
+
+  const mergeMethod = configuredWorkflowEntry(report.configuredWorkflow, "primaryMergeMethod");
+  const caveats = [];
+  if (unavailablePrOpenDiff > 0) {
+    const prefix = mergeMethod
+      ? `Profile context says primary merge method is ${mergeMethod.valueLabel}; this is configured profile context, not observed evidence.`
+      : "Configured workflow fields are profile context, not observed evidence.";
+    const methodLimit = {
+      squash_merge: "Squash merge keeps final PR metadata available through GitHub PR data, but it does not preserve the original branch commit topology on the base branch.",
+      rebase_merge: "Rebase merge keeps final PR metadata available through GitHub PR data, but rebased commits do not provide a reliable open-time diff snapshot from base-branch history.",
+      merge_commit: "Merge commits can preserve a merge boundary, but this analyzer still uses GitHub PR data for final/current PR metadata and does not reconstruct PR-open size from merge commits or branch history.",
+    }[mergeMethod?.value] ?? "Final/current PR metadata can come from GitHub PR data, but PR-open diff growth still needs captured open-time evidence.";
+    caveats.push(`${prefix} ${methodLimit} PR-open diff growth requires an open-time snapshot or equivalent captured state.`);
+  }
+
+  if (unavailableWorkflowRuns > 0) {
+    caveats.push("Unavailable workflow-run coverage remains a GitHub collection coverage limit; configured workflow context can explain the repository's expected workflow shape, but it is not observed run evidence.");
+  }
+
+  return caveats;
+}
+
 function evidenceSignature(bottleneck) {
   return (bottleneck.observedData ?? [])
     .map(evidence => evidence.number)
@@ -1294,6 +1408,27 @@ function renderPrClassContext(prClasses) {
   ].join("\n");
 }
 
+function renderProfileSuggestions(report) {
+  const suggestions = profileSuggestions(report);
+  if (!suggestions.length) return "";
+
+  return [
+    "## Profile Suggestions",
+    "",
+    "Optional profile improvements based on this report's existing evidence. These suggestions do not change scores, rankings, CSV exports, or JSON report fields.",
+    "",
+    renderMarkdownTable(
+      ["Profile area", "Evidence", "Suggested next step"],
+      suggestions.map(suggestion => [
+        suggestion.area,
+        suggestion.evidence,
+        suggestion.suggestion,
+      ]),
+    ),
+    "",
+  ].join("\n");
+}
+
 function renderConfiguredWorkflowContext(configuredWorkflow) {
   const entries = configuredWorkflowEntries(configuredWorkflow);
   if (!entries.length) return "";
@@ -1311,6 +1446,18 @@ function renderConfiguredWorkflowContext(configuredWorkflow) {
   ].join("\n");
 }
 
+function renderWorkflowDataCaveats(report) {
+  const caveats = workflowDataCaveats(report);
+  if (!caveats.length) return "";
+
+  return [
+    "## Workflow Data Caveats",
+    "",
+    renderList(caveats),
+    "",
+  ].join("\n");
+}
+
 function classDominanceCaveat(bottleneck) {
   return bottleneck.classDominance?.status === "single_class_dominates"
     ? bottleneck.classDominance.note
@@ -1465,6 +1612,9 @@ export function renderRepositoryFrictionMarkdown(report) {
     ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
       ? [renderConfiguredWorkflowContext(report.configuredWorkflow)]
       : []),
+    ...(workflowDataCaveats(report).length
+      ? [renderWorkflowDataCaveats(report)]
+      : []),
     "## Evidence Quality And Coverage",
     "",
     renderCoverageSummary(report.coverage),
@@ -1478,6 +1628,7 @@ export function renderRepositoryFrictionMarkdown(report) {
     renderKeyFindings(report),
     "",
     renderPrClassContext(report.prClasses),
+    renderProfileSuggestions(report),
     renderSharedSignalInterpretation(sharedSignals),
     renderSensitivityAnalysis(report.sensitivity),
     "## How Bottlenecks Are Prioritized",
@@ -1532,12 +1683,18 @@ export function renderRepositoryFrictionMarkdown(report) {
     "",
     "- Pull requests are selected upstream by the collection or fixture workflow; this renderer explains the resulting metrics summary.",
     "- File roles and functional surfaces come from repository-profile classification, not from language names alone.",
+    profileSuggestions(report).length
+      ? "- 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.",
     "- Recommendations are inferred from transparent component evidence and representative PR examples; they are not automated changes.",
     "- Missing or partial GitHub data remains visible in coverage tables rather than being inferred from unrelated fields.",
     ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
       ? ["- Configured workflow context is user-configured repository-profile context; it does not change scoring, ranking, CSV exports, or PR class matching."]
       : []),
+    ...(workflowDataCaveats(report).length
+      ? ["- Workflow data caveats explain unavailable evidence using configured profile context without treating merge method as observed evidence or reconstructing open-time PR size."]
+      : []),
     "- Sensitivity analysis, when present, excludes one dominant representative PR at a time to show robustness context without changing the baseline ranking.",
     report.analysisFilter?.excludedPrClasses?.length
       ? "- PR class filtering was explicitly applied before metrics and ranking; PR class context still supports interpretation of the filtered sample."