---
schema_version: 1
id: RAC-KTYZNJ8J7RMV
type: roadmap
---
# RAC v0.12.3 — Watchkeeper GitHub Action

## Status

Planned

## Context

With `rac watchkeeper --format github` complete (v0.12.2), teams still
have to write their own workflow YAML to get product knowledge review
on pull requests. This milestone removes that step: a thin composite
GitHub Action and a reusable workflow wrap the command, and this
repository adopts them on its own pull requests as the live test.

The action contains no logic. Policy, analysis, and rendering live in
the Python package; the action installs RAC, resolves the base
revision, runs one command, and routes its outputs to the step summary
and the job log. That keeps the contract testable in one place and the
action auditable at a glance.

## Outcomes

- A consumer adds product knowledge review to pull requests with a few
  lines of workflow YAML, either `uses:` on this repository's action or
  calling the reusable workflow.
- Pull requests touching the corpus get a step-summary report, inline
  annotations on the artifacts needing attention, and a check that
  fails according to the chosen policy.
- This repository's own pull requests run Watchkeeper from source —
  continuous proof the action works.

## Initiatives

### Initiative 1 — Composite Action

A root-level `action.yml` (composite) with inputs `path`, `base`,
`fail-on`, `annotate`, `rac-version`, and `install-from`. Steps: pin
Python, install RAC from PyPI (default) or from the action checkout
(source mode, for dogfooding), fetch the base ref, run
`rac watchkeeper --format github` with stdout to the step summary and
stderr to the log, and propagate the exit code unchanged.

### Initiative 2 — Reusable Workflow

`.github/workflows/watchkeeper.yml` with `on: workflow_call`
pass-through inputs, so consumers who prefer `uses:
<repo>/.github/workflows/watchkeeper.yml@<tag>` get checkout depth and
base-ref wiring for free.

### Initiative 3 — Dogfood Job

A watchkeeper job in this repository's PR checks using the local action
in source mode — every pull request here exercises the action end to
end against the real corpus.

### Initiative 4 — Documentation and Contract Battery

`docs/watchkeeper.md` covering the command, the action inputs, the
reusable workflow, and version pinning guidance; YAML contract tests
asserting the action's inputs, defaults, and invocation shape so the
wrapper cannot drift from the CLI silently.

## Constraints

- The action performs no analysis and makes no GitHub API calls; the
  only network use is installing RAC and the runner's own machinery.
- All failure policy stays in the CLI's `--fail-on`; the action never
  reinterprets exit codes (ADR-015's consumer posture).
- Consumers pin exact release tags. No moving major tag is published:
  package versions derive from git tags via setuptools-scm, and a
  floating tag would corrupt version derivation.
- Source-mode installs exist because an external action checkout lacks
  git metadata for setuptools-scm; PyPI mode is the consumer default.

## Non-Goals

- SARIF output or code-scanning integration
- A Node.js runtime, JavaScript action, or second toolchain
- A GitHub App, hosted service, webhook receiver, or dashboard
- GitHub API comments or checks — annotations come from workflow
  commands only
- Marketplace publication (may follow once the series has a release)

## Implementation Contract

The following decisions are pinned for v0.12.3.

### Action Inputs

- `path` (default `rac`): corpus directory passed to the CLI.
- `base` (default empty): base ref; when empty the action resolves
  `origin/<pull request base ref>`.
- `fail-on` (default `error`), `annotate` (default `true`): forwarded
  to the CLI.
- `rac-version` (default empty = latest release): PyPI version pin.
- `install-from` (`pypi` default | `source`): where to install RAC
  from; `source` installs the action checkout itself.

### Behaviour

- Python is pinned to a single tested minor (3.12) via the standard
  setup action.
- The run step executes exactly one CLI invocation:
  `rac watchkeeper <path> --base <base> --format github --fail-on
  <fail-on>` (plus `--no-annotate` when `annotate` is `false`), with
  stdout appended to the step summary.
- The job conclusion equals the CLI exit code; `fail-on: none` makes
  the check always green while still publishing the report.

## Success Measures

- A pull request against this repository that plants a clarity
  regression in a fixture corpus shows a failed watchkeeper check, an
  inline annotation, and a step-summary report.
- `fail-on: none` on the same change publishes the report with a green
  check.
- A consumer repository containing only a config and one valid artifact
  runs the action green from PyPI mode once the series is released.

## Risks

- PyPI-mode consumers need a released version carrying the watchkeeper
  command; until the series ships, only source mode works. Mitigated:
  the dogfood job uses source mode, and the docs state the minimum
  version.
- The base ref can be missing in shallow checkouts. Mitigated: the
  action fetches the base ref explicitly and documents checkout depth
  in the reusable workflow.

## 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); this
  item is new in v0.12.x — the original draft deferred GitHub
  integration without scoping it.
- Composite actions and workflow commands remain sufficient; nothing
  here needs a JavaScript action runtime.

## Related Decisions

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

## Related Requirements

- rac-product-intent-ci-watchkeeper

## Related Roadmaps

- v0.12.2-watchkeeper
