delivery-friction-analyzer 0.7.3 → 0.9.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. Milestone 4 adds 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
 
@@ -60,11 +60,13 @@ The Markdown renderer presents the same report data for human review:
 - 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 or unknown file role/surface evidence 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;
 - ranked bottlenecks with representative PR examples rendered as compact PR-size tables;
-- validation, review, and source-label evidence for each representative PR example rendered as plain Markdown detail lists;
+- 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;
 - shared-evidence notes when multiple recommendation categories use the same representative PR set;
 - recommendation-category, comment-source, and core/support-surface tables;
@@ -73,6 +75,8 @@ The Markdown renderer presents the same report data for human review:
 - guardrails, follow-up, and artifact-sensitivity guidance.
 
 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.
 
 ## Recommendation Boundaries
 
@@ -107,6 +111,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 or file/path 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.7.3",
+  "version": "0.9.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 — 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.
+- Why it matters: Maintainers can compare bottleneck evidence more quickly while still seeing when evidence is configured, incomplete, unavailable, or directly observed.
+- Who is affected: Maintainers and contributors reviewing generated Markdown friction reports.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/44
+
 ### 2026-06-19 — Interactive Setup Choice Presets
 
 - What changed: Interactive setup now shows workflow profile choices as labeled selections and can add an opt-in Conventional Commit PR class preset to generated or updated repository profiles.

package/src/report/evidence-artifacts.js

