---
schema_version: 1
id: RAC-KTYZNG3QZ5R0
type: roadmap
---
# RAC v0.12.0 — Repository Review

## Status

Planned

## Context

RAC's intelligence today describes the current state of a repository:
validation, relationships, statistics, and the prioritised findings of
`rac review`. Watchkeeper — the product knowledge review surface defined
in the Product Intent CI requirement — needs intelligence about change:
what differs between a base revision and a head revision, before any
judgement about whether the difference matters.

This milestone introduces repository comparison. It compares two
repository states and reports changed artifacts, validation deltas,
relationship deltas, and statistics deltas. It does not classify
findings or recommend review; those arrive in v0.12.1 and v0.12.2.

The original draft of this series planned to reuse `rac review` for
comparison. That name shipped with current-state semantics and keeps
them; comparison lives under a new `rac watchkeeper` command that
starts here as a skeleton and grows additively across the series.

## Outcomes

- A user can compare two repository states — a git revision against the
  working tree, or any two directories — through one command.
- Added, modified, and removed artifacts are identified across every
  artifact family, with per-artifact requirement diffs where available.
- Validation, relationship, and statistics changes between the states
  are reported as deltas, not as two reports to eyeball.
- The comparison model is reusable by future consumers — intent
  analysis, Watchkeeper recommendations, CI, MCP, agents — without
  re-walking either corpus.

## Initiatives

### Initiative 1 — Comparison Service

A comparison service in the services layer loads each state once
(corpus-once pattern) and derives every delta from the existing
`Repository` model: changed artifacts matched by corpus-relative path,
validation deltas from per-file statuses, relationship deltas from
relationship diagnostics, statistics deltas from the portfolio. No new
analysis logic — comparison consumes what Core already computes.

### Initiative 2 — Revision Materialization

A single git-aware module materializes a corpus directory for a named
revision using `git archive`, extracted to a temporary directory and
limited to the corpus subpath. The comparison service itself stays
git-free: both sides of a comparison are plain directories. ADR-043
records this decision and its alternatives.

### Initiative 3 — Watchkeeper Command Skeleton

`rac watchkeeper [directory] --base REF [--head REF] [--json]` renders
the comparison as a human report (Changed, Validation, Relationships,
Repository Changes) and as stable JSON. Base and head accept either a
git revision or an existing directory path.

### Initiative 4 — Contract Battery

Fixture corpora exercising added, modified, removed, newly invalid, and
newly broken-relationship artifacts; service batteries for comparison
and revision materialization; golden cases pinning the human and JSON
output byte-for-byte using directory-to-directory comparison so the
goldens never depend on git state.

## Constraints

- Every delta is derived from the existing `Repository` model; the
  comparison service introduces no independent analysis (ADR-015).
- JSON output carries `schema_version: "1"` and grows only additively
  across the series (ADR-007).
- Revision materialization is offline and read-only: no network, no
  `.git` mutation, no worktree registration.
- All orderings are deterministic: change-kind then path for changes,
  schema order for type counts.
- `rac review` behaviour and contracts are untouched.

## Non-Goals

- Intent analysis or any classification of why a change matters
  (v0.12.1)
- Review recommendations, exit-code policy, or GitHub output (v0.12.2)
- GitHub Action or workflow integration (v0.12.3)
- Rename detection — a renamed artifact reports as removed plus added
- Comparing more than two states, or historical drift reports

## Implementation Contract

The following decisions are pinned for v0.12.0.

### Module Locations

- Comparison: `src/rac/services/compare.py` — `RepoState`,
  `load_state`, `compare_states`, and the delta dataclasses
  (`ArtifactChange`, `ValidationDelta`, `RelationshipDelta`,
  `StatsDelta`, `RepositoryComparison`).
- Revision materialization: `src/rac/services/revisions.py` — the only
  git-aware module in the package; `materialized_revision(repo_root,
  rev, subpath)` context manager, `RevisionNotFound` and
  `NotAGitRepository` errors.
- Report assembly: `src/rac/services/watchkeeper.py` —
  `build_watchkeeper_report(directory, base, head)` and
  `WatchkeeperReport.to_dict()`.
- Rendering: `render_watchkeeper_human` and `render_watchkeeper_json`
  in the output layer.

### CLI and Exit Codes

- `rac watchkeeper [directory] --base REF [--head REF] [--json]`.
- `directory` defaults to `rac` when present, else `.`; `--base`
  defaults to `main`; `--head` defaults to the working tree.
- Base and head values naming an existing directory are used as-is;
  anything else is resolved as a git revision of the repository
  containing `directory`.
- Exit 0 always in this milestone (comparison is informational until
  recommendations exist); exit 2 for usage errors, unknown revisions,
  and non-git repositories when a revision is requested.
- A revision that does not contain the corpus subpath yields an empty
  base corpus: a brand-new corpus is a valid everything-added review.

### JSON Shape

Top-level keys: `schema_version` (`"1"`), `base`, `head`, `directory`,
`changes` (array of change/type/id/title/path/base_status/head_status
plus requirement-level diff for modified artifacts), `validation`,
`relationships`, `stats`. Artifact matching is by corpus-relative path.

## Success Measures

- Comparing the fixture corpora reports exactly the planted added,
  modified, removed, newly invalid, and newly broken cases — nothing
  more, nothing less — pinned by goldens.
- `rac watchkeeper rac --base main` runs green on this repository on a
  branch with corpus changes and reports them accurately.
- Revision materialization round-trips a corpus byte-for-byte from a
  throwaway git repository and fails cleanly (exit 2) on unknown
  revisions.

## Risks

- Path-based matching reports renames as removed plus added, which can
  overstate churn. Accepted and documented; identity-based rename
  detection is future work.
- A default base of `main` may not exist in CI checkouts. Mitigated:
  the CLI fails with exit 2 and a clear message; CI consumers pass an
  explicit base (v0.12.3).

## Assumptions

- Originally drafted as the v0.9.x watchkeeper series; renumbered to
  v0.12.x because the v0.9.x identities were released as the Explorer
  series, main already carries the v0.10.x Guide series through
  v0.10.6, and v0.11.x is allocated to other in-flight work.
- Release-tagging cadence discussions (calendar versioning) are
  deferred and out of scope for this series.

## Related Decisions

- ADR-007
- ADR-013
- ADR-015
- ADR-027
- ADR-043

## Related Requirements

- rac-product-intent-ci-watchkeeper
- rac-repository-review-mode
