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: add layer pages for AI attribution and Change Records (#3775)

Raghav Chamadiyaf4b78c8dd27d
diff --git a/docs/README.md b/docs/README.md
index 0be57f110..5a1cd2fdb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -61,6 +61,13 @@ For a map of every layer and how they feed each other, read
| [layers/SECURITY.md](layers/SECURITY.md) | The local scan: 22 pattern kinds plus a symbol-name scan, history scanning for secrets, and its limits |
| [start/CI.md](start/CI.md) | Gate pull requests with the GitHub Action or the GitLab template |
+### Know what landed, and who wrote it
+
+| Doc | What it covers |
+|-----|----------------|
+| [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 |
+
### Know which tests matter
| Doc | What it covers |
diff --git a/docs/layers/ATTRIBUTION.md b/docs/layers/ATTRIBUTION.md
new file mode 100644
index 000000000..a8b4112fe
--- /dev/null
+++ b/docs/layers/ATTRIBUTION.md
@@ -0,0 +1,127 @@
+# AI Attribution
+
+Which commits an AI agent wrote, read from evidence a repository already carries, with
+optional edit-time capture for the agents you choose. Every commit gets one of three
+labels, and every share is shown with the coverage behind it.
+
+| Label | Meaning |
+|---|---|
+| `agent` | A marker or a captured edit ties the commit to an agent |
+| `human_attested` | An explicit human record: a git-ai note naming only human authors, or an Agent Trace record whose contributors are all `human` |
+| `unknown` | No marker either way. Unknown is never counted as human |
+
+## What is read by default
+
+With no configuration, indexing reads public markers from local git history. No network
+calls, no model, no prompts.
+
+| Marker | Example |
+|---|---|
+| Bot author or committer | `copilot-swe-agent[bot]`, `devin-ai-integration[bot]`, `[email protected]` |
+| Message footer | `Generated with Claude Code`, the aider `(aider)` author suffix |
+| Trailers | `Co-authored-by:` naming an agent service identity, `Assisted-by:`, `Generated-by:` |
+| git-ai notes | Authorship notes on `refs/notes/ai` ([git-ai standard](https://github.com/git-ai-project/git-ai)) |
+| Agent Trace | `.agent-trace/traces.jsonl` records committed to the repository |
+
+Every pattern is anchored to a service identity (a bot login, a service email, an exact
+footer phrase), never a bare name, so a contributor called Devin stays unlabelled.
+
+To recognise your own bot or footer, add it under `agent_provenance:` in
+`.repowise/config.yaml`:
+
+```yaml
+agent_provenance:
+ service_emails:
+ [email protected]: {agent: mybot, tier: 1}
+ footer_patterns:
+ - {pattern: "Generated by MyBot", agent: mybot}
+```
+
+## Edit-time capture (opt-in)
+
+Capture records which lines an agent wrote as it writes them, so commits carry a label
+even when nothing in the message says so. It is off until both the repository and your
+user config turn it on.
+
+| Agent | Capture |
+|---|---|
+| Claude Code | `PostToolUse` hook installed with the agent hooks |
+| Codex CLI | `PostToolUse` hook installed with the agent hooks |
+| Cursor | `afterFileEdit` hook: `repowise agents add --target=cursor --scope=user` |
+
+Other agents are read through public markers only. The `Attribution` column of
+[INTEGRATIONS.md](../agent/INTEGRATIONS.md) is the live list.
+
+The hook stores line hashes, the repo-relative path, an opaque session id, the tool and
+the model in `.repowise/attribution/events.jsonl`, never prompts or code. `repowise update` (which the
+post-commit hook runs) matches those hashes to the lines new commits added and labels a
+matched commit with the agent. An unmatched commit stays `unknown`.
+
+### `local` and `notes`: what leaves the machine
+
+| Level | Writes | Leaves the machine |
+|---|---|---|
+| `off` (default) | Nothing | Nothing |
+| `local` | The sidecar under `.repowise/attribution/` (gitignored) and labels in the local index | Nothing |
+| `notes` | Everything `local` writes, plus a git-ai v3 note per matched commit on `refs/notes/ai`, and `notes.rewriteRef` so the note follows an amend or rebase | Only when you run `git push origin refs/notes/ai`. Repowise never pushes |
+
+A note holds file paths, line ranges, the tool name, the model and a hashed session id.
+It never holds prompts, code, conversation ids or a person's identity. A commit that
+already has a note keeps it; Repowise only writes notes on commits without one.
+
+## Turning it on and off
+
+```yaml
+# .repowise/config.yaml and ~/.repowise/config.yaml
+attribution:
+ enabled: true # read public markers
+ capture: off # off, local or notes
+ agents: [] # agent target ids, e.g. claude-code, codex, cursor
+```
+
+The stricter value wins per key across the repo and user files:
+
+- `enabled: false` in either file means nothing about AI is stored or shown on any surface.
+- `capture` takes the lower of the two levels, and an unset key counts as `off`.
+- `agents` is the set both files list.
+- `DO_NOT_TRACK=1` keeps capture off.
+- An invalid value counts as the strictest value and is reported by `status`.
+
+Key reference: [CONFIG.md](../reference/CONFIG.md#the-attribution-block).
+
+## Status, purge and doctor
+
+| Command | What it does |
+|---|---|
+| `repowise attribution status [--format json]` | Effective, repo and user values, why any differ, capture per agent, sidecar counts, and commits by label with coverage |
+| `repowise attribution purge [--yes]` | Deletes the index labels and file rollups, the `.repowise/attribution/` sidecar and the notes Repowise wrote locally. Git history, trailers and notes written by anything else stay |
+| `repowise doctor` | At `capture: notes`, checks the fetch refspec, the push refspec and `notes.rewriteRef`, and names the command for anything missing |
+
+## Where it shows
+
+| Surface | What you see |
+|---|---|
+| CLI | `repowise attribution status` |
+| REST | `GET /api/repos/{id}/commits?authorship=agent\|human\|unknown`, `GET /api/repos/{id}/commits/agent-trend` (monthly counts per label, coverage, share) |
+| Web | Commits page: agent badges, an authorship filter and a 12-month trend strip |
+| MCP | `get_context` file cards: agent share and coverage, when the file has agent commits |
+| Change Records | A three-state provenance block per change. See [CHANGES.md](CHANGES.md) |
+
+## Coverage and the share
+
+Coverage is the fraction of commits with a known source (`agent` plus
+`human_attested`). The AI share is the agent fraction of those covered commits, always
+printed beside its coverage, for example "at least 40% of covered commits, coverage
+62%". Below 30% coverage the share is withheld and only the count is shown.
+
+## Limits
+
+- Squash merges that drop trailers lose those markers. PR-level signals (bot PR author,
+ branch names, PR body) need forge APIs and are outside the local reader.
+- Capture labels a commit only when a run of at least two consecutive substantive
+ lines from one agent matches. One-line edits, lines repeated three or more times in a
+ file, and lines two agents both claim stay unmatched.
+- Pending capture events expire after 14 days. Each `update` binds at most 50 new
+ commits and resumes from where it stopped.
+- Capture sees edits made on this machine. Teammates' work reaches you through their
+ own capture or through notes they push.
diff --git a/docs/layers/CHANGES.md b/docs/layers/CHANGES.md
new file mode 100644
index 000000000..a43667d45
--- /dev/null
+++ b/docs/layers/CHANGES.md
@@ -0,0 +1,118 @@
+# Change Records
+
+A Change Record is one merged change (a pull request, a merge request, or a lone
+commit) read back from git: what landed, from which commits, touching which files,
+with what provenance. `repowise init` builds the records and every `repowise update`
+extends them. No forge API is called.
+
+## How changes are reconstructed
+
+The first-parent chain of `HEAD` is the sequence of things that landed. Each
+first-parent commit becomes one change:
+
+| What landed | Shape | Commits in the change | Files |
+|---|---|---|---|
+| A merge commit | `merge` | The commits its branch brought in (`M^1..M^2`) | The merge against its first parent |
+| A squash commit naming a PR or MR | `squash` | The squash commit | That commit's diff |
+| Any other commit | `commit` | The commit itself | That commit's diff |
+
+- A merge that names no change of its own (`Merge branch 'main' of ...`, a release
+ branch merged back) gives up the named squash commits and PR merges inside it as
+ their own changes. It keeps the rest, and is dropped when nothing is left.
+- Rebase merges leave no grouping in git, so each rebased commit is its own change.
+- A merge's title comes from its body when the subject is boilerplate (`Merge pull
+ request #12 from ...`). Its author is the author of the branch's oldest commit.
+- The window is the repository's `commit_limit` first-parent commits. An update reads
+ only what landed after the newest stored change, and rebuilds after a rebase or
+ branch switch.
+
+## Identity
+
+The first that applies:
+
+| Order | Source | Id |
+|---|---|---|
+| 1 | A PR or MR number the message names, read per forge (GitHub, GitLab, Bitbucket, Azure DevOps) | `pr-123` |
+| 2 | A Gerrit `Change-Id:` trailer | `change-I<40 hex>` |
+| 3 | The merge commit | `merge-<sha>` |
+| 4 | The commit | `commit-<sha>` |
+
+A number that appears twice (a PR cherry-picked onto the main line) gets a suffixed id,
+and the change that holds the plain id keeps it across runs.
+
+## Provenance
+
+Each change carries the three-state label from [AI attribution](ATTRIBUTION.md),
+rolled up over its commits, with the counts and coverage behind it:
+
+| Label | When |
+|---|---|
+| `agent` | Any commit in the change is agent-attributed |
+| `human_attested` | Every commit is human-attested |
+| `unknown` | Anything else |
+
+```json
+"provenance": {
+ "label": "agent",
+ "agent_commits": 2,
+ "human_attested_commits": 0,
+ "unknown_commits": 3,
+ "coverage": 0.4
+}
+```
+
+With `attribution.enabled: false` the block is `null`.
+
+## Metadata
+
+Reviewers, approvals, labels and linked issues come through the
+`ChangeMetadataSource` seam. The default source, `git`, reads only what history
+holds: the `Approved-by:` trailers GitLab writes on merge commits, and the issues a
+message closes (`Fixes #12`). A field it cannot read is `null`, which means unknown.
+
+A plugin registers another source under `SeamRegistry("change-metadata")`, selected
+with `REPOWISE_SEAM_CHANGE_METADATA`. See
+[pluggable storage and capability seams](../architecture/pluggable-storage.md).
+
+## Where it shows
+
+| Surface | Use |
+|---|---|
+| CLI | `repowise changes list [--category C] [--shape merge\|squash\|commit] [--grep TEXT]`, `repowise changes show REF [--format table\|json\|in-toto]` |
+| REST | `GET /api/repos/{id}/changes` (filters `category`, `shape`, `q`), `GET /api/repos/{id}/changes/{change_id}` |
+| Web | Changes page with category filters, and a detail page per change |
+
+`show` and the detail route accept a change id or any commit sha the change landed.
+Full flags: [CLI_REFERENCE.md](../reference/CLI_REFERENCE.md#repowise-changes).
+
+## The record and its in-toto export
+
+Every surface serves one versioned JSON shape (`schema_version: 1`): id, identity,
+shape, forge reference, title, merge time, head sha, author, commits, files with
+added and deleted lines, category, provenance and metadata. Each record keeps up to
+1,000 files; `files_changed` carries the full count.
+
+`--format in-toto` wraps the same record as the predicate of an
+[in-toto Statement v1](https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md)
+with predicate type `https://repowise.dev/ChangeRecord/v1`. Its subjects are the
+change's commits, keyed by `gitCommit` digest. It claims no SLSA level.
+
+## Accuracy
+
+Measured on the last ~100 merged pull requests of each repository, a change counts
+as correct when its file set matches the forge's:
+
+| Repository | Forge | Correct |
+|---|---|---|
+| repowise | GitHub | 100% |
+| express | GitHub | 98.7% |
+| gitleaks | GitHub | 97.9% |
+| flask | GitHub | 99.0% |
+| fd | GitHub | 98.9% |
+| gitlab-dangerfiles | GitLab | 100% |
+
+## Limits
+
+- Reviewers and labels stay `null` with the default source; git does not record them.
+- A partial clone (`--filter`) gets no Change Records: reading file stats there would fetch blobs.
+- Changes before the `commit_limit` window are not read.
diff --git a/docs/layers/INTELLIGENCE_LAYERS.md b/docs/layers/INTELLIGENCE_LAYERS.md
index 41d918c4a..47ae40636 100644
--- a/docs/layers/INTELLIGENCE_LAYERS.md
+++ b/docs/layers/INTELLIGENCE_LAYERS.md
@@ -51,6 +51,8 @@ no import between them can still change together every week.
| Hidden coupling | Files that change together with no import link | [CHANGE_RISK.md](CHANGE_RISK.md) |
| Branch overlap | Other branches editing the same files or their co-change partners | [CHANGE_RISK.md](CHANGE_RISK.md#branch-overlap) |
| Secrets in history | Keys and tokens anywhere in the full history, not only the working tree | [SECURITY.md](SECURITY.md) |
+| Change Records | Each merged PR, MR or commit with its commits, files and provenance, exportable as in-toto | [CHANGES.md](CHANGES.md) |
+| AI attribution | Agent, human-attested or unknown per commit, from public markers and opt-in edit capture, with coverage | [ATTRIBUTION.md](ATTRIBUTION.md) |
## 3. Docs: the codebase, readable and searchable
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index bb340c386..a18207ad3 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -622,7 +622,7 @@ attribution:
The same block in `~/.repowise/config.yaml` applies to every repository, and the stricter value wins per key: `enabled: false` in either file, the lower capture level, and the agents both files list. With `enabled: false` nothing about AI is stored or shown in the API, CLI, MCP, web or wiki, and `DO_NOT_TRACK=1` keeps capture off. `repowise attribution status` shows the effective, repo and user values with the coverage of the indexed history.
-With `capture: local` the edit hooks of the listed agents (those with `Yes` under Attribution in [INTEGRATIONS.md](../agent/INTEGRATIONS.md)) record which lines the agent wrote, as hashes with the file, session and model, in `.repowise/attribution/`; prompts and code are never stored. `repowise update` matches them to new commits by content and labels a matched commit with the agent; an unmatched commit stays unknown. `capture: notes` also writes a git-ai v3 note on `refs/notes/ai` and sets `notes.rewriteRef` so the note follows a local amend or rebase; teammates see notes once you `git push origin refs/notes/ai` and add the fetch refspec `repowise doctor` names. Cursor records edits through an `afterFileEdit` hook, which `repowise agents add --target=cursor --scope=user` adds once your user config captures Cursor.
+`capture: local` records the listed agents' edits as line hashes in `.repowise/attribution/`; `capture: notes` also writes git-ai notes on `refs/notes/ai`. What each level stores, and what leaves the machine, is in [ATTRIBUTION.md](../layers/ATTRIBUTION.md).
### The `refactoring:` block
diff --git a/docs/start/DASHBOARD.md b/docs/start/DASHBOARD.md
index c4277b578..aa90ba09b 100644
--- a/docs/start/DASHBOARD.md
+++ b/docs/start/DASHBOARD.md
@@ -260,10 +260,21 @@ The commit table led by repo-relative review priority, a supporting diff-shape
score distribution, a
code-evolution chart, commit-category breakdowns, and AI-agent provenance
badges plus their trend over time, shown as agent, human-attested and unknown
-commits with the agent share of covered commits beside its coverage. The
+commits with the agent share of covered commits beside its coverage (see
+[ATTRIBUTION.md](../layers/ATTRIBUTION.md)). The
risk model is documented in
[docs/layers/CHANGE_RISK.md](../layers/CHANGE_RISK.md).
+## Changes
+
+`/repos/<id>/changes`, `/repos/<id>/changes/<changeId>`
+
+**Answers:** what landed, from which commits, touching which files?
+
+Merged pull requests, merge requests and commits, newest first, filtered by
+category. Each detail page lists the commits, files, provenance and metadata of
+one Change Record. See [CHANGES.md](../layers/CHANGES.md).
+
## Contributors
`/repos/<id>/owners`, `/repos/<id>/owners/<owner>`