delivery-friction-analyzer 0.5.0 → 0.6.0

package/docs/contracts/friction-report.md

@@ -27,6 +27,7 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `metricVersion`: source metrics contract version.
 - `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.
+- `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.
 - `summary`: repository totals and top 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.
@@ -55,6 +56,7 @@ The Markdown renderer presents the same report data for human review:
 - a top-of-report focus snapshot that names focus areas, action categories, evidence reviewed, and confidence caveats before detailed bottlenecks;
 - 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;
 - 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;
@@ -104,6 +106,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;
 - requested and collected PR counts;
 - collection coverage status and API-family diagnostics;
 - scoring, ranking, dominance, sensitivity, and limitation explanations;

package/docs/reference/repository-profile.md

@@ -58,7 +58,7 @@ Interactive setup can add a release PR class rule from a confirmed title convent
 
 ## Workflow Context
 
-`workflow` is optional user-configured context. It records repository workflow assumptions that later setup and report milestones can rely on, but the analyzer does not infer these values from GitHub and does not change scoring, rankings, collection, PR class matching, or report wording.
+`workflow` is optional user-configured context. It records repository workflow assumptions that reports can surface as configured profile context, but the analyzer does not infer these values from GitHub and does not change scoring, rankings, collection, CSV exports, or PR class matching.
 
 When provided, `workflow` must include at least one supported field.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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-19 — Workflow Context Surfacing
+
+- What changed: Friction reports and methodology now show configured repository workflow context from the profile when it is present.
+- Why it matters: Maintainers can see merge, release, and branch assumptions beside report evidence without mistaking them for observed GitHub data or scoring inputs.
+- Who is affected: Maintainers and contributors reviewing generated reports or authoring repository profiles with `workflow` context.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/37
+
 ### 2026-06-18 — Workflow Profile Wizard
 
 - What changed: Interactive setup can now create repository profiles or generated profile copies with confirmed workflow context and release PR title rules.

package/src/cli/analyze-github.js