@@ -2,6 +2,7 @@ import {
   CONFIGURED_WORKFLOW_NOTE,
   configuredWorkflowEntries,
   hasConfiguredWorkflowContext,
+  profileSuggestions,
 } from "./friction-report.js";
 
 const BOT_OR_SCANNER_SOURCES = new Set([
@@ -357,6 +358,30 @@ function formatConfiguredWorkflowContext(report) {
   ];
 }
 
+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, or functional-surface 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")),
+    "",
+  ];
+}
+
 export function renderRepositoryFrictionMethodology({
   report,
   sourceBundle,
@@ -394,6 +419,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,12 @@ 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 PROFILE_SUGGESTION_THRESHOLDS = {
+  minimumPrClassSample: 3,
+  unknownPrClassShare: 0.8,
+  unknownFileShare: 0.25,
+};
+
 const BOTTLENECK_DEFINITIONS = [
   {
     id: "review-churn",
@@ -585,6 +591,61 @@ 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.",
+    });
+  }
+
+  return suggestions;
+}
+
 export function normalizeConfiguredWorkflowContext(workflowContext) {
   if (!workflowContext || typeof workflowContext !== "object" || Array.isArray(workflowContext)) {
     return null;
@@ -933,56 +994,137 @@ function renderEvidenceTable(observedData) {
   );
 }
 
-function renderDetailList(items) {
-  return items.length ? items.map(item => `- ${escapeMarkdownText(item)}`).join("\n") : "- None";
+function statusLabel(status, detail) {
+  return `[${status}] ${detail}`;
 }
 
-function renderEvidenceDetails(observedData) {
+function coverageStatusLabel(value) {
+  switch (value) {
+    case "observed":
+    case "available":
+      return "observed";
+    case "partial":
+      return "partial";
+    default:
+      return "unavailable";
+  }
+}
+
+function validationStatusSummary(validationEvidence = {}) {
+  const coverage = validationEvidence.workflowRunCoverage ?? "unavailable";
+  const coverageStatus = coverageStatusLabel(coverage);
+  const failedCheckRuns = Number(validationEvidence.failedCheckRuns ?? 0);
+  const failedWorkflowRuns = Number(validationEvidence.failedWorkflowRuns ?? 0);
+  const cancelledWorkflowRuns = Number(validationEvidence.cancelledWorkflowRuns ?? 0);
+  const interruptionCount = failedCheckRuns + failedWorkflowRuns + cancelledWorkflowRuns;
+  const coverageLabel = statusLabel(coverageStatus, `workflow coverage: ${coverage}`);
+  let outcomeLabel;
+  if (interruptionCount > 0) {
+    outcomeLabel = statusLabel("warning", `${failedCheckRuns} failed checks, ${failedWorkflowRuns} failed workflows, ${cancelledWorkflowRuns} cancelled workflow runs`);
+  } else if (coverageStatus === "observed") {
+    outcomeLabel = statusLabel("healthy", "no failed or cancelled validation runs");
+  } else if (coverageStatus === "partial") {
+    outcomeLabel = statusLabel("partial", "no failed or cancelled validation runs in sampled workflow evidence");
+  } else {
+    outcomeLabel = statusLabel("unavailable", "validation outcome unavailable");
+  }
+  const conclusions = formatNamedValues(validationEvidence.workflowRunConclusions ?? []);
+
+  return `${coverageLabel}; ${outcomeLabel}; conclusions: ${conclusions}`;
+}
+
+function reviewThreadStatusLabel(reviewEvidence = {}) {
+  const source = reviewEvidence.reviewThreadSource ?? "unavailable";
+  if (source === "unavailable") return "unavailable";
+  if (source.startsWith("not_sampled")) return "partial";
+  return "observed";
+}
+
+function reviewStatusSummary(reviewEvidence = {}) {
+  const threadLabel = statusLabel(
+    reviewThreadStatusLabel(reviewEvidence),
+    `threads: ${reviewEvidence.reviewThreads ?? 0}, resolved: ${reviewEvidence.resolvedThreads ?? 0}, outdated: ${reviewEvidence.outdatedThreads ?? 0}`,
+  );
+
+  return threadLabel;
+}
+
+function reviewDecisionSummary(reviewEvidence = {}) {
+  const observedReviewDecision = hasObservedReviewDecision({
+    state: reviewEvidence.reviewDecision,
+    source: reviewEvidence.reviewDecisionSource,
+  });
+  const status = observedReviewDecision ? "observed" : "unavailable";
+  const humanApproved = formatObservedBoolean(reviewEvidence.humanApproved, observedReviewDecision);
+  const humanChangesRequested = formatObservedBoolean(reviewEvidence.humanChangesRequested, observedReviewDecision);
+  const humanReviewerCount = formatObservedCount(reviewEvidence.humanReviewerCount, observedReviewDecision);
+  const approvalStatus = observedReviewDecision && reviewEvidence.humanApproved
+    ? `; ${statusLabel("healthy", "human approval observed")}`
+    : "";
+
+  return `${statusLabel(status, `${reviewEvidence.reviewDecision ?? "unavailable"} from ${reviewEvidence.reviewDecisionSource ?? "unavailable"}`)}; human reviewers: ${humanReviewerCount}; approved: ${humanApproved}; changes requested: ${humanChangesRequested}${approvalStatus}`;
+}
+
+function commentSourceSummary(reviewEvidence = {}) {
+  const commentSources = reviewEvidence.commentSources ?? [];
+  if (commentSources.length) return statusLabel("observed", formatNamedValues(commentSources));
+  const reviewStatus = reviewThreadStatusLabel(reviewEvidence);
+  if (reviewStatus === "observed") return statusLabel("observed", "none");
+  if (reviewStatus === "partial") return statusLabel("partial", "none in sampled review-thread evidence");
+  return statusLabel("unavailable", "comment sources unavailable");
+}
+
+function prClassStatusSummary(prClass = {}) {
+  const source = prClass.classificationSource ?? "fallback_rule";
+  const status = source === "fallback_rule"
+    ? "observed"
+    : source === "unavailable" ? "unavailable" : "configured";
+  return statusLabel(status, formatPrClass(prClass));
+}
+
+function workflowSourceSummary(validationEvidence = {}) {
+  const source = validationEvidence.workflowRunSource ?? "unavailable";
+  const status = source === "unavailable" ? "unavailable" : "observed";
+  return statusLabel(status, source);
+}
+
+function reviewThreadSourceSummary(reviewEvidence = {}) {
+  const source = reviewEvidence.reviewThreadSource ?? "unavailable";
+  return statusLabel(reviewThreadStatusLabel(reviewEvidence), source);
+}
+
+function sourceLabelSummary(evidence = {}) {
+  return [
+    `PR class: ${prClassStatusSummary(evidence.prClass)}`,
+    `Review thread source: ${reviewThreadSourceSummary(evidence.reviewEvidence)}`,
+    `Workflow source: ${workflowSourceSummary(evidence.validationEvidence)}`,
+  ].join("; ");
+}
+
+function evidenceDetailRows(observedData) {
   return (observedData ?? []).map(evidence => {
     const validationEvidence = evidence.validationEvidence ?? {};
     const reviewEvidence = evidence.reviewEvidence ?? {};
-    const workflowRunConclusions = validationEvidence.workflowRunConclusions ?? [];
-    const reviewCommentSources = reviewEvidence.commentSources ?? [];
-    const observedReviewDecision = hasObservedReviewDecision({
-      state: reviewEvidence.reviewDecision,
-      source: reviewEvidence.reviewDecisionSource,
-    });
 
     return [
-      `Evidence details for PR #${evidence.number}:`,
-      "",
-      "Validation:",
-      "",
-      renderDetailList([
-        `Workflow coverage: ${validationEvidence.workflowRunCoverage ?? "unavailable"}`,
-        `Workflow conclusions: ${formatNamedValues(workflowRunConclusions)}`,
-        `Failed checks: ${validationEvidence.failedCheckRuns ?? 0}`,
-        `Failed workflows: ${validationEvidence.failedWorkflowRuns ?? 0}`,
-        `Cancelled workflows: ${validationEvidence.cancelledWorkflowRuns ?? 0}`,
-      ]),
-      "",
-      "Review:",
-      "",
-      renderDetailList([
-        `Review thread source: ${reviewEvidence.reviewThreadSource ?? "unavailable"}`,
-        `Threads: ${reviewEvidence.reviewThreads ?? 0}`,
-        `Resolved threads: ${reviewEvidence.resolvedThreads ?? 0}`,
-        `Outdated threads: ${reviewEvidence.outdatedThreads ?? 0}`,
-        `Review decision: ${reviewEvidence.reviewDecision ?? "unavailable"} (source: ${reviewEvidence.reviewDecisionSource ?? "unavailable"})`,
-        `Human reviewers: ${formatObservedCount(reviewEvidence.humanReviewerCount, observedReviewDecision)}`,
-        `Human approved: ${formatObservedBoolean(reviewEvidence.humanApproved, observedReviewDecision)}`,
-        `Human changes requested: ${formatObservedBoolean(reviewEvidence.humanChangesRequested, observedReviewDecision)}`,
-        `Comment sources: ${formatNamedValues(reviewCommentSources)}`,
-      ]),
-      "",
-      "Source labels:",
-      "",
-      renderDetailList([
-        `PR class: ${formatPrClass(evidence.prClass)}`,
-        `Workflow source: ${validationEvidence.workflowRunSource ?? "unavailable"}`,
-      ]),
-    ].join("\n");
-  }).join("\n\n");
+      prReference(evidence),
+      validationStatusSummary(validationEvidence),
+      `${reviewStatusSummary(reviewEvidence)}; ${reviewDecisionSummary(reviewEvidence)}; comments: ${commentSourceSummary(reviewEvidence)}`,
+      sourceLabelSummary(evidence),
+    ];
+  });
+}
+
+function renderEvidenceDetails(observedData) {
+  return renderMarkdownTable(
+    [
+      "PR",
+      "Validation",
+      "Review",
+      "Source labels",
+    ],
+    evidenceDetailRows(observedData),
+  );
 }
 
 function recommendationCategoryLabel(bottleneck) {
@@ -1213,6 +1355,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 "";
@@ -1397,6 +1560,7 @@ export function renderRepositoryFrictionMarkdown(report) {
     renderKeyFindings(report),
     "",
     renderPrClassContext(report.prClasses),
+    renderProfileSuggestions(report),
     renderSharedSignalInterpretation(sharedSignals),
     renderSensitivityAnalysis(report.sensitivity),
     "## How Bottlenecks Are Prioritized",
@@ -1451,6 +1615,9 @@ 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, or functional-surface 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.",