Repository navigation
Description
Problem
Repository guidance files (AGENTS.md, CLAUDE.md, nested AGENTS.md files, and the docs/ they link) are where many repositories state the rules a change must follow. Today they reach a reviewer only when an agent prompt tells it to open them in the checkout:
crdoes not read them; the dossier'srepo-guidance.mdcovers only.codereview/agentsprovenance (internal/dossier/dossier.go, "Separate review-guidance files are not used for this review").- With Keep claude_cli and codex_cli reviewer sessions independent of ambient instruction files #681, no adapter loads them implicitly either, which is the right default for isolation.
- The checkout a reviewer reads is the PR head. When a PR edits a guidance file, a reviewer that follows its prompt reads the edited rule, so a PR can loosen the rule it is judged against.
.codereview/agentsalready avoids this by reading from the base branch. - Each prompt has to rediscover which guidance files apply to which changed paths, and prompts differ in how well they do it.
In repositories that pair their AGENTS.md rules with a repo-local reviewer naming those rules, a meaningful share of findings cite the guidance document and section directly, so this input carries real review signal when it is present.
Proposal
Add a reviewer-facing dossier artifact, for example dossier/final/guidance-map.md, built from the pinned base SHA:
- For each changed path, list the guidance files that apply: root
AGENTS.mdandCLAUDE.md, and everyAGENTS.mdorCLAUDE.mdin the path's ancestor directories. - Store the base-branch content of each listed file under the run artifact directory, so reviewers read the trusted version rather than the PR head's.
- Mark guidance files the PR modifies, with a pointer to the diff, so a reviewer can judge the edit itself.
- Keep it a map plus file copies, not prompt text: reviewers read what they need, in line with the checkout-native design that avoids context stuffing.
Out of scope: following links from guidance files into docs/; agent prompts can still do that.
Open question
This changes the context every reviewer sees by default. It should be measured on a fixed PR set before it becomes the default, comparing findings that cite repository rules and false positives with and without the map. An opt-in profile or flag for the trial would make that comparison straightforward.
Acceptance
- Dossier artifact listing applicable guidance files per changed path, with base-SHA content copies and modified-by-PR markers.
- Guidance files changed by the PR do not alter the copies the reviewers receive.
- Measured comparison recorded before enabling by default.
Activity
feat(agents): add a starter agent catalog (#684)