delivery-friction-analyzer 0.16.2 → 0.17.0

package/README.md

@@ -17,40 +17,40 @@ 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
 
-### Try the sample target
+### Guided setup
 
-From this repository, install dependencies and run the analyzer against the sample validation target:
+From this repository, install dependencies and let interactive setup create or confirm the repository profile for a GitHub repository you want to measure:
 
 ```sh
 npm install
 npm run analyze:github -- \
-  --repo hannasdev/mcp-writing \
+  --repo owner/name \
   --limit 30 \
-  --profile fixtures/github/mcp-writing/profile.json \
-  --out reports/mcp-writing
+  --profile profiles/owner-name.json \
+  --out reports/owner-name \
+  --interactive \
+  --dry-run
 ```
 
-Open `reports/mcp-writing/friction-report.md` first. It is the main human-readable report. Use the JSON and CSV files when you want to audit a finding, compare PRs, or build follow-up analysis.
+If the profile path does not exist, interactive setup can create a minimal `repository-profile.v1` profile. `--dry-run` validates repository access, profile JSON, output directory writability, and a small sample of GitHub API coverage without writing the full report bundle. When the profile looks right, rerun the command without `--dry-run`.
 
-### Analyze your own repository
+### Run the analysis
 
-For a guided first run in a local terminal, let interactive setup create or confirm the repository profile:
+After you have a repository profile, run the analyzer against the target repository:
 
 ```sh
 npm run analyze:github -- \
-  --interactive \
   --repo owner/name \
   --limit 30 \
   --profile profiles/owner-name.json \
-  --out reports/owner-name \
-  --dry-run
+  --out reports/owner-name
 ```
 
-If the profile path does not exist, interactive setup can create a minimal `repository-profile.v1` profile. `--dry-run` validates repository access, profile JSON, output directory writability, and a small sample of GitHub API coverage without writing the full report bundle. When the profile looks right, rerun the command without `--dry-run`.
+Open `reports/owner-name/friction-report.md` first. It is the main human-readable report. Use the JSON and CSV files when you want to audit a finding, compare PRs, or build follow-up analysis.
 
 To run the CLI from another project with the npm package, pass the same choices as explicit flags:
 
@@ -78,7 +78,7 @@ Profiles can define:
 
 For a new repository, the easiest path is the guided `--interactive --dry-run` command in Quickstart. If the profile path does not exist, interactive setup asks whether to create it, then writes a minimal `repository-profile.v1` profile with user-provided workflow context and optional release PR title rules. It may create the output directory and briefly write then remove a temporary probe file to confirm writability. When interactive setup saves or generates a profile during a dry run, the completion output prints the saved profile path so you can inspect and edit it before a full run.
 
-Use `fixtures/github/mcp-writing/profile.json` as a starting point when you prefer to copy an existing profile by hand. The full profile format is documented in `docs/reference/repository-profile.md`, and the schema lives at `schemas/repository-profile.schema.json`.
+Use `docs/reference/repository-profile.md` and `schemas/repository-profile.schema.json` when you prefer to create a profile by hand. Existing profiles and fixtures in this repository are internal validation examples; copy them only if their repository-specific assumptions match your target.
 
 ## Outputs
 
@@ -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.
 
@@ -163,7 +163,7 @@ The current product focus is a maintainer workflow:
 
 The product should eventually combine GitHub delivery friction with token and model usage, but GitHub-only analytics remain the active validation surface.
 
-`hannasdev/mcp-writing` remains the first validation target and fixture source, not product-specific scope.
+`hannasdev/mcp-writing` remains an internal validation target and fixture source, not a public tutorial path or product-specific scope.
 
 The existing metrics-summary-only report command remains available for fixture and advanced workflows:
 

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/contracts/target-repository.md

@@ -11,15 +11,15 @@ The local analyzer accepts a target repository and a pull request sample size. T
 - `defaultBranch`: expected default branch for merge-base and branch lookup context.
 - `visibility`: `public`, `private`, or `unknown`.
 - `analysisPullRequestLimit`: latest merged pull request count from 1 to 100, supplied by the live CLI as `--limit`.
-- `isValidationTarget`: optional flag for fixture-source repositories such as `hannasdev/mcp-writing`.
+- `isValidationTarget`: optional metadata flag for internal validation or fixture-source repositories such as `hannasdev/mcp-writing`. It does not bypass target repository validation.
 
 Schema: `schemas/target-repository.schema.json`. Live analysis selection is latest-N merged pull requests, not a rolling day window.
 
 ## Product Repository Separation
 
