delivery-friction-analyzer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hanna Rosengren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# Delivery Friction Analyzer
+
+Delivery Friction Analyzer is a product concept for measuring where AI-assisted software delivery still wastes time: review loops, CI churn, scope drift, missing validation, and repeated corrective work after a pull request opens.
+
+The core idea is to use GitHub data as the first durable signal. Pull request diffs, review comments by source, check runs, commits, changed-file spread, file roles, and merge timelines can reveal which repositories, modules, and workflow stages create the most back-and-forth before work becomes mergeable.
+
+## Product Direction
+
+Delivery Friction Analyzer is currently a local, GitHub-connected analyzer that produces repository-level friction reports from live pull request data. It is repo-source-agnostic: repository-specific assumptions live in profiles, while generated artifacts preserve source evidence, coverage caveats, and interpretation limits.
+
+`hannasdev/mcp-writing` remains the first validation target and fixture source, not product-specific scope.
+
+The current product wedge is a maintainer workflow:
+
+- collect the latest merged PR sample from a target repository;
+- classify files and PRs through repository profiles;
+- generate Markdown, JSON, methodology, and CSV artifacts;
+- explain review, validation, scope, planning, PR-size, and PR-class friction with traceable evidence;
+- support explicit follow-up filtering when maintainers want to inspect a configured PR population separately.
+
+The report helps answer:
+
+- Where do PRs require the most corrective loops?
+- Which feedback patterns repeat across PRs?
+- Which issues are preventable with better local checks, repo-specific AI instructions, skills, hooks, or smaller delivery slices?
+- Which changes create the largest gap between the PR opened state and the merged state?
+- Which changed files are part of the repository's configured product surface versus tests, docs, generated artifacts, release notes, marketing surfaces, or other support surfaces?
+
+The product should eventually combine GitHub delivery friction with token and model usage, but GitHub-only analytics remain the active validation surface.
+
+## Local GitHub Analysis
+
+Run the live analyzer with local `gh` credentials:
+
+```sh
+npm run analyze:github -- \
+  --repo hannasdev/mcp-writing \
+  --limit 30 \
+  --profile fixtures/github/mcp-writing/profile.json \
+  --out reports/mcp-writing
+```
+
+After installing from npm, the same analyzer is available as a CLI:
+
+```sh
+npx delivery-friction-analyzer \
+  --repo hannasdev/mcp-writing \
+  --limit 30 \
+  --profile path/to/repository-profile.json \
+  --out reports/mcp-writing
+```
+
+The npm CLI still expects a local repository profile JSON. Use the sample profile from this repository as a starting point, then save a copy for the repository you want to analyze.
+
+The command writes:
+
+- `source-bundle.json`
+- `normalized.json`
+- `metrics-summary.json`
+- `friction-report.json`
+- `friction-report.md`
+- `methodology.md`
+- `pr-metrics.csv`
+- `bottleneck-examples.csv`
+- `comment-sources.csv`
+- `collection-coverage.csv`
+
+Use `--dry-run` or `--metadata-only` to validate repository access, profile JSON, output directory writability, and sampled API coverage without writing full report artifacts. Use `--no-csv` when you want the Markdown, JSON, source, normalized, metrics, and methodology artifacts without spreadsheet-friendly CSV exports. Use `--exclude-pr-class <class>` to explicitly remove a configured PR class from downstream normalized, metrics, report, methodology, and CSV artifacts; `source-bundle.json` still preserves the full collected sample for auditability.
+
+Successful runs print a concise completion message with `friction-report.md` first, followed by the key supporting artifacts and collection coverage status. Use `--json` when automation needs the full machine-readable completion receipt on stdout.
+
+Read `friction-report.md` first, then inspect `methodology.md`, the CSV exports, `friction-report.json`, and `source-bundle.json` when a bottleneck looks surprising. Each ranked bottleneck example includes the workflow-run source, workflow-run conclusions, review-thread source, comment-source breakdown, and a dominance note when one PR contributes most of the displayed signal.
+
+Ranked bottlenecks are ordered by their strongest displayed representative score, not by an opaque composite priority score. PR size columns show final/current additions, deletions, changed files, and changed lines so maintainers can compare size against review, validation, and planning signals.
+
+Known MVP interpretation limits:
+
+- PR-open diff growth is unavailable unless an open-time snapshot or reconstruction exists; the local historical collector does not infer it from merge-time diff data.
+- Workflow runs are collected from branch-based pull-request Actions history, which can be unavailable or partial for deleted, renamed, reused, or inaccessible branches.
+- Review-thread counts depend on GraphQL review-thread coverage; unavailable thread access is reported instead of silently treated as zero review churn.
+- A single PR or PR class, such as release, dependency, bot-driven, or unusually broad feature work, can dominate validation or review findings. Treat PR and class dominance notes as prompts to inspect the raw evidence before generalizing; use `--exclude-pr-class` only when you intentionally want a filtered follow-up view.
+
+Generated artifacts may contain repository names, PR URLs, PR titles, file paths, comment metadata, curated CSV evidence, and coverage diagnostics. Treat source bundles, normalized data, metrics summaries, reports, methodology, and CSV exports as local/private unless you intentionally review and share them.
+
+The existing metrics-summary-only report command remains available for fixture and advanced workflows:
+
+```sh
+npm run report:fixture
+```
+
+Maintainer release automation is documented in `docs/reference/release-automation.md`.

