---
schema_version: 1
id: RAC-KV2E59A2KK2H
type: roadmap
---
# RAC v0.13.4 — Commit-Time Nudge

## Status

Planned

## Context

The cadence nudge (v0.13.3) only fires when a user remembers to run
`rac review --stale-after`. The whole problem is that they stop
remembering. To make the write habit ambient, the nudge needs to reach
the user where they already are — at the git commit — without anyone
having to invoke RAC.

Git hooks are the standard mechanism, and RAC already ships installable
resources the right way: `rac skill install` writes bundled Claude Code
skills as package resources, never overwriting, with `--json` and the
established exit-code convention. This milestone mirrors that exactly for
a git hook: `rac hook install` writes a bundled hook script into
`.git/hooks`.

The hook is a post-commit advisory by default: after each commit it runs
a lightweight cadence check and prints the nudge, and it never blocks the
commit. A non-blocking nudge builds the habit without punishing it — a
pre-commit gate that fails commits would add the very friction that
erodes retention. A `--style pre-commit` option exists for teams that
want validation enforced, but the default protects the habit.

## Outcomes

- A user installs a commit-time cadence nudge with one command
  (`rac hook install`), mirroring `rac skill install`.
- By default the hook is post-commit and advisory: it surfaces the
  cadence nudge after a commit and never blocks committing.
- Teams that want enforcement opt into `--style pre-commit`, which
  validates staged artifacts before the commit completes.
- Installation never overwrites an existing hook, ships from the wheel as
  a package resource, and follows the established CLI contract (human and
  `--json` output, conventional exit codes).

## Initiatives

### Initiative 1 — Bundled Hook Resources

Hook scripts ship as package resources (under `rac.hooks`), loaded with
`importlib.resources`, mirroring `rac.skills` and `rac.templates`
(ADR-021): a `post-commit` advisory script and a `pre-commit` validation
script, each a thin shell wrapper that invokes the `rac` CLI and degrades
gracefully when `rac` is not on PATH.

### Initiative 2 — `rac hook install` Command

`rac hook install [--dir PATH] [--style post-commit|pre-commit]` writes
the selected hook into `<dir>/.git/hooks/<hook>`, creating nothing it
should not, never overwriting an existing hook file, and making the
script executable. `rac hook list` enumerates the bundled hooks. Output
and exit codes follow the `rac skill` pattern: usage error for a missing
git directory, refusal (exit 1) when a hook already exists.

### Initiative 3 — Hook Behaviour

The post-commit script runs `rac review --stale-after` against the
repository's corpus and prints only the cadence nudge, swallowing other
output and always exiting 0 (advisory). The pre-commit script runs
`rac validate` on staged artifact files and exits non-zero only on
validation errors, blocking the commit.

## Constraints

- Never overwrite an existing hook file (the `rac skill install` posture):
  a populated `.git/hooks/<hook>` is refused, untouched, with exit 1.
- The post-commit hook never blocks a commit: it always exits 0 whatever
  the cadence result.
- Hooks degrade gracefully: if `rac` is not on PATH the script prints a
  one-line hint and exits 0, never breaking the user's commit flow.
- Hook scripts ship as resources and are byte-identical to any dogfood
  copy, enforced by a test (the `rac skill` byte-equality convention).

## Non-Goals

- A hook manager, chaining with existing hooks, or `pre-commit`-framework
  (the tool) integration — RAC writes one script, it does not orchestrate
  hook ecosystems.
- Installing into `core.hooksPath` or non-default hook directories beyond
  what `--dir` resolves.
- Server-side hooks, CI integration (watchkeeper already covers CI), or
  any network behaviour.

## Implementation Contract

The following decisions are pinned for v0.13.4.

### Command

- `rac hook install [--dir PATH] [--style post-commit|pre-commit]
  [--json]` and `rac hook list [--json]`.
- `--dir` defaults to the current directory and must contain a `.git`
  directory (usage error, exit 2, otherwise).
- `--style` defaults to `post-commit`.

### Behaviour and exit codes

- Success: write `<dir>/.git/hooks/<hook>` (executable), exit 0.
- Refuse (exit 1): the target hook file already exists — left untouched.
- Operational error (exit 1): the bundled hook resource is missing
  (broken installation), mirroring `SkillResourceMissing`.
- Usage error (exit 2): `--dir` has no `.git` directory, or an unknown
  `--style`.

### Output

- Human: the installed hook path and a one-line description of what it
  does. `--json`: `{schema_version, installed, hook: {style, path}}`.

## Success Measures

- `rac hook install` in a git repository writes an executable
  `post-commit` hook; a commit afterward prints the cadence nudge and
  succeeds.
- `rac hook install --style pre-commit` then committing a corpus with an
  invalid artifact blocks the commit; fixing it lets the commit through.
- Re-running `rac hook install` with a hook already present exits 1 and
  leaves the existing hook untouched.
- The bundled hook resources are byte-identical to their dogfood copies,
  asserted by a test.

## Risks

- A pre-commit gate could frustrate users and reduce the habit it means
  to build. Mitigated: post-commit advisory is the default; pre-commit is
  an explicit opt-in.
- Hooks live outside version control (`.git/hooks` is not committed), so
  the install must be re-run per clone. Mitigated: documented, and the
  command is one line; teams wanting committed hooks use `core.hooksPath`
  themselves.

## Assumptions

- The user has git installed and a `.git` directory present; `rac hook`
  does not initialise repositories.
- A non-blocking nudge is the right default for retention; enforcement is
  the exception, not the rule.

## Related Decisions

- adr-007
- adr-013
- adr-021

## Related Requirements

- rac-growth-adoption

## Related Roadmaps

- v0.13.3-cadence-nudge
