delivery-friction-analyzer 0.16.3 → 0.17.0

package/README.md

@@ -17,7 +17,7 @@ The analyzer runs locally with your GitHub credentials. Generated artifacts pres
 - GitHub CLI (`gh`) installed and authenticated with access to the target repository.
 - A repository profile JSON for the repository you want to analyze. Interactive setup can create a starter profile for you.
 
-For public repositories, ordinary read access is usually enough. Private repositories need a `gh` token with enough read access for the requested API families. With a classic PAT, that usually means the `repo` scope. With a fine-grained token or GitHub App, grant read permissions for repository metadata and contents, pull requests, Actions, and checks where available. Missing or partial API coverage is recorded in the generated methodology and coverage artifacts instead of being treated as complete data.
+For public repositories, ordinary read access is usually enough. Private repositories need a `gh` token with enough read access for the requested source families. With a classic PAT, that usually means the `repo` scope. With a fine-grained token or GitHub App, grant read permissions for repository metadata and contents, pull requests, Actions, and checks where available. Missing or partial source coverage is recorded in the generated methodology and coverage artifacts instead of being treated as complete data.
 
 ## Quickstart
 
@@ -94,7 +94,7 @@ Use these when you want to audit, automate, or build follow-up analysis:
 - `normalized.json`: normalized repository, PR, file, review, and validation entities.
 - `source-bundle.json`: collected source data for auditability. Its canonical
   analyzer contract is documented in `docs/contracts/source-bundle.md` and
-  checked by `schemas/github-source-bundle.schema.json`; it is not a full GitHub
+  checked by `schemas/source-bundle.schema.json`; it is not a full GitHub
   API payload schema.
 
 When CSV exports are enabled, the bundle also includes spreadsheet-friendly evidence files:
@@ -102,7 +102,7 @@ When CSV exports are enabled, the bundle also includes spreadsheet-friendly evid
 - `pr-metrics.csv`: per-PR metrics for spreadsheet review.
 - `bottleneck-examples.csv`: representative bottleneck examples.
 - `comment-sources.csv`: review-comment source breakdowns.
-- `collection-coverage.csv`: API coverage diagnostics.
+- `collection-coverage.csv`: source-family coverage diagnostics.
 
 Each ranked bottleneck example includes source references, workflow-run conclusions, review-thread source information, comment-source breakdowns, and a dominance note when one PR contributes most of the displayed signal.
 

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 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.
+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 source data, mutate repositories, rank individuals, or depend on services beyond the source collection path that produced the metrics summary.
 
 ## Outputs
 
@@ -19,16 +19,19 @@ Local artifact generation is available from an existing metrics summary:
 node src/report/generate-report.js --metrics-summary fixtures/github/mcp-writing/metrics-summary.golden.json --json-out fixtures/github/mcp-writing/reports/friction-report.golden.json --markdown-out fixtures/github/mcp-writing/reports/friction-report.golden.md
 ```
 
-The command reads local `friction-metrics.v1` JSON and writes deterministic `friction-report.v1` JSON and Markdown files. It does not fetch GitHub data, mutate the analyzed repository, or write CSV/methodology companion artifacts.
+The command reads local `friction-metrics.v1` JSON and writes deterministic `friction-report.v1` JSON and Markdown files. It does not fetch source data, mutate the analyzed repository, or write CSV/methodology companion artifacts.
 
 ## Report Shape
 
 - `reportVersion`: report contract version.
 - `metricVersion`: source metrics contract version.
+- `source`: optional source-bundle provenance copied into live-generated report
+  artifacts, including `kind` and a human-readable label.
 - `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.