package/docs/contracts/friction-metrics.md

@@ -0,0 +1,52 @@
+# Friction Metrics Contract
+
+Milestone 2 introduces `friction-metrics.v1`, a deterministic metrics summary computed from normalized fixture data. The metrics layer does not fetch GitHub data and does not generate the final human-facing report.
+
+## Summary Shape
+
+- `metricVersion`: formula version for every repository and PR summary.
+- `targetRepository`: normalized target repository input.
+- `analysisFilter`: optional metadata for explicit analysis filters, such as excluded PR classes and before/after PR counts.
+- `totals`: repository-level counts for pull requests, changed lines, non-generated changed lines, review comments, review threads, failed checks, and cancelled workflow runs.
+- `rankings`: PR rankings by review churn, changed-file spread, validation gap, planning gap, review surprise, and fix amplification.
+- `pullRequests`: per-PR metrics with PR class evidence, diff, file spread, review comments, review-thread churn, review decision evidence, CI, lifecycle, iteration, coverage, and transparent component metrics.
+
+## Component Metrics
+
+Every score-like component exposes `formulaVersion`, `value`, and `inputs`.
+
+- `commentSourceDensity`: comment counts and per-100-changed-line density by source.
+- `functionalSurfaceDensity`: functional surface count and changed lines by surface.
+- `iterationDrag`: commits after first review, review threads, and failed review attempts.
+- `diffGrowthRatio`: PR-open to merge growth when PR-open diff data is direct or reconstructed; otherwise unavailable.
+- `changedFileSpread`: core file count plus directory and functional-surface spread.
+- `validationGapScore`: failed check runs, failed workflow runs, and cancelled workflow runs.
+- `planningGapScore`: deterministic signal from repository-profile planning-doc changes.
+- `reviewSurpriseScore`: deterministic functional-surface spread signal without title/body NLP.
+- `fixAmplification`: commits after first review plus explicit diff-growth availability.
+
+## Classification And Coverage
+
+Observed GitHub data remains separate from inferred or configured classifications:
+
+- file paths and changed lines come from normalized GitHub payloads;
+- file categories, roles, functional surfaces, and generated flags come from repository profile or fallback rules;
+- PR class, PR class source, and PR class rule ID come from repository profile rules or fallback rules;
+- `files.classificationSources` counts the classification source used by each changed file;
+- PR-open diff growth and workflow-run metrics carry coverage status when source data is unavailable;
+- review decision evidence carries the normalized review-event source label so clean human approval can be distinguished from unavailable review evidence and from observed absence of human review.
+
+Generated or low-signal roles are not hidden. They are counted separately, excluded from core file metrics, and down-weighted in `weightedChangedLines`.
+
+When an explicit PR class filter is applied, metrics are computed from the filtered normalized PR set. Rankings, totals, and CSV evidence should describe that filtered sample, while `analysisFilter` records the excluded classes and the original collected count for auditability.
+
+## Formula Constants
+
+`friction-metrics.v1` exposes formula constants in code and in metric output where they affect file-spread calculations:
+
+- Low-signal roles use `lowSignalRoleWeight: 0.25` in `weightedChangedLines`.
+- Generated files and `generated_or_vendored` files contribute `0` to `weightedChangedLines`.
+- `smallDiffWideSpread` is true when non-generated core files have `coreChangedLines > 0`, `coreChangedLines <= 600`, and `coreFiles >= 3`.
+- Core roles for spread calculations are `core_product_code` and `product_ui`.
+
+Validation gap metrics treat GitHub check-run failures and workflow interruptions separately. Failure-like check conclusions include `failure`, `failed`, `timed_failure`, `startup_failure`, `action_required`, `timed_out`, `stale`, `error`, `cancelled`, and `canceled`. Workflow-run `cancelled` / `canceled` conclusions are counted as cancelled workflow runs rather than double-counted as failed workflow runs.

