vocabulary

# NLPM Domain Vocabulary

> The canonical noun-and-verb set NLPM uses to name what it does. Every artifact name, command name, agent name, rule wording, and prose description should draw from this registry. Synonyms are flagged by `/nlpm:check` and penalized by `/nlpm:score`.
>
> **Sister skill:** `nlpm:conventions` holds upstream Claude Code framework terms (hook events, frontmatter fields, manifest keys). This skill holds NLPM-internal domain language. If a term is from Anthropic's docs, it belongs in `conventions`. If it is from NLPM's own corpus, it belongs here.

---

## How this registry is built

Every term listed below has **literary warrant** — it appears in at least one NLPM artifact today, captured by `analysis/scripts/extract-vocabulary.py`. Re-run that script after adding or renaming artifacts; the freshest output lives at `analysis/vocabulary-extract/summary.md`. New terms enter the registry only after one of the four warrant types from `analysis/vocabulary-design-principles.md` (P6) is satisfied — literary warrant alone is the entry bar for terms already in use; new coinages need user, structural, or domain warrant.

---

## Two scopes (P1)

NLPM has two declared scopes. A homonym across them is a **boundary**, not a collision.

| Scope | Lives in | What it operates on |
|-------|----------|---------------------|
| **internal** | `commands/`, `agents/`, `skills/`, `bin/`, `scripts/`, project CLAUDE.md | NLPM's own behavior — scoring, checking, fixing, testing, listing, trending NL artifacts in the current project. |
| **auditor** | `.github/workflows/auditor-*.yml`, `auditor/` | The self-evolution pipeline that audits external repos, opens contribution PRs, tracks outcomes, refines rules. |

A verb that appears in both scopes (`scan`, `test`, `discover`) carries the same identity criterion in both — these are sanctioned homonyms. A verb that appears in only one scope (`audit`, `contribute`, `track` in auditor; `score`, `check`, `fix`, `ls`, `trend`, `init` in internal) is scope-bound; using it in the other scope requires either renaming or declaring a second scope-specific definition.

---

## Verbs

### Internal scope (NLPM commands)

| Canonical verb | Output | Judgment? | Examples in corpus |
|----------------|--------|-----------|--------------------|
| `score` | number + penalty list | no (deterministic) | `commands/score.md`, `agents/scorer.md` |
| `check` | consistency violation list | no (deterministic) | `commands/check.md`, `agents/checker.md` |
| `test` | pass/fail against named specs | no (deterministic) | `commands/test.md`, `agents/tester.md` |
| `scan` | pattern-match findings against a signature database | no (deterministic) | `commands/security-scan.md`, `agents/vague-scanner.md`, `agents/security-scanner.md` |
| `fix` | mutated artifact | no (mechanical) | `commands/fix.md` |
| `ls` | inventory of artifacts | no | `commands/ls.md`, `agents/scanner.md` |
| `trend` | history report | no | `commands/trend.md` |
| `init` | config file | no | `commands/init.md` |

**Deprecated synonyms (do not use in internal scope):**
- `lint`, `validate` → use `check` (structural) or `score` (quality)
- `find`, `search`, `list` → use `ls`
- `analyze` → use `score` (if quantitative) or pick a more specific verb
- `audit` → not in internal scope; live in auditor scope only

### Auditor scope (`.github/workflows/auditor-*.yml`, `auditor/scripts/`)

| Canonical verb | Output | Judgment? | Examples in corpus |
|----------------|--------|-----------|--------------------|
| `discover` | candidate-repo list | no | `auditor-discover.yml` |
| `audit` | composite quality + security report | **yes** | `auditor-audit.yml` |
| `contribute` | PR(s) to target repo | no | `auditor-contribute.yml` |
| `track` | outcome events appended to `events.jsonl` | no | `auditor-track.yml` |
| `classify` | categorical label on a PR comment | no (model-deterministic) | `auditor-classify.yml` |
| `refine` | rule-edit PR (human-gated) | no (LLM-generated, human-merged) | `auditor-refine-rules.yml` |
| `cite` | citation-edit PR (human-gated) | no | `auditor-cite-exemplars.yml`, `propose-rule-citations.py` |
| `diff` | finding-by-finding comparison | no | `diff-findings.py`, `auditor-docs-diff.yml` |
| `report` | rolled-up summary at a cadence | no | `auditor-daily-report.yml`, `generate-daily-report.py` |
| `review` | rule-review issue body (human reads, decides) | **yes** (human) | `auditor-rule-review.yml`, `generate-rule-review-body.py` |
| `propose` | a draft for human approval | no | `propose-rule-citations.py` |
| `validate` | yes/no on a structural rule | no | `validate-feedback.sh`, `validate-rule-ids.py` |