+- `collectionCoverage`: optional source collection coverage metadata copied into live-generated report JSON artifacts. `collectionCoverage.status` records aggregate coverage, and `collectionCoverage.sourceFamilies` lists source-family entries with `family`, `status`, `attempts`, `source`, `diagnostics`, and `downstreamImpact`. This uses the generic `source-bundle.v1` `coverage.sourceFamilies` name; legacy GitHub `apiFamilies` is not a live `friction-report.v1` field.
 - `summary`: repository totals and top bottleneck identifiers.
 - `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.
@@ -99,7 +102,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. 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.
+Reports must label unavailable or partial source evidence instead of inferring unavailable values from merge-time data. Final/current PR metadata can come from source-bundle PR evidence, 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.
 
@@ -119,7 +122,7 @@ Full live analysis writes `methodology.md` as a hybrid artifact: stable explanat
 - 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;
+- collection coverage status and source-family diagnostics from `collectionCoverage.sourceFamilies`;
 - scoring, ranking, dominance, sensitivity, and limitation explanations;
 - generated artifact names and artifact-sensitivity guidance.
 
@@ -138,11 +141,11 @@ Minimum CSV column groups:
 - `pr-metrics.csv`: PR number, title, URL, PR class, PR class source/rule evidence, changed lines, non-generated changed lines, review comments, review threads, review decision, human reviewer count, human approval / changes-requested booleans, failed checks, failed workflow runs, cancelled workflow runs, post-review commits, review-thread source, workflow-run source/coverage, and main ranking scores.
 - `bottleneck-examples.csv`: bottleneck identity, recommendation category, PR identity, score/value, changed lines, validation counts, review counts, comment-source counts, workflow/review source and coverage labels, dominance, and source labels.
 - `comment-sources.csv`: source name, total comments, bot/scanner classification, human/author classification, and share of all comments.
-- `collection-coverage.csv`: API family, status, attempts, source label, diagnostics, and downstream impact.
+- `collection-coverage.csv`: source family, status, attempts, source label, diagnostics, and downstream impact.
 
 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.
+Contributor-source coverage appears in `collection-coverage.csv` as the `contributor_source` source 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
 
@@ -153,7 +156,7 @@ Use `friction-report.json` as the structured source of truth for report identity
 - `pr-metrics.csv` for analyzed PR rows, class labels, review/validation counts, and ranking scores.
 - `bottleneck-examples.csv` for representative examples tied to bottleneck identity, recommendation category, evidence sources, dominance, and score/value.
 - `comment-sources.csv` for source-grouped comment totals and classification flags.
-- `collection-coverage.csv` for API-family coverage, attempts, source labels, diagnostics, and downstream impact.
+- `collection-coverage.csv` for source-family coverage, attempts, source labels, diagnostics, and downstream impact.
 
 A guarded narrative-drafting workflow should:
 

package/docs/contracts/source-bundle.md

@@ -1,15 +1,40 @@
 # Source Bundle Contract
 
-Schema: `schemas/github-source-bundle.schema.json`.
+Schema: `schemas/source-bundle.schema.json`.
 
-`source-bundle.json` is the analyzer's canonical GitHub collection artifact. It
-is source-shaped evidence for later normalization, metrics, reports, and audit
-work, but it is not a full GitHub REST or GraphQL API dump.
+`source-bundle.json` is the analyzer's canonical source-evidence artifact. It is
+the shared analyzer contract for live GitHub collection and bundled tutorial
+sample data, not a raw provider dump. Both source kinds feed the same
+normalization, metrics, report, methodology, and CSV pipeline, so they share one
+contract with explicit provenance instead of pretending sample evidence is live
+GitHub evidence.
 
-The `github-source-bundle.v1` schema covers collector-owned fields:
+The current product contract is `source-bundle.v1`.
 
-- collection metadata, target repository, repository metadata, latest-merged PR
-  selection, API coverage diagnostics, and language distribution context;
+## Provenance
+
+Every bundle records the source boundary:
+
+- `schemaVersion`: must be `source-bundle.v1`.
+- `source.kind`: `github` for live GitHub evidence or `sample` for bundled
+  synthetic sample evidence.
+- `source.label`: human-readable label used by generated artifacts where source
+  provenance is shown.
+- `collector`: collector identity and provider details. Collector names are not
+  constrained to a GitHub-only value.
+
+Sample data must use labels that identify it as sample or synthetic evidence.
+Live GitHub data should use labels such as `GitHub live collection` and
+provider-specific source labels where the evidence came from GitHub APIs or
+`gh`.
+
+## Analyzer Evidence
+
+The schema covers collector-owned fields:
+
+- collection metadata, source provenance, target repository, repository
+  metadata, PR selection, source-family coverage diagnostics, and language
+  distribution context;
 - optional sanitized contributor-source metadata: source type, repository path,
   coverage/status diagnostics, and parsed hint count;
 - pull request fields consumed downstream: identity, title, author object, URL,
@@ -25,11 +50,56 @@ than pretending zero runs were observed.
 
 Contributor-source metadata must not persist raw contributor file contents or
 parsed login lists. Parsed contributor hints may be used transiently during a
-run, but generated artifacts keep only the sanitized metadata and `hintCount`.
-
-The schema is strict for analyzer-owned wrapper objects and mapped entities. It
-does not attempt to schema every raw GitHub field, and normal upstream GitHub API
-additions should not require schema updates unless the collector maps them into
-the canonical bundle. Future raw or provider-specific payloads must live under
-an explicit `raw` subtree so downstream normalization stays tied to canonical
-fields.
+run, but generated artifacts keep only sanitized metadata and `hintCount`.
+
+## Coverage
+
+Top-level `coverage.status` is retained as the aggregate source coverage status.
+`coverage.sourceFamilies` lists the source-family entries that make up the
+aggregate status. Each entry preserves the existing coverage-entry shape:
+
+- `family`
+- `source`
+- `status`
+- `attempts`
+- `diagnostics`
+- `downstreamImpact`
+
+The `source` label is generic. Live entries may name GitHub REST, GraphQL, or
+`gh` sources; sample entries may name bundled tutorial evidence. The per-PR
+`pullRequests[*].coverage` object is retained in place with keys such as
+`prOpenDiff`, `reviewThreads`, and `workflowRuns`.
+
+## Field Migration From Legacy GitHub Bundles
+
+`github-source-bundle.v1` is a legacy artifact shape. Current generated bundles
+must use `source-bundle.v1`. There is no silent compatibility adapter in the
+runtime; legacy artifacts need an explicit migration before they can validate
+against the current schema.
+
+| Legacy `github-source-bundle.v1` field | `source-bundle.v1` treatment |
+| --- | --- |
+| `schemaVersion` | Rename value to `source-bundle.v1`. |
+| `collectedAt` | Retained as the materialization timestamp for live and sample bundles. |
+| `collector` | Retained and generalized; `collector.name` is no longer constrained to a GitHub-only value. |
+| `source` | New required object with `kind`, `label`, and optional metadata. |
+| `targetRepository` | Retained. Sample bundles use fictional placeholder repository identity. |
+| `repositoryMetadata` | Retained. Sample metadata must be fictional and clearly synthetic. |
+| `selection` | Retained and generalized; selection strategies and source labels do not have to be GitHub-only. |
+| `coverage.status` | Retained as the aggregate status over `coverage.sourceFamilies`. |
+| `coverage.apiFamilies` | Renamed to `coverage.sourceFamilies`; entry shape is preserved. |
+| `languageDistribution` | Retained with generalized source labels. |
+| `contributorSource` | Retained as optional sanitized metadata with generalized source labels. |
+| `pullRequests` | Retained as GitHub-shaped PR evidence consumed by normalization. |
+| `pullRequests[*].coverage` | Retained as the per-PR coverage object with current per-family keys. |
+| `raw` | Retained as the only subtree for provider- or sample-specific raw details. |
+
+No analyzer-owned evidence field from `github-source-bundle.v1` is intentionally
+removed in this migration.
+
+The schema remains strict for analyzer-owned wrapper objects and mapped
+entities. It does not attempt to schema every raw provider field, and normal
+upstream GitHub API additions should not require schema updates unless the
+collector maps them into canonical bundle fields. Future raw or
+provider-specific payloads must live under an explicit `raw` subtree so
+downstream normalization stays tied to canonical fields.

package/docs/reference/github-data-inventory.md

@@ -54,6 +54,6 @@ Availability decision:
 
 Fixtures store compact, redacted source-shaped data rather than full raw payloads.
 Live `source-bundle.json` artifacts use the analyzer-owned
-`github-source-bundle.v1` contract in `schemas/github-source-bundle.schema.json`;
+`source-bundle.v1` contract in `schemas/source-bundle.schema.json`;
 that schema covers the canonical fields consumed downstream, not the full GitHub
 REST or GraphQL API response shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.16.3",
+  "version": "0.17.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-26 — Generic Source Bundle Report Wording
+
+- What changed: Report Markdown, methodology-adjacent contract docs, and CSV coverage expectations now use generic source-bundle and source-family wording for `source-bundle.v1`, including `collectionCoverage.status` and `collectionCoverage.sourceFamilies`.
+- Why it matters: Maintainers can review live GitHub output and future bundled sample output without stale GitHub-only labels implying that every report source is live API evidence.
+- Who is affected: Maintainers reviewing generated reports, `friction-report.v1` JSON, contract docs, or source coverage CSV exports during the tutorial sample migration.
+- Action needed: Update any scripts or downstream tooling that parse source coverage fields from `apiFamilies`/`api_family` to `sourceFamilies`/`source_family`.
+- PR: #60
+
 ### 2026-06-23 — Tutorial Target Guidance
 
 - What changed: Public quickstart guidance no longer depends on `hannasdev/mcp-writing`, and product-repository rejection plus `--validation-target` help now make the analysis boundary clearer.

package/schemas/{github-source-bundle.schema.json → source-bundle.schema.json}

@@ -1,12 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://delivery-friction-analyzer.local/schemas/github-source-bundle.schema.json",
-  "title": "GitHubSourceBundle",
+  "$id": "https://delivery-friction-analyzer.local/schemas/source-bundle.schema.json",
+  "title": "SourceBundle",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "schemaVersion",
     "collectedAt",
+    "source",
     "collector",
     "targetRepository",
     "repositoryMetadata",
@@ -16,14 +17,27 @@
     "pullRequests"
   ],
   "properties": {
-    "schemaVersion": { "const": "github-source-bundle.v1" },
+    "schemaVersion": { "const": "source-bundle.v1" },
     "collectedAt": { "type": "string" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "label"],
+      "properties": {
+        "kind": { "enum": ["github", "sample"] },
+        "label": { "type": "string", "minLength": 1 },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
     "collector": {
       "type": "object",
       "additionalProperties": false,
       "required": ["name", "provider"],
       "properties": {
-        "name": { "const": "github-live-collector" },
+        "name": { "type": "string", "minLength": 1 },
         "provider": { "type": "string", "minLength": 1 }
       }
     },
@@ -48,7 +62,7 @@
       "additionalProperties": false,
       "required": ["strategy", "requestedLimit", "collectedCount", "source"],
       "properties": {
-        "strategy": { "const": "latest_merged_pull_requests" },
+        "strategy": { "type": "string", "minLength": 1 },
         "requestedLimit": { "type": "integer", "minimum": 1, "maximum": 100 },
         "collectedCount": { "type": "integer", "minimum": 0, "maximum": 100 },
         "source": { "type": "string", "minLength": 1 }
@@ -57,12 +71,12 @@
     "coverage": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["status", "apiFamilies"],
+      "required": ["status", "sourceFamilies"],
       "properties": {
         "status": { "$ref": "#/$defs/coverageStatus" },
-        "apiFamilies": {
+        "sourceFamilies": {
           "type": "array",
-          "items": { "$ref": "#/$defs/apiCoverageEntry" }
+          "items": { "$ref": "#/$defs/sourceCoverageEntry" }
         }
       }
     },
@@ -71,7 +85,7 @@
       "additionalProperties": false,
       "required": ["source", "bytesByLanguage", "coverage"],
       "properties": {
-        "source": { "const": "rest:/repos/{owner}/{repo}/languages" },
+        "source": { "type": "string", "minLength": 1 },
         "bytesByLanguage": {
           "type": "object",
           "additionalProperties": { "type": "integer", "minimum": 0 }
@@ -83,7 +97,7 @@
               "type": "object",
               "properties": {
                 "family": { "const": "languages" },
-                "source": { "const": "rest:/repos/{owner}/{repo}/languages" }
+                "source": { "type": "string", "minLength": 1 }
               }
             }
           ]
@@ -104,7 +118,7 @@
               "type": "object",
               "properties": {
                 "family": { "const": "contributor_source" },
-                "source": { "const": "rest:/repos/{owner}/{repo}/contents/{path}" }
+                "source": { "type": "string", "minLength": 1 }
               }
             }
           ]
@@ -150,7 +164,7 @@
         "downstreamImpact": { "type": ["string", "null"] }
       }
     },
-    "apiCoverageEntry": {
+    "sourceCoverageEntry": {
       "allOf": [
         { "$ref": "#/$defs/coverageEntry" },
         {
@@ -319,7 +333,7 @@
       "additionalProperties": false,
       "required": ["source", "totalCount", "nodes"],
       "properties": {
-        "source": { "enum": ["graphql:repository.pullRequest.reviewThreads", "unavailable"] },
+        "source": { "type": "string", "minLength": 1 },
         "totalCount": { "type": "integer", "minimum": 0 },
         "nodes": {
           "type": "array",
@@ -378,7 +392,7 @@
       "additionalProperties": false,
       "required": ["source", "totalCount", "conclusions", "runs"],
       "properties": {
-        "source": { "enum": ["rest:/repos/{owner}/{repo}/actions/runs?branch={branch}&event=pull_request", "unavailable"] },
+        "source": { "type": "string", "minLength": 1 },
         "totalCount": { "type": ["integer", "null"], "minimum": 0 },
         "conclusions": {
           "type": "object",
@@ -434,7 +448,7 @@
               "type": "object",
               "properties": {
                 "family": { "const": "pr_open_diff" },
-                "source": { "const": "historical_snapshot" },
+                "source": { "type": "string", "minLength": 1 },
                 "status": { "enum": ["available", "partial", "unavailable", "rate_limited"] }
               }
             }
@@ -447,7 +461,7 @@
               "type": "object",
               "properties": {
                 "family": { "const": "review_threads" },
-                "source": { "const": "graphql:repository.pullRequest.reviewThreads" }
+                "source": { "type": "string", "minLength": 1 }
               }
             }
           ]
@@ -459,7 +473,7 @@
               "type": "object",
               "properties": {
                 "family": { "const": "workflow_runs" },
-                "source": { "const": "rest:/repos/{owner}/{repo}/actions/runs?branch={branch}&event=pull_request" }
+                "source": { "type": "string", "minLength": 1 }
               }
             }
           ]

package/src/cli/analyze-github.js

@@ -1400,16 +1400,22 @@ export async function writeAnalysisArtifacts(outDir, paths, artifacts, { disable
 }
 
 function collectionCoverageMarkdown(sourceBundle) {
+  const source = sourceBundle.source;
+  const sourceLabel = source?.label
+    ? `${source.label}${source.kind ? ` (${source.kind})` : ""}`
+    : "not recorded";
   const lines = [
     "",
     "## Collection Coverage",
     "",
+    `Source: ${sourceLabel}`,
+    "",
     `Overall collection coverage: ${sourceBundle.coverage.status}`,
     "",
-    "API families:",
+    "Source families:",
   ];
 
-  for (const family of sourceBundle.coverage.apiFamilies ?? []) {
+  for (const family of sourceBundle.coverage.sourceFamilies ?? []) {
     const diagnostics = (family.diagnostics ?? []).length ? `; diagnostics: ${family.diagnostics.join(" | ")}` : "";
     const impact = family.downstreamImpact ? `; impact: ${family.downstreamImpact}` : "";
     lines.push(`- ${family.family}: ${family.status} (${family.attempts ?? 1} attempt(s))${diagnostics}${impact}`);
@@ -1422,6 +1428,7 @@ function collectionCoverageMarkdown(sourceBundle) {
 function attachCollectionCoverage(report, sourceBundle) {
   return {
     ...report,
+    source: sourceBundle.source,
     collectionCoverage: sourceBundle.coverage,
     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.",
   };
@@ -1607,7 +1614,7 @@ function coverageLine(family) {
 }
 
 function coverageCaveats(coverage) {
-  return (coverage?.apiFamilies ?? []).filter(family => {
+  return (coverage?.sourceFamilies ?? []).filter(family => {
     const diagnostics = (family.diagnostics ?? []).filter(Boolean);
     return family.status !== "available" || diagnostics.length > 0;
   });

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

@@ -18,7 +18,7 @@ import {
   redactDiagnostic,
 } from "./coverage.js";
 
-export const GITHUB_SOURCE_BUNDLE_VERSION = "github-source-bundle.v1";
+export const SOURCE_BUNDLE_VERSION = "source-bundle.v1";
 
 const REPOSITORY_SLUG = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/;
 function parseRepositoryInput(input) {
@@ -507,7 +507,7 @@ export async function collectGitHubSourceBundle({
     pullRequests.push(pr);
   }
 
-  const apiFamilies = [
+  const sourceFamilies = [
     repositoryCoverage,
     languagesAttempt.coverage,
     inventoryCoverage,
@@ -542,8 +542,12 @@ export async function collectGitHubSourceBundle({
   ];
 
   return {
-    schemaVersion: GITHUB_SOURCE_BUNDLE_VERSION,
+    schemaVersion: SOURCE_BUNDLE_VERSION,
     collectedAt,
+    source: {
+      kind: "github",
+      label: "GitHub live collection",
+    },
     collector: {
       name: "github-live-collector",
       provider: provider.kind ?? "custom",
@@ -557,8 +561,8 @@ export async function collectGitHubSourceBundle({
       source: "gh pr list --state merged --search \"is:merged sort:merged-desc\"",
     },
     coverage: {
-      status: buildCoverageSummary(apiFamilies),
-      apiFamilies,
+      status: buildCoverageSummary(sourceFamilies),
+      sourceFamilies,
     },
     languageDistribution: {
       source: "rest:/repos/{owner}/{repo}/languages",

package/src/report/evidence-artifacts.js

@@ -247,17 +247,17 @@ function commentSourcesCsv(report, analysisFilter) {
 
 function collectionCoverageCsv(collectionCoverage, analysisFilter) {
   const headers = [
-    "api_family",
+    "source_family",
     "status",
     "attempts",
     "source",
     "diagnostics",
     "downstream_impact",
   ];
-  const rows = [...(collectionCoverage?.apiFamilies ?? [])]
+  const rows = [...(collectionCoverage?.sourceFamilies ?? [])]
     .sort((left, right) => String(left.family).localeCompare(String(right.family)))
     .map(family => ({
-      api_family: family.family,
+      source_family: family.family,
       status: family.status,
       attempts: family.attempts ?? 1,
       source: family.source,
@@ -283,8 +283,13 @@ function repositoryLabel(report) {
     : "unknown repository";
 }
 
+function sourceLabel(source) {
+  if (!source?.label) return "not recorded";
+  return `${source.label}${source.kind ? ` (${source.kind})` : ""}`;
+}
+
 function formatCoverageFamilies(collectionCoverage) {
-  const families = collectionCoverage?.apiFamilies ?? [];
+  const families = collectionCoverage?.sourceFamilies ?? [];
   if (!families.length) return "- No collection coverage families were recorded.";
   return families
     .map(family => {
@@ -419,12 +424,14 @@ export function renderRepositoryFrictionMethodology({
 }) {
   const selection = sourceBundle?.selection ?? {};
   const collectionCoverage = sourceBundle?.coverage ?? report.collectionCoverage;
+  const source = sourceBundle?.source ?? report.source;
 
   return `${[
     `# Methodology: ${repositoryLabel(report)}`,
     "",
     `Report version: ${report.reportVersion}`,
     `Metric version: ${report.metricVersion}`,
+    `Source: ${sourceLabel(source)}`,
     `Repository: ${repositoryLabel(report)}`,
     `Profile path: ${profilePath ?? "not recorded"}`,
     `Requested pull requests: ${selection.requestedLimit ?? "unknown"}`,
@@ -434,7 +441,7 @@ export function renderRepositoryFrictionMethodology({
     "",
     "## What This Analysis Uses",
     "",
-    "The analyzer collects merged GitHub pull requests, normalizes repository-specific fields through the supplied profile, computes transparent component metrics, and renders a repository-level report. It does not inspect local working trees, mutate repositories, rank people, or apply recommendations automatically.",
+    "The analyzer normalizes source-bundle pull request evidence through the supplied profile, computes transparent component metrics, and renders a repository-level report. It does not inspect local working trees, mutate repositories, rank people, or apply recommendations automatically.",
     "",
     "## Pull Request Selection",
     "",

package/src/report/friction-report.js

@@ -1624,6 +1624,9 @@ export function renderRepositoryFrictionMarkdown(report) {
     "",
     `Report version: ${report.reportVersion}`,
     `Metric version: ${report.metricVersion}`,
+    ...(report.source?.label
+      ? [`Source: ${report.source.label}${report.source.kind ? ` (${report.source.kind})` : ""}`]
+      : []),
     `Pull requests analyzed: ${report.summary?.pullRequests ?? "unknown"}`,
     "",
     ...analysisFilterLines,
@@ -1641,7 +1644,7 @@ export function renderRepositoryFrictionMarkdown(report) {
     "",
     "## How To Read This Report",
     "",
-    "- Observed evidence is measured from GitHub data and repository-profile classifications.",
+    "- Observed evidence is measured from source-bundle evidence and repository-profile classifications.",
     "- 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.",
@@ -1731,7 +1734,7 @@ export function renderRepositoryFrictionMarkdown(report) {
       : "- 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.",
+    "- Missing or partial source evidence 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."]
       : []),