package/docs/contracts/friction-report.md

@@ -0,0 +1,131 @@
+# Friction Report Contract
+
+Milestone 3 introduces `friction-report.v1`, a deterministic report generated from a `friction-metrics.v1` repository metrics summary. The report layer does not fetch GitHub data, mutate repositories, rank individuals, or depend on services beyond the data collection path that produced the metrics summary.
+
+## Outputs
+
+- JSON report artifacts for contract tests and future UI work.
+- Markdown report artifacts for maintainer review.
+- A detailed `methodology.md` artifact for full live analysis runs.
+- Curated CSV evidence exports for full live analysis runs unless `--no-csv` is passed:
+  - `pr-metrics.csv`
+  - `bottleneck-examples.csv`
+  - `comment-sources.csv`
+  - `collection-coverage.csv`
+
+Local artifact generation is available from an existing metrics summary:
+
+```sh
+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.
+
+## Report Shape
+
+- `reportVersion`: report contract version.
+- `metricVersion`: source metrics contract version.
+- `targetRepository`: analyzed repository identity; live analysis sample size is encoded as `targetRepository.analysisPullRequestLimit` from collection metadata.
+- `analysisFilter`: optional metadata for explicit filters applied before metrics computation, including excluded PR classes and before/after PR counts.
+- `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.
+- `surfaces`: core, low-signal, generated, support-surface, role, and functional-surface breakdowns.
+- `prClasses`: PR class distribution for the analyzed sample, including PR counts, changed lines, share of PRs, and classification source counts by class.
+- `bottlenecks`: ranked friction patterns with observed data, inferred diagnosis, and suggested action kept as separate fields.
+- `bottlenecks[].observedData[]`: representative PR examples with PR identity, score/value, PR class evidence, final/current additions, deletions, changed-file count, and changed-line count.
+- `bottlenecks[].observedData[].validationEvidence`: workflow-run source label, workflow-run coverage, workflow-run conclusions, failed check-run count, failed workflow-run count, and cancelled workflow-run count for representative PR examples.
+- `bottlenecks[].observedData[].reviewEvidence`: review-thread source label, thread counts, resolution/outdated counts, review decision label/source, human reviewer count, human approval / changes-requested booleans, comment-source breakdown, bot comment count, human reviewer comment count, and author reply count for representative PR examples.
+- `bottlenecks[].dominance`: whether the displayed examples are dominated by a single PR, including the top PR number, share of displayed signal, and a human-readable interpretation note.
+- `bottlenecks[].classDominance`: whether the displayed examples are dominated by one PR class, including the dominant class, share, contribution basis, sample count, and a caveated interpretation note.
+- `sharedSignals`: report-layer interpretation groups for displayed bottlenecks that share a ranking key or the same representative PR evidence. These groups do not change bottleneck scores, ranking, or recommendation categories.
+- `sensitivity`: optional robustness summaries for displayed bottlenecks dominated by one PR. Each summary names the excluded PR, affected bottlenecks, baseline top bottlenecks, top bottlenecks without that PR, and an interpretation note.
+- `recommendationCategories`: supported recommendation categories and how many bottlenecks triggered each one.
+- `guardrails`: machine-readable checks that the report avoids individual ranking, separates evidence from inference, and does not use an opaque composite score.
+- `followUp`: non-automated future work suggested by the report.
+
+Bottlenecks are ordered by their strongest observed representative metric value, with stable category order used only to break ties. Final/current PR size fields are context for comparing size against friction signals; they only affect ordering for metric families that explicitly measure changed-file spread.
+
+## Markdown Output
+
+The Markdown renderer presents the same report data for human review:
+
+- executive summary totals in a table;
+- explicit analysis filter labels when downstream artifacts were generated from a filtered PR class sample;
+- a short "How To Read This Report" guide that distinguishes observed evidence, interpretation, recommendations, and caveats;
+- evidence-quality and coverage tables before detailed recommendations;
+- key findings that highlight top bottlenecks, strongest displayed signal, outlier caveats, PR class caveats, and coverage caveats;
+- a PR class context table that shows analyzed PR counts, changed lines, sample share, and classification sources by class;
+- a top-level shared-signal interpretation callout when multiple displayed bottlenecks share a ranking key or representative PR evidence;
+- outlier and sensitivity analysis when displayed examples are dominated by one PR;
+- a prioritization explanation that describes strongest-signal ordering and how PR size is used as context;
+- ranked bottlenecks with representative PR examples rendered as compact PR-size tables;
+- validation, review, and source-label evidence for each representative PR example rendered as plain Markdown detail lists;
+- separately labeled inferred diagnosis, suggested action, and confidence/caveat blocks for each bottleneck;
+- shared-evidence notes when multiple recommendation categories use the same representative PR set;
+- recommendation-category, comment-source, and core/support-surface tables;
+- a concise methodology summary;
+- a reference to the detailed `methodology.md` artifact generated by full live analysis;
+- guardrails, follow-up, and artifact-sensitivity guidance.
+
+Markdown output should not include individual contributor or reviewer rankings.
+
+## Recommendation Boundaries
+
+Recommendations are inferred from transparent component metrics and representative PR examples. They suggest workflow interventions such as readiness gates, preflight scripts, smaller milestones, planning artifacts, or scope control. They do not automate repository changes.
+
+The M3 report contract supports these recommendation categories:
+
+- hooks;
+- preflight scripts;
+- repo-specific AI skills or instructions;
+- PR readiness gates;
+- smaller milestones;
+- planning artifacts;
+- test infrastructure.
+
+## Coverage And Confidence
+
+Reports must label unavailable or partial GitHub data instead of inferring unavailable values from merge-time data. PR-open diff growth remains unavailable unless direct or reconstructed counts exist. Workflow coverage and review-thread sources are summarized separately.
+
+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.
+
+Shared-signal groups are interpretation support only. The report may group bottlenecks by the metric ranking key they use or by identical displayed representative PR sets, but it must still preserve each bottleneck and its recommendation category so readers can distinguish one underlying signal from different possible actions.
+
+PR class context and dominance notes are interpretation support only. They must preserve baseline ranking, avoid automatic filtering, and caveat class dominance for small class sample sizes.
+
+Sensitivity summaries are robustness context only. They must preserve the baseline ranking, avoid implying that the analyzer discarded inconvenient data, and label excluded-PR summaries as "without this PR" comparisons rather than replacement truth.
+
+## Methodology Artifact
+
+Full live analysis writes `methodology.md` as a hybrid artifact: stable explanatory text plus run-specific facts. It should include:
+
+- target repository and report/metric versions;
+- profile path when available;
+- requested and collected PR counts;
+- collection coverage status and API-family diagnostics;
+- scoring, ranking, dominance, sensitivity, and limitation explanations;
+- generated artifact names and artifact-sensitivity guidance.
+
+The methodology artifact should stay aligned with this contract and the Markdown methodology summary, but it may be more detailed than the main report.
+
+When PR class filtering is applied, `source-bundle.json` remains the full collected sample, while `normalized.json`, `metrics-summary.json`, `friction-report.json`, `friction-report.md`, `methodology.md`, and CSV exports describe the filtered sample. The methodology and CLI completion output must name the excluded PR classes and show the filtered PR count. If filtering excludes every collected PR, the analysis must fail without writing complete-looking empty reports.
+
+## CSV Evidence Exports
+
+Full live analysis writes curated CSV exports by default. `--no-csv` suppresses CSV generation while preserving Markdown, JSON, source bundle, normalized data, metrics summary, and methodology artifacts.
+
+CSV exports are supporting evidence trails, not replacements for JSON artifacts. They should be deterministic, properly escaped, mitigate formula-like text cells for spreadsheet inspection, and avoid raw comments or logs.
+
+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.
+
+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.
+
+## Guardrails
+
+Reports present repository-level patterns, representative PR examples, and file surface evidence. They must keep observed data, inferred diagnosis, and suggested action distinct, and they must not rank contributors or reviewers.

