Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs: add layer pages for AI attribution and Change Records (#3775)
Raghav Chamadiyaf4b78c8dd27d
diff --git a/docs/README.md b/docs/README.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 searchablediff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.mdindex 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:` blockdiff --git a/docs/start/DASHBOARD.md b/docs/start/DASHBOARD.mdindex 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-shapescore distribution, acode-evolution chart, commit-category breakdowns, and AI-agent provenancebadges 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)). Therisk 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>`