-The validator rejects a target repository that exactly matches the configured product repository. For this repository, the product repository is `hannasdev/delivery-friction-analyzer`; the first validation target is `hannasdev/mcp-writing`.
+The validator rejects a target repository that exactly matches the configured product repository. For this repository, the product repository is `hannasdev/delivery-friction-analyzer`; `hannasdev/mcp-writing` is an internal validation target and fixture source.
 
-Live GitHub analysis enforces this separation before GitHub collection starts. If `--repo` names this tool's product repository, the command fails before provider calls, tells you to choose the repository you want to measure with `--repo owner/name`, and confirms that no GitHub data was collected. The product repository identity is repo-local implementation configuration, not a public CLI option.
+Live GitHub analysis enforces this separation before GitHub collection starts. If `--repo` names this tool's product repository, the command fails before provider calls, explains that the guard prevents accidental self-analysis during normal live runs rather than protecting already readable GitHub data, tells you to choose the repository you want to measure with `--repo owner/name`, and confirms that no GitHub data was collected. `--validation-target` only marks output metadata and does not bypass this guard. The product repository identity is repo-local implementation configuration, not a public CLI option.
 
 ## Degraded Behavior
 

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

@@ -1,6 +1,6 @@
 # GitHub Data Inventory
 
-Checked against `hannasdev/mcp-writing` on 2026-06-08 with `gh` authenticated as `hannasdev`.
+Internal validation inventory was checked against `hannasdev/mcp-writing` on 2026-06-08 with `gh` authenticated as `hannasdev`. This repository is fixture and calibration context, not the public tutorial target.
 
 ## API Fields
 
@@ -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/release-automation.md

@@ -9,7 +9,7 @@ The npm package allowlist includes:
 - runtime source in `src`;
 - JSON schemas in `schemas`;
 - public contract and reference docs in `docs/contracts` and `docs/reference`;
-- the sample repository profile at `fixtures/github/mcp-writing/profile.json`;
+- the internal validation repository profile at `fixtures/github/mcp-writing/profile.json`;
 - `LICENSE`;
 - `README.md`;
 - `release-log.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.16.2",
+  "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,22 @@
 
 ## 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.
+- Why it matters: First-time users and maintainers get a clearer path for learning the CLI without confusing internal validation history, product-repository guardrails, or validation-target metadata for an override.
+- Who is affected: Users running the CLI for the first time and maintainers reviewing first-run documentation or help text.
+- Action needed: None.
+- PR: #59
+
 ### 2026-06-21 — Done Initiative Hygiene Guard
 
 - What changed: `npm test` now enforces completed initiative documentation hygiene, and `AGENTS.md` documents how shipped, deferred, future-decision, backlog-linked, and intentionally omitted items should be recorded in done initiative docs.

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

@@ -125,7 +125,7 @@ Options:
   --dry-run                 Validate inputs and sample GitHub coverage without writing artifacts.
   --no-dry-run              Disable dry-run mode when a preset enabled it.
   --metadata-only           Alias for --dry-run.
-  --validation-target       Mark the target repository as a validation target in output metadata.
+  --validation-target       Mark output metadata as an internal validation run; does not bypass target validation.
   --no-validation-target    Disable validation-target mode when a preset enabled it.
   --exclude-pr-class <cls>  Exclude a PR class from normalized, metrics, report, methodology, and CSV artifacts. Repeat or comma-separate values.
   --csv                     Enable curated CSV evidence exports when a preset disabled them.
@@ -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/contracts/target-repository.js

@@ -99,5 +99,5 @@ export function productRepositoryTargetError(input) {
   const repository = typeof input?.owner === "string" && typeof input?.name === "string"
     ? `${input.owner}/${input.name}`
     : "the requested repository";
-  return `Cannot analyze ${repository} because it is this tool's product repository, not the target repository to measure. Choose a different repository with --repo owner/name. No GitHub data was collected.`;
+  return `Cannot analyze ${repository} because it is this tool's product repository. The guard prevents accidental self-analysis during normal live runs; it is not a data-security boundary. Choose a different repository with --repo owner/name. No GitHub data was collected.`;
 }

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."]
       : []),