package/docs/contracts/normalized-entities.md

@@ -0,0 +1,39 @@
+# Normalized Entity Contract
+
+Schema: `schemas/normalized-entities.schema.json`.
+
+Milestone 1 defines the first normalized fixture shape. It is intentionally limited to source inventory and classification transparency, not friction scoring.
+
+## Entities
+
+- `TargetRepository`: owner/name/default branch/visibility/window for the repository being analyzed.
+- `AnalysisFilter`: optional metadata for downstream analysis filters applied after collection and normalization. When present, it records excluded PR classes, the original collected PR count, and the filtered PR count.
+- `RepositoryLanguageDistribution`: byte counts from `GET /repos/{owner}/{repo}/languages`, stored as context only.
+- `PullRequest`: source IDs, author login when known, URL, state, PR class evidence, lifecycle timestamps, final diff shape, PR-open diff source confidence, optional PR-open additions/deletions/changed-file counts when direct or reconstructed data is available, files, reviews, review decision summary, review threads, comments, checks, and workflow-run coverage.
+- `PrClassSummary`: profile-driven PR class, classification source, and winning rule ID. Unmatched PRs use `class: "unknown"`, `classificationSource: "fallback_rule"`, and `ruleId: null`.
+- `Commit`: commit OID, authored timestamp, committed timestamp when present, and message headline.
+- `ChangedFile`: path, additions, deletions, change type, category, role, functional surface, generated flag, and classification source.
+- `Review`: review attempt with author source, submitted timestamp, commit OID, generated comment count when known, and failed-attempt marker.
+- `ReviewDecisionSummary`: coarse human review state derived from observed review events, with human approval / changes-requested booleans, unique human reviewer count, and source label. `none` means review events were collected and no human review events were observed; `unavailable` means review-event coverage cannot support an absence claim.
+- `ReviewThread`: GraphQL thread count, resolved count, outdated count, and source coverage.
+- `ReviewCommentSummary`: source-grouped comment counts, separating PR-author replies from human reviewer feedback when author context is available.
+- `CheckRun`: final check/status rollup entries.
+- `WorkflowRunSummary`: pull-request workflow-run coverage by conclusion when branch history is available.
+
+## Source Labels
+
+Normalized data must preserve whether a value came from a public API, GraphQL thread query, repository profile rule, fallback rule, internal UI partial, or unavailable coverage. Later metric and report stages should use those source labels before making confidence claims.
+
+## Analysis Filters
+
+`source-bundle.json` remains the full collected sample. When a local analysis excludes one or more PR classes, `normalized.json` contains the filtered PR set and an `analysisFilter` object:
+
+- `excludedPrClasses`: class names explicitly excluded by the user;
+- `originalPullRequests`: collected PR count before filtering;
+- `filteredPullRequests`: PR count after filtering.
+
+Filtering must be explicit and must fail rather than writing complete-looking empty artifacts when every collected PR is excluded.
+
+## PR-Open Diff Counts
+
+`prOpenDiff` always records `source` and `confidence`. When `source` is `direct` or `reconstructed`, normalized data may also include non-negative `additions`, `deletions`, and `changedFiles` counts so the metrics engine can compute open-to-merge diff growth. When those counts are missing or the source is `snapshot_only` / `unavailable`, diff-growth metrics must remain explicitly unavailable rather than inferred from merge-time data.

