<!-- 01-principles.md -->

# Level 1 — Core Principles (Words)

STE-Code Level 1 controls **which words you may use** in code documentation.
Every other level builds on it. This file is the LLM-facing form of Section 1
(Rules 1.1–1.14), plus ready-to-use document templates.

## Contract

Every word in code documentation must pass one of three gates:

1. It is **approved in the controlled terminology** (the STE-Code dictionary).
2. It is a **code-domain technical noun** (Rule 1.5 categories).
3. It is a **code-domain technical verb** (Rule 1.12).

If a word passes none of the three gates, it is forbidden. There is no fourth
category.

Scope: README files, API reference, docstrings, inline comments, commit
messages, error messages, test specifications, code review and PR feedback.

## Principle index (P1–P14)

| ID | Rule | Principle |
|----|------|-----------|
| P1 | 1.1 | Use words that are approved in the controlled terminology, code-domain technical nouns, or code-domain technical verbs. |
| P2 | 1.2 | Use approved words only as the specified part of speech. |
| P3 | 1.3 | Use approved words only with their approved meanings. |
| P4 | 1.4 | Use only the approved forms of verbs and adjectives. |
| P5 | 1.5 | You can use words that fit a code-domain technical noun category (19 categories). |
| P6 | 1.6 | Use a non-approved word only when it is a code-domain technical noun, or part of one. |
| P7 | 1.7 | Do not use words that are technical nouns as verbs. |
| P8 | 1.8 | Use technical nouns that are approved in your project, company, industry, or subject field. |
| P9 | 1.9 | When you must select a technical noun, use one which is short and easy to understand. |
| P10 | 1.10 | Do not use regional, slang, or jargon words as technical nouns. |
| P11 | 1.11 | Do not use different technical nouns for the same item. |
| P12 | 1.12 | You can use verbs that fit a technical verb category. |
| P13 | 1.13 | Do not use technical verbs as nouns. |
| P14 | 1.14 | Use American English spelling unless other official directives tell you differently. |

## P1 (Rule 1.1) — Approved words, technical nouns, technical verbs

In code documentation, use words that are approved in the project controlled
terminology, code-domain technical nouns, or code-domain technical verbs.

- A **code-domain technical noun** names a concept in software development
  (`UserAuthenticator`, `connection pool`, `stack trace`).
- A **code-domain technical verb** names an operation or process
  (`serialize`, `compile`, `deploy`).
- The controlled terminology also lists non-approved words with approved
  alternatives. Keep both lists in the project glossary.

Common substitutions:

| Do not write | Write |
|---|---|
| execute, invoke (prose) | run, call |
| generate, construct, instantiate | make |
| configure, assign | set |
| retrieve, fetch | get |
| transmit | send |
| delete, purge | remove |
| validate, verify, ensure | check |
| utilize, leverage, employ | use |
| initiate, commence, bootstrap | start |
| terminate | stop |
| unable to | cannot |
| invalid, malformed | not correct |
| maintain | keep |
| perform | do |
| optimize | make faster, make smaller |
| aggregate | collect |
| persists | continues |
| prior to | before |

Examples:

> **Non-STE:** To begin utilizing the build toolchain, you must first generate
> the distributable artifact, then execute the compiled binary to bootstrap the
> local development service.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the
> local service.

> **Non-STE:** `Error: Unable to establish connection to the database. Please
> verify your credentials and retry.`
>
> **STE:** `Error: Cannot connect to the database. Check your credentials and
> try again.`

> **Non-STE:** `feat: implement JWT authentication middleware for API routes`
>
> **STE:** `feat: add JWT authentication middleware for API routes`

## P2 (Rule 1.2) — One part of speech per approved word

Each approved word has a specified part of speech. Use the word only as that
part of speech.

- "query" is an approved noun, not a verb → "Send a query to the database."
- "static" is an approved adjective, not a verb → "Make the variable static."
- Some words are approved as more than one part of speech ("call" is a verb and
  a noun). Sentence position shows which one you use.

| Violating form | Error | Write instead |
|---|---|---|
| Query the database / Cache the result / Queue the job / Log the error | Technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log |
| Docker the app / Git the change / Terraform the VPC | Tool name used as verb | Use Docker / Save with Git / Use Terraform |
| Secure the endpoint / Empty the buffer | Adjective used as verb | Make the endpoint secure / Make the buffer empty |
| Static the variable / Ready the worker | Adjective used as verb | Make the variable static / Make the worker ready |
| Utilize the cache / Leverage the library | Unapproved verb | Use the cache / Use the library |
| Orchestrate the services / Facilitate the sync | Unapproved verb | Control the services / Help the sync |

If a word is not in the controlled terminology: find it in a standard English
dictionary, find the best approved synonym, then use the approved word or a
different sentence construction.

## P3 (Rule 1.3) — Approved meanings only

Each approved word has one or more approved meanings, often more restricted
than standard English. Do not use an approved word with a meaning it does not
have in the controlled terminology.

Check procedure for each word:

1. Identify the part of speech as you wrote it.
2. Look up the approved meaning for that part of speech.
3. Ask whether your sentence uses exactly that meaning.
4. If not, replace the word or restructure the sentence.

> **Sentence:** The background worker runs every night.
> The approved meaning of the verb "run" is "execute a program or command."
> The writer means "operates on a schedule" — the meaning does not match.
> **Rewrite:** The background worker operates every night.

## P4 (Rule 1.4) — Approved verb and adjective forms only

The controlled terminology gives each approved verb with its approved forms,
and each approved adjective with its comparative and superlative forms.

| Infinitive/Imperative | Simple present | Simple past | Past participle |
|---|---|---|---|
| (To) Compile / Compile | Compile(s) | Compiled | Compiled |

`FAST (adj) (FASTER, FASTEST)` — base, comparative, superlative.
Adjectives that form the comparative with "more" and "most" have no listed
forms, because "more" and "most" are approved words.

Do not invent forms such as "compilating" or "compilates."

> **Non-STE:** The compiler is compilating the source files every time you save.
>
> **STE:** The compiler compiles the source files each time you save.

## P5 (Rule 1.5) — The 19 code-domain technical noun categories

You may use a word that is not in the controlled terminology when you can put
it in one or more of these categories. The examples are not a full list.

