# CLI verb-grammar audit (2026-05-02)

**Status:** Working doc — point-in-time audit; updates as migrations land.
**Owner:** Benjamin Booth
**Parents:** [`spec-aeos-0.1.md §4.3.1 Verb grammar`](../specs/spec-aeos-0.1.md), [`spec-axi-cli.md §UI Affordances`](../specs/spec-axi-cli.md)

---

## Why this audit exists

The AEOS verb-grammar rule (§4.3.1) requires verbs to be **imperative
actions**, not bare resource names. The rule was authored after several
shipped extensions had already adopted noun-as-verb patterns
(`axi tidy worktrees`, `axi rivet patterns`, etc.). This doc is the
point-in-time audit of the offenders + proposed migrations.

Audit method: `python -c "from axiom.extensions.builtins.commands import discovery; …"`
walked every installed extension's `kind=cmd` blocks, called each entry's
`build_parser()`, and enumerated subparser names. Each name was
classified against the imperative-verb set + reserved list.

## Findings

### Conforming (no migration needed)

These extensions' verb sets pass the rule outright:

- `commands` — `generate`, `list`, `regenerate` ✅
- `db` — `bootstrap`, `delete`, `migrate`, `up`, `down` (last two reserved) ✅
- `directive` — `add`, `list`, `revoke` ✅
- `memory` — `migrate`, `show` ✅
- `nodes` — `add`, `list`, `remove`, `upgrade` (`status` reserved) ✅

### Mixed — most verbs conform; a handful need migration

Extensions where a few verbs need to be renamed but most are fine:

#### `tidy` (hygiene) — 5 offenders out of 10

| Current | Issue | Proposed |
|---|---|---|
| `axi tidy worktrees` | bare noun | `axi tidy stat worktrees` (observability) + `axi tidy prune --worktrees` (action) |
| `axi tidy health` | bare noun | `axi tidy check health` or `axi tidy stat health` |
| `axi tidy vitals` | bare noun | `axi tidy monitor vitals` or `axi tidy stat vitals` |
| `axi tidy retention` | bare noun | `axi tidy manage retention` or `axi tidy stat retention` |
| `axi tidy ci` | bare noun (abbrev) | `axi tidy stat ci` |

Conforming verbs (keep as-is): `clean`, `diagnose`, `ls`, `purge`, `status`.

#### `rivet` (release) — 3 offenders out of 9

| Current | Issue | Proposed |
|---|---|---|
| `axi rivet heartbeat` | bare noun | `axi rivet check heartbeat` or `axi rivet pulse` |
| `axi rivet patterns` | bare plural noun | `axi rivet list patterns` |
| `axi rivet watched` | past participle as verb | `axi rivet list watched` (nominalized) or `axi rivet show watches` |

Conforming: `check`, `mode` (borderline; reserved), `plan`, `unwatch`, `watch`. (`status` reserved.)

#### `triage` (diagnostics) — 2 offenders out of 3

| Current | Issue | Proposed |
|---|---|---|
| `axi triage heartbeat` | bare noun | `axi triage check heartbeat` or `axi triage pulse` |
| `axi triage checks` | plural noun used as verb | `axi triage run checks` or `axi triage list checks` |

Conforming: `sweep`.

#### `agents` — 1 offender out of 6

| Current | Issue | Proposed |
|---|---|---|
| `axi agents logs` | plural noun used as verb | `axi agents show logs` or `axi agents tail logs` |

Conforming: `register`, `start`, `stop`, `unregister`. (`status` reserved.)

#### `ide` — 2 offenders out of 4

| Current | Issue | Proposed |
|---|---|---|
| `axi ide extensions` | bare plural noun | `axi ide list extensions` or `axi ide install extensions` |
| `axi ide syntax` | bare noun | `axi ide check syntax` or `axi ide refresh syntax` |

Conforming: `setup`. (`status` reserved.)

### Heavy — most verbs need migration

#### `knowledge` (federation) — 6 offenders out of 7

This extension's verb set was authored as descriptive labels rather
than commands. Recommend a structural pass rather than per-verb fixes.