package/docs/contracts/target-repository.md

@@ -0,0 +1,24 @@
+# Target Repository Input Contract
+
+The product repository is where the analyzer runs. The target repository is the repository being analyzed. They must be modeled separately so the analyzer does not accidentally treat its own repository history as validation data.
+
+## Input And Selection
+
+The local analyzer accepts a target repository and a pull request sample size. Target repository identity and sample selection are separate concepts:
+
+- `owner`: GitHub owner or organization.
+- `name`: GitHub repository name.
+- `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`.
+
+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`.
+
+## Degraded Behavior
+
+If a target repository is private or the token lacks access, the analyzer should report coverage as unavailable or partial instead of silently emitting complete-looking metrics. Missing `defaultBranch` or malformed owner/name input is a hard contract error.

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

@@ -0,0 +1,25 @@
+# GitHub Access And Coverage Matrix
+
+The MVP runs locally with the user's GitHub credentials. Reports must expose unavailable or partial data instead of implying complete coverage.
+
+| API Family | Auth Mode | Minimum Public Repo Access | Minimum Private Repo Access | Used For | Degraded Output |
+| --- | --- | --- | --- | --- | --- |
+| REST repository metadata | unauthenticated or token | public read | `repo` or fine-grained metadata read | repository visibility, default branch confirmation | mark repository metadata partial |
+| REST languages | unauthenticated or token | public read | `repo` or fine-grained contents/metadata read | language byte distribution context | omit language context; do not infer file role from language |
+| Pull request metadata | `gh` token / GraphQL-backed PR fields | public read | `repo` or pull request read | lifecycle, final diff shape, files, commits, reviews | mark PR inventory partial |
+| REST review comments | token recommended | public read | `repo` or pull request read | individual review comments and comment paths | source breakdown based only on reviews if unavailable |
+| GraphQL review threads | token | public read | `repo` or pull request read | thread count, resolved state, outdated state | thread metrics unavailable; comment count can remain REST-only |
+| Actions workflow runs | token | public Actions read when enabled | `repo` and Actions read | CI churn and rerun history | final check rollup only; mark churn history partial |
+| Check runs per commit | token | public checks read when enabled | `repo` or checks read | check detail by commit SHA | check detail unavailable; retain final status rollup |
+| GitHub UI partials | authenticated browser/session or HTTP request | repo page access | repo page access | experimental Copilot severity source | severity source `unavailable` unless explicitly enabled |
+
+## Rate Limits And Missing Scopes
+
+The analyzer should record:
+
+- API family attempted.
+- Coverage status: `available`, `partial`, `unavailable`, or `rate_limited`.
+- Required scope or permission when known.
+- Impact on downstream metrics.
+
+Missing coverage must flow into report metadata. For example, unavailable GraphQL review threads should disable thread-resolution metrics while preserving REST review-comment counts.

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

@@ -0,0 +1,55 @@
+# GitHub Data Inventory
+
+Checked against `hannasdev/mcp-writing` on 2026-06-08 with `gh` authenticated as `hannasdev`.
+
+## API Fields
+
+| Area | Fields | Source | Coverage Notes |
+| --- | --- | --- | --- |
+| Target repository | owner, name, default branch, visibility | local target contract plus REST repository metadata | The target repository is separate from the product repository. |
+| Language distribution | language byte counts | `GET /repos/{owner}/{repo}/languages` | Context only; does not determine file role or risk. |
+| Pull request lifecycle | number, title, URL, state, createdAt, mergedAt, updatedAt, baseRefName, headRefName, headRefOid | `gh pr view --json` / GraphQL-backed PR fields | Directly available for current and historical PRs. |
+| Commits | commit OID, authoredDate, committedDate, message headline | `gh pr view --json commits` | Useful for post-open and post-review iteration counts. |
+| Final diff shape | additions, deletions, changedFiles, files path/additions/deletions/changeType | `gh pr view --json additions,deletions,changedFiles,files` | Final/current PR diff is direct. |
+| PR-open diff shape | files/lines at PR open | reconstruction from commits/timeline, or future snapshot | Not directly available from simple PR metadata; record confidence or unavailable. |
+| Reviews and attempts | review ID, author login, state, submittedAt, commit OID, body summary | `gh pr view --json reviews` | Copilot no-new-comment and failed attempts appear as reviews and should be retained. |
+| Review comments | comment ID, author, path, line, timestamps, URL | REST `GET /repos/{owner}/{repo}/pulls/{number}/comments` and GraphQL review threads | REST is good for individual comments; GraphQL is required for thread grouping. Author login is retained so PR-author replies can be separated from human reviewer feedback when known. |
+| Review thread state | totalCount, isResolved, isOutdated, path, line, grouped comments | GraphQL `pullRequest.reviewThreads` | Required for thread-aware review analytics. |
+| Check runs | name, workflowName, status, conclusion, startedAt, completedAt | `gh pr view --json statusCheckRollup` and check-runs per commit | Final rollup only reflects the current/final head. |
+| Workflow-run churn | run id, workflow name, head SHA, conclusion, status, run timestamps | REST `GET /repos/{owner}/{repo}/actions/runs?branch=...&event=pull_request` | Branch lookup may degrade after branch deletion or rename. |
+| Copilot review effort | review-level effort setting | public docs / currently not observed in checked PR payloads | Store as unavailable or fallback until a stable API path is confirmed. |
+| Copilot comment severity | high/medium/low UI label | GitHub UI partial if experimental extractor is enabled | Not observed in checked REST or GraphQL payloads; label as `internal_ui_partial`, `inferred`, `unavailable`, or excluded. |
+| Vendor confidence / visibility | confidence, hidden-comment state, hide-severity-label state | GitHub UI partial if experimental extractor is enabled | Not observed in checked REST or GraphQL payloads. For MVP scoring, treat as `unavailable` or `internal_ui_partial`; do not infer correctness from it. |
+
+## Diff Snapshot Support
+
+PR-open diff support must be recorded as one of:
+
+- `direct`: observed from a stable API payload.
+- `reconstructed`: derived from commits/timeline with a confidence label.
+- `snapshot_only`: requires a future GitHub App or webhook snapshot captured at PR open.
+- `unavailable`: not computed for the current run.
+
+The Milestone 1 fixtures mark PR-open diff data as `unavailable`; final diff data is direct.
+
+## Vendor Signal Support
+
+Copilot review effort, Copilot comment severity, and vendor confidence/visibility are separate fields. The checked PR metadata did not expose review effort as structured data. The checked REST and GraphQL review-comment payloads did not expose comment-level severity, confidence, or hidden-comment visibility state. Prior validation found severity and `hideSeverityLabel` in an undocumented GitHub UI partial. The MVP should not use those unstable labels as primary trend metrics or correctness signals.
+
+Availability decision:
+
+- Review effort: `unavailable` in checked PR payloads unless a stable public API source is later confirmed.
+- Comment severity: `unavailable` through checked public APIs; `internal_ui_partial` only if an explicit experimental extractor is enabled.
+- Confidence / visibility: `unavailable` through checked public APIs; `internal_ui_partial` only if an explicit experimental extractor is enabled; excluded from MVP scoring.
+
+## Source Commands Used For Fixtures
+
+- `gh api repos/hannasdev/mcp-writing/languages`
+- `gh pr view 223 --repo hannasdev/mcp-writing --json ...`
+- `gh pr view 221 --repo hannasdev/mcp-writing --json ...`
+- `gh pr view 239 --repo hannasdev/mcp-writing --json ...`
+- `gh api repos/hannasdev/mcp-writing/pulls/239/comments`
+- `gh api graphql` querying `repository.pullRequest.reviewThreads`
+- `gh api 'repos/hannasdev/mcp-writing/actions/runs?branch=feat/extended-vocabulary-resolution&event=pull_request&per_page=30'`
+
+Fixtures store compact, redacted source-shaped data rather than full raw payloads.

package/docs/reference/release-automation.md

@@ -0,0 +1,65 @@
+# Release Automation
+
+Delivery Friction Analyzer publishes the unbundled source package to npm. This reference is for maintainers and agents preparing release-related changes; the README stays focused on CLI usage.
+
+## Package Artifact
+
+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`;
+- `LICENSE`;
+- `README.md`;
+- `release-log.md`.
+
+Generated reports, tests, initiative docs, and calibration fixtures are intentionally excluded from the npm artifact.
+
+## CI
+
+The CI workflow runs on pull requests and pushes to `main`.
+
+It validates:
+
+- `npm ci`;
+- `npm test`;
+- `npm pack --dry-run`.
+
+CI runs on Node 20 and Node 24 so the advertised `engines.node >=20` floor is exercised before release.
+
+## Release Workflow
+
+The release workflow runs on pushes to `main` and skips commits whose subject starts with `Release `.
+
+It:
+
+- validates that `RELEASE_DEPLOY_KEY` is configured;
+- checks out the repository with full tag history and the deploy key;
+- validates that the package version is not behind the latest `v*` tag;
+- determines the next semantic version from conventional commits since the latest `v*` tag;
+- runs tests;
+- bumps `package.json` and `package-lock.json`;
+- commits the version bump;
+- creates a matching `vX.Y.Z` tag;
+- pushes the release commit and tag atomically;
+- creates a GitHub release with generated notes.
+
+`RELEASE_DEPLOY_KEY` must contain a private SSH key whose public key is configured as a write-enabled repository deploy key.
+
+## Publish Workflow
+
+The publish workflow runs on `v*.*.*` tags and can also be started manually.
+
+Tag-triggered runs:
+
+- verify that the package is not private;
+- verify that the Git tag matches the package version;
+- infer `next` for prerelease versions and `latest` for stable versions;
+- skip versions already published on npm;
+- run `npm pack --dry-run`;
+- publish the package to npm.
+
+Manual `workflow_dispatch` runs are dry-run only. They use the selected npm dist-tag and execute `npm publish --dry-run`; real publishes require pushing a matching version tag.
+
+Configure npm trusted publishing for this repository before relying on tag-triggered publish.