| # | Category | Examples |
|---|---|---|
| 1 | Code components, modules, and libraries | class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility |
| 2 | Computing devices and their components | CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal |
| 3 | Development tools, environments, and support equipment | CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack |
| 4 | Data structures, types, and formats | array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML |
| 5 | Infrastructure, deployment, and platforms | AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel |
| 6 | Systems, subsystems, and architectural components | API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket |
| 7 | Mathematical, algorithmic, and scientific terms | Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal |
| 8 | Interface elements and navigation | button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip |
| 9 | Numbers, units of measurement, and time | byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB) |
| 10 | Quoted text | `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused` |
| 11 | Professional roles, teams, and organizations | administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user |
| 12 | Official documents, API references, and standards | API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning |
| 13 | Runtime environments and operational conditions | development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine |
| 14 | Colors | black, blue, cyan, gray, green, magenta, orange, red, white, yellow |
| 15 | Defects, errors, and fault terminology | assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error |
| 16 | Computer science, information, and communication technology | AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization |
| 17 | Legal and licensing terms | Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty |
| 18 | Database and storage terminology | connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view |
| 19 | Network and protocol terminology | DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket |

Colors are adjectives, but STE-Code identifies them as code-domain technical
nouns. Comparative and superlative color forms (blacker, the reddest) are not
permitted.

### Glossary registration (required)

Before you use a code-domain technical noun, add it to the project glossary
with: the noun term, its category or categories, its approved meaning in the
project context, and one correct example sentence.

### Grammar notes

- **Articles.** Use "the" for a specific instance, "a"/"an" for an indefinite
  instance, no article for plural general references.
- **Modifiers.** A technical noun can modify another technical noun
  ("Redis cache server"). Both nouns must belong to a recognized category.
- **Possessive.** Use `'s` only with category 11 (roles, teams, organizations).
  Write "the configuration of the Docker container", not
  "the Docker container's configuration".
- **Plurals.** Add a lowercase "s" with no apostrophe: `APIs`, not `API's`.
- **Capitalization.** Proper nouns keep their original form (`TypeScript`).
  Common technical nouns are lowercase unless they start the sentence.

### Edge cases

1. **Framework names that are also common words** (React, Vue, Swift, Go, Rust,
   Next, Nest) are technical nouns in category 3 or 5. Capitalize them, or use
   the full term ("the Swift language"), so they are not read as approved words.
2. **Code keywords** (`if`, `for`, `return`, `class`, `async`) are quoted text
   (category 10) when they appear in documentation. Status codes and literals
   must be quoted too: "return `500 Internal Server Error`".
3. **Abbreviations and acronyms** (API, JSON, SQL, HTTP, TLS) are technical
   nouns in categories 16, 18, or 19. Define each one at first use unless the
   audience universally understands it.
4. **Generated code and generated documentation** are exempt, because a machine
   produces them. Human-written comments inside generated files are not exempt.
5. **Project-specific internal names** (`PhoenixCache`) are technical nouns
   only when they are in the project glossary. Without registration they are
   non-approved words and violate P6.
6. **Numbers as technical nouns.** Version numbers, HTTP status codes, and port
   numbers are category 9 nouns or quoted text and must appear verbatim
   ("port 5432", "`404 Not Found`"), not "the default db port".

## P6 (Rule 1.6) — Non-approved words only as technical nouns

Use a word that is not approved only when it is a code-domain technical noun or
part of one.

- "handler" is not approved; the alternative is "function (n)".

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.

But "handler" is permitted inside a compound technical noun (category 1):

> **STE:** The event handler processes each incoming event.

- "main" is not approved; the approved adjective is "primary".

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.

## P7 (Rule 1.7) — Do not use technical nouns as verbs

Use a code-domain technical noun only as a noun, or as a modifier inside
another technical noun. Restructure the sentence with an approved verb.

> **Non-STE:** Database the user records before the migration.
>
> **STE:** Store the user records in the database before the migration.

Same pattern: "cache the result" → "keep the result in the cache";
"host the service" → "run the service" or "make the service available".

## P8 (Rule 1.8) — Use the technical nouns your project already approves

If your project, company, industry, or subject field has an approved name for a
class, module, function, method, variable, component, or process, use that
name. Do not invent a description for something that already has a name in the
codebase.

> **STE:** The dashboard page has a `UserTable` component and a `FilterPanel`
> component.

The reader must be able to find the exact element in the source tree from the
name you used.

## P9 (Rule 1.9) — Short, clear technical nouns

When you must select a code-domain technical noun, use one that is short (not
more than three words) and easy to understand. If a code snippet, line number,
diagram, or API reference already identifies the item, use the shortest
unambiguous term. Add one or two adjectives only when the reader needs them.

> **Non-STE:** Call the asynchronous JavaScript XML HTTP request wrapper utility
> function (line 42) to get the serialized JSON payload from the remote
> application programming interface endpoint.
>
> **STE:** Call the `fetchUtility` function (line 42) to get the JSON data from
> the API endpoint.

## P10 (Rule 1.10) — No regional words, slang, or jargon

Some technical words are used only inside one community or one technology
ecosystem. Readers from a different background, a different stack, or a
different first language cannot understand them. Select well-known words.

| Do not write | Write |
|---|---|
| cruft | unnecessary code |
| snag the repo | clone the repository |
| fire up / spin up | start |
| kick off | start |
| crunch the data | process the data |
| wonky, funky | not correct, known defect |
| hack | workaround |
| repo, K8s, TS (in prose) | repository, Kubernetes, TypeScript |
| thing, stuff | the exact technical noun |

> **Non-STE:** `"""Remove all the cruft from the legacy module."""`
>
> **STE:** `"""Remove all the unnecessary code from the legacy module."""`

## P11 (Rule 1.11) — One technical noun per item

Do not use different code-domain technical nouns for the same item. The source
of truth for the name is the code: the class, function, module, table,
resource, environment variable, or configuration key as the repository defines
it.

> **Non-STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the AccountManager to check a user.
> 3. The UserHandler gives a session token that you send in later requests.

The repository defines one class, `UserService`. Use that name in all three
sentences. When the reader sees three names, the reader cannot know whether
there is one class or three.

## P12 (Rule 1.12) — The 4 code-domain technical verb categories

A code-domain technical verb names an operation or process in software
development. You may use a technical verb when you can put it in one of these
four categories. The examples are not a full list.

