delivery-friction-analyzer 0.16.3 → 0.18.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/docs/reference/repository-profile.md

@@ -41,6 +41,12 @@ This keeps validation-target details in profile data rather than hardcoded produ
 
 Each file rule must include a unique lowercase `id`, a non-empty `match` object, a supported `category`, and a supported `role`. Optional `functionalSurface` values use the same lowercase identifier shape as rule IDs. Optional `generated` values must be booleans. Unsupported rule or matcher keys fail validation, and invalid JavaScript regexes fail before collection with the rule ID and matcher field in the error.
 
+File rules may include an optional `notes` string. Notes are human-readable
+profile context for maintainers and reviewers. They can explain why a path rule
+exists, what product surface it represents, or why a generated or low-signal
+path is intentionally classified. Notes do not affect matching order,
+classification output, scoring, collection, reports, or CSV exports.
+
 ## Pull Request Classes
 
 `prClasses` is optional. Rules are evaluated in order and the first matching rule wins. The current profile contract supports title-only matchers:
@@ -64,6 +70,12 @@ Class identifiers are validated as lower-kebab-case or lower_snake_case strings.
 
 PR class evidence is interpretive and profile-driven. It helps reports show class distributions, dominance notes, and explicit `--exclude-pr-class` filtering when you request filtering, but configured PR class rules do not change default scoring, ranking formulas, collection, or CSV export shape by themselves.
 
+PR class rules may include an optional `notes` string. Use notes to document the
+repository convention behind a class rule, such as Conventional Commit-style
+title prefixes or release-train naming. Notes are valid JSON profile data for
+humans only; they do not change title matching, PR class assignment, filtering,
+scoring, collection, reports, or CSV exports.
+
 Interactive setup can add a release PR class rule from a confirmed title convention using the current title-only matcher shape. Branch strategy answers stay in `workflow` context only; they do not create branch-based PR class matching. Branch-based class matching is deferred until a future matcher contract supports branch fields explicitly.
 
 ### Copyable PR Class Examples

package/examples/tutorial/profile.json

@@ -0,0 +1,110 @@
+{
+  "schemaVersion": "repository-profile.v1",
+  "repository": {
+    "owner": "example-org",
+    "name": "delivery-dashboard"
+  },
+  "rules": [
+    {
+      "id": "frontend-ui-paths",
+      "match": { "prefix": "apps/web/" },
+      "category": "code",
+      "role": "product_ui",
+      "functionalSurface": "dashboard_ui",
+      "generated": false,
+      "notes": "Maps the customer-facing dashboard app to the UI surface so broad UI changes are not treated as unknown code."
+    },
+    {
+      "id": "api-runtime-paths",
+      "match": { "prefix": "services/api/" },
+      "category": "code",
+      "role": "core_product_code",
+      "functionalSurface": "delivery_api",
+      "generated": false,
+      "notes": "Represents backend delivery workflow behavior that usually needs API-focused review."
+    },
+    {
+      "id": "worker-runtime-paths",
+      "match": { "prefix": "workers/" },
+      "category": "code",
+      "role": "core_product_code",
+      "functionalSurface": "background_jobs",
+      "generated": false
+    },
+    {
+      "id": "integration-tests",
+      "match": { "prefix": "tests/integration/" },
+      "category": "tests",
+      "role": "tests",
+      "functionalSurface": "test_suite",
+      "generated": false
+    },
+    {
+      "id": "workflow-config",
+      "match": { "prefix": ".github/workflows/" },
+      "category": "infrastructure",
+      "role": "infrastructure",
+      "functionalSurface": "ci_workflows",
+      "generated": false,
+      "notes": "Classifies CI workflow edits separately from product runtime changes."
+    },
+    {
+      "id": "planning-notes",
+      "match": { "prefix": "docs/initiatives/" },
+      "category": "docs",
+      "role": "planning_docs",
+      "functionalSurface": "planning",
+      "generated": false
+    },
+    {
+      "id": "release-notes",
+      "match": { "exact": "CHANGELOG.md" },
+      "category": "docs",
+      "role": "release_notes",
+      "functionalSurface": "release_docs",
+      "generated": false
+    },
+    {
+      "id": "generated-api-client",
+      "match": { "prefix": "packages/generated-client/" },
+      "category": "generated",
+      "role": "generated_or_vendored",
+      "functionalSurface": "generated_client",
+      "generated": true,
+      "notes": "Shows how generated code can stay visible while receiving low-signal weighting."
+    }
+  ],
+  "prClasses": [
+    {
+      "id": "feature-title",
+      "class": "feature",
+      "match": { "titleRegex": "^feat(?:\\([^)]+\\))?:" },
+      "notes": "Use when feature PR titles follow a Conventional Commit-style prefix."
+    },
+    {
+      "id": "fix-title",
+      "class": "fix",
+      "match": { "titleRegex": "^fix(?:\\([^)]+\\))?:" },
+      "notes": "Separates corrective work from feature delivery in the class distribution."
+    },
+    {
+      "id": "test-title",
+      "class": "test",
+      "match": { "titleRegex": "^test(?:\\([^)]+\\))?:" }
+    },
+    {
+      "id": "maintenance-title",
+      "class": "maintenance",
+      "match": { "titleRegex": "^(?:chore|ci|build|refactor)(?:\\([^)]+\\))?:" }
+    }
+  ],
+  "workflow": {
+    "primaryMergeMethod": "squash_merge",
+    "releaseStrategy": "release_prs",
+    "branchStrategy": "trunk_based"
+  },
+  "contributors": {
+    "sourceType": "all_contributors",
+    "path": ".all-contributorsrc"
+  }
+}