package/docs/reference/repository-profile.md

@@ -0,0 +1,55 @@
+# Repository Profile Format
+
+Repository profiles map paths to file categories, file roles, and functional surfaces before metrics are computed. They can also classify pull requests into repository-specific classes such as `release`, `dependency`, or `unknown`. The same language or PR title pattern can mean different product surfaces in different repositories, so language distribution and PR class assumptions stay in profile data.
+
+Schema: `schemas/repository-profile.schema.json`.
+
+## Categories
+
+- `code`
+- `tests`
+- `docs`
+- `config`
+- `generated`
+- `infrastructure`
+- `unknown`
+
+## Roles
+
+- `core_product_code`
+- `product_ui`
+- `tests`
+- `generated_docs`
+- `release_notes`
+- `planning_docs`
+- `marketing_site`
+- `config`
+- `infrastructure`
+- `fixtures`
+- `generated_or_vendored`
+- `unknown`
+
+## Rule Matching
+
+Rules are evaluated in order and can match by `exact`, `prefix`, `suffix`, `includes`, or `regex`. The first matching rule wins. If no profile rule matches, the fallback classifier assigns a conservative category from path conventions and leaves the role as `unknown` except for tests.
+
+This keeps validation-target details in profile data rather than hardcoded product assumptions.
+
+## Pull Request Classes
+
+`prClasses` is optional. Rules are evaluated in order and the first matching rule wins. M1 supports title-only matchers:
+
+- `titleIncludes`: literal substring match against the PR title.
+- `titleRegex`: JavaScript regular expression matched against the PR title.
+
+If both matchers are present on one rule, both must match. If no rule matches, the normalized PR receives:
+
+```json
+{
+  "class": "unknown",
+  "classificationSource": "fallback_rule",
+  "ruleId": null
+}
+```
+
+Class identifiers are validated as lower-kebab-case or lower_snake_case strings. Profile validation rejects duplicate PR class rule IDs, empty match objects, invalid class identifiers, and invalid title regexes.