> **Sibling-granularity note (P1):** `report` is broader than its peers (`classify`, `refine`, `cite`, `diff`). The auditor's noun-named workflow convention absorbs this — workflows that produce reports are noun-named after the output (`auditor-daily-report`, `auditor-rule-review`), and the verb `report` is the generic act behind that family. Documented inconsistency, not a P1 violation; flagged here so future additions don't replicate the pattern without intent.

**Cross-scope homonyms (same meaning in both scopes):**
- `scan` — pattern-match against a signature database (used by `security-scan` command and `scan-suppressions.py`)
- `test` — pass/fail against named specs (used by `/nlpm:test` and `auditor-integration-test.yml`)
- `discover` — produce a candidate list (`/nlpm:ls` description text and `auditor-discover.yml`)

### Verbs proposed but not entered

Per the precedence order in `analysis/vocabulary-design-principles.md` (P6 last; warrant is an entry check, not a veto), proposed terms split into two lists.

**Deferred (P2–P5 satisfied; awaiting warrant):**

| Proposed verb | Closure gap or judgment named | Warrant needed |
|---------------|------------------------------|----------------|
| `triage` | Finding-disposition (P4 closure: `finding` has no consumer verb) | User warrant — practitioner reaches for the term unprompted |
| `review` (internal scope) | Human-in-the-loop reading, sanctioned cross-scope homonym with auditor `review` | User warrant — practitioner names a review act in internal artifacts |
| `rationalize` | Vocabulary curation (P5: act of picking canonical from extracted frequencies has no name) | User warrant — practitioner names the curation act |

Deferred terms are documented but not yet canonical. R51 does **not** flag them as deprecated — they are nameless gaps, not synonyms.

**Rejected by higher principle (no entry possible regardless of warrant):**

| Proposed verb | Blocking principle | Reason |
|---------------|--------------------|--------|
| `audit` (internal scope) | P1 | Merge test fails — `score`+`check` already cover internal-scope evaluation |
| `lint` (internal scope) | P1 | Synonym of `check`; same identity criterion |
| `validate` (internal scope) | P1 | Collapses to `check` in internal scope (canonical in auditor scope) |
| `analyze` (internal scope) | P1 | Synonym of `score`; quantitative evaluation |

---

## Nouns

### Artifact-class nouns (rigid; survive state changes)

| Canonical noun | What it is | Examples |
|----------------|------------|----------|
| `artifact` | any NL programming file Claude Code consumes | umbrella term |
| `command` | `commands/*.md`, invoked via `/<plugin>:<command>` | `commands/score.md` |
| `agent` | `agents/*.md`, invoked via Task tool with `subagent_type` | `agents/scorer.md` |
| `skill` | `skills/<plugin>/<name>/SKILL.md`, auto-loaded by description match | `skills/nlpm/rules/SKILL.md` |
| `rule` | a numbered item (R01–R50) inside the rules skill | inside `skills/nlpm/rules/SKILL.md` |
| `hook` | shell script wired via `hooks.json` | `hooks/hooks.json` |
| `manifest` | `plugin.json` or `marketplace.json` | `.claude-plugin/plugin.json` |
| `frontmatter` | YAML block delimited by `---` at the top of a Markdown file | every command, agent, skill |

### Implementation-role nouns (P2/P3 — agent names ride alongside command verbs)

| Role-noun | Paired verb | File |
|-----------|-------------|------|
| `scanner` | `ls` | `agents/scanner.md` |
| `scorer` | `score` | `agents/scorer.md` |
| `checker` | `check` | `agents/checker.md` |
| `tester` | `test` | `agents/tester.md` |
| `vague-scanner` | `score` (sub-step) | `agents/vague-scanner.md` |
| `security-scanner` | `scan` | `agents/security-scanner.md` |

These are **not top-level verbs in their own right** (P3). They are role-names for sub-step agents. Treat them as nouns naming the worker, not as operations on artifacts.

### Output-class nouns (produced by verbs)

| Noun | Produced by | Notes |
|------|-------------|-------|
| `score` | `score` verb | number 0–100 + penalty breakdown |
| `finding` | `score`, `check`, `scan` | one problem detected; carries a fingerprint in auditor scope |
| `violation` | `check` | a finding specifically from cross-reference checking |
| `penalty` | `score` | the points subtracted by a single finding |
| `snapshot` | `score`, `trend` | a point-in-time record appended to `.claude/nlpm-history.json` |
| `inventory` | `ls` | the list of artifacts discovered in a path |
| `report` | `audit`, `report`, `trend` | a roll-up document |
| `spec` | `test` | a `.nlpm-test/*.spec.md` file defining expected behavior |

### Auditor-scope nouns (only meaningful inside `auditor/`)

