/ca-metrics

name: ca-metrics
description: Read-only 3-metric governance glance — override rate, small-lane rate, sprint low-confidence ratio — each with a trend arrow vs. the prior 20-commit window.
argument-hint: "[--window N]"

$ca-metrics — governance trend glance

A bare-numbers summary of the three governance-health metrics that `_metricslib.py` tracks across commit windows. Each metric shows its value for the **current** 20-commit window and a direction arrow (↑/↓/→) relative to the immediately preceding window.

This is NOT a second `$ca-audit` packet. It prints numbers and arrows only — no verbatim override lines, no commit list, no file write. Use it to spot a trend at a glance; reach for `$ca-audit` when you need the full evidentiary packet.

Flow

1. **Invoke the helper.** Call the thin entry hook `metrics.py`, which wraps `compute` from `_metricslib.py`. Resolve the interpreter once by presence — `PY=python3; { command -v python3 >/dev/null 2>&1 && python3 --version >/dev/null 2>&1; } || PY=python` — never `python3 … || python …`, which reruns the helper on any nonzero exit and reports the second run's code instead of the first's (#577). Pass `<project-root>` as `--root`. If `--window N` was supplied, pass it through as `--window N`; otherwise omit it (the helper applies the default of 20).

   "$PY" "${PLUGIN_ROOT}/hooks/metrics.py" --root "<project-root>"

> **`ensure_ascii` note — do not remove this.** `metrics.py` calls `json.dumps` > with its default `ensure_ascii=True`. This ASCII-escapes the arrow glyphs > (↑↓→) in the subprocess stdout, which avoids a `UnicodeEncodeError` on Windows > `cp1252` consoles that cannot encode those code-points raw. The rendered output > you present to the user (step 2 below) uses the real glyphs — they are written > by the assistant, not piped through the subprocess stdout. Do NOT add > `ensure_ascii=False` here.

With a custom window size:

   "$PY" "${PLUGIN_ROOT}/hooks/metrics.py" --root "<project-root>" --window N

Replace `N` with the integer the user supplied.

2. **Render the glance.** Parse the returned JSON dict. Present exactly three lines, one per metric, in this order:

   override rate:          <current>  <arrow>  (prior: <prior>)
   small-lane rate:        <current>  <arrow>  (prior: <prior>)
   sprint low-conf ratio:  <current>  <arrow>  (prior: <prior>)

• Use the real glyphs ↑, ↓, → in your message (not the JSON-escaped forms).
• For `sprint_low_conf_ratio`, the `current` or `prior` value may be the string

`"n/a"` — render it literally (e.g. `n/a ↑`).

• ↑ on `override_rate` and `sprint_low_conf_ratio` is a worsening signal; state

this briefly below the table so the reader does not have to guess.

3. **State the window.** Append one line naming the window size used, e.g. `Window: 20 commits (default)` or `Window: N commits (--window N)`.

Hard gate

• Read-only. MUST NOT write, create, or modify any file. MUST NOT stage or commit.

`git status` MUST be unchanged after a run.

• Emits ONLY the fixed 3-metric glance: `override_rate`, `small_lane_rate`,

`sprint_low_conf_ratio`. MUST NOT emit verbatim override log lines, verbatim triage entries, commit lists, or any other content from the governance logs.

• MUST NOT require `$ca-init` to have been run. The helper degrades gracefully on

absent logs (counts return 0 / ratio returns `"n/a"`); surface the degraded values as-is rather than blocking.

• If the helper subprocess fails entirely (import error, Python not found), report

the error and stop — do not fabricate metric values.

When NOT to use

• Full governance packet with verbatim overrides and audit trail → `$ca-audit`.
• Live project state (active sprint, open confirms, hook health) → `$ca-status`.