---
schema_version: 1
id: RAC-KTQ63DYJ1D1R
type: roadmap
---
# RAC v0.7.9 — Repository Review

## Problem

RAC's repository intelligence exists as separate commands (`validate`, `relationships`,
`portfolio`, `improve`). Users must know which primitive to run and combine the results
themselves to answer:

> What needs attention in this repository?

REQ-Repository-Review-Mode asks for a single review entry point. REQ-Trust-Transparency
asks the repository itself to demonstrate determinism: golden output tests, a visible CI
badge, and a corpus that RAC validates dogfood-style. Both are Proposed with no
implementation, and the documented workflow `rac validate rac/` does not work because
`validate` rejects directories.

---

## Outcomes

- A repository can be reviewed with one command: `rac review <directory>`.
- `rac review --json` provides a stable automation contract for CI, agents, and Explorer.
- `rac validate <directory>` works as documented in `docs/repo-workflow.md`.
- RAC's own corpus under `rac/` passes its own validation and relationship checks,
  enforced by a CI dogfood battery.
- Output determinism for core commands is locked by golden output tests.
- The README signals trust: CI badge plus a short determinism section.

---

## Initiatives

### Initiative 1 — Directory Validation

`rac validate <directory>` shall validate every recognized artifact beneath a directory.

- Classification picks the validator per file (same dispatch as single-file validate).
- Unknown-type files are reported as skipped, not failed — matching `rac portfolio`
  semantics. Single-file behavior is unchanged (legacy requirement fallback).
- Exit codes: 0 all recognized artifacts valid, 1 any invalid, 2 usage.

### Initiative 2 — Review Service

A `review` service in the RAC service layer (ADR-015: consumers render, never analyze)
shall aggregate existing intelligence — portfolio, validation, relationship resolution —
into one prioritized report.

Issue priority order (REQ-Repository-Review-Mode):

1. Invalid artifacts
2. Broken, ambiguous, self-referencing relationships
3. Unrecognized artifacts (missing required information)
4. Missing recommended sections

Each issue carries a deterministic suggested action (a runnable `rac` command or a
concrete edit). The service duplicates no analysis logic: it consumes
`build_portfolio_summary` and the relationship summary it already contains.

### Initiative 3 — Review CLI

```bash
rac review <directory>
rac review <directory> --json
```

Human output: artifact inventory, validation and relationship summaries, prioritized
issues, suggested actions, health score. JSON output: stable, additive contract
(ADR-007). Exit codes: 0 no priority-1/2 issues, 1 invalid artifacts or relationship
issues present, 2 usage.

### Initiative 4 — Corpus Dogfooding

Repair RAC's own corpus so the gate can be green:

- Fix the invalid roadmap artifact (`v0.7.10-artifact-templates.md` missing Outcomes).
- Repair all broken relationship references in `rac/designs/` and `rac/roadmaps/`
  (placeholder `ADR-XXX` entries, retitled references, roadmap references filed under
  Related Requirements).

Add a CI dogfood battery asserting zero invalid artifacts and zero relationship issues
in `rac/`.

### Initiative 5 — Golden Output Tests

Golden output tests (REQ-Trust-Transparency FR-4) shall pin the exact human and JSON
output of `validate`, `stats`, `diff`, `schema`, and `review` against committed
fixtures. Golden changes are intentional product changes, refreshed via an explicit
update flag.

### Initiative 6 — Trust Optics

- README gains the CI workflow badge (FR-6) and a short trust section (FR-10).
- No coverage badge until coverage reporting exists (FR-7).
- `docs/cli.md` documents `rac review` and directory validation.

---

## Success Measures

- `rac review rac/` exits 0 on the repository's own corpus.
- `rac validate rac/` runs as documented and exits 0.
- CI fails when corpus validation or relationship integrity regresses.
- Golden tests fail on any unintended output drift in covered commands.
- README displays live CI status.

## Assumptions

- Classification heuristics are unchanged in this release; legacy corpus documents that
  classify as Unknown remain Unknown and are surfaced (not failed) by review.
- The portfolio JSON contract may gain additive fields (ADR-007 allows additive change).

## Risks

- Golden tests add maintenance cost when output intentionally changes; mitigated by a
  single documented refresh flag.
- Corpus normalization (legacy roadmaps/prompts re-authored to their schemas) is larger
  than this release; deferred to a future roadmap item rather than rushed here.

## Non-Goals

- No artifact rewriting, scoring trends, or configurable review policies (future
  REQ-Repository-Review-Mode considerations).
- No Watchkeeper / PR integration (consumes review mode later, per
  REQ-Product-Intent-CI-Watchkeeper).
- No re-authoring of legacy corpus documents to force classification.

## Related Requirements

- rac-repository-review-mode
- rac-trust-transparency
- rac-documentation-structure

## Related Decisions

- ADR-007
- ADR-015
- ADR-027
