Vault Command Tree + ADR Audit CLI

Status: shipped
Date: 2026-02-28
Deciders: Joel Hooks, Panda
Related: ADR-0081 (vault CLI access), ADR-0169 (CLI capability contracts), ADR-0173 (ADR collision remediation)

Context

joelclaw vault existed, but ADR operations were mixed into generic commands:

• No dedicated ADR subtree for inventory workflows
• No one-command ADR hygiene check (status validity, collisions, index drift)
• No deterministic machine-readable report for ADR grooming loops

ADR collisions are now a known risk (ADR-0173). We need a first-class command tree for vault/ADR operations.

Decision

Extend joelclaw vault with an ADR-focused command tree:

• joelclaw vault adr list [--status <status>] [--limit <limit>]
• joelclaw vault adr collisions
• joelclaw vault adr audit

adr audit contract

joelclaw vault adr audit returns a JSON envelope with:

• canonical status distribution
• missing/non-canonical statuses
• duplicate ADR-number collisions
• broken superseded-by targets
• README index drift (missing_from_index, extra_in_index)

Status vocabulary

Audit enforces canonical statuses only:

• proposed
• accepted
• shipped
• superseded
• deprecated
• rejected

Consequences

• ADR maintenance becomes scriptable and repeatable.
• Agents get a stable interface for ADR grooming and collision remediation.
• joelclaw capabilities can route memory/vault workflows through a dedicated ADR audit step.
• CLI docs and skills must track this command tree as the canonical vault ADR workflow.