feat(FR-3052): terminology governance — approved verbs, unknown-term checker, precedence & rename rules

[yomybaby]

Resolves #7740 (FR-3052)

Builds on FR-3048 (#7737, merged) — the machine-readable terminology.json single source of truth + i18n terminology checker.

What

Extends the FR-3048 termbase from nouns only to a full terminology-governance layer covering verbs, candidate-term detection, and the human process around both. Three tightly-coupled deliverables shipped as one PR (the governance prose references the verb-list rename flow and the new checker capability, so splitting them would create dangling references).

1. Approved verbs (verbs[])

• New top-level verbs[] array in terminology.json (8 entries: cancel, delete, remove, terminate, stop, inactivate→Deactivate, purge, hide), each context-qualified: id, intent (enum, all 8 covered exactly once), context, preferred.en, per-entry avoid[] of rejected synonyms, doc-only reversible, and decidingFR.
• Chosen as a new array — not avoid[] rows (CHECK 1 whole-word-matches every i18n value and would fire on every Delete/Remove/Stop label) and not a sibling verbs.json (would double the schema/generator/drift surface).
• terminology.schema.json gains a verbs property + verbEntry definition (verbs intentionally not in root required → backward-compatible).
• generate-terminology.mjs renders an ## Approved Verbs table into TERMINOLOGY.md, gated on terminology:auto:verbs markers. Round-trips idempotently (--check green).

2. Unknown-term checker (CHECK 3)

• check-terminology-i18n.mjs gains CHECK 3 — flags capitalized user-facing nouns in i18n values not yet in the termbase (candidate new terms).
• OFF by default, opt-in via --check3 (mirrors --check2). Always report-only — every finding carries severity:"report" and provably cannot reach the --strict exit gate (which derives blocking from CHECK 1 error-severity only). --strict --check3 exits 0.
• verify.sh and pnpm run lint:terminology do not pass --check3 → the CI harness stays clean.
• New ignoreNouns allowlist in terminology-i18n.allowlist.json for known proper nouns / product names.

3. Governance docs (lexical, not behavioral)

• TERMINOLOGY.md: ## Precedence (live UI label > terminology.json > style guide), ## Governance (Term Owner of Record = docs-lead, New-Term Gate built on CHECK 3's unknown-term report), and ## Rename / Deprecation Checklist (atomic rename flow the verb list assumes). All prose lives outside the terminology:auto:* markers → generator --check stays green.
• AGENTS.md: new ### Terminology Precedence subsection. (CLAUDE.md is a symlink to AGENTS.md, so only AGENTS.md is edited.)

Scope guards

• No new dependency — no package.json / pnpm-lock.yaml / pnpm-workspace.yaml changes; both scripts import only node: builtins.
• Lexical, not behavioral — the approved-verb list governs wording, not destructive-confirmation UX (encoded in the schema descriptions, a :::warning[Lexical, not behavioral] admonition, and per-entry descriptions).
• Per-locale verb forms out of scope for v1 (the destructive-confirmation UX is language-agnostic).

Verification

• node packages/backend.ai-webui-docs/scripts/generate-terminology.mjs --check → in sync (exit 0).
• node scripts/check-terminology-i18n.mjs --warn → unknown-noun 0 (CHECK 3 off by default); --check3 → 25 report-only candidates; --strict --check3 exits 0.
• bash scripts/verify.sh → === ALL PASS === (terminology step warn-only: 1 pre-existing CHECK 1 warn).

Follow-ups (not in this PR)

• Triage the ~13 genuine CHECK 3 candidates (Fair Share Scheduler, Rate Limit, Resource Policy, Model Store, …) into terminology.json concepts, then promote CHECK 3 toward a default warn — tracked separately.
• FR-3050 (CHECK 2 redesign), FR-3051 (ko/ja/th drift), FR-3049 (flip gate to blocking) build on this.

🤖 Generated with Claude Code

[yomybaby]

• feat(FR-3052): terminology governance — approved verbs, unknown-term checker, precedence & rename rules #7748 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• flow:merge-queue - adds this PR to the back of the merge queue
• flow:hotfix - for urgent changes, fast-track this PR to the front of the merge queue

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has required the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Coverage Report for root-coverage

Status	Category	Percentage	Covered / Total
🔵	Lines	8.3%	28 / 337
🔵	Statements	9.14%	32 / 350
🔵	Functions	11.53%	6 / 52
🔵	Branches	9.09%	18 / 198

File Coverage

No changed files found.

Generated in workflow #2708 for commit ba56fbb by the Vitest Coverage Report Action

[Copilot]

Pull request overview

Introduces a more formal “terminology governance” workflow for Backend.AI WebUI documentation and i18n, by extending the terminology termbase schema/content and enhancing the terminology lint script with an opt-in heuristic for surfacing likely-new user-facing terms.

Changes:

• Added a verbs lexicon to terminology.json (and schema) and generated an “Approved Verbs” section in TERMINOLOGY.md.
• Extended scripts/check-terminology-i18n.mjs with opt-in CHECK 3 (--check3) to report unknown capitalized nouns in English prose, plus a new allowlist mechanism (ignoreNouns).
• Documented terminology precedence and rename/deprecation governance rules in TERMINOLOGY.md and AGENTS.md.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/terminology-i18n.allowlist.json	Adds ignoreNouns allowlist entries to suppress known proper nouns/product names in CHECK 3.
scripts/check-terminology-i18n.mjs	Adds CHECK 3 implementation + CLI flag and reporting; wires allowlist support for ignoreNouns.
packages/backend.ai-webui-docs/terminology.schema.json	Extends schema to support verbs[] entries and clarifies avoid[] as noun/phrase-only for CHECK 1.
packages/backend.ai-webui-docs/TERMINOLOGY.md	Adds precedence + governance prose and introduces a generated “Approved Verbs” section.
packages/backend.ai-webui-docs/terminology.json	Adds the initial verbs[] lexicon entries (Cancel/Delete/Remove/Terminate/Stop/Deactivate/Purge/Hide).
packages/backend.ai-webui-docs/scripts/generate-terminology.mjs	Adds optional marker support and renderer for the generated verbs table.
AGENTS.md	Documents terminology precedence for contributors/agents.