delivery-friction-analyzer 0.9.0 → 0.11.0

package/docs/contracts/friction-report.md

@@ -1,6 +1,6 @@
 # Friction Report Contract
 
-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.
+Milestone 3 introduced `friction-report.v1`, a deterministic report generated from a `friction-metrics.v1` repository metrics summary. Milestone 4 added configured workflow context. Milestone 5 adds sanitized contributor-source metadata for configured `.all-contributorsrc` coverage without raw contributor file contents or individual rankings. 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
 
@@ -28,6 +28,7 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `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.
+- `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.
 - `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.
@@ -57,10 +58,12 @@ 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;
+- a contributor source context section only when a contributor source is configured, labeled as metadata that may improve comment-source classification coverage without changing scores, authorship conclusions, reviewer attribution, CSV export shape, person-level CSV output, or individual ranking guardrails;
+- 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 or unknown file role/surface evidence cross deterministic thresholds;
+- 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;
@@ -74,10 +77,12 @@ The Markdown renderer presents the same report data for human review:
 - a reference to the detailed `methodology.md` artifact generated by full live analysis;
 - guardrails, follow-up, and artifact-sensitivity guidance.
 
-Markdown output should not include individual contributor or reviewer rankings.
+Markdown output should not include raw contributor file contents or individual contributor/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
 
 Recommendations are inferred from transparent component metrics and representative PR examples. They suggest workflow interventions such as readiness gates, preflight scripts, smaller milestones, planning artifacts, or scope control. They do not automate repository changes.
@@ -94,7 +99,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.
 
@@ -111,7 +116,8 @@ 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;
+- contributor-source context when configured, including source type, path, coverage status, and parsed hint count, without raw contributor contents or rankings;
+- 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;
@@ -136,6 +142,8 @@ Minimum CSV column groups:
 
 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.
 
+Contributor-source coverage appears in `collection-coverage.csv` as the `contributor_source` API 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.
+
 ## Optional Downstream Narrative Drafting
 
 The existing `friction-report.json` artifact plus the curated CSV exports are sufficient context for an optional local workflow where a separate model drafts a narrative summary. M2 does not justify a new `report-context.json`, CLI flag, fixture output, or artifact write path.

package/docs/contracts/normalized-entities.md

@@ -9,6 +9,7 @@ Milestone 1 defines the first normalized fixture shape. It is intentionally limi
 - `TargetRepository`: owner/name/default branch/visibility/window for the repository being analyzed.
 - `AnalysisFilter`: optional metadata for downstream analysis filters applied after collection and normalization. When present, it records excluded PR classes, the original collected PR count, and the filtered PR count.
 - `RepositoryLanguageDistribution`: byte counts from `GET /repos/{owner}/{repo}/languages`, stored as context only.
+- `ContributorSource`: optional sanitized metadata from a configured structured contributor source. It records source type, path, coverage status, diagnostics, and parsed hint count. It must not preserve raw contributor file contents or contributor login lists.
 - `PullRequest`: source IDs, author login when known, URL, state, PR class evidence, lifecycle timestamps, final diff shape, PR-open diff source confidence, optional PR-open additions/deletions/changed-file counts when direct or reconstructed data is available, files, reviews, review decision summary, review threads, comments, checks, and workflow-run coverage.
 - `PrClassSummary`: profile-driven PR class, classification source, and winning rule ID. Unmatched PRs use `class: "unknown"`, `classificationSource: "fallback_rule"`, and `ruleId: null`.
 - `Commit`: commit OID, authored timestamp, committed timestamp when present, and message headline.
@@ -24,6 +25,8 @@ Milestone 1 defines the first normalized fixture shape. It is intentionally limi
 
 Normalized data must preserve whether a value came from a public API, GraphQL thread query, repository profile rule, fallback rule, internal UI partial, or unavailable coverage. Later metric and report stages should use those source labels before making confidence claims.
 
+Configured contributor hints may classify otherwise-unknown comment authors into existing comment-source groups during the analysis run, but parsed login lists are transient and must not be persisted in generated artifacts. Hints must not change PR authorship, reviewer attribution, scoring formulas, or person-level report/CSV rows.
+
 ## Analysis Filters
 
 `source-bundle.json` remains the full collected sample. When a local analysis excludes one or more PR classes, `normalized.json` contains the filtered PR set and an `analysisFilter` object:

package/docs/reference/github-access-coverage.md

@@ -6,6 +6,7 @@ The MVP runs locally with the user's GitHub credentials. Reports must expose una
 | --- | --- | --- | --- | --- | --- |
 | REST repository metadata | unauthenticated or token | public read | `repo` or fine-grained metadata read | repository visibility, default branch confirmation | mark repository metadata partial |
 | REST languages | unauthenticated or token | public read | `repo` or fine-grained contents/metadata read | language byte distribution context | omit language context; do not infer file role from language |
+| REST repository contents for configured contributor source | token recommended | public contents read | `repo` or fine-grained contents read | optional `.all-contributorsrc` contributor hints for comment-source classification metadata | mark contributor-source coverage unavailable, malformed, partial, or unsupported; do not infer identities from other sources |
 | Pull request metadata | `gh` token / GraphQL-backed PR fields | public read | `repo` or pull request read | lifecycle, final diff shape, files, commits, reviews | mark PR inventory partial |
 | REST review comments | token recommended | public read | `repo` or pull request read | individual review comments and comment paths | source breakdown based only on reviews if unavailable |
 | GraphQL review threads | token | public read | `repo` or pull request read | thread count, resolved state, outdated state | thread metrics unavailable; comment count can remain REST-only |
@@ -18,8 +19,10 @@ The MVP runs locally with the user's GitHub credentials. Reports must expose una
 The analyzer should record:
 
 - API family attempted.
-- Coverage status: `available`, `partial`, `unavailable`, or `rate_limited`.
+- Coverage status: `available`, `partial`, `unavailable`, `malformed`, `unsupported`, or `rate_limited`.
 - Required scope or permission when known.
 - Impact on downstream metrics.
 
 Missing coverage must flow into report metadata. For example, unavailable GraphQL review threads should disable thread-resolution metrics while preserving REST review-comment counts.
+
+Contributor-source coverage is optional. Missing, inaccessible, malformed, or unsupported contributor files should not fail analysis and should not cause the analyzer to infer private identity data from names, emails, commits, or external services.

package/docs/reference/repository-profile.md

@@ -160,3 +160,27 @@ Example:
 Use stable identifiers exactly as shown above. Display labels such as "squash merges" or "release PRs" belong in CLI prompts or documentation, not in profile data.
 
 When interactive setup writes profile changes, it preserves deterministic two-space JSON formatting in place. If an existing profile uses other formatting, setup writes a generated profile copy and prints that generated path in completion output instead of rewriting the original file.
+
+## Contributor Source
+
+`contributors` is optional user-configured context for structured contributor hints. The first supported source is `.all-contributorsrc` as `all_contributors` JSON. When omitted, analysis runs normally without contributor hints.
+
+Supported fields:
+
+- `sourceType`: optional, defaults to `all_contributors` when `contributors` is present.
+- `path`: optional trimmed, slash-delimited repository-relative path, defaults to `.all-contributorsrc`.
+
+Example:
+
+```json
+{
+  "contributors": {
+    "sourceType": "all_contributors",
+    "path": ".all-contributorsrc"
+  }
+}
+```
+
+Markdown contributor files such as `CONTRIBUTORS.md` are not supported contributor sources in this milestone. The analyzer records them as unsupported/unparsed coverage when encountered and does not parse Markdown into identities.
+
+Contributor hints may improve repository-level comment-source classification coverage, such as classifying a configured contributor login as an existing human-reviewer source. They do not change scoring formulas, PR authorship conclusions, reviewer attribution, PR class matching, CSV export shape, or individual rankings. Generated artifacts expose only contributor-source metadata such as type, path, status, diagnostics, and parsed hint count; they do not include raw contributor file contents, contributor login lists, or contributor rankings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.9.0",
+  "version": "0.11.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 — Contributor Source Configuration
+
+- What changed: Repository profiles can now configure `.all-contributorsrc` as a structured contributor source, and analysis records contributor-source coverage while using sanitized hints only for aggregate comment-source classification.
+- Why it matters: Maintainers can improve comment-source coverage without parsing Markdown contributor files, changing scores, or emitting raw contributor contents or person rankings in reports or CSVs.
+- Who is affected: Maintainers authoring repository profiles or reviewing generated reports, methodology, and coverage artifacts.
+- Action needed: Optional; add `contributors.sourceType: "all_contributors"` and a repository-relative `contributors.path` when a target repository has a trusted `.all-contributorsrc`.
+- PR: #47
+
+### 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.

package/schemas/normalized-entities.schema.json

@@ -36,6 +36,32 @@
         }
       }
     },
+    "contributorSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceType", "path", "coverage", "hintCount"],
+      "properties": {
+        "sourceType": { "enum": ["all_contributors"] },
+        "path": { "type": "string" },
+        "coverage": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["family", "source", "status", "attempts", "diagnostics", "downstreamImpact"],
+          "properties": {
+            "family": { "const": "contributor_source" },
+            "source": { "type": "string" },
+            "status": { "enum": ["available", "partial", "unavailable", "malformed", "unsupported", "rate_limited"] },
+            "attempts": { "type": "integer", "minimum": 1 },
+            "diagnostics": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "downstreamImpact": { "type": ["string", "null"] }
+          }
+        },
+        "hintCount": { "type": "integer", "minimum": 0 }
+      }
+    },
     "pullRequests": {
       "type": "array",
       "items": {

package/schemas/repository-profile.schema.json

@@ -103,6 +103,29 @@
         }
       },
       "minProperties": 1
+    },
+    "contributors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sourceType": {
+          "enum": ["all_contributors"]
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S",
+          "not": {
+            "anyOf": [
+              { "pattern": "^/" },
+              { "pattern": "^\\s|\\s$" },
+              { "pattern": "\\\\" },
+              { "pattern": "(^|/)\\.\\.(/|$)" }
+            ]
+          }
+        }
+      },
+      "minProperties": 1
     }
   }
 }

package/src/cli/analyze-github.js

@@ -24,6 +24,7 @@ import {
   WORKFLOW_RELEASE_STRATEGIES,
   assertValidWorkflowContext,
 } from "../profile/workflow.js";
+import { assertValidContributorSource } from "../profile/contributor-source.js";
 
 const ALLOWED_OPTIONS = new Set([
   "repo",
@@ -311,6 +312,7 @@ function normalizeMultiSelectAnswer(raw, prompt) {
 function validateProfile(profile) {
   assertValidPrClassRules(profile);
   assertValidWorkflowContext(profile);
+  assertValidContributorSource(profile);
 }
 
 function parseProfileJson(text) {
@@ -1128,7 +1130,7 @@ function attachCollectionCoverage(report, sourceBundle) {
   return {
     ...report,
     collectionCoverage: sourceBundle.coverage,
-    artifactSensitivity: "Generated artifacts may include repository names, PR URLs, titles, file paths, comment metadata, curated CSV evidence, and coverage diagnostics. Treat them as local/private unless intentionally shared.",
+    artifactSensitivity: "Generated artifacts may include repository names, PR URLs, titles, file paths, comment metadata, contributor-source metadata, curated CSV evidence, and coverage diagnostics. Raw contributor file contents and individual contributor rankings are not emitted. Treat artifacts as local/private unless intentionally shared.",
   };
 }
 
@@ -1214,6 +1216,7 @@ export async function runAnalyzeGithub(options, {
     provider,
     collectedAt: now(),
     isValidationTarget: options.isValidationTarget,
+    contributors: repositoryProfile.contributors,
   });
 
   if (options.dryRun) {
@@ -1238,7 +1241,10 @@ export async function runAnalyzeGithub(options, {
   );
   const metrics = computeRepositoryMetrics(normalized);
   const report = attachCollectionCoverage(
-    generateRepositoryFrictionReport(metrics, { workflowContext: repositoryProfile.workflow }),
+    generateRepositoryFrictionReport(metrics, {
+      workflowContext: repositoryProfile.workflow,
+      contributorSource: normalized.contributorSource,
+    }),
     sourceBundle,
   );
   const markdown = `${renderRepositoryFrictionMarkdown(report)}${collectionCoverageMarkdown(sourceBundle)}`;

package/src/collect/coverage.js

@@ -2,6 +2,8 @@ export const COVERAGE_STATUS = Object.freeze({
   available: "available",
   partial: "partial",
   unavailable: "unavailable",
+  malformed: "malformed",
+  unsupported: "unsupported",
   rateLimited: "rate_limited",
 });
 
@@ -65,8 +67,14 @@ export function mergeCoverageEntries({ family, source, entries, downstreamImpact
   let status = COVERAGE_STATUS.available;
   if (statuses.has(COVERAGE_STATUS.rateLimited)) {
     status = COVERAGE_STATUS.rateLimited;
+  } else if (statuses.size === 1 && statuses.has(COVERAGE_STATUS.unsupported)) {
+    status = COVERAGE_STATUS.unsupported;
+  } else if (statuses.size === 1 && statuses.has(COVERAGE_STATUS.malformed)) {
+    status = COVERAGE_STATUS.malformed;
   } else if (statuses.has(COVERAGE_STATUS.unavailable)) {
     status = statuses.size > 1 ? COVERAGE_STATUS.partial : COVERAGE_STATUS.unavailable;
+  } else if (statuses.has(COVERAGE_STATUS.unsupported) || statuses.has(COVERAGE_STATUS.malformed)) {
+    status = COVERAGE_STATUS.partial;
   } else if (statuses.has(COVERAGE_STATUS.partial)) {
     status = COVERAGE_STATUS.partial;
   }

package/src/collect/gh-provider.js

@@ -105,6 +105,13 @@ function requireGraphqlPage(page, label) {
   return page;
 }
 
+function encodeContentPath(path) {
+  return String(path)
+    .split("/")
+    .map(segment => encodeURIComponent(segment))
+    .join("/");
+}
+
 function wait(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -153,6 +160,10 @@ export function createGhCliProvider({
       return runGhJson(["api", `repos/${owner}/${name}/languages`]);
     },
 
+    async getRepositoryContent({ owner, name, path }) {
+      return runGhJson(["api", `repos/${owner}/${name}/contents/${encodeContentPath(path)}`]);
+    },
+
     async listMergedPullRequests({ owner, name, limit }) {
       const prs = await runGhJson([
         "pr",

package/src/collect/github-source-bundle.js

@@ -1,4 +1,10 @@
 import { validateTargetRepository } from "../contracts/target-repository.js";
+import {
+  assertValidContributorSource,
+  normalizeContributorSourceConfig,
+  parseAllContributorsHints,
+  withTransientContributorHints,
+} from "../profile/contributor-source.js";
 import {
   COVERAGE_STATUS,
   classifyCoverageStatus,
@@ -187,6 +193,90 @@ function unavailableWorkflowRuns() {
   };
 }
 
+function isMarkdownContributorPath(path = "") {
+  return /\.(md|mdx|markdown)$/i.test(String(path));
+}
+
+function unsupportedContributorSource(config = {}) {
+  const sourceType = config.sourceType ?? "unknown";
+  const path = config.path ?? null;
+  const diagnostic = path && isMarkdownContributorPath(path)
+    ? `Contributor source path '${path}' is a Markdown file; Markdown contributor files are intentionally not parsed in this milestone.`
+    : `Contributor source type '${sourceType}' is unsupported.`;
+  const coverage = coverageEntry({
+    family: "contributor_source",
+    source: "rest:/repos/{owner}/{repo}/contents/{path}",
+    status: COVERAGE_STATUS.unsupported,
+    diagnostics: [diagnostic],
+    downstreamImpact: "Contributor-aware comment-source hints are unavailable; scoring and person-level outputs are unchanged.",
+  });
+  return withTransientContributorHints({
+    sourceType,
+    path,
+    coverage,
+  });
+}
+
+function unavailableContributorSource(config = {}, error) {
+  const coverage = coverageEntry({
+    family: "contributor_source",
+    source: "rest:/repos/{owner}/{repo}/contents/{path}",
+    status: classifyCoverageStatus(error),
+    diagnostics: [redactDiagnostic(error?.message ?? error)],
+    downstreamImpact: "Contributor-aware comment-source hints are unavailable; scoring and person-level outputs are unchanged.",
+  });
+  return withTransientContributorHints({
+    sourceType: config.sourceType,
+    path: config.path,
+    coverage,
+  });
+}
+
+function contentTextFromResponse(response) {
+  if (typeof response === "string") return response;
+  if (response && typeof response.content === "string" && response.encoding === "base64") {
+    return Buffer.from(response.content.replace(/\s+/g, ""), "base64").toString("utf8");
+  }
+  if (response && typeof response.content === "string") {
+    return response.content;
+  }
+  throw new Error("GitHub content response did not include readable file content.");
+}
+
+async function collectContributorSource({ targetInput, provider, contributors }) {
+  if (contributors == null) return null;
+  assertValidContributorSource({ contributors });
+  const config = normalizeContributorSourceConfig(contributors);
+  if (!config) return null;
+  if (config.sourceType !== "all_contributors" || isMarkdownContributorPath(config.path)) {
+    return unsupportedContributorSource(config);
+  }
+  if (typeof provider.getRepositoryContent !== "function") {
+    return unavailableContributorSource(config, new Error("provider does not support repository content collection."));
+  }
+
+  try {
+    const response = await provider.getRepositoryContent({ ...targetInput, path: config.path });
+    const parsed = parseAllContributorsHints(contentTextFromResponse(response));
+    const coverage = coverageEntry({
+      family: "contributor_source",
+      source: "rest:/repos/{owner}/{repo}/contents/{path}",
+      status: parsed.status,
+      diagnostics: parsed.diagnostics,
+      downstreamImpact: parsed.status === COVERAGE_STATUS.available || parsed.status === COVERAGE_STATUS.partial
+        ? "Contributor-aware comment-source hints are available; scoring and person-level outputs are unchanged."
+        : "Contributor-aware comment-source hints are unavailable; scoring and person-level outputs are unchanged.",
+    });
+    return withTransientContributorHints({
+      sourceType: config.sourceType,
+      path: config.path,
+      coverage,
+    }, parsed.hints);
+  } catch (error) {
+    return unavailableContributorSource(config, error);
+  }
+}
+
 function mapPullRequestDetails(details) {
   return {
     number: details.number,
@@ -261,7 +351,14 @@ export function buildCoverageSummary(entries) {
   const statuses = new Set(entries.map(entry => entry.status));
   if (statuses.has(COVERAGE_STATUS.rateLimited)) return COVERAGE_STATUS.rateLimited;
   if (statuses.size === 1 && statuses.has(COVERAGE_STATUS.unavailable)) return COVERAGE_STATUS.unavailable;
-  if (statuses.has(COVERAGE_STATUS.unavailable) || statuses.has(COVERAGE_STATUS.partial)) return COVERAGE_STATUS.partial;
+  if (statuses.size === 1 && statuses.has(COVERAGE_STATUS.unsupported)) return COVERAGE_STATUS.unsupported;
+  if (statuses.size === 1 && statuses.has(COVERAGE_STATUS.malformed)) return COVERAGE_STATUS.malformed;
+  if (
+    statuses.has(COVERAGE_STATUS.unavailable)
+    || statuses.has(COVERAGE_STATUS.partial)
+    || statuses.has(COVERAGE_STATUS.unsupported)
+    || statuses.has(COVERAGE_STATUS.malformed)
+  ) return COVERAGE_STATUS.partial;
   return COVERAGE_STATUS.available;
 }
 
@@ -274,6 +371,7 @@ export async function collectGitHubSourceBundle({
   collectedAt = new Date().toISOString(),
   analysisPullRequestLimit,
   isValidationTarget = false,
+  contributors = null,
 } = {}) {
   if (!provider) {
     throw new Error("provider is required.");
@@ -313,6 +411,12 @@ export async function collectGitHubSourceBundle({
     run: () => provider.getLanguages(targetInput),
   });
 
+  const contributorSource = await collectContributorSource({
+    targetInput,
+    provider,
+    contributors,
+  });
+
   const inventory = (await provider.listMergedPullRequests({ ...targetInput, limit: targetPullRequestLimit }))
     .sort((left, right) => String(right.mergedAt ?? "").localeCompare(String(left.mergedAt ?? "")))
     .slice(0, targetPullRequestLimit);
@@ -424,6 +528,7 @@ export async function collectGitHubSourceBundle({
       diagnostics: ["PR-open diff reconstruction and snapshot capture are intentionally not implemented in M1."],
       downstreamImpact: "Diff growth metrics must remain unavailable.",
     }),
+    ...(contributorSource ? [contributorSource.coverage] : []),
   ];
 
   return {
@@ -450,6 +555,7 @@ export async function collectGitHubSourceBundle({
       bytesByLanguage: languagesAttempt.value ?? {},
       coverage: languagesAttempt.coverage,
     },
+    ...(contributorSource ? { contributorSource } : {}),
     pullRequests,
   };
 }

package/src/github/comment-source.js

@@ -11,11 +11,12 @@ const SOURCE = {
 
 export const COMMENT_SOURCES = Object.freeze(Object.values(SOURCE));
 
-export function classifyCommentSource(author = {}, { pullRequestAuthorLogin } = {}) {
+export function classifyCommentSource(author = {}, { pullRequestAuthorLogin, contributorHints } = {}) {
   const login = String(author.login ?? "").toLowerCase();
   const type = String(author.type ?? author.__typename ?? "").toLowerCase();
   const url = String(author.htmlUrl ?? author.html_url ?? "").toLowerCase();
   const prAuthorLogin = String(pullRequestAuthorLogin ?? "").toLowerCase();
+  const contributorLogins = contributorHints?.logins;
 
   if (login === "copilot" || login === "copilot-pull-request-reviewer" || url.includes("/apps/copilot-pull-request-reviewer")) {
     return SOURCE.copilot;
@@ -41,6 +42,10 @@ export function classifyCommentSource(author = {}, { pullRequestAuthorLogin } =
     return SOURCE.unknownBot;
   }
 
+  if (login && contributorLogins?.has?.(login)) {
+    return SOURCE.human;
+  }
+
   if (type === "user" || author.authorAssociation) {
     return SOURCE.human;
   }

package/src/normalize/github-fixture.js

@@ -1,5 +1,10 @@
 import { classifyCommentSource, groupByCommentSource } from "../github/comment-source.js";
 import { classifyFilePath } from "../profile/file-role.js";
+import {
+  assertValidContributorSource,
+  contributorHintsFromSource,
+  contributorSourceArtifactMetadata,
+} from "../profile/contributor-source.js";
 import { assertValidPrClassRules, classifyPullRequest } from "../profile/pr-class.js";
 import { assertValidWorkflowContext } from "../profile/workflow.js";
 
@@ -114,6 +119,8 @@ export function normalizeFixtureBundle(bundle, { repositoryProfile } = {}) {
   const profile = repositoryProfile ?? {};
   assertValidPrClassRules(profile);
   assertValidWorkflowContext(profile);
+  assertValidContributorSource(profile);
+  const contributorHints = contributorHintsFromSource(bundle.contributorSource);
 
   const pullRequests = (bundle.pullRequests ?? []).map(pr => {
     const reviewDates = (pr.reviews ?? []).map(review => review.submittedAt);
@@ -155,7 +162,7 @@ export function normalizeFixtureBundle(bundle, { repositoryProfile } = {}) {
       },
       reviewComments: {
         totalCount: threadComments.length,
-        bySource: groupByCommentSource(threadComments, { pullRequestAuthorLogin: pr.author?.login }),
+        bySource: groupByCommentSource(threadComments, { pullRequestAuthorLogin: pr.author?.login, contributorHints }),
       },
       checkRuns: (pr.statusCheckRollup ?? []).map(check => ({
         source: check.__typename === "StatusContext" ? "status_context" : "check_run",
@@ -174,6 +181,7 @@ export function normalizeFixtureBundle(bundle, { repositoryProfile } = {}) {
     schemaVersion: "normalized-fixture.v1",
     targetRepository: bundle.targetRepository,
     languageDistribution: bundle.languageDistribution,
+    ...(bundle.contributorSource ? { contributorSource: contributorSourceArtifactMetadata(bundle.contributorSource) } : {}),
     pullRequests,
   };
 }

package/src/profile/contributor-source.js

@@ -0,0 +1,165 @@
+export const CONTRIBUTOR_SOURCE_TYPES = Object.freeze([
+  "all_contributors",
+]);
+
+export const DEFAULT_ALL_CONTRIBUTORS_PATH = ".all-contributorsrc";
+
+const transientContributorHints = new WeakMap();
+
+function isObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasParentDirectorySegment(path) {
+  return String(path).split(/[\\/]+/).includes("..");
+}
+
+export function normalizeContributorSourceConfig(contributors = null) {
+  if (!contributors || typeof contributors !== "object" || Array.isArray(contributors)) {
+    return null;
+  }
+  if (contributors.sourceType === undefined && contributors.path === undefined) {
+    return null;
+  }
+  return {
+    sourceType: contributors.sourceType ?? "all_contributors",
+    path: contributors.path ?? DEFAULT_ALL_CONTRIBUTORS_PATH,
+  };
+}
+
+export function validateContributorSource(profile = {}) {
+  const errors = [];
+  if (!isObject(profile) || !Object.prototype.hasOwnProperty.call(profile, "contributors")) {
+    return errors;
+  }
+
+  const contributors = profile.contributors;
+  if (!isObject(contributors)) {
+    return ["contributors must be an object when provided"];
+  }
+  if (Object.keys(contributors).length === 0) {
+    return ["contributors must include at least one field when provided"];
+  }
+
+  for (const key of Object.keys(contributors)) {
+    if (!["sourceType", "path"].includes(key)) {
+      errors.push(`contributors.${key} is not supported`);
+    }
+  }
+
+  const sourceType = contributors.sourceType ?? "all_contributors";
+  if (!CONTRIBUTOR_SOURCE_TYPES.includes(sourceType)) {
+    errors.push(`contributors.sourceType must be one of: ${CONTRIBUTOR_SOURCE_TYPES.join(", ")}`);
+  }
+
+  if (contributors.path !== undefined) {
+    if (typeof contributors.path !== "string" || contributors.path.trim() === "") {
+      errors.push("contributors.path must be a non-empty string when provided");
+    } else if (
+      contributors.path.trim() !== contributors.path
+      || contributors.path.startsWith("/")
+      || contributors.path.includes("\\")
+      || hasParentDirectorySegment(contributors.path)
+    ) {
+      errors.push("contributors.path must be a trimmed slash-delimited repository-relative path without parent-directory segments");
+    }
+  }
+
+  return errors;
+}
+
+export function assertValidContributorSource(profile = {}) {
+  const errors = validateContributorSource(profile);
+  if (errors.length > 0) {
+    throw new Error(`invalid contributor source profile context: ${errors.join("; ")}`);
+  }
+}
+
+function loginFromContributor(contributor) {
+  if (!isObject(contributor)) return null;
+  const candidate = contributor.login ?? contributor.github ?? contributor.username;
+  if (typeof candidate !== "string") return null;
+  const login = candidate.trim().replace(/^@/, "");
+  return login ? login.toLowerCase() : null;
+}
+
+export function parseAllContributorsHints(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return {
+      status: "malformed",
+      hints: { logins: [] },
+      diagnostics: [`Could not parse .all-contributorsrc JSON: ${error.message}`],
+    };
+  }
+
+  if (!isObject(parsed) || !Array.isArray(parsed.contributors)) {
+    return {
+      status: "malformed",
+      hints: { logins: [] },
+      diagnostics: [".all-contributorsrc must contain a contributors array."],
+    };
+  }
+
+  const logins = new Set();
+  let malformedEntries = 0;
+  for (const contributor of parsed.contributors) {
+    const login = loginFromContributor(contributor);
+    if (login) {
+      logins.add(login);
+    } else {
+      malformedEntries += 1;
+    }
+  }
+
+  return {
+    status: malformedEntries > 0 ? "partial" : "available",
+    hints: { logins: [...logins].sort() },
+    diagnostics: malformedEntries > 0
+      ? [`Skipped ${malformedEntries} contributor entr${malformedEntries === 1 ? "y" : "ies"} without a supported login hint.`]
+      : [],
+  };
+}
+
+function normalizeLoginSet(logins = []) {
+  if (!Array.isArray(logins)) return new Set();
+  return new Set(logins.map(login => String(login).toLowerCase()).filter(Boolean));
+}
+
+function hintLoginsFromSource(contributorSource = null) {
+  return transientContributorHints.get(contributorSource)?.logins ?? contributorSource?.hints?.logins ?? [];
+}
+
+export function contributorSourceArtifactMetadata(contributorSource = null, hints = null) {
+  if (!isObject(contributorSource)) return null;
+  const logins = Array.isArray(hints?.logins) ? hints.logins : hintLoginsFromSource(contributorSource);
+  return {
+    sourceType: contributorSource.sourceType,
+    path: contributorSource.path,
+    coverage: contributorSource.coverage,
+    hintCount: Number.isInteger(contributorSource.hintCount)
+      ? contributorSource.hintCount
+      : normalizeLoginSet(logins).size,
+  };
+}
+
+export function withTransientContributorHints(contributorSource = null, hints = { logins: [] }) {
+  const metadata = contributorSourceArtifactMetadata(contributorSource, hints);
+  if (!metadata) return null;
+  transientContributorHints.set(metadata, {
+    logins: Array.isArray(hints?.logins) ? [...hints.logins] : [],
+  });
+  return metadata;
+}
+
+export function contributorHintsFromSource(contributorSource = null) {
+  const usableStatuses = new Set(["available", "partial"]);
+  if (!usableStatuses.has(contributorSource?.coverage?.status)) {
+    return { logins: new Set() };
+  }
+  return {
+    logins: normalizeLoginSet(hintLoginsFromSource(contributorSource)),
+  };
+}

package/src/report/evidence-artifacts.js

@@ -1,8 +1,10 @@
 import {
   CONFIGURED_WORKFLOW_NOTE,
+  CONTRIBUTOR_SOURCE_NOTE,
   configuredWorkflowEntries,
   hasConfiguredWorkflowContext,
   profileSuggestions,
+  workflowDataCaveats,
 } from "./friction-report.js";
 
 const BOT_OR_SCANNER_SOURCES = new Set([
@@ -346,6 +348,7 @@ function formatSensitivitySummaries(report) {
 function formatConfiguredWorkflowContext(report) {
   const configuredWorkflow = report.configuredWorkflow;
   if (!hasConfiguredWorkflowContext(configuredWorkflow)) return [];
+  const caveats = workflowDataCaveats(report);
 
   return [
     "## Configured Workflow Context",
@@ -354,6 +357,31 @@ function formatConfiguredWorkflowContext(report) {
     "",
     ...configuredWorkflowEntries(configuredWorkflow)
       .map(entry => `- ${entry.label}: ${entry.valueLabel}`),
+    ...(caveats.length
+      ? [
+          "",
+          "Workflow data caveats:",
+          "",
+          ...caveats.map(caveat => `- ${caveat}`),
+        ]
+      : []),
+    "",
+  ];
+}
+
+function formatContributorSourceContext(report) {
+  const contributorSource = report.contributorSource;
+  if (!contributorSource) return [];
+
+  return [
+    "## Contributor Source Context",
+    "",
+    contributorSource.note ?? CONTRIBUTOR_SOURCE_NOTE,
+    "",
+    `- Source type: ${contributorSource.sourceType ?? "unknown"}`,
+    `- Path: ${contributorSource.path ?? "not recorded"}`,
+    `- Coverage status: ${contributorSource.status ?? "unavailable"}`,
+    `- Parsed hint count: ${contributorSource.hintCount ?? 0}`,
     "",
   ];
 }
@@ -364,7 +392,7 @@ function formatProfileSuggestions(report) {
     return [
       "## Profile Suggestions",
       "",
-      "- No profile suggestion thresholds were triggered by this report's PR class, role, or functional-surface evidence.",
+      "- No profile suggestion thresholds were triggered by this report's PR class, role, functional-surface, or workflow-coverage evidence.",
       "",
     ];
   }
@@ -421,6 +449,7 @@ export function renderRepositoryFrictionMethodology({
     "",
     ...formatProfileSuggestions(report),
     ...formatConfiguredWorkflowContext(report),
+    ...formatContributorSourceContext(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.",
@@ -444,8 +473,8 @@ export function renderRepositoryFrictionMethodology({
     "## Artifact Sensitivity",
     "",
     csvEnabled
-      ? "Generated artifacts may include repository names, PR URLs, titles, file paths, comment-source counts, and coverage diagnostics. CSV files are curated for spreadsheet inspection but should still be treated as local/private unless intentionally shared."
-      : "Generated artifacts may include repository names, PR URLs, titles, file paths, comment metadata, and coverage diagnostics. CSV export generation was disabled for this run.",
+      ? "Generated artifacts may include repository names, PR URLs, titles, file paths, comment-source counts, contributor-source metadata, and coverage diagnostics. CSV files are curated for spreadsheet inspection but should still be treated as local/private unless intentionally shared. Raw contributor file contents and individual contributor rankings are not emitted."
+      : "Generated artifacts may include repository names, PR URLs, titles, file paths, comment metadata, contributor-source metadata, and coverage diagnostics. CSV export generation was disabled for this run. Raw contributor file contents and individual contributor rankings are not emitted.",
     "",
   ].join("\n").trimEnd()}\n`;
 }