package/examples/tutorial/report-excerpt.md

@@ -0,0 +1,7 @@
+# Tutorial Sample Report Excerpt
+
+Source: Bundled synthetic sample, not live GitHub data.
+
+The generated sample report opens by pointing readers to Change scope, Review churn, and Repo guidance gap. It also shows why the first findings should not be overgeneralized: PR #104 is intentionally broad and outlier-sensitive, PR-open diff coverage is partial, and one PR has unavailable workflow-run history.
+
+Use the excerpt in public docs to set expectations: the sample is synthetic tutorial evidence, not observed GitHub data, and its value is showing how caveats, profile classifications, PR classes, workflow context, and CSV evidence appear in a local report bundle.

package/examples/tutorial/source-bundle.json

@@ -0,0 +1,388 @@
+{
+  "schemaVersion": "source-bundle.v1",
+  "collectedAt": "2026-06-15T12:00:00Z",
+  "source": {
+    "kind": "sample",
+    "label": "Bundled synthetic sample, not live GitHub data",
+    "metadata": {
+      "tutorial": true,
+      "publicSafety": "fully synthetic placeholder data"
+    }
+  },
+  "collector": {
+    "name": "tutorial-sample-collector",
+    "provider": "bundled-sample"
+  },
+  "targetRepository": {
+    "owner": "example-org",
+    "name": "delivery-dashboard",
+    "defaultBranch": "main",
+    "visibility": "public",
+    "analysisPullRequestLimit": 4,
+    "isValidationTarget": false
+  },
+  "repositoryMetadata": {
+    "id": "sample-repository-001",
+    "name": "delivery-dashboard",
+    "owner": "example-org",
+    "fullName": "example-org/delivery-dashboard",
+    "defaultBranch": "main",
+    "visibility": "public",
+    "isPrivate": false,
+    "htmlUrl": "https://example.com/example-org/delivery-dashboard"
+  },
+  "selection": {
+    "strategy": "bundled_tutorial_pull_requests",
+    "requestedLimit": 4,
+    "collectedCount": 4,
+    "source": "bundled tutorial sample"
+  },
+  "coverage": {
+    "status": "partial",
+    "sourceFamilies": [
+      {
+        "family": "repository_metadata",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Fictional repository identity is available for report labeling."
+      },
+      {
+        "family": "pull_request_inventory",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Four fictional merged pull requests are available for normalization and metrics."
+      },
+      {
+        "family": "pull_request_details",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Synthetic lifecycle, files, reviews, checks, and workflow summaries are populated."
+      },
+      {
+        "family": "review_threads",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Review-thread counts and comment sources are populated without comment text."
+      },
+      {
+        "family": "workflow_runs",
+        "source": "bundled tutorial sample",
+        "status": "partial",
+        "attempts": 1,
+        "diagnostics": ["One PR intentionally has unavailable workflow-run history to demonstrate coverage caveats."],
+        "downstreamImpact": "Validation-gap metrics use observed runs where present and preserve unavailable coverage where missing."
+      },
+      {
+        "family": "pr_open_diff",
+        "source": "bundled tutorial sample",
+        "status": "partial",
+        "attempts": 1,
+        "diagnostics": ["One PR intentionally lacks PR-open diff data to demonstrate partial diff-growth coverage."],
+        "downstreamImpact": "Diff-growth ratios are computed only for PRs with open-time snapshots."
+      },
+      {
+        "family": "languages",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Language distribution is illustrative context only."
+      },
+      {
+        "family": "contributor_source",
+        "source": "bundled tutorial sample",
+        "status": "partial",
+        "attempts": 1,
+        "diagnostics": ["Synthetic contributor hints omit one reviewer to demonstrate partial profile context."],
+        "downstreamImpact": "Contributor-aware comment-source hints are available; scoring and person-level outputs are unchanged."
+      }
+    ]
+  },
+  "languageDistribution": {
+    "source": "bundled tutorial sample",
+    "bytesByLanguage": {
+      "TypeScript": 420000,
+      "JavaScript": 180000,
+      "Markdown": 52000,
+      "YAML": 18000
+    },
+    "coverage": {
+      "family": "languages",
+      "source": "bundled tutorial sample",
+      "status": "available",
+      "attempts": 1,
+      "diagnostics": [],
+      "downstreamImpact": "Language distribution is illustrative context only."
+    }
+  },
+  "contributorSource": {
+    "sourceType": "all_contributors",
+    "path": ".all-contributorsrc",
+    "coverage": {
+      "family": "contributor_source",
+      "source": "bundled tutorial sample",
+      "status": "partial",
+      "attempts": 1,
+      "diagnostics": ["Synthetic contributor hints omit one reviewer to demonstrate partial profile context."],
+      "downstreamImpact": "Contributor-aware comment-source hints are available; scoring and person-level outputs are unchanged."
+    },
+    "hintCount": 3
+  },
+  "pullRequests": [
+    {
+      "number": 101,
+      "title": "feat: add route health dashboard",
+      "author": { "login": "sample-author-ui", "type": "User" },
+      "url": "https://example.com/pull/101",
+      "state": "MERGED",
+      "createdAt": "2026-05-04T09:00:00Z",
+      "mergedAt": "2026-05-05T16:30:00Z",
+      "updatedAt": "2026-05-05T16:45:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/route-health-dashboard",
+      "headRefOid": "sample101merge",
+      "additions": 410,
+      "deletions": 96,
+      "changedFiles": 5,
+      "prOpenDiff": { "source": "direct", "confidence": "high", "additions": 190, "deletions": 44, "changedFiles": 5 },
+      "commits": [
+        { "oid": "sample101a", "authoredDate": "2026-05-04T08:40:00Z", "committedDate": "2026-05-04T08:42:00Z", "messageHeadline": "feat: add route health dashboard" },
+        { "oid": "sample101b", "authoredDate": "2026-05-05T12:15:00Z", "committedDate": "2026-05-05T12:16:00Z", "messageHeadline": "test: cover delayed route states" }
+      ],
+      "files": [
+        { "path": "apps/web/src/routes/RouteHealthPanel.tsx", "additions": 140, "deletions": 22, "changeType": "ADDED" },
+        { "path": "apps/web/src/routes/RouteHealthChart.tsx", "additions": 94, "deletions": 16, "changeType": "ADDED" },
+        { "path": "services/api/src/routes/health-summary.ts", "additions": 78, "deletions": 18, "changeType": "MODIFIED" },
+        { "path": "tests/integration/route-health.test.ts", "additions": 82, "deletions": 20, "changeType": "ADDED" },
+        { "path": "CHANGELOG.md", "additions": 16, "deletions": 20, "changeType": "MODIFIED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-101-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-04T14:20:00Z", "state": "CHANGES_REQUESTED", "commitOid": "sample101a", "generatedCommentCount": 0, "failedAttempt": true },
+        { "id": "sample-review-101-b", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-05T15:20:00Z", "state": "APPROVED", "commitOid": "sample101b", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": {
+        "source": "bundled tutorial sample:review_threads",
+        "totalCount": 2,
+        "nodes": [
+          { "id": "sample-thread-101-a", "isResolved": true, "isOutdated": false, "path": "apps/web/src/routes/RouteHealthPanel.tsx", "line": 88, "comments": [
+            { "databaseId": "sample-comment-101-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "path": "apps/web/src/routes/RouteHealthPanel.tsx", "line": 88, "originalLine": 88, "createdAt": "2026-05-04T14:21:00Z", "updatedAt": "2026-05-04T14:21:00Z", "url": "https://example.com/pull/101#discussion-sample-101-a" },
+            { "databaseId": "sample-comment-101-b", "author": { "login": "sample-author-ui", "type": "User" }, "path": "apps/web/src/routes/RouteHealthPanel.tsx", "line": 88, "originalLine": 88, "createdAt": "2026-05-05T12:18:00Z", "updatedAt": "2026-05-05T12:18:00Z", "url": "https://example.com/pull/101#discussion-sample-101-b" }
+          ] },
+          { "id": "sample-thread-101-b", "isResolved": true, "isOutdated": true, "path": "services/api/src/routes/health-summary.ts", "line": 41, "comments": [
+            { "databaseId": "sample-comment-101-c", "author": { "login": "sample-reviewer-b", "type": "User" }, "path": "services/api/src/routes/health-summary.ts", "line": 41, "originalLine": 41, "createdAt": "2026-05-04T15:02:00Z", "updatedAt": "2026-05-04T15:02:00Z", "url": "https://example.com/pull/101#discussion-sample-101-c" }
+          ] }
+        ]
+      },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-04T09:10:00Z", "completedAt": "2026-05-04T09:16:00Z" },
+        { "__typename": "CheckRun", "name": "integration", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "FAILURE", "startedAt": "2026-05-04T09:12:00Z", "completedAt": "2026-05-04T09:24:00Z" },
+        { "__typename": "CheckRun", "name": "integration", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-05T12:20:00Z", "completedAt": "2026-05-05T12:31:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "bundled tutorial sample:workflow_runs",
+        "totalCount": 2,
+        "conclusions": { "success": 1, "failure": 1 },
+        "runs": [
+          { "id": "sample-run-101-a", "name": "CI", "workflowName": "CI", "headSha": "sample101a", "headBranch": "sample/route-health-dashboard", "event": "pull_request", "status": "completed", "conclusion": "failure", "createdAt": "2026-05-04T09:10:00Z", "updatedAt": "2026-05-04T09:24:00Z", "runStartedAt": "2026-05-04T09:12:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-101-a" },
+          { "id": "sample-run-101-b", "name": "CI", "workflowName": "CI", "headSha": "sample101b", "headBranch": "sample/route-health-dashboard", "event": "pull_request", "status": "completed", "conclusion": "success", "createdAt": "2026-05-05T12:20:00Z", "updatedAt": "2026-05-05T12:31:00Z", "runStartedAt": "2026-05-05T12:21:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-101-b" }
+        ]
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Diff-growth metrics can compare open and merge sizes." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Workflow-run evidence is available." }
+      }
+    },
+    {
+      "number": 102,
+      "title": "fix: retry stalled dispatch jobs",
+      "author": { "login": "sample-author-api", "type": "User" },
+      "url": "https://example.com/pull/102",
+      "state": "MERGED",
+      "createdAt": "2026-05-07T10:00:00Z",
+      "mergedAt": "2026-05-07T18:10:00Z",
+      "updatedAt": "2026-05-07T18:20:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/retry-dispatch-jobs",
+      "headRefOid": "sample102merge",
+      "additions": 126,
+      "deletions": 34,
+      "changedFiles": 4,
+      "prOpenDiff": { "source": "direct", "confidence": "high", "additions": 120, "deletions": 30, "changedFiles": 4 },
+      "commits": [
+        { "oid": "sample102a", "authoredDate": "2026-05-07T09:45:00Z", "committedDate": "2026-05-07T09:46:00Z", "messageHeadline": "fix: retry stalled dispatch jobs" },
+        { "oid": "sample102b", "authoredDate": "2026-05-07T15:10:00Z", "committedDate": "2026-05-07T15:12:00Z", "messageHeadline": "test: cover retry backoff" }
+      ],
+      "files": [
+        { "path": "workers/dispatch/retry.ts", "additions": 58, "deletions": 18, "changeType": "MODIFIED" },
+        { "path": "services/api/src/jobs/dispatch.ts", "additions": 24, "deletions": 8, "changeType": "MODIFIED" },
+        { "path": "tests/integration/dispatch-retry.test.ts", "additions": 42, "deletions": 8, "changeType": "ADDED" },
+        { "path": "docs/initiatives/retry-jobs/checklist.md", "additions": 2, "deletions": 0, "changeType": "ADDED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-102-a", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-07T13:00:00Z", "state": "COMMENTED", "commitOid": "sample102a", "generatedCommentCount": 0, "failedAttempt": false },
+        { "id": "sample-review-102-b", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-07T17:40:00Z", "state": "APPROVED", "commitOid": "sample102b", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": {
+        "source": "bundled tutorial sample:review_threads",
+        "totalCount": 1,
+        "nodes": [
+          { "id": "sample-thread-102-a", "isResolved": true, "isOutdated": false, "path": "workers/dispatch/retry.ts", "line": 30, "comments": [
+            { "databaseId": "sample-comment-102-a", "author": { "login": "sample-reviewer-b", "type": "User" }, "path": "workers/dispatch/retry.ts", "line": 30, "originalLine": 30, "createdAt": "2026-05-07T13:01:00Z", "updatedAt": "2026-05-07T13:01:00Z", "url": "https://example.com/pull/102#discussion-sample-102-a" },
+            { "databaseId": "sample-comment-102-b", "author": { "login": "sample-author-api", "type": "User" }, "path": "workers/dispatch/retry.ts", "line": 30, "originalLine": 30, "createdAt": "2026-05-07T15:15:00Z", "updatedAt": "2026-05-07T15:15:00Z", "url": "https://example.com/pull/102#discussion-sample-102-b" }
+          ] }
+        ]
+      },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-07T10:10:00Z", "completedAt": "2026-05-07T10:16:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "bundled tutorial sample:workflow_runs",
+        "totalCount": 1,
+        "conclusions": { "success": 1 },
+        "runs": [
+          { "id": "sample-run-102-a", "name": "CI", "workflowName": "CI", "headSha": "sample102b", "headBranch": "sample/retry-dispatch-jobs", "event": "pull_request", "status": "completed", "conclusion": "success", "createdAt": "2026-05-07T15:20:00Z", "updatedAt": "2026-05-07T15:29:00Z", "runStartedAt": "2026-05-07T15:21:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-102-a" }
+        ]
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Diff-growth metrics can compare open and merge sizes." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Workflow-run evidence is available." }
+      }
+    },
+    {
+      "number": 103,
+      "title": "test: add billing webhook contract coverage",
+      "author": { "login": "sample-author-test", "type": "User" },
+      "url": "https://example.com/pull/103",
+      "state": "MERGED",
+      "createdAt": "2026-05-10T11:00:00Z",
+      "mergedAt": "2026-05-10T14:40:00Z",
+      "updatedAt": "2026-05-10T14:45:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/billing-webhook-tests",
+      "headRefOid": "sample103merge",
+      "additions": 88,
+      "deletions": 10,
+      "changedFiles": 3,
+      "prOpenDiff": { "source": "unavailable", "confidence": "unavailable", "reason": "Open-time snapshot intentionally omitted from the bundled sample." },
+      "commits": [
+        { "oid": "sample103a", "authoredDate": "2026-05-10T10:40:00Z", "committedDate": "2026-05-10T10:41:00Z", "messageHeadline": "test: add billing webhook contract coverage" }
+      ],
+      "files": [
+        { "path": "tests/integration/billing-webhooks.test.ts", "additions": 72, "deletions": 4, "changeType": "ADDED" },
+        { "path": "services/api/src/billing/webhook-fixtures.ts", "additions": 10, "deletions": 4, "changeType": "MODIFIED" },
+        { "path": "packages/generated-client/billing.ts", "additions": 6, "deletions": 2, "changeType": "MODIFIED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-103-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-10T13:30:00Z", "state": "APPROVED", "commitOid": "sample103a", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": { "source": "bundled tutorial sample:review_threads", "totalCount": 0, "nodes": [] },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-10T11:10:00Z", "completedAt": "2026-05-10T11:15:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "unavailable",
+        "totalCount": null,
+        "conclusions": {},
+        "runs": []
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "unavailable", "attempts": 1, "diagnostics": ["Open-time snapshot intentionally omitted from the bundled sample."], "downstreamImpact": "Diff-growth metrics are unavailable for this PR." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available and shows zero threads." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "unavailable", "attempts": 1, "diagnostics": ["Workflow-run history intentionally omitted for this PR."], "downstreamImpact": "Validation-gap metrics preserve unavailable workflow coverage." }
+      }
+    },
+    {
+      "number": 104,
+      "title": "feat: consolidate dispatch settings",
+      "author": { "login": "sample-author-platform", "type": "User" },
+      "url": "https://example.com/pull/104",
+      "state": "MERGED",
+      "createdAt": "2026-05-14T08:00:00Z",
+      "mergedAt": "2026-05-17T19:00:00Z",
+      "updatedAt": "2026-05-17T19:15:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/consolidate-dispatch-settings",
+      "headRefOid": "sample104merge",
+      "additions": 980,
+      "deletions": 420,
+      "changedFiles": 8,
+      "prOpenDiff": { "source": "direct", "confidence": "high", "additions": 260, "deletions": 90, "changedFiles": 6 },
+      "commits": [
+        { "oid": "sample104a", "authoredDate": "2026-05-14T07:45:00Z", "committedDate": "2026-05-14T07:46:00Z", "messageHeadline": "feat: consolidate dispatch settings" },
+        { "oid": "sample104b", "authoredDate": "2026-05-15T10:20:00Z", "committedDate": "2026-05-15T10:22:00Z", "messageHeadline": "fix: split overloaded settings model" },
+        { "oid": "sample104c", "authoredDate": "2026-05-16T16:30:00Z", "committedDate": "2026-05-16T16:31:00Z", "messageHeadline": "test: cover settings migration" },
+        { "oid": "sample104d", "authoredDate": "2026-05-17T13:00:00Z", "committedDate": "2026-05-17T13:02:00Z", "messageHeadline": "ci: repair migration fixture" }
+      ],
+      "files": [
+        { "path": "apps/web/src/settings/DispatchSettingsPage.tsx", "additions": 210, "deletions": 90, "changeType": "MODIFIED" },
+        { "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "additions": 180, "deletions": 70, "changeType": "ADDED" },
+        { "path": "services/api/src/settings/dispatch-settings.ts", "additions": 190, "deletions": 88, "changeType": "MODIFIED" },
+        { "path": "workers/dispatch/settings-sync.ts", "additions": 150, "deletions": 64, "changeType": "ADDED" },
+        { "path": "tests/integration/dispatch-settings.test.ts", "additions": 120, "deletions": 30, "changeType": "ADDED" },
+        { "path": ".github/workflows/dispatch-settings.yml", "additions": 62, "deletions": 20, "changeType": "ADDED" },
+        { "path": "docs/initiatives/dispatch-settings/prd.md", "additions": 48, "deletions": 22, "changeType": "MODIFIED" },
+        { "path": "packages/generated-client/settings.ts", "additions": 20, "deletions": 36, "changeType": "MODIFIED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-104-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-14T16:00:00Z", "state": "CHANGES_REQUESTED", "commitOid": "sample104a", "generatedCommentCount": 0, "failedAttempt": true },
+        { "id": "sample-review-104-b", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-15T14:00:00Z", "state": "CHANGES_REQUESTED", "commitOid": "sample104b", "generatedCommentCount": 0, "failedAttempt": true },
+        { "id": "sample-review-104-c", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-16T18:30:00Z", "state": "COMMENTED", "commitOid": "sample104c", "generatedCommentCount": 0, "failedAttempt": false },
+        { "id": "sample-review-104-d", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-17T17:45:00Z", "state": "APPROVED", "commitOid": "sample104d", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": {
+        "source": "bundled tutorial sample:review_threads",
+        "totalCount": 3,
+        "nodes": [
+          { "id": "sample-thread-104-a", "isResolved": true, "isOutdated": true, "path": "services/api/src/settings/dispatch-settings.ts", "line": 65, "comments": [
+            { "databaseId": "sample-comment-104-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "path": "services/api/src/settings/dispatch-settings.ts", "line": 65, "originalLine": 65, "createdAt": "2026-05-14T16:02:00Z", "updatedAt": "2026-05-14T16:02:00Z", "url": "https://example.com/pull/104#discussion-sample-104-a" },
+            { "databaseId": "sample-comment-104-b", "author": { "login": "sample-author-platform", "type": "User" }, "path": "services/api/src/settings/dispatch-settings.ts", "line": 65, "originalLine": 65, "createdAt": "2026-05-15T10:24:00Z", "updatedAt": "2026-05-15T10:24:00Z", "url": "https://example.com/pull/104#discussion-sample-104-b" }
+          ] },
+          { "id": "sample-thread-104-b", "isResolved": true, "isOutdated": false, "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "line": 112, "comments": [
+            { "databaseId": "sample-comment-104-c", "author": { "login": "sample-reviewer-b", "type": "User" }, "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "line": 112, "originalLine": 112, "createdAt": "2026-05-15T14:05:00Z", "updatedAt": "2026-05-15T14:05:00Z", "url": "https://example.com/pull/104#discussion-sample-104-c" },
+            { "databaseId": "sample-comment-104-d", "author": { "login": "sample-author-platform", "type": "User" }, "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "line": 112, "originalLine": 112, "createdAt": "2026-05-16T16:40:00Z", "updatedAt": "2026-05-16T16:40:00Z", "url": "https://example.com/pull/104#discussion-sample-104-d" }
+          ] },
+          { "id": "sample-thread-104-c", "isResolved": false, "isOutdated": false, "path": ".github/workflows/dispatch-settings.yml", "line": 18, "comments": [
+            { "databaseId": "sample-comment-104-e", "author": { "login": "sample-ci-bot", "type": "Bot" }, "path": ".github/workflows/dispatch-settings.yml", "line": 18, "originalLine": 18, "createdAt": "2026-05-17T13:10:00Z", "updatedAt": "2026-05-17T13:10:00Z", "url": "https://example.com/pull/104#discussion-sample-104-e" }
+          ] }
+        ]
+      },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "FAILURE", "startedAt": "2026-05-14T08:10:00Z", "completedAt": "2026-05-14T08:16:00Z" },
+        { "__typename": "CheckRun", "name": "integration", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "FAILURE", "startedAt": "2026-05-14T08:12:00Z", "completedAt": "2026-05-14T08:28:00Z" },
+        { "__typename": "CheckRun", "name": "migration", "context": null, "workflowName": "Migration checks", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-17T13:10:00Z", "completedAt": "2026-05-17T13:24:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "bundled tutorial sample:workflow_runs",
+        "totalCount": 4,
+        "conclusions": { "success": 1, "failure": 2, "cancelled": 1 },
+        "runs": [
+          { "id": "sample-run-104-a", "name": "CI", "workflowName": "CI", "headSha": "sample104a", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "failure", "createdAt": "2026-05-14T08:10:00Z", "updatedAt": "2026-05-14T08:28:00Z", "runStartedAt": "2026-05-14T08:12:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-a" },
+          { "id": "sample-run-104-b", "name": "CI", "workflowName": "CI", "headSha": "sample104b", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "failure", "createdAt": "2026-05-15T10:30:00Z", "updatedAt": "2026-05-15T10:48:00Z", "runStartedAt": "2026-05-15T10:31:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-b" },
+          { "id": "sample-run-104-c", "name": "CI", "workflowName": "CI", "headSha": "sample104c", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "cancelled", "createdAt": "2026-05-16T16:36:00Z", "updatedAt": "2026-05-16T16:39:00Z", "runStartedAt": "2026-05-16T16:37:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-c" },
+          { "id": "sample-run-104-d", "name": "Migration checks", "workflowName": "Migration checks", "headSha": "sample104d", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "success", "createdAt": "2026-05-17T13:10:00Z", "updatedAt": "2026-05-17T13:24:00Z", "runStartedAt": "2026-05-17T13:11:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-d" }
+        ]
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Diff-growth metrics can compare open and merge sizes." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "partial", "attempts": 1, "diagnostics": ["One cancelled run is included to demonstrate validation caveats."], "downstreamImpact": "Validation-gap metrics include observed failed and cancelled workflow runs." }
+      }
+    }
+  ],
+  "raw": {
+    "sample": {
+      "description": "Fictional tutorial data for Delivery Friction Analyzer.",
+      "containsPrivateData": false
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.16.3",
+  "version": "0.18.0",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "schemas",
+    "examples/tutorial",
     "docs/contracts",
     "docs/reference",
     "fixtures/github/mcp-writing/profile.json",

package/release-log.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+### 2026-06-27 — Tutorial Sample Bundle
+
+- What changed: Added the packaged tutorial sample source bundle, educational sample profile, and generated-aligned report excerpt for a fully synthetic repository.
+- Why it matters: Maintainers can review and ship a public-safe sample report experience without relying on private repository access or live GitHub data.
+- Who is affected: Maintainers preparing the tutorial sample experience and future users who inspect the bundled sample artifacts after sample CLI wiring lands.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/61
+
+### 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."]
       : []),