| # | Category | Sub-group | Examples |
|---|---|---|---|
| 1 | Development processes | Write and modify code | compile, concatenate, import, inject, instantiate, lint, minify, marshal, optimize, polyfill, refactor, resolve, shim, stub, substitute, tokenize, transpile, trace, vectorize |
| 1 | Development processes | Test and verify code | assert, benchmark, debug, fuzz, instrument, mock, profile, snapshot, spy, stub, unit-test |
| 1 | Development processes | Build and package | bundle, deploy, package, publish, release, tag, version |
| 1 | Development processes | Manage dependencies | hoist, install, link, lock, pin, update, upgrade |
| 2 | Computer processes and applications | Input and output | click, copy, cut, digitize, enter, paste, press, print, scan, swipe, tap, type |
| 2 | Computer processes and applications | User interface and application operations | clear, close, delete, deselect, disable, drag, drag and drop, enable, encrypt, erase, filter, hide, highlight, invalidate, maximize, minimize, navigate, open, save, scroll, select, show, sort, store, submit, toggle, validate, zoom in, zoom out |
| 2 | Computer processes and applications | System operations | abort, authenticate, authorize, boot, cache, communicate, configure, debug, deserialize, download, format, hydrate, initialize, install, load, log, manage, mount, process, reboot, render, retry, serialize, spawn, synchronize, throttle, update, upgrade, upload |
| 3 | Applicable subject fields | Algorithmic, mathematical, and data | aggregate, bisect, compute, concatenate, convert, count, decode, encode, escape, filter, hash, index, map, merge, normalize, parse, pipeline, precompute, recalculate, reduce, tokenize, transform, validate, verify |
| 3 | Applicable subject fields | Database and storage | backup, compact, flush, index, migrate, persist, query, replicate, restore, roll back, seed, shard, upsert, vacuum, write-ahead |
| 3 | Applicable subject fields | Network and communication | broadcast, connect, disconnect, establish, forward, handshake, intercept, listen, poll, proxy, reject, resolve, route, send, stream, timeout, tunnel, unsubscribe, webhook |
| 3 | Applicable subject fields | Security and authentication | authenticate, authorize, decrypt, decode, encode, encrypt, hash, revoke, salt, sanitize, sign, validate, verify |
| 4 | Legal and licensing terms | Legal and regulatory texts only | acknowledge, assign, comply with, conform to, disclose, enforce, explain, grant, inform, license, modify, notify, permit, regulate, sign, supersede, waive |

Constraints:

- If an approved verb gives the instruction or the information accurately, use
  the approved verb. Do not use a technical verb when approved words are enough.
- Use only technical verbs that are correct in your context. Do not use general
  or unclear technical verbs.
- Where possible, use an approved verb together with a code-domain technical
  noun instead of a technical verb.
- Technical verbs obey the same rules as other approved verbs (section 3).

## P13 (Rule 1.13) — Do not use technical verbs as nouns

Use a code-domain technical verb only as a verb. When you need a noun, use an
approved noun or a code-domain technical noun with the same meaning.

| Do not write | Write |
|---|---|
| Do a build of the project | Build the project |
| The function does a parse of the input string | The function parses the input string |
| Does a compile of the source files | Compiles the source files |
| `// A retry of the connection` | `// Retry the connection` |
| Addition of login endpoint | Add login endpoint |
| Compile of module 'auth' failed | Failed to compile module 'auth' |

Some words belong to a verb category (P12) and a noun category (P5) at the same
time. When the API returns a named artifact (a `Build` object, a `Deployment`
resource), the noun form is a technical noun, not a misused verb.

## P14 (Rule 1.14) — American English spelling

Use the spelling given in the controlled terminology (American English). Use a
different spelling only when a project specification, style guide, contract, or
other official directive requires it.

| Do not write | Write |
|---|---|
| colour | color |
| fibre | fiber |
| initialise | initialize |
| serialise | serialize |
| behaviour | behavior |
| centre | center |

Do not change the spelling inside quoted text. If an error message, a comment,
or a user interface shows British English spelling, keep it verbatim:

> **STE:** The terminal shows the message `Colour profile not recognised`.

## Application by documentation type

| Document type | What P1–P14 constrain most |
|---|---|
| README | Imperative verbs in setup steps; adjectives and adverbs in the overview. Tool, file, and command names are technical nouns. |
| API reference | Prose around parameters, return values, and error conditions. Function, type, and endpoint names are technical nouns (P5). |
| Docstrings and inline comments | The shortest approved verb. `NOTE:`, `WARNING:` are approved nouns; `FIXME:` is a technical noun. |
| Commit messages | The smallest approved vocabulary, imperative form: add, fix, remove, update, set, make, check, run. |
| Error messages | Approved words only, so non-native readers understand. "cannot", not "unable to"; "not correct", not "invalid". |
| Test specifications | Name the component under test and the condition with technical nouns from categories 1, 4, and 15. |
| Code review and PR feedback | Approved verbs in every request for change; one technical noun per item (P11); no jargon (P10). |

## Template — code review comment

```markdown
**File:** `<path>:<line>`
**Type:** defect | question | suggestion
**Principle:** P<n> (Rule 1.<n>)

**What I see:** <one sentence, approved verb, present tense>

**Why it is a problem:** <one or two sentences; name the defect with a
category 15 technical noun where one applies>

**What to do:** <imperative sentence that starts with an approved verb:
add, remove, change, set, make, check, move, rename, split>
```

Filled example:

```markdown
**File:** `src/auth/UserService.ts:42`
**Type:** defect
**Principle:** P11 (Rule 1.11)

**What I see:** The docstring calls this class `AccountManager`. The file
defines the class `UserService`.

**Why it is a problem:** Two names for one class. The reader cannot know
whether there is one class or two.

**What to do:** Change the docstring to use `UserService` in all sentences.
```

Rules for review comments:

- Start each request for change with an approved imperative verb.
- Use one sentence for one point. Do not join two points with "and".
- Name the file and the line. Do not write "this thing" or "the stuff above".
- Do not use slang ("nit", "wonky", "hacky", "LGTM") in the body of the
  comment. Write "small point", "not correct", "workaround", "I approve".
- Do not use a technical noun as a verb (P7) or a technical verb as a noun
  (P13) in your own feedback.

## Template — pull request description

```markdown
# <Imperative summary line, one approved verb first, 72 characters or less>

## What this change does

<One paragraph. Each sentence has one clause. Use approved verbs and
code-domain technical nouns. Name every component with the name the
repository uses.>

## Why

<The defect, the request, or the requirement. Name the defect with a
category 15 technical noun: race condition, memory leak, regression,
timeout, type error.>

## How to check it

1. <Imperative step, approved verb first.>
2. <Imperative step, approved verb first.>
3. <The result the reviewer must see.>

## Risk

<What can break. Name the affected component and environment
(development, staging, production).>

## Related

- Issue: #<n>
- Documents changed: <README | API reference | changelog | none>
```

Filled example:

```markdown
# Fix the timeout defect in the connection pool

## What this change does

The `ConnectionPool` class now closes each idle connection after 30 seconds.
The class writes one line in the log for each connection that it closes.

## Why

The pool kept idle connections open. The database refused new connections
after 100 idle connections. This caused a crash in production.

## How to check it

1. Start the service in the development environment.
2. Send 120 requests to the `/orders` endpoint.
3. Check the log. The log must show `closed idle connection` for each
   connection that the pool closes.

## Risk

A short timeout can close a connection that a slow query still uses. Set
`POOL_IDLE_TIMEOUT` to a larger value if the staging tests show this defect.

## Related

- Issue: #482
- Documents changed: changelog
```

## Template — PR review summary

```markdown
**Decision:** approve | request changes | comment

**Summary:** <One sentence. What the change does, in approved words.>

**Blocking points**
1. `<path>:<line>` — <imperative sentence>
2. `<path>:<line>` — <imperative sentence>

**Non-blocking points**
1. `<path>:<line>` — <imperative sentence>

**Checked:** <what you ran or read: tests, linter, documentation>
```

## Level 1 compliance checklist

Run this list on every document before you publish it.

1. Each word is an approved word, a code-domain technical noun, or a
   code-domain technical verb. (P1)
2. Each approved word is used as its specified part of speech. (P2)
3. Each approved word carries only its approved meaning. (P3)
4. Each verb and adjective uses an approved form. (P4)
5. Each non-approved word fits one of the 19 noun categories, or is part of a
   compound that does. (P5, P6)
6. No technical noun is used as a verb. (P7)
7. Each component uses the name the project glossary and the repository give
   it. (P8)
8. Each technical noun is short (three words or less) and clear. (P9)
9. No regional word, slang word, or jargon word appears. (P10)
10. One item has exactly one name in the whole document. (P11)
11. Each technical verb fits one of the four verb categories, and no approved
    verb could do the same work. (P12)
12. No technical verb is used as a noun. (P13)
13. All spelling is American English, except inside quoted text. (P14)
14. Every technical noun and technical verb you introduced is registered in the
    project glossary.

---

<!-- 02-synonyms.md -->

# Level 1 — Technical Noun Categories (Rule 1.5)

This is the Rule 1.5 slice of STE-Code Level 1: the **code-domain technical noun
categories** — the "approved-word / synonym table" that lets you use precise
domain terms outside the approved-word dictionary.

Level 1 controls *which words you may use*. Every other level builds on it. This
file is the LLM-facing form of Rule 1.5 (one of the three word-gates in Section 1).
It is faithful to the standard: the nineteen categories and their example terms
are taken from the authoritative Rule 1.5 adaptation, not invented. All examples
stay inside the code domain.

## Rule 1.5 — what it permits

**Rule 1.5** You can use words that you can include in a code-domain technical
noun category.

A code-domain technical noun is a noun term that refers to a specified concept in
software development and is applicable to a subject field. The controlled
terminology does not include all code-domain technical nouns because there are
too many, and each project or subject field uses different technical nouns. You
can find many of these in your project glossary or terminology database.

STE-Code gives you a list of nineteen categories, with examples, to help you:
- Select code-domain technical nouns to put in your project glossary.
- Use code-domain technical nouns correctly.

You can use code-domain technical nouns in procedural and descriptive writing if
you can include them in one or more of these nineteen categories.

Rule 1.5 is the **gateway for all domain-specific vocabulary**. Without it, every
project noun (`repository`, `middleware`, `race condition`) would be forbidden and
documentation would be unusable. With it, a non-approved word is allowed *only*
when it names a precise concept in one of the nineteen categories below.

## The three-word gate (Rules 1.1, 1.5, 1.6)

Use an approved word whenever one exists. Use a code-domain technical noun only
when no approved word names the concept. These three rules form a gate with no
fourth category:

| Gate | Rule | Allows |
|------|------|--------|
| Approved word | 1.1 | A word listed in the controlled terminology (the dictionary). |
| Technical noun | 1.5 | A non-approved word that fits at least one of the 19 categories below **and** is registered in your glossary. |
| Technical verb | 1.12 | A verb in the technical-verb category (for example `build`, `deploy`, `test`, `lint`, `compile`, `debug`). |

Any word that passes **none** of these three gates is forbidden by Rule 1.6.

> Non-STE: The developer used the thing to get data from the storage layer and put it on the screen.
> STE: The frontend developer used the API client to get data from the database and show it on the UI.
> (`frontend developer` = category 11, `API client` = category 16, `database` = category 18, `UI` = category 8 — each names a precise concept; "thing", "storage layer", "screen" do not.)

## Glossary registration (required)

Before you use a code-domain technical noun in documentation, add it to the
project glossary or terminology database. The glossary entry must specify:
- The noun term.
- The STE-Code category (or categories) it belongs to.
- The approved meaning in the project context.
- An example sentence that uses the noun correctly.

A project without a glossary risks ambiguity: the same noun may mean different
things to different readers, which also violates Rule 1.11 (one term per concept).
Project-specific internal names (for example `PhoenixCache`, `Hammerhead subsystem`)
are permitted only after glossary registration; without it they are non-approved
words and violate Rule 1.6.

---

## The 19 code-domain technical noun categories

The terms under each category are **examples only** — Rule 1.5 does not give a
full list. A word belongs in a category if it names a precise software concept.
Register every project-specific noun in your glossary before using it. When a term
is a literal identifier, API name, or exact string from code (a class name,
function name, environment variable, or error message), show it in backticks —
for example `UserRepository`, `NODE_ENV`, `"404 Not Found"`.

### 1. Code components, modules, and libraries
Software parts, packages, and reusable units of code.
`class`, `controller`, `helper`, `hook`, `middleware`, `mixin`, `module`, `package`, `plugin`, `provider`, `repository`, `service`, `utility`

### 2. Computing devices and their components
Hardware, devices, and physical computing resources.
`CPU`, `disk`, `GPU`, `keyboard`, `laptop`, `memory`, `monitor`, `mouse`, `printer`, `screen`, `server`, `smartphone`, `tablet`, `terminal`

### 3. Development tools, environments, and support equipment
Development tools, IDEs, build systems, and testing frameworks.
`CLI`, `compiler`, `debugger`, `Docker`, `editor`, `IDE`, `Git`, `Jest`, `linter`, `loader`, `Prettier`, `terminal`, `test runner`, `TypeScript`, `webpack`