package/src/report/friction-report.js

@@ -82,6 +82,9 @@ 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.";
+export const CONTRIBUTOR_SOURCE_NOTE = "Contributor source metadata comes from the configured repository profile source. It may improve comment-source classification coverage, but it does not change scores, PR authorship conclusions, reviewer attribution, CSV export shape, person-level CSV output, or individual ranking guardrails.";
+
+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,
@@ -421,9 +424,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.");
@@ -643,6 +644,26 @@ export function profileSuggestions(report = {}) {
     });
   }
 
+  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;
 }
 
@@ -682,6 +703,55 @@ export function hasConfiguredWorkflowContext(configuredWorkflow) {
   return configuredWorkflowEntries(configuredWorkflow).length > 0;
 }
 
+export function normalizeContributorSourceMetadata(contributorSource) {
+  if (!contributorSource || typeof contributorSource !== "object" || Array.isArray(contributorSource)) {
+    return null;
+  }
+  return {
+    source: "repository_profile",
+    sourceType: contributorSource.sourceType ?? "unknown",
+    path: contributorSource.path ?? null,
+    status: contributorSource.coverage?.status ?? "unavailable",
+    hintCount: Number.isInteger(contributorSource.hintCount)
+      ? contributorSource.hintCount
+      : Array.isArray(contributorSource.hints?.logins) ? contributorSource.hints.logins.length : 0,
+    note: CONTRIBUTOR_SOURCE_NOTE,
+  };
+}
+
+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)
@@ -832,18 +902,20 @@ function summarizeSensitivity(metricsSummary, baselineBottlenecks) {
 }
 
 export function generateRepositoryFrictionReport(metricsSummary, options = {}) {
-  const { workflowContext } = options ?? {};
+  const { workflowContext, contributorSource } = 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);
+  const contributorSourceMetadata = normalizeContributorSourceMetadata(contributorSource);
   return {
     reportVersion: FRICTION_REPORT_VERSION,
     metricVersion: metricsSummary.metricVersion,
     targetRepository: metricsSummary.targetRepository,
     ...(metricsSummary.analysisFilter ? { analysisFilter: metricsSummary.analysisFilter } : {}),
     ...(configuredWorkflow ? { configuredWorkflow } : {}),
+    ...(contributorSourceMetadata ? { contributorSource: contributorSourceMetadata } : {}),
     summary: {
       pullRequests: metricsSummary.totals?.pullRequests ?? 0,
       changedLines: metricsSummary.totals?.changedLines ?? 0,
@@ -1250,6 +1322,27 @@ function renderCoverageSummary(coverage) {
   );
 }
 
+function renderContributorSourceContext(contributorSource) {
+  if (!contributorSource) return "";
+
+  return [
+    "## Contributor Source Context",
+    "",
+    contributorSource.note ?? CONTRIBUTOR_SOURCE_NOTE,
+    "",
+    renderMarkdownTable(
+      ["Field", "Value"],
+      [
+        ["Source type", contributorSource.sourceType],
+        ["Path", contributorSource.path ?? "not recorded"],
+        ["Coverage status", contributorSource.status],
+        ["Parsed hint count", contributorSource.hintCount],
+      ],
+    ),
+    "",
+  ].join("\n");
+}
+
 function renderKeyFindings(report) {
   const topBottlenecks = topBottleneckLabels(report);
   const strongest = report.bottlenecks?.[0];
@@ -1393,6 +1486,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
@@ -1547,6 +1652,12 @@ export function renderRepositoryFrictionMarkdown(report) {
     ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
       ? [renderConfiguredWorkflowContext(report.configuredWorkflow)]
       : []),
+    ...(report.contributorSource
+      ? [renderContributorSourceContext(report.contributorSource)]
+      : []),
+    ...(workflowDataCaveats(report).length
+      ? [renderWorkflowDataCaveats(report)]
+      : []),
     "## Evidence Quality And Coverage",
     "",
     renderCoverageSummary(report.coverage),
@@ -1617,13 +1728,19 @@ export function renderRepositoryFrictionMarkdown(report) {
     "- 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.",
+      : "- 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."]
       : []),
+    ...(report.contributorSource
+      ? ["- Contributor source metadata is coverage context only; raw contributor contents and individual contributor rankings are not emitted."]
+      : []),
+    ...(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."