| Noun | What it is | File evidence |
|------|------------|---------------|
| `case-study` | post-merge article comparing original audit to HEAD | `auditor/audits/<slug>.re-audit.md` |
| `exemplar` | teaching artifact from a high-scoring audit | `auditor/exemplars/<slug>.md` |
| `fingerprint` | content-hash identity of a finding across re-runs | `compute-fingerprint.sh` |
| `event` | one append-only record in `events.jsonl` | `auditor/logs/events.jsonl` |
| `disagreement` | self/maintainer dispute over a finding | `auditor/disagreements.jsonl` |
| `registry` | the tracked-repo database | `auditor/registry/repos.json` |
| `disposition` | a finding's lifecycle status | enum values inside `events.jsonl` |
| `policy gate` | a pre-PR check (no-external-PRs, CLA, pushback) | `auditor-contribute.yml` |

---

## The bright-line table (P1, P5)

When the evaluation cluster overlaps in practice, use this table to disambiguate:

| Verb | Scope | Deterministic? | Judgment? | Output | Use when |
|------|-------|----------------|-----------|--------|----------|
| `score` | internal | yes | no | number + penalty list | quantifying quality with a rubric |
| `check` | internal | yes | no | violation list | verifying cross-references and structural consistency |
| `test` | both | yes | no | pass/fail | comparing actual behavior against a named spec |
| `scan` | both | yes | no | findings against signatures | pattern-matching for a known class of problems |
| `audit` | auditor | partly | **yes** | composite report | full quality assessment that combines score + scan + judgment |
| `review` | auditor | no | **yes (human)** | comment trail | a human reads and forms an opinion |

Two verbs share a scope and an identity criterion ⇒ one must be retired or scope-split. Two verbs share an identity criterion across scopes ⇒ that is a sanctioned homonym (declare it in this table).

---

## How to extend this registry

1. **Add a term only if it has warrant.** The four warrant types come from `analysis/vocabulary-design-principles.md` P6: literary, user, structural, domain. Literary warrant is automatic via the extraction script — if the script picks the term up, it qualifies.
2. **Re-run the extraction script.** `python3 analysis/scripts/extract-vocabulary.py` writes `analysis/vocabulary-extract/summary.md`. New terms appear there.
3. **Slot the term.** Add a row to the right table above (internal verb / auditor verb / artifact-class noun / role-noun / output-class noun / auditor-scope noun).
4. **Cite the file evidence.** Every row has an "examples" or "file evidence" column. Cite at least one path.
5. **If retiring a synonym, list it under its canonical verb's "deprecated synonyms" line.** Do not silently drop terms; deprecation is itself a vocabulary act and needs to be visible.

---

## Deferred work (documented, not yet executed)

| Item | Why deferred | What unblocks it |
|------|--------------|------------------|
| Per-rule warrant tags on R01–R50 | Requires reading every rule + judging which warrant it earns its place by. User warrant data lives in `rule-health.py` outputs. | A separate `auditor-refine-rules` follow-up pass that combines rule-health data with this principle set. |
| Adding `triage` as a `/nlpm:triage` command | P4 closure gap is real but `triage` has zero literary warrant today. User warrant is the missing evidence. | A practitioner reaching for the word unprompted in actual NLPM use. |
| Resolving the agent-name-vs-command-name shadowing (`scanner`/`ls`, `scorer`/`score`) | Already documented above as a class boundary; no rename proposed. | A confirmed case of practitioner confusion. None observed today. |
| (resolved 2026-05-19) Workflow filename convention | Declared as sanctioned split. See "Auditor workflow filename convention" below. | — |

---

## Auditor workflow filename convention

`.github/workflows/auditor-*.yml` filenames follow a **two-rule split**, both sanctioned:

| Pattern | Use when | Examples |
|---------|----------|----------|
| `auditor-<verb>` | The workflow changes state (gates a transition, opens a PR, classifies, moves a finding through its lifecycle) | `auditor-audit.yml`, `auditor-contribute.yml`, `auditor-track.yml`, `auditor-classify.yml`, `auditor-refine-rules.yml`, `auditor-cite-exemplars.yml`, `auditor-discover.yml` |
| `auditor-<output-noun>` | The workflow's purpose is to produce a named artifact that downstream tooling consumes by name | `auditor-case-study.yml`, `auditor-exemplar.yml`, `auditor-daily-report.yml`, `auditor-suppressions.yml`, `auditor-docs-diff.yml`, `auditor-rule-review.yml` |

By P3, both patterns produce or gate, so both pass the top-level-verb test. The split is genuine: noun-named workflows are named after what they write, verb-named workflows after what they do.

**Outlier:** `auditor-batch-processor.yml` is named after a process role, not a verb or an output noun. Rename candidate: `auditor-promote-batch`. Deferred — git history, badge, and external references make the rename costly, and the existing name has literary warrant.

---

## Scope note

This skill loads on requests to write, review, or name NLPM artifacts. For framework-level facts (hook event names, manifest field schemas, Claude Code naming conventions), see [[conventions]]. For the 50 quality rules (R01–R50), see [[rules]]. For penalty tables, see [[scoring]].