### 4. Data structures, types, and formats
Data representation, storage structures, and file formats.
`array`, `boolean`, `buffer`, `CSV`, `enum`, `hash map`, `integer`, `JSON`, `linked list`, `object`, `queue`, `stack`, `string`, `struct`, `tree`, `tuple`, `XML`, `YAML`

### 5. Infrastructure, deployment, and platforms
Hosting, deployment, containerization, and runtime platforms.
`AWS`, `CI/CD`, `container`, `deployment`, `Heroku`, `Kubernetes`, `load balancer`, `Node.js`, `pipeline`, `pod`, `production`, `staging`, `Vercel`

### 6. Systems, subsystems, and architectural components
System design, architecture patterns, and their parts.
`API gateway`, `authentication layer`, `caching layer`, `client`, `database layer`, `message broker`, `microservice`, `proxy`, `rate limiter`, `REST API`, `routing layer`, `server`, `WebSocket`

### 7. Mathematical, algorithmic, and scientific terms
Algorithms, computational concepts, and mathematical formulas.
`Big O notation`, `binary search`, `coefficient`, `complexity`, `exponent`, `hash function`, `iteration`, `logarithm`, `matrix`, `recursion`, `regex`, `sorting algorithm`, `time complexity`, `traversal`

### 8. Interface elements and navigation
UI components, navigation controls, and layout elements.
`button`, `checkbox`, `dialog`, `dropdown`, `footer`, `header`, `menu`, `modal`, `navigation bar`, `radio button`, `scrollbar`, `sidebar`, `tab`, `text field`, `toggle`, `tooltip`

### 9. Numbers, units of measurement, and time
Quantitative data, measurements, and time-related information.
`byte`, `gigabyte (GB)`, `hertz (Hz)`, `hour (h)`, `kilobyte (KB)`, `megabyte (MB)`, `millisecond (ms)`, `minute`, `nanosecond (ns)`, `second (s)`, `terabyte (TB)`

### 10. Quoted text
Texts you cannot change in code documentation — error messages, code snippets, UI labels, log output.
`Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused`

### 11. Professional roles, teams, and organizations
Roles, individuals, organizations, and teams related to software development.
`administrator`, `backend developer`, `contributor`, `DevOps engineer`, `frontend developer`, `Google`, `maintainer`, `Microsoft`, `product owner`, `QA engineer`, `reviewer`, `scrum master`, `user`

### 12. Official documents, API references, and standards
Documentation types, standards, specifications, and their structural parts.
`API reference`, `changelog`, `code of conduct`, `contributing guide`, `diagram`, `figure`, `Getting Started guide`, `HTTP specification`, `note`, `paragraph`, `README`, `release notes`, `RFC`, `section`, `table`, `warning`

### 13. Runtime environments and operational conditions
Execution contexts, environment variables, and operating parameters.
`development`, `environment variable`, `garbage collection`, `heap`, `hot reload`, `live reload`, `memory leak`, `production`, `sandbox`, `stack trace`, `staging`, `test`, `thread`, `timeout`, `virtual machine`

### 14. Colors
Colors that identify color-related properties in code (CSS, terminal output, syntax highlighting).
`black`, `blue`, `cyan`, `gray`, `green`, `magenta`, `orange`, `red`, `white`, `yellow`
Colors are adjectives, but STE-Code identifies them as code-domain technical nouns. Comparative and superlative forms (for example, `blacker`, `the reddest`) are not permitted.

### 15. Defects, errors, and fault terminology
Types of software defects, errors, and malfunctions.
`assertion failure`, `bug`, `crash`, `deadlock`, `defect`, `exception`, `hang`, `infinite loop`, `memory leak`, `null pointer`, `race condition`, `regression`, `stack overflow`, `timeout`, `type error`

### 16. Computer science, information, and communication technology
Concepts, technologies, and architectures in computing and communication.
`AI`, `algorithm`, `authentication`, `authorization`, `blockchain`, `containerization`, `cryptography`, `database`, `encoding`, `encryption`, `firewall`, `hashing`, `internet`, `machine learning`, `metadata`, `neural network`, `protocol`, `query`, `sandbox`, `schema`, `token`, `virtualization`

### 17. Legal and licensing terms
Software licenses, legal documents, and compliance terminology.
`Apache 2.0`, `BSD license`, `compliance`, `copyright`, `GPL`, `license`, `MIT license`, `open source`, `proprietary`, `terms of service`, `third-party`, `trademark`, `warranty`

### 18. Database and storage terminology
Database concepts, storage systems, and data persistence.
`connection pool`, `cursor`, `foreign key`, `index`, `migration`, `NoSQL`, `ORM`, `PostgreSQL`, `primary key`, `query`, `Redis`, `relation`, `row`, `schema`, `seed`, `SQL`, `SQLite`, `stored procedure`, `table`, `transaction`, `view`

### 19. Network and protocol terminology
Networking concepts, protocols, and communication.
`DNS`, `endpoint`, `HTTP`, `HTTPS`, `IP address`, `localhost`, `middleware`, `packet`, `port`, `request`, `response`, `route`, `socket`, `SSH`, `TCP`, `TLS`, `UDP`, `URL`, `VPN`, `WebSocket`

---

## Apply the categories by document type

Use the categories named here as your first-choice technical nouns for each kind
of documentation. Use an approved verb everywhere an approved word fits.

- **README files** — categories 1 (code components), 3 (development tools), 5 (infrastructure), 17 (legal). Example: "This package provides a `middleware` for `Express`." (`package` c1, `middleware` c1, `Express` c5.)
- **API documentation** — categories 6 (systems), 18 (database), 19 (network). Example: "The `GET /users/:id` route returns a `JSON` object with a user `struct`." (`route` c19, `JSON` c4, `struct` c4.)
- **Docstrings and inline comments** — categories 4 (data types), 7 (algorithms), 15 (defects). Example: "Traverse the binary search tree in-order and return a sorted `array`."
- **Commit messages** — categories 1 (code components), 15 (defects), 18 (database). Example: "Fix a `timeout` defect in the `connection pool` that caused a `deadlock` on `PostgreSQL`."
- **Error messages** — categories 13 (runtime), 15 (defects), 19 (network). Example: "Connection refused: the `TCP` `socket` on `port 5432` timed out after 30 seconds."
- **Test specifications** — categories 1 (code components), 4 (data types), 15 (defects). Example: "The test calls the `parseConfig` function with a `null pointer` and checks that it returns an `assertion failure`."

## Paradigm-specific guidance

Use the categories shown as your first-choice technical nouns for each paradigm.