| Current | Issue |
|---|---|
| `axi knowledge accumulation` | bare noun |
| `axi knowledge gaps` | bare noun |
| `axi knowledge impact` | bare noun |
| `axi knowledge saved` | past participle |
| `axi knowledge velocity` | bare noun |

Likely structural rewrite: `axi knowledge stat <accumulation|gaps|impact|velocity>`
+ `axi knowledge list saved` + keep `axi knowledge report` (reserved
or borderline; accepted as verb).

Conforming: `report` (borderline — accepted). (`status` reserved.)

#### `model` (model_corral) — 4 offenders out of 24

| Current | Issue | Proposed |
|---|---|---|
| `axi model contributors` | bare plural noun | `axi model list contributors` |
| `axi model lineage` | bare noun | `axi model show lineage` or `axi model trace lineage` |
| `axi model materials` | bare plural noun | `axi model list materials` |
| `axi model reviews` | bare plural noun | `axi model list reviews` |

Conforming: `add`, `audit`, `clone`, `diff`, `export`, `generate`, `init`, `invite`, `lint`, `list`, `pull`, `receive`, `resolve`, `review`, `search`, `share`, `show`, `submit`, `sweep`, `validate`. (`status` reserved.)

#### `federation` — 3 offenders out of 8

| Current | Issue | Proposed |
|---|---|---|
| `axi federation inference` | bare noun | `axi federation run inference` |
| `axi federation peers` | bare plural noun | `axi federation list peers` |
| `axi federation resources` | bare plural noun | `axi federation list resources` |

Conforming: `init`, `invite`, `join`, `leave`. (`status` reserved.)

#### `facility` (model_corral) — 1 offender out of 8

| Current | Issue | Proposed |
|---|---|---|
| `axi facility materials` | bare plural noun | `axi facility list materials` |

Conforming: `init`, `install`, `list`, `publish`, `show`, `sync`, `uninstall`.

#### `research` (federation) — 1 borderline out of 7

| Current | Note |
|---|---|
| `axi research claim` | could be verb (file a claim) or noun (a claim instance). Accept as verb. |

Conforming: `chain`, `create`, `list`, `publish`, `show`, `submit`.

## Summary

| Extension | Total verbs | Offenders | Cleanup priority |
|---|---|---|---|
| `tidy` | 10 | 5 | High (canonical hygiene; sets the example) |
| `knowledge` | 7 | 6 | High (worst ratio; needs structural rewrite) |
| `rivet` | 9 | 3 | Medium |
| `triage` | 3 | 2 | Medium |
| `model` | 24 | 4 | Medium |
| `federation` | 8 | 3 | Medium |
| `ide` | 4 | 2 | Low |
| `agents` | 6 | 1 | Low |
| `facility` | 8 | 1 | Low |
| `research` | 7 | 1 (borderline) | None |
| `commands`, `db`, `directive`, `memory`, `nodes` | — | 0 | None — clean |

**Total: ~28 verbs across 9 extensions need migration.**

## Migration plan

Per `feedback_no_backward_compat_shims`: pre-public-launch we refactor
cleanly. No deprecation aliases. Rename + update all call sites in
one commit per extension.

Suggested order (by priority + risk):

1. **`tidy`** — sets the example; canonical hygiene; small touch
2. **`knowledge`** — heaviest cleanup; structural rewrite worth doing
   before any third-party extension copies the pattern
3. **`triage`** — heartbeat naming overlaps with `rivet`; align both
4. **`rivet`** — same heartbeat alignment
5. **`agents`**, **`ide`**, **`facility`**, **`federation`**, **`model`** —
   one PR each; small touches

Migrations are gated by:
- AEOS schema validator passes
- `axi ext lint --strict` reports zero verb-grammar violations
- Per-extension test suite passes
- Cross-harness shim regenerator (`axi commands regenerate`) emits
  fresh shims with the new verb names

## After-state target

Once migration completes, `axi ext lint --strict` becomes a CI gate
across the repo. Any new `kind=cmd` block that introduces a
noun-as-verb fails CI without manifest-level approval (the
`verb_overrides.<verb>.grammar = "approved"` escape hatch with a
required rationale).

---

_Copyright (c) 2026 The University of Texas at Austin and B-Tree Labs.
Apache-2.0 licensed._
