vocabulary-agent-files

Vocabulary Agent Files

Trigger

• Use when a workspace governed by the agent-files four-file contract needs one fixed vocabulary shared by its documents and code.
• Use when reports and code in a workspace have drifted into near-synonyms and need a recorded merge procedure.
• Do not use for a one-off glossary in a workspace that has no agent-files contract; scaffold the contract first or keep a plain glossary instead.
• Do not use to rename stored data keys, command-line names, or frozen experiment text; those surfaces are explicitly protected below.

Inputs

• target_dir: directory holding the agent-files contract where AGENT_VOCABULARY.md will be created
• sources: optional list of files or directories (documents, code) to scan for the workspace's established words
• overwrite: when true, an existing AGENT_VOCABULARY.md is replaced; otherwise it is kept and recorded in files_skipped

The Vocabulary File Contract

AGENT_VOCABULARY.md opens with a short statement — "This file lists the words used in the documents and the code. Use these words and no others." — followed by three highlighted rules in one blockquote:

1. Merge rule. If two words mean the same thing, keep only the most proper one and replace the other everywhere.
2. Self-contained rule. Each description uses only everyday words and words defined earlier in the file.
3. Recursive word check. Check every description word by word, and recursively: any vague word, and any word that is neither an everyday word nor defined earlier in the file, must be replaced by a concrete one — then re-check the replacement, until every word passes.

The body holds four sections, each one entry per line in the format word: short description.:

• ## Nouns, ## Adjectives, ## Verbs — the established words, ordered so every description depends only on entries above it (base words of the domain first).
• ## Unmerged Words (temporary memory) — words found in the sources that are not yet merged, one line each in the format word — where it lives — what to do (a merge target, or open when no proper word is chosen yet). This section is working memory: lines are removed when their merge is executed and added when new drift is found.