Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs: change evidence, components, policy and reports in the README and docs (#3947)

Raghav Chamadiyac9bbf7d4e2ed
diff --git a/README.md b/README.md
index 5764d13f2..c1e700e5d 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,10 @@
<p align="center">Repowise indexes your code, call graph, git history, tests, docs and design<br />
decisions once, on your machine. Then you and your coding agent ask it things:<br />
-what calls this, what breaks if I change it, what is dead, what to fix first, and why it was built this way.</p>
+what calls this, what breaks if I change it, what is dead, what to fix first, why it was built this way,<br />
+and what evidence stands behind each change that landed.</p>
+
+<p align="center"><strong>Free for one developer on a laptop. Built to run across a company's repositories.</strong></p>
<p align="center">
<a href="https://www.repowise.dev/?src=oss_readme_hero"><img src="https://img.shields.io/badge/LIVE_DEMO-repowise.dev-0A0A0A?style=for-the-badge&labelColor=F59520" alt="Open the live Repowise demo" /></a>
@@ -18,17 +21,14 @@ what calls this, what breaks if I change it, what is dead, what to fix first, an
<tr>
<td align="center" width="250"><b>−31.6%</b><br /><sub>less agent output · <em>p&lt;0.0001</em></sub></td>
<td align="center" width="250"><b>2.3×</b><br /><sub>defects found vs CodeScene · <em>p=0.003</em></sub></td>
-<td align="center" width="250"><b>58,924</b><br /><sub>files indexed on one laptop · <em>120 min</em></sub></td>
+<td align="center" width="250"><b>15M</b><br /><sub>lines of code indexed once on one laptop · <em>then incremental on every commit</em></sub></td>
</tr>
</table>
-<p align="center"><sub><strong>Call graph checked against the compiler:</strong> 0.976 to 0.995 precision on Go and TypeScript,<br />
-and no tool that finds as much of the graph gets more of it right, in 7 of 7 comparisons.<br />
-<em>5 tools · 37,853 compiler edges · every losing row published</em></sub></p>
-
<p align="center"><sub>
-Graph, risk, health, tests and dead code make <strong>zero LLM calls</strong> · no API key needed ·
-free and self-hosted · AGPL-3.0 or commercial
+Graph, risk, health, tests and dead code make <strong>zero LLM calls</strong> · same diff, same answer ·
+runs inside your network · scoped tokens for REST and MCP · change policy in CI with SARIF ·
+free, AGPL-3.0 or commercial
</sub></p>
<p align="center">
@@ -64,13 +64,21 @@ because an agent that can ask the index stops searching, opening and re-reading
files to find out. Measured against the other context tools on the same agent
tasks, it is also the largest saving.
+The same engine serves a developer who wants their agent to stop rediscovering the
+code and a platform team that has to show what changed, who owns it and which tests
+reached it. Every engine capability is in the free, open-source version. The
+commercial layer adds organisation-wide operation on top.
+
<a id="hosted"></a>
<a id="foresight"></a>
## Hosted, and Foresight
Everything in this README runs free on your own machine. [repowise.dev](https://www.repowise.dev/?src=oss_readme_section)
-runs it for you, private repos included, and is where **Foresight** arrives first.
+runs it for you, private repos included, and is where **Foresight** arrives first:
+models trained on years of real commits and fixes that rank the files a fix will
+touch, name what a change forgot, and explain every answer, with no LLM.
+[What Foresight does →](docs/business/FORESIGHT.md)
<a href="https://www.repowise.dev/?src=oss_readme_section"><img src=".github/assets/hosted-foresight.webp" alt="Hosted at repowise.dev: everything in this README with nothing to run, private repos included, one MCP endpoint for Claude, ChatGPT and Cursor, the PR bot with free deterministic review and AI review for cents a pull request, Jira and Confluence, and team workspaces. Coming to repowise.dev: Foresight, models trained on how real codebases change that rank the files a fix will touch, flag what a change forgot, and explain every answer." width="100%" /></a>
@@ -195,6 +203,7 @@ dashboard and CLI on the same local index. No API key and nothing uploaded.</sub
| **A coding agent that knows the repository** | Task-shaped context in fewer calls, with decisions and risk delivered before the agent asks. [For agents ↓](#your-agent-stops-guessing) |
| **Safer pull requests and faster CI** | Change risk, symbol-level callers, missing co-changes and the tests a diff needs. [Change intelligence ↓](#know-whats-dangerous-before-you-merge) |
| **Paying down the code most likely to hurt you** | A defect-validated health score, then the concrete fix. [Code health ↓](#code-health) |
+| **Showing what changed, to a reviewer or an auditor** | Each merged change with its evidence, change policy in CI, and reports you can hand over. [Change evidence ↓](#change-evidence) |
| **An estate of many repositories** | Contracts matched across repos, breaking-change guards, architecture rules in CI, one MCP endpoint for everything. [Workspaces ↓](#past-one-repo) |
| **Rolling it out across a company** | Self-hosted with nothing leaving your network, per-language accuracy, sizing, compliance status and licensing in one place. [Teams and enterprise ↓](#for-teams-and-enterprises) |
@@ -351,6 +360,36 @@ the same diff always gets the same review.
---
+<a id="change-evidence"></a>
+
+## Every change, with its evidence
+
+Repowise reads each merged pull request, merge request or commit back from git as a
+**Change Record**: the commits it brought in, the components it touched and their
+declared owners, the tests that reach it, the contracts and decisions it crosses, its
+provenance, and what happened after it landed. No forge API is called, and every item
+says what it rests on: measured, inferred, declared or unknown.
+
+| You ask | Repowise gives you |
+|---|---|
+| *What landed in this PR, and what backs it up?* | The change's evidence checklist, each item `ok`, `attention` or `unknown`, with an in-toto export. [Change Records](docs/layers/CHANGES.md) |
+| *Can CI hold changes to our payment code to a higher bar?* | Rules in `.repowise/policies.yaml`, matched to components by name, tag or criticality and evaluated by `repowise check`, with SARIF or JUnit output. [Change policy](docs/layers/POLICY.md) |
+| *Something broke. Which change do we read first?* | Recent changes ranked against an error, a stack trace or an issue. On 43 real regressions, the change a later revert or fix named was in the top 5 for 67% of them, against 28% for ranking by shared files. [Suspects](docs/layers/CHANGES.md#suspects) |
+| *Who owns this, and are they still working on it?* | Backstage-shaped components with owners from your catalog and CODEOWNERS, compared with the last 90 days of commits. [Components](docs/layers/COMPONENTS.md) |
+| *Can we show an auditor or an acquirer where we stand?* | Evidence packs: a repository assessment, a change report for a period and a component inventory, as JSON, Markdown, HTML or CSV. [Reports](docs/layers/REPORTS.md) |
+
+```bash
+repowise changes show pr-412 # one change and its evidence checklist
+repowise check main..HEAD --sarif-file policy.sarif # run .repowise/policies.yaml in CI
+repowise suspects --trace stacktrace.txt # the recent changes to read first
+repowise report changes --format html --out q3.html # change evidence for the last 90 days
+```
+
+Owners and reviewers are counted, never ranked or named, and every report states what
+git alone cannot attest.
+
+---
+
<a id="code-health"></a>
## ★ Know exactly what to fix
@@ -784,6 +823,26 @@ threat model and data flows are in the
[security review pack](docs/business/SECURITY_COMPLIANCE.md). The published research each layer is built on, and how we
checked it, is in [LINEAGE.md](docs/LINEAGE.md).
+On a shared server, REST, MCP over HTTP and webhooks resolve every caller to a
+principal scoped to repositories and tools, and scoped tokens are stored as hashes.
+Authentication, team directories, change metadata and event delivery are named
+plugin seams, so your own identity provider or directory connects without changing
+the open-source code.
+
+### Evidence you can hand to someone else
+
+| Who is asking | What Repowise produces |
+|---|---|
+| An auditor reviewing change management (SOC 2 CC8.1, ISO 27001 A.8.32, PCI DSS 6.5) | Every change in the period with its review record, reaching tests, policy verdict and later outcome: `repowise report changes` |
+| A software inventory review (PCI DSS 6.3.2) | Components with owner teams, languages, entry points and the packages they import: `repowise report inventory` |
+| A security team asking which of your code uses a package | Import sites with component, owner team and reachability, plus a CycloneDX 1.6 usage export: `repowise packages where` |
+| An acquirer, a board or a migration committee | Component posture, hotspots, bus factor, dead code, test reach and contracts: `repowise report assessment` |
+| An incident review | The recent changes to read first, with the signals behind each: `repowise suspects` |
+
+These packs are evidence for those reviews, not a certification. Missing evidence is
+reported as unresolved, never as a pass. Trying it on your own code takes an
+afternoon: [evaluating Repowise for your company](docs/business/EVALUATION.md).
+
### How accurate, and how big
Call-graph accuracy is graded against each language's own compiler toolchain, and we
@@ -792,9 +851,9 @@ publish precision and recall per language, with the misses, in the
0.996 for Go, TypeScript, Dart, C and most Python, 0.87 to 0.95 for Java, 0.94 for
Kotlin applications, 0.85 to 0.90 for Rust and 0.72 to 0.92 for C#.
-The largest repository indexed so far is dotnet/runtime: 58,924 files in 120 minutes
-at 11.7 GiB peak memory, on one 31 GB laptop with no API key. Time and memory by
-repository size: [scale](docs/BENCHMARKS.md#scale).
+The largest repository indexed so far is dotnet/runtime: about 15 million lines of
+code in 58,924 files, in 120 minutes at 11.7 GiB peak memory, on one 31 GB laptop
+with no API key. Time and memory by repository size: [scale](docs/BENCHMARKS.md#scale).
### Source control and CI
@@ -802,7 +861,9 @@ Any git host works, because indexing reads a local checkout. On top of that:
- **GitHub**: the [PR bot](#the-pr-bot) (GitHub App), a GitHub Action for the CI
gates, and webhook auto-sync.
-- **GitLab**: a CI template for the same gates and webhook auto-sync.
+- **GitLab**: a CI template for the same gates and webhook auto-sync. On
+ [repowise.dev](https://www.repowise.dev/?src=oss_readme_enterprise), connect a
+ GitLab.com account, add projects and sync on every push.
- **Bitbucket Pipelines and others**: the gates run as plain CLI commands with the
pipeline's own branch variables. ([Repowise in CI](docs/start/CI.md))
- **Managed integrations** for GitHub Enterprise, Azure DevOps, GitLab self-managed
@@ -816,9 +877,9 @@ Any git host works, because indexing reads a local checkout. On top of that:
| Status | Capability |
|---|---|
-| **Shipping in open source** | Every deterministic layer, ten MCP tools, multi-repo workspaces, contract extraction and cross-repo blast radius, test intelligence, [architecture conformance](docs/scale/WORKSPACES.md#architecture-conformance), local dashboard, auto-sync, full-history secret scanning. |
-| **GA commercially** | Hosted graph-aware security, CVE prioritization, CycloneDX SBOM and VEX, PCI-DSS and SOC 2 control-coverage reports, audit export and webhook stream, Jira and Confluence, reference HA topology on your infrastructure, custom language extensions, SLA support, IP indemnification. |
-| **Rolling out** | Managed GitHub Enterprise, Azure DevOps, GitLab and Bitbucket integrations. SAML/OIDC SSO and SCIM. Engineering-leader dashboards. |
+| **Shipping in open source** | Every deterministic layer, ten MCP tools, multi-repo workspaces, contract extraction and cross-repo blast radius, test intelligence, [architecture conformance](docs/scale/WORKSPACES.md#architecture-conformance), local dashboard, auto-sync, full-history secret scanning. Change Records with evidence and outcomes, local change policy with SARIF and JUnit, evidence packs, Backstage-shaped components with declared and active owners, package usage with CycloneDX export, scoped tokens for REST, MCP and webhooks, and plugin seams. |
+| **GA commercially** | Hosted GitHub and GitLab.com repositories, hosted graph-aware security, CVE prioritization, CycloneDX SBOM and VEX, PCI-DSS and SOC 2 control-coverage reports, audit export and webhook stream, Jira and Confluence, reference HA topology on your infrastructure, custom language extensions, SLA support, IP indemnification. |
+| **Rolling out** | Managed GitHub Enterprise, Azure DevOps, GitLab self-managed and Bitbucket integrations. SAML/OIDC SSO and SCIM. Engineering-leader dashboards. |
| **Planned** | RBAC and multi-tenancy, a packaged air-gap install bundle, the Helm chart. |
Repowise holds no SOC 2, ISO 27001 or other audited certification today. The SOC 2 and
@@ -828,9 +889,10 @@ export says so. Every item is tracked with its status in the
### Pricing, licence and support
-Commercial licences are priced **per indexed repository**, with unlimited seats inside
-the licensed set. More and more of the code in a repository is written and read by
-agents and CI, so seat counts stop tracking the value.
+Commercial licences come in three models: **per seat**, **per indexed repository**
+with unlimited seats inside the licensed set, or **enterprise-wide**. Per-repository
+fits teams where agents and CI do most of the reading, since seat counts stop
+tracking the value there. Every model includes the full commercial feature set.
[Details →](docs/business/COMMERCIAL.md#7-licensing--pricing)
**Do we have to open-source our code because of the AGPL?** No. Using Repowise inside
@@ -898,6 +960,12 @@ repowise health # code-health KPIs and lowest-scoring files
repowise risk main..HEAD # score a branch or PR range
repowise overlap # other branches editing the same files
repowise impacted-tests # only the tests a diff exercises
+repowise changes show ID # one merged change and its evidence checklist
+repowise check # evaluate .repowise/policies.yaml against a change
+repowise suspects # recent changes ranked against a symptom
+repowise components # declared and derived components, owners vs activity
+repowise packages where # where a third-party package is imported
+repowise report # assessment, change evidence and inventory packs
repowise dead-code # unreachable code by confidence tier
repowise doc-drift # documentation the code no longer supports
repowise security # secrets and risky patterns, tree or full history
diff --git a/ROADMAP.md b/ROADMAP.md
index b8eb2b134..f3e23d991 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -70,7 +70,7 @@ Adding one touches per-language subpackages rather than the parser core, which
is what makes this tractable at the rate above. Open an issue and we will scope
it in public. Commercial customers can have a language or framework built and
maintained by us as a line item, which is
-[GA today](docs/business/COMMERCIAL.md#54-enterprise-operations), and the result
+[GA today](docs/business/COMMERCIAL.md#55-enterprise-operations), and the result
still ships to everyone under AGPL.
---
@@ -117,7 +117,7 @@ gaps between them.
|---|---|---|
| Cross-repo intelligence at scale | In development | Hotspots, dead code and ownership across a whole estate with centralized dashboards, beyond the local-workspace scope already shipping in open source |
| Column-level blast radius for SQL / dbt | Planned | Lineage is table-level today through `ref()` and `source()`. Column-level answers "who breaks if I drop this field" |
-| Custom decision policies | Planned | Required-reviewer rules, mandatory `get_why` checks on governed paths, and merge gating tied to findings |
+| Organisation-wide change policy | Planned | Local change policy ships today ([POLICY.md](docs/layers/POLICY.md)). This adds central policy management across repositories, approvals and a policy audit trail |
---
@@ -166,6 +166,7 @@ The half of the roadmap that has nothing to do with procurement.
| Interface-dispatch recall | Exploring | The measured ceiling on our call-graph recall. On `syft`, 44% of what we miss is dynamic dispatch alone and a further 39% is dispatch with a closure at one end. Nobody in the [measured field](docs/BENCHMARKS.md#8-the-same-question-against-an-answer-key-we-do-not-control) has cleared it, at 6.5 possible targets per call site, and matching that recall naively means emitting six edges where one is right. |
| A sealed JavaScript / TypeScript retrieval corpus | In development | Built and half graded. The sealed half is unrun, and nothing from it is quoted anywhere until it is evaluated, once. |
| More compiler oracles for graph precision | Exploring | Go and TypeScript are done. C#, Java, Kotlin and C++ each need a toolchain and a working build per repository; Rust has the toolchain and no sound call-graph tool exists for it; Python, Ruby and PHP admit no oracle even in principle. The honest status is "probably not", not "planned". |
+| Foresight | Waitlist | Learned models that rank where a fix goes, what a change forgot and which tests to update, with no LLM. Hosted and enterprise. [FORESIGHT.md](docs/business/FORESIGHT.md) |
| Session intelligence harvesting | Planned | Architectural decisions surfaced from AI coding sessions and proposed to the team knowledge base, so knowledge generated during agent work does not evaporate when the session ends |
---
diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
index aed4a5b7f..2b54865ac 100644
--- a/docs/BENCHMARKS.md
+++ b/docs/BENCHMARKS.md
@@ -19,7 +19,7 @@ another tool leads, that row is here too. The research behind each method is in
| [Work saved in an agent loop](#2-what-changes-in-a-real-agent-loop) | **31.6% less** agent output than no tool, 3.8 tool calls against 7.2 | 43 django questions on Codex, p < 0.0001 |
| [Health score against CodeScene](#5-code-health-predicts-defects) | **2.3x** the later-defective files inside a 20% review budget | 2,770 files, 21 repositories, p = 0.003 |
| [Which tests cover a file, with no coverage run](#test-intelligence) | **95.7%** precision on what reaches a file, **97.5%** on the tests to run | 46 claims and 47 targets, checked against per-test coverage |
-| [Largest repository indexed](#scale) | **58,924 files** (dotnet/runtime) in 120 minutes at 11.7 GiB peak | one keyless run on a laptop |
+| [Largest repository indexed](#scale) | **About 15M lines of code, 58,924 files** (dotnet/runtime) in 120 minutes at 11.7 GiB peak | one keyless run on a laptop |
| [Memory to build the call graph](#what-it-costs-to-run) | **75 MB** median against 757 MB for CodeGraph, lowest on **35 of 35** repositories | 35 repositories, 5 tools |
### One index, the work of several tools
@@ -408,14 +408,19 @@ Large public repositories, indexed end to end on one Windows laptop (31 GB RAM),
keyless (`repowise init --no-prose`), limited to 8 CPUs and 2 parse workers.
October 2026.
-| Repository | Tracked files | First index | Peak memory | Index on disk |
-|---|---:|---:|---:|---:|
-| dotnet/aspnetcore v8.0.31 | 15,510 | 20 min | 4.0 GiB | 1.4 GiB |
-| elastic/elasticsearch v8.19.22 | 34,315 | 52 min | 7.8 GiB | 4.2 GiB |
-| dotnet/runtime v8.0.31 | **58,924** | **120 min** | **11.7 GiB** | 7.7 GiB |
+| Repository | Tracked files | Lines of code | First index | Peak memory | Index on disk |
+|---|---:|---:|---:|---:|---:|
+| dotnet/aspnetcore v8.0.31 | 15,510 | 1.5M | 20 min | 4.0 GiB | 1.4 GiB |
+| elastic/elasticsearch v8.19.22 | 34,315 | 4.0M | 52 min | 7.8 GiB | 4.2 GiB |
+| dotnet/runtime v8.0.31 | **58,924** | **15.0M** | **120 min** | **11.7 GiB** | 7.7 GiB |
+
+Lines of code are non-blank lines in tracked source files (C#, IL, C, C++, Java,
+TypeScript, JavaScript, Python, shell, assembly and similar), with data, markup and
+docs left out. Peak memory is the whole process tree, one run per repository.
-Peak memory is the whole process tree, one run per repository. On aspnetcore,
-an update with no changes takes about 4 seconds.
+The first index is a one-time cost: it builds the call graph, git history, health,
+tests, dead code and docs together. After that, each update re-analyses only what
+changed. On aspnetcore, an update with no changes takes about 4 seconds.
---
diff --git a/docs/README.md b/docs/README.md
index 3d8557686..2ec38cf8c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -68,6 +68,14 @@ For a map of every layer and how they feed each other, read
| [layers/CHANGES.md](layers/CHANGES.md) | Change Records: each merged PR, MR or commit read back from git, with an in-toto export |
| [layers/ATTRIBUTION.md](layers/ATTRIBUTION.md) | AI attribution: public markers read by default, opt-in edit capture, and coverage beside every share |
+### Govern change across a team
+
+| Doc | What it covers |
+|-----|----------------|
+| [layers/COMPONENTS.md](layers/COMPONENTS.md) | Backstage-shaped components, declared owners against recent activity, events and package usage |
+| [layers/POLICY.md](layers/POLICY.md) | Change policy in `.repowise/policies.yaml`, checked locally or in CI with SARIF and JUnit |
+| [layers/REPORTS.md](layers/REPORTS.md) | Assessment, change evidence and inventory packs to hand to an auditor, acquirer or board |
+
### Know which tests matter
| Doc | What it covers |
@@ -106,8 +114,10 @@ For a map of every layer and how they feed each other, read
| Doc | What it covers |
|-----|----------------|
+| [business/EVALUATION.md](business/EVALUATION.md) | Try it on your own code in an afternoon, offline, from index to evidence packs |
| [business/SECURITY_COMPLIANCE.md](business/SECURITY_COMPLIANCE.md) | What leaves your machine, what is stored, and the answers your security team wants |
| [business/COMMERCIAL.md](business/COMMERCIAL.md) | Hosted tier, enterprise options and commercial licensing |
+| [business/FORESIGHT.md](business/FORESIGHT.md) | Foresight: learned models that predict where a fix goes and what a change forgot, coming to hosted and enterprise |
| [BENCHMARKS.md](BENCHMARKS.md) | Every published number with its sample size and method, including the rows we lose |
| [LINEAGE.md](LINEAGE.md) | The published research each layer is built on, where it lives in the code, and how we checked it |
| [../ROADMAP.md](../ROADMAP.md) | What we are building next, and what we are not |
diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.md
index ec51f4454..85c098d59 100644
--- a/docs/business/COMMERCIAL.md
+++ b/docs/business/COMMERCIAL.md
@@ -20,8 +20,9 @@ models. Specific pricing figures are provided in a separate proposal.
The open-source distribution covers the full developer-experience surface: the five
intelligence layers, the ten MCP tools, multi-repo workspaces, the local dashboard,
-auto-sync, and auto-generated `CLAUDE.md`. That is everything an engineer or a team
-needs to make their AI coding agents codebase-aware.
+auto-sync, auto-generated `CLAUDE.md`, and change evidence with local policy and
+reports. That is everything an engineer or a team needs to make their AI coding
+agents codebase-aware and to account for what lands.
The commercial license is for organizations that need to roll Repowise out **at
scale, in a regulated or security-sensitive environment**:
@@ -87,6 +88,17 @@ All of the following ship in `pip install repowise` today, free for internal use
`coverage run --contexts=test`. Measured and inferred rows are labelled and
never averaged. Zero LLM calls, no CI integration needed.
([TEST_INTELLIGENCE.md](../layers/TEST_INTELLIGENCE.md))
+- **Change evidence and governance**: Change Records with an evidence checklist
+ and outcomes, `repowise suspects`, Backstage-shaped components with declared
+ owners compared against recent activity, local change policy (`repowise check`,
+ SARIF and JUnit), assessment, change and inventory reports, and package usage
+ with a CycloneDX 1.6 export. ([CHANGES.md](../layers/CHANGES.md),
+ [COMPONENTS.md](../layers/COMPONENTS.md), [POLICY.md](../layers/POLICY.md),
+ [REPORTS.md](../layers/REPORTS.md))
+- **Scoped access and plugin seams**: REST, MCP over HTTP and webhooks resolve
+ each caller to a principal scoped to repositories and tools, with hashed,
+ expiring tokens. Authentication, team directory, change metadata, event
+ delivery and report sections are named seams a plugin can fill.
- **Privacy** (self-hosted): source never leaves your infrastructure, BYOK or fully
offline via Ollama. Anonymous, opt-out usage telemetry (command names and coarse
environment only, never code, paths or repo names) can be turned off with
@@ -128,7 +140,7 @@ would not survive a technical evaluation. Full ladder:
**Languages are never gated.** Every one of them ships in the AGPL distribution,
including the ones still climbing. COBOL now ships at the Good tier; remaining
work is on the public [roadmap](../../ROADMAP.md#languages). Where you need a language
-or framework that is not there, §5.4 covers having it built and maintained by us
+or framework that is not there, §5.5 covers having it built and maintained by us
as a commercial line item, and the result still ships to everyone under AGPL.
For estates built on a particular stack, the relevant Full-tier capabilities are
@@ -147,7 +159,7 @@ worth calling out. For **.NET**, as one example:
The same depth exists for the other Full-tier languages. The language pipeline is
modular by design; adding or deepening a language touches per-language subpackages,
not the parser core, which is what makes the **custom language / framework
-extensions** in §5.4 a tractable commercial offering.
+extensions** in §5.5 a tractable commercial offering.
---
@@ -170,6 +182,14 @@ the items that matter most to you can be prioritized.
| Test intelligence (coverage ingestion **and** the graph-inferred test map) | ✅ | ✅ |
| Local full-history secret scan (`repowise security scan --history`) | ✅ | ✅ |
| Local CI security gate on a change (`repowise security check`, SARIF output, committed baseline) | ✅ | ✅ |
+| Change Records, evidence checklist and suspects | ✅ | ✅ |
+| Local change policy in CI (`repowise check`, SARIF / JUnit) | ✅ | ✅ |
+| Components, declared vs active owners, component events | ✅ | ✅ |
+| Assessment, change evidence and inventory reports | ✅ | ✅ |
+| Package usage with CycloneDX 1.6 usage export | ✅ | ✅ |
+| Scoped tokens for REST, MCP HTTP and webhooks; plugin seams | ✅ | ✅ |
+| Central policy management, org-wide enforcement, approvals and policy audit | — | ✅ *(planned)* |
+| Foresight: learned fix localization, forgotten files, tests to update, learned health | — | ✅ *(waitlist, [FORESIGHT.md](FORESIGHT.md))* |
| Graph-aware enhanced security scanning | — | ✅ *(GA on hosted)* |
| Language-specific security rulesets | — | ✅ *(dev)* |
| CVE-aware dependency analysis (KEV / EPSS / priority-scored) | — | ✅ *(GA on hosted)* |
@@ -180,7 +200,8 @@ the items that matter most to you can be prioritized.
| Compliance reporting (PCI-DSS / SOC 2) | — | ✅ *(GA on hosted, Teams)* |
| Audit trail (in-product + JSON / CSV export + webhook stream) | — | ✅ *(GA on hosted, security surface)* |
| Jira / Confluence integration | — | ✅ *(GA on hosted, Teams)* |
-| GitHub Enterprise / Azure DevOps / GitLab / Bitbucket | — | ✅ *(rolling out)* |
+| GitLab.com repositories (connect, add projects, sync on push) | — | ✅ *(GA on hosted)* |
+| GitHub Enterprise / Azure DevOps / GitLab self-managed / Bitbucket | — | ✅ *(rolling out)* |
| Slack / Teams security alerting (signed webhooks) | — | ✅ *(GA on hosted, Teams)* |
| SAML / OIDC SSO + SCIM | — | ✅ *(rolling out)* |
| RBAC + multi-tenant | — | ✅ *(planned)* |
@@ -283,7 +304,9 @@ integrations beyond this list are available on request.
page, updated in place and never duplicated; every page carries a link-back and
a freshness banner stating the exact source commit, with an explicit stale
warning when the snapshot trails the repository head.
-- **GitHub Enterprise / Azure DevOps / GitLab / Bitbucket**: managed webhooks, a
+- **GitLab.com** *(available on the hosted platform)*: connect a GitLab account,
+ add projects, and keep them current on every push or through polling.
+- **GitHub Enterprise / Azure DevOps / GitLab self-managed / Bitbucket**: managed webhooks, a
PR-comment bot that posts blast-radius and reviewer suggestions, and a
branch-protection check that blocks merges touching hotspots without a reviewer
from the ownership list.
@@ -316,14 +339,22 @@ presentation and policy layer is what's rolling out commercially.
- **Cross-repo intelligence at scale** *(dev)*: hotspots, dead code, and ownership
across the entire estate with centralized dashboards (beyond the local-workspace
scope already shipping in OSS).
-- **Custom decision policies** *(planned)*: required-reviewer rules, mandatory
- `get_why` checks for governed paths, and merge-gating policies tied to Repowise
- findings. Policy authoring and local or CI evaluation are planned for open
- source, following the local security gate that ships today. The commercial layer adds
- central policy management, organisation-wide enforcement across repositories,
- approval workflows and a policy audit trail.
+- **Organisation-wide change policy** *(planned)*: policy authoring and local or
+ CI evaluation ship in open source today (`.repowise/policies.yaml` and
+ `repowise check`). The commercial layer adds central policy management,
+ organisation-wide enforcement across repositories, approval workflows and a
+ policy audit trail.
-### 5.4 Enterprise Operations
+### 5.4 Foresight *(waitlist)*
+
+Learned models, trained on years of public open-source history, that read the
+index to predict what a piece of work will need: the files and functions a fix
+will touch, the file a change forgot, the tests to update, and a health signal
+with learned weights. No LLM, CPU only, local inference, so it runs self-hosted or
+air-gapped, and it never trains on customer code. Measured results and the
+waitlist: [FORESIGHT.md](FORESIGHT.md).
+
+### 5.5 Enterprise Operations
- **Role-based access control** *(planned)*: repo-, module-, and decision-level
permissions; SCIM group mapping.
@@ -372,8 +403,10 @@ an in-memory NetworkX graph. The LLM provider and the git server sit alongside
Repowise in the same network boundary; no outbound connectivity is required in
air-gapped mode.
-**Indexing:** the graph, git, dead-code, and code-health layers build in minutes with
-zero LLM calls (`repowise init --no-prose`); the documentation layer's one-time
+**Indexing:** the graph, git, dead-code, and code-health layers build with zero LLM
+calls (`repowise init --no-prose`), about 20 minutes for a 1.5M-line repository and
+two hours for a 15M-line one on a single laptop
+([scale](../BENCHMARKS.md#scale)); the documentation layer's one-time
wiki generation scales with repo size and can run in the background. Incremental
updates after each commit complete in under 30 seconds.
diff --git a/docs/business/EVALUATION.md b/docs/business/EVALUATION.md
new file mode 100644
index 000000000..89d07c88b
--- /dev/null
+++ b/docs/business/EVALUATION.md
@@ -0,0 +1,82 @@
+# Evaluating Repowise for Your Company
+
+Written for a platform, AppSec or architecture lead trying Repowise on their own code
+before a wider rollout. Everything below runs on one machine with the open-source
+package and no API key. No code, index or report leaves that machine.
+
+Plan an afternoon. Pick one repository you know well, so you can judge the answers.
+
+## 1. Index it, offline
+
+```bash
+uv tool install repowise # or: pipx install repowise
+export DO_NOT_TRACK=1 # switches off anonymous CLI telemetry too
+cd /path/to/your/repo
+repowise init --yes --no-prose # graph, git history, health, tests, dead code
+repowise serve # local dashboard and MCP server
+```
+
+`--no-prose` makes no model calls. Indexing time and memory by repository size are in
+[BENCHMARKS.md](../BENCHMARKS.md#scale).
+
+## 2. Check what it says about code you know
+
+Open the dashboard and look at Code Health, Fix first and Dead code, or run
+`repowise next` and `repowise dead-code`. After indexing, Repowise reports how many of
+its lowest-scoring files had bug fixes in your own recent history, which tells you
+whether the health score holds on your code.
+
+## 3. Name your components
+
+Declare two or three components, including one you consider critical, in
+`.repowise/components.yaml`, or point Repowise at your existing `catalog-info.yaml`.
+
+```bash
+repowise components check
+repowise components ownership # declared owners against the last 90 days
+```
+
+See [Components and ownership](../layers/COMPONENTS.md).
+
+## 4. Read a few recent changes
+
+```bash
+repowise changes list --limit 10
+repowise changes show <id> # the evidence checklist for one change
+```
+
+Pick a change you remember and check the components, owners, reaching tests and
+contracts it lists. See [Change Records](../layers/CHANGES.md).
+
+## 5. Write one policy and run it
+
+Add a rule to `.repowise/policies.yaml`, for example that changes to the critical
+component need reaching tests, and run it the way CI would:
+
+```bash
+repowise check HEAD~1..HEAD --sarif-file policy.sarif
+```
+
+See [Change policy](../layers/POLICY.md) and [Repowise in CI](../start/CI.md).
+
+## 6. Produce the packs you would hand over
+
+```bash
+repowise report assessment --format html --out assessment.html
+repowise report changes --format html --out changes.html
+```
+
+Read them as the auditor, acquirer or committee would. Every item says whether it is
+measured, inferred, declared or unresolved. See [Evidence reports](../layers/REPORTS.md).
+
+## 7. Optional: more than one repository
+
+Add a second repository that talks to the first and see the contracts between them and
+the cross-repository blast radius. See [Workspaces](../scale/WORKSPACES.md).
+
+## Before a wider rollout
+
+- Security review: [SECURITY_COMPLIANCE.md](SECURITY_COMPLIANCE.md) answers what is
+ stored, what can leave the network and how a shared server authenticates callers.
+- Commercial licence, on-prem topology and support: [COMMERCIAL.md](COMMERCIAL.md).
+- Questions: [[email protected]](mailto:[email protected]).
diff --git a/docs/business/FORESIGHT.md b/docs/business/FORESIGHT.md
new file mode 100644
index 000000000..dc107af5f
--- /dev/null
+++ b/docs/business/FORESIGHT.md
@@ -0,0 +1,145 @@
+<div align="center">
+
+# Repowise Foresight
+
+### Know what a change will need before you open a file.
+
+<p>Every fix your team has shipped, every file someone forgot, every test someone had to<br />
+go back and update is already written down in git. Foresight learned from years of that<br />
+history across many open-source projects, and now reads yours.</p>
+
+<a href="https://www.repowise.dev/foresight?src=oss_docs_foresight#waitlist"><img src="https://img.shields.io/badge/FORESIGHT-join_the_waitlist-0A0A0A?style=for-the-badge&labelColor=B9A3E3" alt="Join the Foresight waitlist" /></a>
+<a href="https://cal.com/repowise-demo/30min"><img src="https://img.shields.io/badge/BOOK_A_DEMO-30_min-0A0A0A?style=for-the-badge&labelColor=F59520" alt="Book a Foresight demo" /></a>
+
+<sub>Coming to Repowise hosted and enterprise · no LLM · milliseconds on a CPU · air-gap ready</sub>
+
+</div>
+
+---
+
+## The bug report that names no file
+
+A customer writes in:
+
+> **Checkout sometimes charges twice after a timeout.**
+> On a slow connection the payment page times out, the customer tries again, and the
+> card is charged twice.
+
+Keyword search, the way most agents and people find code today, returns whatever says
+"checkout":
+
+```text
+web/checkout_page.tsx matches "checkout" 14 times
+tests/test_checkout_ui.py matches "checkout" 9 times
+README.md matches "charges" 3 times
+web/checkout.css matches "checkout" 6 times
+```
+
+Foresight answers with where the fix will actually land, and why:
+
+```text
+payments/retry.py likely fixed for a similar timeout bug 3 weeks ago
+billing/ledger.py possible changes with retry.py 9 of 11 times
+payments/gateway.py possible raises the Timeout that retry.py catches
+```
+
+The issue never mentions `retry.py`. The history does. Your agent starts on the right
+file instead of reading the checkout page first.
+
+<sub>An illustrative example. Measured results are below.</sub>
+
+---
+
+## What it answers
+
+The open-source index knows what your code *is*. Foresight predicts what a piece of
+work will *need*.
+
+| | Foresight tells you | For example |
+|---|---|---|
+| **Where the fix goes** | Paste a bug report or a stack trace and get the files, and the functions inside them, the fix will touch | `payments/retry.py`: fixed for a similar timeout bug |
+| **What the change forgot** | Mid-edit, before any commit message, the file that usually changes with yours and is missing from the diff | `billing/ledger.py`: changes with `retry.py` 9 of 11 times |
+| **What still holds the old name** | Rename or remove an identifier or a literal, and see the files that still reference it | `config/settings.py`: still references `SESSION_TTL` |
+| **Tests to update** | The test files that will need edits too, ranked, so the pull request arrives complete | `test_retry.py`: moves with `retry.py` |
+| **Code health that learns** | A health signal whose weights are learned from how real projects needed fixes | `payments/processor.py`: first in line for review |
+| **Confidence you can act on** | A calibrated band and the evidence behind every answer, so an agent or reviewer knows when to trust it | `likely`: 3 signals agree |
+
+---
+
+## Measured on real bugs
+
+Every result was run on the code as it stood before the fix, on projects the models
+never trained on.
+
+<table>
+<tr>
+<td align="center" width="25%"><h2>87%</h2><sub><b>right file in the top five</b><br />SWE-bench Verified, 493 real bugs, no LLM</sub></td>
+<td align="center" width="25%"><h2>2.6x</h2><sub><b>better where search fails</b><br />when the report names no file: right file first 42% of the time, against 16% for keyword search</sub></td>
+<td align="center" width="25%"><h2>3 in 4</h2><sub><b>right file in the top five on real issues</b><br />114 real openclaw bugs: 75%, against 48% for keyword search</sub></td>
+<td align="center" width="25%"><h2>6 of 7</h2><sub><b>unseen projects won</b><br />ahead of keyword search on 6 projects it never saw, tied on the seventh</sub></td>
+</tr>
+</table>
+
+That last number matters most. Foresight is trained once, on public history, and then
+works on code it has never seen. It does not need months of your data before it is
+useful, and it never trains on your code.
+
+---
+
+## How it runs
+
+| | |
+|---|---|
+| **No LLM** | Small learned models. No prompt and no tokens, and the same input gets the same answer every time. |
+| **CPU only** | Runs on the machine that already runs Repowise. No GPU. |
+| **Milliseconds** | Under half a second on a laptop, so it can run on every edit, commit and pull request. |
+| **Air-gap ready** | Inference is local. Self-hosted and air-gapped deployments keep code inside your network. |
+| **Reads your history** | Each answer draws on your repository's own co-change, fix and ownership record from the Repowise index. |
+| **Explains itself** | Every ranked file carries the reason it ranked, in plain words. |
+| **Keeps learning** | We retrain on new public history, so each release has learned from more real changes than the last. |
+
+---
+
+## Where you see it
+
+Foresight sits on top of the Repowise index and reaches you through the surfaces you
+already use:
+
+- **Your coding agent**, through the same Repowise MCP tools, so it opens the right
+ file first and reads less to get there.
+- **Pull requests**, where the files and tests a change forgot show up before review.
+- **The dashboard**, next to change risk, code health and each Change Record.
+
+The open-source engine stays complete without it. Foresight is the learned layer on
+top, for teams that want the next step predicted as well as the current state
+explained.
+
+---
+
+## Questions
+
+**When can we use it?** Foresight is coming to Repowise hosted and enterprise. Teams on
+the waitlist get access first, in the order it opens.
+
+**Does our code leave our network?** No. Foresight makes no model-provider call. The
+models are trained ahead of time on public open-source history and run on a CPU next
+to the index, so enterprise deployments run it self-hosted or fully air-gapped.
+
+**Is it open source?** No. The Repowise engine is AGPL-3.0 and fully usable without
+Foresight. Foresight is part of the hosted and commercial products. See
+[COMMERCIAL.md](COMMERCIAL.md).
+
+**Does it replace our coding agent or our reviewers?** No. It gives both a better
+starting point: the right files, the forgotten ones, and how sure it is.
+
+---
+
+<div align="center">
+
+### Be first to run Foresight on your code.
+
+<a href="https://www.repowise.dev/foresight?src=oss_docs_foresight#waitlist"><img src="https://img.shields.io/badge/FORESIGHT-join_the_waitlist-0A0A0A?style=for-the-badge&labelColor=B9A3E3" alt="Join the Foresight waitlist" /></a>
+
+<sub>Questions first? <a href="https://cal.com/repowise-demo/30min">Book a 30-minute demo</a> or write to <a href="mailto:[email protected]">[email protected]</a>.</sub>
+
+</div>
diff --git a/docs/business/SECURITY_COMPLIANCE.md b/docs/business/SECURITY_COMPLIANCE.md
index 9561093ed..b51bc89af 100644
--- a/docs/business/SECURITY_COMPLIANCE.md
+++ b/docs/business/SECURITY_COMPLIANCE.md
@@ -249,6 +249,9 @@ own product and adds the layer above.
| Is there an audit log? | On the hosted platform, insert-only, covering the security surface, with user, IP, and timestamp, JSON/CSV export, and an opt-in signed-webhook stream. Broader coverage is in development. |
| Do you store secrets you find? | Only a fingerprint and a redacted preview. Never the secret value. |
| What does the MCP server expose to an AI agent? | Read-only query tools over the local index. The lean MCP container exposes no ports and speaks stdio only. |
+| How is a shared server authenticated? | REST, MCP over HTTP (streamable HTTP and SSE) and webhooks resolve every caller to a principal. Scoped tokens in `~/.repowise/tokens.yaml` are stored as SHA-256 hashes, can expire, and can be limited to repositories and MCP tools. MCP HTTP serves an RFC 9728 protected-resource document. A server reachable from the network refuses requests until a key is set. See [API_REFERENCE.md §2](../reference/API_REFERENCE.md#2-authentication). |
+| Can we connect our own identity provider or directory? | Authentication, authorisation, team directory, change metadata and event delivery are named plugin seams. An installed plugin fills them without changes to the open-source code, and `repowise plugins` shows which implementation each seam uses. Managed SSO and SCIM are part of the commercial layer. |
+| Does AI attribution monitor developers? | No. By default only public markers already in git history are read. Edit capture is opt-in per agent and stores line hashes, never prompts, code or identities. `attribution.enabled: false` stores and shows nothing about AI. Reports count owners and reviewers and never rank or name them. See [ATTRIBUTION.md](../layers/ATTRIBUTION.md). |
| What license are we accepting? | AGPL-3.0 for the OSS engine, free for internal use. A commercial license is required to embed Repowise in a product without AGPL obligations. |
| Who do we contact for a security review? | [[email protected]](mailto:[email protected]). Commercial scoping: [[email protected]](mailto:[email protected]). |
diff --git a/docs/layers/COMPONENTS.md b/docs/layers/COMPONENTS.md
new file mode 100644
index 000000000..f36186d6c
--- /dev/null
+++ b/docs/layers/COMPONENTS.md
@@ -0,0 +1,66 @@
+# Components and Ownership
+
+A component is a part of the codebase your organisation names: a service, a library,
+the payments module. Health, hotspots, bus factor, test reach, dead code and changes
+all roll up to components, so a finding reads as "the payments component" and not as a
+list of files.
+
+## Declaring components
+
+Components follow the Backstage model (`Component`, `System`, `Group`). Declare them in
+`.repowise/components.yaml`, or let Repowise read the `catalog-info.yaml` your developer
+portal already uses. `repowise.dev/*` annotations add paths, criticality, tags and
+business capability.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: payments
+ annotations:
+ repowise.dev/paths: "services/payments/**"
+ repowise.dev/criticality: critical
+ repowise.dev/tags: "pci, customer-facing"
+spec:
+ type: service
+ owner: group:default/payments-team
+ lifecycle: production
+```
+
+With no file, components are derived from workspace services, module pages or
+top-level directories, so every repository has them from the first index. A full
+example is in [examples/components](../../examples/components/components.yaml).
+
+## Declared owners against recent activity
+
+Owners come from the catalog, CODEOWNERS (GitHub, and GitLab with sections) and an
+optional `.repowise/teams.yaml`. `repowise components ownership` compares them with the
+last 90 days of commits and flags a critical component with no active owner, an owner
+with no recent changes on its files, a bus factor of 1 on a critical component, and a
+catalog entry that claims no files. Findings name components and teams. Individuals
+are counted, never named.
+
+## Changes over time
+
+Every `init` and `update` stores a snapshot per component. What moved since the last
+run becomes a typed event (ownership shift, bus factor drop, new hotspot, contract
+broken, decision stale, dead-code growth, test reach drop), written as CloudEvents to
+`.repowise/events.jsonl` and listed by `repowise events`.
+
+## Packages
+
+`repowise packages where <name>` lists where a third-party package is imported, with
+the component, owner teams and reachability. `repowise packages export --format
+cyclonedx` writes that usage as CycloneDX 1.6, and `repowise packages import` joins an
+SBOM or advisory file you already have to the import sites. Nothing is fetched. See
+[package usage](../reference/PACKAGE_USAGE.md).
+
+```bash
+repowise components list
+repowise components ownership
+repowise events --since 30d
+repowise packages where log4j-core
+```
+
+Every field: [CONFIG.md](../reference/CONFIG.md#repowisecomponentsyaml) and the
+[CLI reference](../reference/CLI_REFERENCE.md#repowise-components).
diff --git a/docs/layers/INTELLIGENCE_LAYERS.md b/docs/layers/INTELLIGENCE_LAYERS.md
index 514444a57..d517e11bd 100644
--- a/docs/layers/INTELLIGENCE_LAYERS.md
+++ b/docs/layers/INTELLIGENCE_LAYERS.md
@@ -97,6 +97,21 @@ against real bug history. The same machinery judges a change before it merges.
| Tests and coverage gates | Impacted tests, patch coverage, untested hotspots | [TEST_INTELLIGENCE.md](TEST_INTELLIGENCE.md), [CI.md](../start/CI.md) |
| Security signals | Secrets and risky calls, with a pre-commit check and a CI gate | [SECURITY.md](SECURITY.md) |
+## Changes and components: where the layers roll up
+
+Two units collect the layers into things an organisation names. A Change Record is one
+merged change with its evidence from every layer: owners, reaching tests, contracts,
+decisions crossed, provenance and later outcome. A component is a declared or derived
+part of the codebase that health, hotspots, bus factor, test reach and dead code roll up
+to. Change policy and evidence reports are built on both.
+
+| Built on it | What you get | Read more |
+|---|---|---|
+| Change Records | Each merged change with its evidence checklist and outcomes, and suspects for a symptom | [CHANGES.md](CHANGES.md) |
+| Components | Backstage-shaped components, declared owners against recent activity, events, package usage | [COMPONENTS.md](COMPONENTS.md) |
+| Change policy | Rules over a change's evidence, checked locally or in CI | [POLICY.md](POLICY.md) |
+| Evidence reports | Assessment, change evidence and inventory packs | [REPORTS.md](REPORTS.md) |
+
## Where the layers meet
The most useful answers cross layers. A few examples:
diff --git a/docs/layers/POLICY.md b/docs/layers/POLICY.md
new file mode 100644
index 000000000..4b9743c17
--- /dev/null
+++ b/docs/layers/POLICY.md
@@ -0,0 +1,51 @@
+# Change Policy
+
+A change policy holds some changes to a higher bar than others. Rules live in
+`.repowise/policies.yaml`, next to the code they govern, and `repowise check` evaluates
+them against any change, locally or in CI. Nothing is sent anywhere.
+
+```yaml
+version: 1
+rules:
+ - name: payments-need-tests
+ match:
+ components: {tags: [pci]}
+ when:
+ reaching_tests: missing
+ action: require_tests
+ - name: no-silent-contract-breaks
+ when:
+ contract_break: true
+ action: fail
+ - name: no-new-secrets
+ gate: security
+ with: {fail_on: high}
+ action: fail
+```
+
+## What a rule can look at
+
+A rule selects [components](COMPONENTS.md) by name, tag or criticality, then tests
+conditions over the change's [evidence checklist](CHANGES.md): provenance, reaching
+tests, contract breaks, decisions crossed and bus factor. A rule can also wrap an
+existing gate (`security`, `coverage` or `doc_drift`), which then runs exactly as the
+command does on its own. There is no risk-score condition: rules rest on evidence you
+can check.
+
+A condition whose evidence is not available, for example with no index, is reported
+as not evaluated and never fires.
+
+## Running it
+
+```bash
+repowise check main..HEAD
+repowise check main..HEAD --sarif-file policy.sarif --junit-file policy.xml
+```
+
+Actions are `warn`, `require_owner_review`, `require_tests` and `fail`. Only `fail`
+exits 1; the others are reported in every format. SARIF 2.1.0 feeds GitHub code
+scanning or reviewdog, and JUnit shows up in any CI test view. Teams that already run
+OPA can pass the `evidence` object from `--format json` to Rego.
+
+Every key, condition and exit code: [CONFIG.md](../reference/CONFIG.md#repowisepoliciesyaml)
+and [CLI reference](../reference/CLI_REFERENCE.md#repowise-check-revspec).
diff --git a/docs/layers/REPORTS.md b/docs/layers/REPORTS.md
new file mode 100644
index 000000000..86bfa8612
--- /dev/null
+++ b/docs/layers/REPORTS.md
@@ -0,0 +1,36 @@
+# Evidence Reports
+
+`repowise report` writes documents a team hands to someone else: an auditor, an
+acquirer, a board or a migration committee. Each is built from the local index, and
+JSON is the canonical form, with Markdown, CSV and a self-contained HTML file that
+opens offline.
+
+| Report | What it holds | Typical reader |
+|---|---|---|
+| `report assessment` | Component posture, hotspots, bus factor, dead code by tier, test reach, contracts, governing decisions, provenance coverage and what moved in the last quarter | Acquirer, board, platform lead, migration committee |
+| `report changes` | Every change merged in a period: components and owning teams, review record, reaching tests, policy verdict, provenance and later outcome, with a period summary | Auditor reviewing change management (SOC 2 CC8.1, ISO 27001 A.8.32, PCI DSS 6.5) |
+| `report inventory` | Components with owner teams, languages, entry points and the packages they import | Software inventory review (PCI DSS 6.3.2) |
+
+```bash
+repowise report assessment --format html --out assessment.html
+repowise report changes --since 2026-07-01 --format markdown --out q3-changes.md
+repowise report inventory --format csv --out inventory.csv
+```
+
+In a workspace, `report assessment` and `report inventory` cover every repository.
+
+## How to read them
+
+Every item says how it is known: `measured`, `inferred`, `declared` or `unresolved`.
+Missing evidence is reported as unresolved, never as a low score or a pass. Assessment
+items keep the OpenSSF Scorecard check shape, so existing tooling can read them. The
+change report ends with a method appendix that states what git alone cannot attest,
+such as a review that left no trace in the history.
+
+The reports describe code and components. Owners and reviewers are counted, never
+ranked or named, and local paths are removed. They are evidence for a review, not a
+certification.
+
+Sections and renderers are plugin seams, so an organisation can add its own section
+or output format. Every section and option: the
+[CLI reference](../reference/CLI_REFERENCE.md#repowise-report-assessment-path).