---
schema_version: 1
id: RAC-KTYZNHHNC5Y6
type: roadmap
---
# RAC v0.12.2 — Watchkeeper

## Status

Planned

## Context

Comparison (v0.12.0) and intent analysis (v0.12.1) provide the
intelligence. Reviewers need a consolidated answer: does this change
need attention? This milestone completes the `rac watchkeeper` command
as RAC's product knowledge review surface — deterministic review
recommendations, a CI-ready exit-code policy, and a GitHub-oriented
output format — while remaining a pure consumer of Core intelligence.

Watchkeeper does not determine whether a change is correct. It
identifies changes requiring attention and says why.

## Outcomes

- A reviewer running one command sees changed artifacts, validation
  status, relationship impact, repository changes, intent findings, and
  a clear review verdict with reasons.
- CI systems control failure behaviour through one flag, with exit
  codes that mean the same thing everywhere.
- GitHub workflows get a rendering designed for them: a Markdown
  step-summary report and inline annotations pointing at the artifacts
  that triggered attention — without any GitHub API dependency.

## Initiatives

### Initiative 1 — Review Recommendations

A deterministic mapping from deltas and findings to recommendation
reasons: newly invalid artifacts, newly broken relationships, and the
clarity-regression findings (specificity regression, constraint
weakened or removed, acceptance criteria or success measures removed)
each recommend review with a Core-owned reason sentence. Ambiguity,
unlinked scope, and relationship impact inform but never recommend on
their own.

### Initiative 2 — Output Formats

`--format human|json|github`. The github format writes GitHub-flavored
Markdown to stdout (suitable for `$GITHUB_STEP_SUMMARY`) and workflow
command annotations (`::warning`/`::error` with file paths) to stderr,
so one invocation feeds both the job summary and inline annotations.
`--no-annotate` suppresses the annotation stream. `--json` remains as
an alias for `--format json`.

### Initiative 3 — Exit Policy

`--fail-on error|warning|none` (default `error`): `error` fails the
command when review is recommended; `warning` also fails on any
warning-severity finding; `none` never fails. Usage and revision errors
keep exit 2 regardless.

### Initiative 4 — Contract Battery

A watchkeeper battery pins the recommendation mapping, the fail-on
matrix, the annotation line format, and the github Markdown shape; a
github-format golden joins the human and JSON goldens.

## Constraints

- Recommendations are derived solely from v0.12.0 deltas and v0.12.1
  findings; Watchkeeper implements no independent intelligence
  (ADR-015).
- The JSON contract grows additively with a `review` block (ADR-007).
- The github format requires no network and no GitHub API: workflow
  commands and a Markdown document are plain text.
- Annotation file paths are repository-relative so GitHub can map them
  onto pull request files.

## Non-Goals

- Approving or rejecting changes automatically
- Posting comments or checks via the GitHub API
- Configurable review policies in `.rac/config.yaml` — `--fail-on`
  covers CI policy in this series; a policy block is future work
- Requiring GitHub: human and JSON formats remain first-class

## Implementation Contract

The following decisions are pinned for v0.12.2.

### Recommendation Mapping

- `validation_regression`: any path in `validation.newly_invalid`.
- `broken_relationship`: any issue in `relationships.new_issues`.
- Finding-driven: `specificity_regression`, `constraint_weakened`,
  `constraint_removed`, `acceptance_criteria_removed`,
  `success_measures_removed`.
- JSON gains `review`: `{"recommended": bool, "reasons":
  [{"code", "reason"}]}`; reasons are deduplicated by code and stably
  ordered.

### CLI and Exit Codes

- `--format human|json|github` (default `human`); `--json` is an alias
  for `--format json`.
- `--fail-on error|warning|none` (default `error`); `--no-annotate`
  applies only to the github format.
- Exit 0: nothing requiring attention under the chosen policy.
- Exit 1: review recommended (`error`), or additionally any warning
  finding (`warning`); never under `none`.
- Exit 2: usage errors, unknown revisions, not a git repository.

### GitHub Format

- stdout: a Markdown report — heading, changed-artifact table, delta
  summaries, findings list, verdict line with reasons.
- stderr: one workflow command per annotated finding —
  `::warning file=<path>::<code>: <detail>` for findings,
  `::error file=<path>::<code>: <reason>` for recommendation triggers.

## Success Measures

- The fail-on matrix behaves exactly as documented across fixture
  corpora with and without planted regressions, pinned by the battery.
- Redirecting github-format stdout to a file yields a complete,
  readable Markdown report; stderr contains only workflow commands.
- The roadmap example — changed artifacts, a missing relationship, a
  specificity regression, "Review Recommended" — reproduces end to end
  on fixtures.

## Risks

- Exit-code policy semantics are easy to get subtly wrong in CI.
  Mitigated: the matrix is pinned by tests and documented with the
  command.
- Workflow-command output formats drift on GitHub's side. Accepted:
  the commands used are the long-stable warning/error forms.

## Assumptions

- Part of the watchkeeper series originally drafted as v0.9.x and
  renumbered to v0.12.x (see v0.12.0 for the renumbering record).
- Step summaries and workflow commands remain the GitHub-native way to
  surface reports and annotations without API calls.

## Related Decisions

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

## Related Requirements

- rac-product-intent-ci-watchkeeper

## Related Roadmaps

- v0.12.0-repository-review
- v0.12.1-intent-analysis