@@ -1123,7 +1123,10 @@ export async function runAnalyzeGithub(options, {
     options.excludedPrClasses ?? [],
   );
   const metrics = computeRepositoryMetrics(normalized);
-  const report = attachCollectionCoverage(generateRepositoryFrictionReport(metrics), sourceBundle);
+  const report = attachCollectionCoverage(
+    generateRepositoryFrictionReport(metrics, { workflowContext: repositoryProfile.workflow }),
+    sourceBundle,
+  );
   const markdown = `${renderRepositoryFrictionMarkdown(report)}${collectionCoverageMarkdown(sourceBundle)}`;
   const methodology = renderRepositoryFrictionMethodology({
     report,

package/src/report/evidence-artifacts.js

@@ -1,3 +1,9 @@
+import {
+  CONFIGURED_WORKFLOW_NOTE,
+  configuredWorkflowEntries,
+  hasConfiguredWorkflowContext,
+} from "./friction-report.js";
+
 const BOT_OR_SCANNER_SOURCES = new Set([
   "copilot",
   "github_actions_bot",
@@ -336,6 +342,21 @@ function formatSensitivitySummaries(report) {
   }).join("\n");
 }
 
+function formatConfiguredWorkflowContext(report) {
+  const configuredWorkflow = report.configuredWorkflow;
+  if (!hasConfiguredWorkflowContext(configuredWorkflow)) return [];
+
+  return [
+    "## Configured Workflow Context",
+    "",
+    configuredWorkflow.note ?? CONFIGURED_WORKFLOW_NOTE,
+    "",
+    ...configuredWorkflowEntries(configuredWorkflow)
+      .map(entry => `- ${entry.label}: ${entry.valueLabel}`),
+    "",
+  ];
+}
+
 export function renderRepositoryFrictionMethodology({
   report,
   sourceBundle,
@@ -373,6 +394,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.",
     "",
+    ...formatConfiguredWorkflowContext(report),
     "## Scores And Rankings",
     "",
     "The report ranks bottlenecks by transparent component metrics from `friction-metrics.v1`: review churn, change scope (the internal changed-file-spread signal: core files touched plus directories touched plus functional surfaces touched), validation gap, planning gap, review surprise, and fix amplification. These are not an opaque composite score, and they are not individual contributor or reviewer rankings.",

package/src/report/friction-report.js

@@ -61,6 +61,28 @@ const RANKING_SIGNAL_LABELS = new Map([
   ["fixAmplification", "fix amplification"],
 ]);
 
+const WORKFLOW_CONTEXT_FIELDS = [
+  ["primaryMergeMethod", "Primary merge method"],
+  ["releaseStrategy", "Release strategy"],
+  ["branchStrategy", "Branch strategy"],
+];
+
+const WORKFLOW_CONTEXT_VALUE_LABELS = new Map([
+  ["merge_commit", "Merge commit"],
+  ["squash_merge", "Squash merge"],
+  ["rebase_merge", "Rebase merge"],
+  ["release_prs", "Release PRs"],
+  ["direct_tags", "Direct tags"],
+  ["release_branches", "Release branches"],
+  ["trunk_based", "Trunk-based"],
+  ["main_plus_release_branches", "Main plus release branches"],
+  ["long_lived_development_branches", "Long-lived development branches"],
+  ["mixed", "Mixed"],
+  ["unknown", "Unknown"],
+]);
+
+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 BOTTLENECK_DEFINITIONS = [
   {
     id: "review-churn",
@@ -563,6 +585,42 @@ function summarizeRecommendationCategories(bottlenecks) {
   }));
 }
 
+export function normalizeConfiguredWorkflowContext(workflowContext) {
+  if (!workflowContext || typeof workflowContext !== "object" || Array.isArray(workflowContext)) {
+    return null;
+  }
+
+  const configuredWorkflow = {
+    source: "repository_profile",
+    note: CONFIGURED_WORKFLOW_NOTE,
+  };
+  for (const [field] of WORKFLOW_CONTEXT_FIELDS) {
+    if (workflowContext[field] !== undefined) {
+      configuredWorkflow[field] = workflowContext[field];
+    }
+  }
+
+  return WORKFLOW_CONTEXT_FIELDS.some(([field]) => configuredWorkflow[field] !== undefined)
+    ? configuredWorkflow
+    : null;
+}
+
+export function configuredWorkflowEntries(configuredWorkflow) {
+  if (!configuredWorkflow || typeof configuredWorkflow !== "object") return [];
+  return WORKFLOW_CONTEXT_FIELDS
+    .filter(([field]) => configuredWorkflow[field] !== undefined)
+    .map(([field, label]) => ({
+      field,
+      label,
+      value: configuredWorkflow[field],
+      valueLabel: WORKFLOW_CONTEXT_VALUE_LABELS.get(configuredWorkflow[field]) ?? configuredWorkflow[field],
+    }));
+}
+
+export function hasConfiguredWorkflowContext(configuredWorkflow) {
+  return configuredWorkflowEntries(configuredWorkflow).length > 0;
+}
+
 function evidenceSignature(bottleneck) {
   return (bottleneck.observedData ?? [])
     .map(evidence => evidence.number)
@@ -712,16 +770,19 @@ function summarizeSensitivity(metricsSummary, baselineBottlenecks) {
   };
 }
 
-export function generateRepositoryFrictionReport(metricsSummary) {
+export function generateRepositoryFrictionReport(metricsSummary, options = {}) {
+  const { workflowContext } = options ?? {};
   const prClasses = summarizePrClasses(metricsSummary);
   const bottlenecksWithSharedSignalKeys = summarizeBottlenecks(metricsSummary, prClasses);
   const sharedSignals = summarizeSharedSignals(bottlenecksWithSharedSignalKeys);
   const bottlenecks = bottlenecksWithSharedSignalKeys.map(({ rankingKey, ...bottleneck }) => bottleneck);
+  const configuredWorkflow = normalizeConfiguredWorkflowContext(workflowContext);
   return {
     reportVersion: FRICTION_REPORT_VERSION,
     metricVersion: metricsSummary.metricVersion,
     targetRepository: metricsSummary.targetRepository,
     ...(metricsSummary.analysisFilter ? { analysisFilter: metricsSummary.analysisFilter } : {}),
+    ...(configuredWorkflow ? { configuredWorkflow } : {}),
     summary: {
       pullRequests: metricsSummary.totals?.pullRequests ?? 0,
       changedLines: metricsSummary.totals?.changedLines ?? 0,
@@ -1152,6 +1213,23 @@ function renderPrClassContext(prClasses) {
   ].join("\n");
 }
 
+function renderConfiguredWorkflowContext(configuredWorkflow) {
+  const entries = configuredWorkflowEntries(configuredWorkflow);
+  if (!entries.length) return "";
+
+  return [
+    "## Configured Workflow Context",
+    "",
+    configuredWorkflow.note ?? CONFIGURED_WORKFLOW_NOTE,
+    "",
+    renderMarkdownTable(
+      ["Field", "Configured value"],
+      entries.map(entry => [entry.label, entry.valueLabel]),
+    ),
+    "",
+  ].join("\n");
+}
+
 function classDominanceCaveat(bottleneck) {
   return bottleneck.classDominance?.status === "single_class_dominates"
     ? bottleneck.classDominance.note
@@ -1299,7 +1377,13 @@ export function renderRepositoryFrictionMarkdown(report) {
     "- Interpretation is the analyzer's explanation of what the observed evidence suggests.",
     "- Recommendation is a workflow intervention to consider; the report does not modify repositories.",
     "- Confidence and caveats call out outliers, missing coverage, and evidence-quality limits before you act.",
+    ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
+      ? ["- Configured workflow context, when shown, comes from the repository profile and is not observed GitHub evidence."]
+      : []),
     "",
+    ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
+      ? [renderConfiguredWorkflowContext(report.configuredWorkflow)]
+      : []),
     "## Evidence Quality And Coverage",
     "",
     renderCoverageSummary(report.coverage),
@@ -1370,6 +1454,9 @@ export function renderRepositoryFrictionMarkdown(report) {
     "- 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."]
+      : []),
     "- 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."