---
id: ADR-pool.advisory-scorecard-promotion-velocity
status: Pool
parent: PRD-GZKIT-1.0.0
lane: lite
enabler: null
---

# ADR-pool.advisory-scorecard-promotion-velocity: Advisory-Scorecard Promotion Velocity Metric

## Status

Pool

## Intent

Extend `gz validate --advisory-scorecard` (or a sibling scope) so the
classification taxonomy it enforces — Mechanical / Promotable / Judgment /
Ambiguous — surfaces a **rate-of-transition** signal alongside its
existing rule-by-rule coverage check. Today the scorecard is a static
catalogue: every rule in `CLAUDE.md` and `.gzkit/rules/**` has a row,
the meta-validator (GHI #212) fails closed if any row is missing, but
nothing measures whether Promotable rules are actually being converted
into Mechanical ones at the cadence doctrine implies.

This pool ADR captures the architectural absence: doctrine
(`docs/governance/advisory-rules-audit.md` § Promotion process) and
external thesis (OpenAI *Harness Engineering*, 2026-02-11 — *"Human taste
is captured once, then enforced continuously on every line of code… When
documentation falls short, we promote the rule into code"*) both name
the Promotable → Mechanical transition as the desired pipeline, but the
mechanical surface that would render that pipeline visible — promotion
counts, aging buckets, overdue candidates — does not yet exist. The
result is that Promotable can function as a quiet permanent home, with
no scorecard-level signal that the system has stalled.

The pattern generalizes. Any classification taxonomy where a transition
is doctrinally encouraged but mechanically uninstrumented sits in the
same shape — pool → foundation/feature ADR promotion, defect → fixed,
open → closed GHI conversion. The advisory-scorecard is the first
observable instance; once the velocity-metric pattern lands here it
becomes a precedent for the broader family.

## Decision

Pool-staged decision space (not yet committed; promotion will refine):

1. **Validator surface.** Either extend `gz validate --advisory-scorecard`
   in place or add a sibling `--advisory-scorecard-velocity` scope. The
   sibling-scope shape mirrors the existing one-validator-one-concern
   pattern across `gz validate --*-fresh` scopes and keeps the meta-
   validator's structural-coverage check from coupling to a time-axis
   computation.
2. **Per-quarter transition count.** Walk `.gzkit/ledger.jsonl` for rule
   edits whose scorecard entry changed classification from Promotable to
   Mechanical within the quarter. Render as a count plus the rule names
   that moved.
3. **Aging signal.** For each currently-Promotable rule, compute
   time-since-classification. Rules > 180 days surface as
   "promotion candidates due for review." Threshold is configurable so
   doctrine drift can recalibrate without code change.
4. **Layer-3 derived view.** Render the per-quarter summary plus the
   aging buckets into a new § Velocity section in
   `docs/governance/advisory-rules-audit.md`, regenerated by the
   validator on every run. Same pattern as `gz register-adrs` for
   `docs/governance/GovZero/adr-status.md`: hand-edit is forbidden;
   freshness is fail-closed via a paired `--*-fresh` scope.
5. **Doc-gardening integration.** When the doc-gardening scheduled chore
   (ADR-pool.doc-gardening-scheduled-chore, GHI #496) lands, the cadence
   runner invokes the velocity-report regeneration on the same loop as
   the other Layer-3 regenerators, opening single-purpose PRs when the
   velocity numbers drift since last run.
6. **`RemediationPayload.recovery` integration.** Once ADR-0.0.53 lands,
   overdue-Promotable warnings emit structured payloads pointing the
   operator at the promotion ceremony (file the GHI, author the
   mechanical validator, retire the advisory copy).

## Alternatives Considered

1. **Status quo: scorecard remains static.** Rejected as the failure
   case this pool ADR exists to address. The structural-coverage check
   from GHI #212 guarantees no rule is unclassified, but says nothing
   about whether classifications are moving in the doctrinally-intended
   direction. Promotable functions as a permanent home in silence.
2. **Manual quarterly review via runbook.** Rejected: human review
   without a derived-view diff is exactly the *"reconciliation as
   maintenance chore"* failure named in `AGENTS.md` § Architectural
   Boundaries #4. A manual quarterly pass collapses into the
   between-sessions silent-drift pattern the doc-gardening ADR was
   filed to close.
3. **Emit warnings without rendering a derived view.** Rejected:
   warnings on validator runs are session-local and disappear without
   audit trail. The whole point is to make the velocity *visible* —
   that requires a committed Layer-3 derived view in the same shape
   as `adr-status.md` and `agents-md-map.md`, so drift over time
   shows up in `git log` rather than only in transient stderr.
4. **Author as a feature ADR directly (skip pool).** Rejected (for now):
   the velocity validator's `RemediationPayload.recovery` shape is
   downstream of ADR-0.0.53 (Pending), and its scheduled-cadence
   integration is downstream of ADR-pool.doc-gardening-scheduled-chore.
   Pool staging is the right home until those land — promotion can then
   carry the integrated scope cleanly, the same routing rationale used
   for the doc-gardening pool ADR itself.

## Notes

Pool ADRs are backlog items — they carry no `semver:` or `kind:` frontmatter.
Promotion into the active tree (foundation or feature) is performed via
`gz adr promote`, which rewrites the frontmatter with the chosen taxonomy.

### Sourcing

- GHI #497 — original observation routing this pool ADR closes
- GHI #212 (closed) — advisory-rules-audit scorecard meta-validator
  (the structural-coverage prerequisite this velocity layer compounds)
- GHI #314 (closed) — single-rule promotion precedent
  (agent-failure-modes.md → mechanical surface)
- GHI #327 (closed) — AGENTS.md lift precedent
- GHI #496 (open) / ADR-pool.doc-gardening-scheduled-chore — cadence
  integration surface; velocity-report regeneration becomes one of the
  scheduled gardener's drift checks
- ADR-0.0.53 (Pending) — `RemediationPayload.recovery` carries the
  canonical promotion-ceremony pointer for overdue-Promotable warnings
- `docs/governance/advisory-rules-audit.md` § Promotion process — the
  doctrinal hook this pool ADR operationalizes
- External: OpenAI, *Harness Engineering* (2026-02-11),
  https://openai.com/index/harness-engineering/ — *"When documentation
  falls short, we promote the rule into code"*