- **Object-oriented (Java, C++, C#, Python classes)** — categories 1 (code components), 4 (data types), 6 (systems). Class, method, interface, and design-pattern names are technical nouns. Acceptable: "The `UserRepository` class extends the `BaseRepository` abstract class and implements the `IAuditable` interface." Do not write "The repo leverages the base to retrieve user data." (`leverage` is not approved; `repo` is a non-standard abbreviation — use `repository`.)
- **Functional (Haskell, Elixir, Clojure, Rust)** — categories 7 (algorithms), 4 (data types), 16 (computer science). Terms such as `monad`, `functor`, `closure`, `currying`, `pattern matching`, `recursion`, `immutability` are technical nouns. Acceptable: "The function returns an `Option` monad. Use pattern matching to extract the value." Do not write "The combinator stuff chains stuff together to make new stuff."
- **Procedural (C, Go, Bash)** — categories 4 (data types), 13 (runtime), 19 (network). Terms such as `pointer`, `struct`, `mutex`, `goroutine`, `channel`, `file descriptor`, `signal` are technical nouns. Acceptable: "The C function accepts a `pointer` to a `FILE` struct and returns an integer status code." Do not write "The script fires off a subprocess to crunch the numbers." (`fires off` → `starts`; `crunch` → `process`.)
- **Declarative (SQL, Terraform, Kubernetes YAML)** — categories 18 (database), 5 (infrastructure), 12 (official documents). `SELECT`, `JOIN`, resource, module, provider, pod, deployment, namespace are technical nouns; SQL keywords and YAML keys are quoted text (category 10) when referenced verbatim. Acceptable: "The `SELECT` statement uses an `INNER JOIN` on the `users` and `orders` tables." Do not write "K8s spins up a bunch of pods inside the thing." (`K8s` → `Kubernetes`; `spins up` → `starts`; `thing` → `namespace`.)
- **Systems programming (Rust ownership, C memory management)** — categories 13 (runtime), 4 (data types), 15 (defects). `ownership`, `borrow`, `lifetime`, `stack`, `heap`, `allocation`, `undefined behavior`, `segmentation fault` are technical nouns. Acceptable: "The Rust compiler enforces the ownership rules. The borrow checker prevents dangling pointers at compile time." Do not write "Rust's thingy stops you from shooting yourself in the foot with memory stuff."

---

## Edge cases

- **Framework names that are also common words** (`React`, `Vue`, `Swift`, `Go`, `Rust`, `Elm`, `Next`, `Nest`). When a framework name is also an approved word, the framework name is a code-domain technical noun (category 3 or 5) and does not follow the approved meaning. Always capitalize it to disambiguate: "Use the `React` framework to build the user interface" (not the verb *react*); "The `Go` compiler builds the binary" (not the verb *go*).
- **Code keywords in documentation.** Keywords (`if`, `else`, `for`, `while`, `return`, `class`, `def`, `fn`, `let`, `const`, `var`, `async`, `await`) are quoted text (category 10) when they appear in documentation. Use backticks. When you use them as English words in a sentence, they must follow approved meanings. Write: "If the request fails, return `500 Internal Server Error`." (not "return a 500" — `500` is quoted text or a category-9 noun and must appear verbatim).
- **Abbreviations and acronyms** (`API`, `JSON`, `SQL`, `HTML`, `CSS`, `HTTP`, `TCP`, `TLS`, `DNS`, `URL`). Permissible as technical nouns in categories 16, 18, or 19. Define each at first use unless universally understood: "The application programming interface (API) uses Hypertext Transfer Protocol Secure (HTTPS)." Then "The API returns a JSON response over HTTPS." Do not write "The API leverages HTTPS to transmit the payload" (`leverage`/`transmit`/`payload` are not approved — use `use`/`send`/`data` or define `payload` as a technical noun).
- **Generated code and auto-generated docs.** OpenAPI specs, protobuf stubs, migration files, JSDoc/Sphinx output are not required to follow STE-Code (a machine produces them). Any human-written comment, description, or annotation inside generated files must follow STE-Code. Write `// Workaround: clear the Redis cache when the heap reaches the limit.` Do not write `// this hack works around a funky TS bug` (`hack` → `workaround`; `funky` → `known defect`; `TS` → `TypeScript`).
- **Project-specific internal names.** Permitted under category 1 or 6 only after glossary registration. "The `PhoenixCache` layer stores frequently accessed data in memory." is acceptable *with* a glossary entry; without it, Rule 1.6 forbids the name.
- **Numbers as technical nouns.** A version (`Node.js 18`), HTTP status (`404`), or port (`port 5432`) is a category-9 noun or quoted text (category 10) when it is a fixed, named token, not a measured quantity. Write: "The service runs on `port 5432` and returns `404 Not Found` when the row is absent." Do not write "the default db port" or "a not found error."

## Grammar notes

- **Articles.** Use `the` for a specific instance, `a`/`an` for an indefinite instance, and no article for plural general references. "The `UserController` handles a request. The controller returns a response." / "Kubernetes pods run in a namespace."
- **Technical nouns as modifiers.** A technical noun can modify another noun to form a compound, if both belong to a recognized category. "The `Redis` cache server stores the session data." (`Redis` c18 modifies `cache server` c6; `session data` = `session` c13 + `data` c4.) Do not write "The thing layer processes the stuff queue."
- **Possessive form.** Permit `'s` only with category-11 nouns (roles, organizations). "The user's session data is encrypted." Use "of" or noun-as-modifier for all other categories: "The configuration of the `Docker` container is stored in a YAML file." Do not write "The `Docker` container's configuration…".
- **Pluralization.** Standard English rules. Acronyms take a lowercase `s` without an apostrophe. "The system uses two APIs and three SQL queries." Do not write "two API's and three SQL's".
- **Capitalization.** Proper-noun technical nouns (language names, company names, product names) keep their capitalization; common technical nouns use lowercase unless sentence-initial. "The `TypeScript` compiler checks the types. The controller handles the request." Do not write "the typescript compiler" or "The Controller".

## Cross-references

- **Rule 1.1 (Approved Words):** the dictionary of approved common-vocabulary words. Rule 1.5 is the exception that lets you use non-approved words as technical nouns.
- **Rule 1.2 (Part of Speech):** use a technical noun only as a noun or noun modifier; never as a verb.
- **Rule 1.3 (Approved Meanings):** use each technical noun only with the meaning registered in your glossary.
- **Rule 1.4 (Verb and Adjective Forms):** a word that is a technical noun may still have an approved verb form — use the verb form for actions and the noun form for naming concepts.
- **Rule 1.6 (Non-Approved Words):** forbids every non-approved word that is not a code-domain technical noun. Read Rules 1.5 and 1.6 together.
- **Rule 1.7 (Technical Nouns as Verbs):** a technical noun cannot be used as a verb (for example `host` is a noun; use `make available` or `run`).
- **Rule 1.8 (Standard Technical Nouns):** use widely accepted terms; do not invent one when a standard exists.
- **Rule 1.9 (Short Technical Nouns):** prefer short, clear technical nouns.
- **Rule 1.11 (One Term per Concept):** each technical noun refers to exactly one concept in your project.
- **Rule 1.12 (Technical Verbs):** `build`, `deploy`, `test`, `lint`, `compile`, `debug` and similar are permitted technical verbs — they are not technical nouns; do not confuse the two.

## Summary

Rule 1.5 is the gateway for all domain-specific vocabulary. It permits a word
outside the approved dictionary *only* when that word names a precise concept in
one of the nineteen code-domain categories above and is registered in your project
glossary. Follow it together with Rules 1.1 and 1.6: documentation then uses exactly
two kinds of words — approved STE-Code words for common vocabulary, and code-domain
technical nouns (plus technical verbs) for domain-specific concepts. There is no
third category.

---

<!-- 03-dictionary.md -->

# Level 1 — Adapted Dictionary (A–Z excerpt)

A code-domain adaptation of the ASD-STE100 Issue 9 dictionary (Part 2, pp. 149–434).
It teaches the STE approval model for words: which words are approved, which are
not, and how to rewrite unapproved words into approved ones using code examples.

Use this slice when you write or review:
- API documentation and reference pages
- Commit messages and pull-request descriptions
- README sections and module/package overviews
- Inline code comments and docstrings

Scope note: this excerpt shows the entry format with a few canonical examples
(letter **A**). The complete approved (~875) and unapproved (~1274) word lists
are bundled at higher STE-Code tiers. Lower tiers use this curated sample to
learn the pattern; do not invent words beyond what the dictionary lists.

---

## How to read an entry

- **UPPERCASE words** are approved in STE-Code — you may use them.
- **lowercase words** are unapproved — replace them with the listed alternative.
  Unapproved status is also marked with the tag **UNNAPROVED** on the entry.
- Each entry carries a part-of-speech tag:
  `(v)` verb · `(n)` noun · `(adj)` adjective · `(adv)` adverb ·
  `(prep)` preposition · `(conj)` conjunction · `(pron)` pronoun · `(art)` article
- Code-domain technical tags:
  `(TN)` = code-domain Technical Noun (e.g. *config*, *endpoint*, *pipeline*)
  `(TV)` = code-domain Technical Verb (e.g. *deploy*, *build*, *parse*)
- Every entry shows three things:
  1. the original ASD-STE100 rule text,
  2. the same idea rewritten for code documentation,
  3. one or more STE / non-STE code-example pairs demonstrating the approved form.

### LLM guidance

When generating or reviewing code documentation, prefer UPPERCASE-approved words
and the verbs listed as alternatives for unapproved words (e.g. use `STOP`/`TERMINATE`
instead of `abandon`, `CAN` instead of `ability to`). Keep the approved form as
the short, direct sentence; the non-STE form is the longer, indirect phrasing to
avoid.

---

# A

## A (art)
Function word: indefinite article.
- **Original:** A FUEL PUMP IS INSTALLED IN ZONE 10.
- **Code-domain:** A CONFIG FILE IS INCLUDED IN THE ROOT DIRECTORY.
- **STE:** A config file is included in the root directory.
- **Non-STE:** Config files included in root directory.

## ABANDON (v) — UNNAPROVED
Not approved. Replace with `STOP` (v) or `TERMINATE` (v).
- **Original:** GO (v), STOP (v). IF THERE IS A FIRE, IMMEDIATELY GO TO A SAFE AREA. / IF THE VALUES ARE INCORRECT, STOP THE TEST PROCEDURE.
- **Code-domain:** TERMINATE (v), STOP (v). IF THE BUILD FAILS, STOP THE DEPLOYMENT PIPELINE. / IF THE VALUES ARE INCORRECT, TERMINATE THE TEST RUN.
- **STE:** If the build fails, stop the deployment pipeline.
- **Non-STE:** If the build fails, abandon the deployment pipeline.
- **STE:** If the values are incorrect, terminate the test run.
- **Non-STE:** If the values are incorrect, abandon the test procedure.

## ABILITY (n) — UNNAPROVED
Not approved. Replace with `CAN` (v).
- **Original:** CAN (v). ONE GENERATOR CAN SUPPLY POWER FOR ALL THE SYSTEMS.
- **Code-domain:** CAN (v). ONE CONFIGURATION CAN HANDLE REQUESTS FOR ALL THE ENDPOINTS.
- **STE:** One configuration can handle requests for all the endpoints.
- **Non-STE:** One configuration has the ability to handle requests for all the endpoints.

---

## Quick substitutions (from this excerpt)

| Unapproved (avoid) | Approved replacement | Example (STE) |
| --- | --- | --- |
| abandon (v) | STOP (v), TERMINATE (v) | If the build fails, stop the deployment pipeline. |
| ability (n) (as "has the ability to") | CAN (v) | One configuration can handle all the endpoints. |

When you see an unapproved word in source text, swap it for the approved verb and
keep the sentence short and direct. Approved articles such as **A** stay as-is.

---

<!-- 04-templates.md -->

# Level 1 — Document Templates (Code Review / PR Feedback)

These templates apply STE-Code Level 1 (Rules 1.1–1.14) to the two document
types where controlled words matter most in day-to-day engineering work: code
review comments and pull request feedback.

Each template is a fill-in shape. Every word you add must pass one of the three
Level 1 gates:

1. It is approved in the controlled terminology (the STE-Code dictionary).
2. It is a code-domain technical noun (Rule 1.5, 19 categories).
3. It is a code-domain technical verb (Rule 1.12).

Identifiers, file paths, commands, and type names are technical nouns. Write
them in backticks and do not inflect them.

## Template selection

| Situation | Template |
|-----------|----------|
| One line or one hunk in a diff | T1 — Inline review comment |
| A defect the author must fix before merge | T2 — Blocking review finding |
| An optional improvement | T3 — Non-blocking suggestion |
| The summary you leave on the whole pull request | T4 — PR review summary |
| The description the author writes on the pull request | T5 — PR description |
| A reply to review feedback | T6 — Author response |

## Shared word rules for all templates

| Do not write | Write |
|--------------|-------|
| This looks a bit weird / smells off | This function returns `null` when the input list is empty. |
| Can we maybe just not do this? | Remove the call to `resetCache`. |
| It'd be great if you could refactor | Move the retry logic into `RetryPolicy`. |
| The code is broken | The `parseDate` function throws `TypeError` for an empty string. |
| We should probably handle errors | Catch `IOError` in `readConfig` and return a default value. |

Rules applied above: 1.1 (approved words only), 1.9 (short technical nouns),
1.10 (no slang or jargon), 1.11 (one noun per item).

## T1 — Inline review comment

Shape (three parts, in this order):

```
<observation>: one sentence, one subject, present tense.
<effect>: one sentence that gives the result of the observation.
<action>: one imperative sentence.
```

Example:

> The `getUser` function returns `undefined` when `id` is `0`.
> The caller in `UserController` then reads a property of `undefined`.
> Return `null` for an unknown `id`, and check the result in `UserController`.

Constraints:

- Use the imperative form for the action (Rule 5.3 style, applied at word level
  by Rule 1.4: approved verb forms only).
- Name the item with the same technical noun each time (Rule 1.11). Do not write
  `getUser`, then "the getter", then "that helper".
- Do not use a technical noun as a verb (Rule 1.7). Write "Send a request to the
  `/users` endpoint", not "Endpoint the request".

## T2 — Blocking review finding

```
**Finding:** <one sentence: what is wrong>
**Location:** `<path>:<line>` in `<symbol>`
**Cause:** <one sentence>
**Result:** <one sentence: what fails, and when>
**Required change:** <one imperative sentence>
```

Example:

> **Finding:** The `saveOrder` method does not validate the `quantity` field.
> **Location:** `src/orders/service.ts:142` in `OrderService.saveOrder`
> **Cause:** The method writes the request body to the database with no check.
> **Result:** A negative `quantity` value is written to the `orders` table.
> **Required change:** Reject a request when `quantity` is less than `1`.

Use "required change" for a defect. Do not use "must" as an intensifier in the
prose. The field label already gives the obligation.

## T3 — Non-blocking suggestion

```
**Suggestion (optional):** <one imperative sentence>
**Reason:** <one sentence>
```

Example:

> **Suggestion (optional):** Move the three retry constants into `RetryPolicy`.
> **Reason:** The same three values occur in `HttpClient` and in `QueueWorker`.

Mark the comment as optional in the first word. Do not use hedge words such as
"maybe", "perhaps", or "just" to signal that a comment is optional (Rule 1.10).

## T4 — PR review summary

```
**Decision:** Approve | Request changes | Comment
**Scope:** <one sentence: what the pull request changes>
**Blocking findings:** <count>
1. <one sentence each, with `path:line`>
**Optional suggestions:** <count>
1. <one sentence each>
**Verification:** <one sentence: what you ran or read>
```

Example:

> **Decision:** Request changes
> **Scope:** The pull request adds a rate limiter to the `/api/v1/login` route.
> **Blocking findings:** 1
> 1. `src/middleware/rateLimit.ts:58` — The limiter counts a failed request and
>    a successful request in the same bucket.
> **Optional suggestions:** 1
> 1. Give the `WINDOW_MS` constant a unit in its name.
> **Verification:** I ran `npm test` and read the diff in `src/middleware`.

Write the decision as one of the three approved values. Do not invent a fourth
value, and do not write the decision as a sentence.

## T5 — PR description (author)

```
## What
<one to three sentences. One subject in each sentence.>

## Why
<one to three sentences. Give the cause, then the result.>

## How
1. <imperative sentence>
2. <imperative sentence>

## Test
- <one sentence per check, with the command in backticks>

## Risk
<one sentence. Write "None." when there is no risk.>
```

Example:

> ## What
> This pull request adds a retry to the `PaymentClient.charge` method.
>
> ## Why
> The payment gateway returns `503` during a deployment. The current client
> fails the order on the first `503` response.
>
> ## How
> 1. Add a `RetryPolicy` class with three attempts and an exponential delay.
> 2. Call `RetryPolicy.execute` from `PaymentClient.charge`.
>
> ## Test
> - Run `npm test -- payment` to check the new unit tests.
> - Send a request to the sandbox gateway to check the delay values.
>
> ## Risk
> A retry can create a duplicate charge if the gateway accepted the first
> request. The client sends an idempotency key to prevent this result.

## T6 — Author response to feedback

```
**Comment:** <link or `path:line`>
**Response:** Done | Changed | Not changed
**Detail:** <one sentence>
```

Example:

> **Comment:** `src/middleware/rateLimit.ts:58`
> **Response:** Changed
> **Detail:** The limiter now counts only a failed request in the login bucket.

Use one of the three approved response values. Do not use "LGTM", "nit", "wontfix",
or other jargon labels (Rule 1.10).

## Approved verbs for review and PR text

Use these code-domain technical verbs in the action line of any template. Use
the base form for an instruction, and the third-person form for a statement of
fact.

| Verb | Use it for |
|------|-----------|
| add | New code, a new field, a new file |
| remove | Deleted code or a deleted field |
| replace | One item exchanged for another |
| move | Code relocated with no change in behavior |
| rename | A new name for the same item |
| return | The value a function gives back |
| throw / raise | An error the code emits |
| catch / handle | An error the code accepts |
| validate | A check on input |
| reject | A refused input or request |
| call | Invocation of a function or method |
| read / write | Access to a file, field, or record |
| log | A record written to the audit trail or log |
| test | A check that runs in the test suite |

Do not use a verb from this table as a noun (Rule 1.13). Write "The function
returns a value", not "The return of the function".

## Forbidden words in review and PR text

| Forbidden | Reason | Use instead |
|-----------|--------|-------------|
| nit, LGTM, WIP, PTAL, IMO | jargon (Rule 1.10) | the full template label |
| smelly, hacky, ugly, clean | subjective, not approved (Rule 1.1) | the concrete defect |
| stuff, thing, some code | not a technical noun (Rule 1.5) | the identifier in backticks |
| leverage, utilize | not approved (Rule 1.3) | use |
| behaviour, initialise, colour | British spelling (Rule 1.14) | behavior, initialize, color |
| we should maybe possibly | hedging (Rule 1.1) | one imperative sentence |

## Checklist before you post

1. Each sentence has one subject.
2. Each item has one name, used every time (Rule 1.11).
3. Each identifier is in backticks and is not inflected.
4. Each action is one imperative sentence.
5. No word from the forbidden table is present.
6. Spelling is American English (Rule 1.14).
