Conventions

These conventions define formatting, naming, and repository structure.

1. Formatting

Use 4-space indents in code and Markdown when the format supports configurable indentation.
Do not use tabs when the format supports spaces.
Use one sentence per line in Markdown, so git diff is easier to read.
Break long quoted lists in shell scripts to one item per line, so git diff is easier to read.
Use UPPERCASE names for shell variables that stay constant once defined.
Use whole words in shell variable names; do not abbreviate.
Give shell constants at least two words in semantic-sort order, broad first.
Prefix shell variable names with the type word, like file_input.
Use short, concise sentences in the style of Douglas Adams.
Do not apply sentence-per-line rules to code blocks.
Do not combine independent statements on one physical line.
Follow the target language’s formatter and syntax rules.
Follow the target language’s brace and block syntax.
Language and framework conventions override generic rules when required for correctness.

Compare constants first, on the left: write 5 == a, never a == 5.
An assignment where a comparison was intended becomes 5 = a, which the compiler flags as an error.
Write relational comparisons lesser-to-greater: write 5 < a, never a > 5.
Reading comparisons in one consistent order makes a reversed operator harder to miss.
Combine both conventions when the constant is the lesser value: write 5 < a, never a > 5.
When the variable is the lesser value, keep it on the left: write a < 5, never 5 > a.
Use <= and >= only when the strict form is wrong; apply the same lesser-on-the-left order.

The required directories are:

Feature numbers must be unique and must match the task, TODO item, or feature dependency.
Use the established feature name.
Do not invent a new feature name.
Use whole words in directory and filenames.
Do not use abbreviations in directory and filenames.
Scripts use semantic-sort names such as site-build.sh and site-sync.sh.
Script names order components from broad meaning to narrow meaning: <domain>-<role>.sh.
Source modules use names such as aspect_facet_category.ext.

Use an existing filename when the task identifies an existing file.
Before creating a file, reuse an established filename pattern.
A filename is valid only if it is:
- explicitly named by the task.
- already present in the repository.
- required by an established language, framework, or tool convention.
- required by a referenced feature specification.
- free of spaces and non-ASCII characters.
Do not invent filenames from an informal description.
Do not create synonymous, abbreviated, pluralized, or alternative filenames for an existing concept.
If more than one filename is plausible, ask for clarification.
If the required filename cannot be determined from the task, repository, or conventions, ask instead of guessing.
Do not rename an existing file unless the task explicitly requests it.

Document public APIs, non-obvious behavior, invariants, side effects, and externally visible formats.
Do not add comments that merely restate the code.
Include comments only when requested or when they explain non-obvious behavior.

Maintain .gitignore rules for generated output and logs.
Preserve required empty directories with placeholder files.
Generated files must be identified as generated.
Do not edit generated files manually unless explicitly requested.
Write generated output only to the designated output directory.
Do not mix source, prompt, and generated files.
Commit messages use one line in imperative mood with a conventional prefix (feat:, fix:, docs:, test:, chore:, refactor:) and a short summary.
A commit contains only the files of one completed task.
Never commit generated output or logs.
Live-state facts in hand-written documents carry a verification date: verified 2026-08-22.
Prefer generated documents over hand-written ones for anything that reflects live state.

A project whose documents reflect live or derived state should keep a single source of truth and generate the documents from it:

The model lives in sources/, for example sources/<area>-model.yaml.
A generator script in scripts/ produces the human documents from the model.
The generator provides a validation mode that checks the model and exits nonzero on errors.
Every generated document carries a provenance header: Generated from <model> by <script> — do not edit by hand.
The documents index (documents/README.md) marks generated documents as generated.
The generator’s validation mode runs under make test when the project defines it.

A program version is a build-time fact, not a source literal.

Derive the version from git state: date-branch-hash or date-branch-tag-hash.
date is the build date in YYYY-MM-DD form.
branch is the current git branch.
tag is appended only when all sources are committed and the current commit is tagged.
hash is the short git commit hash; it disambiguates builds from different commits, directories, and developers.
Suffix the hash with -changes when the working tree has uncommitted changes.
A build-time script generates a header that contains the version components and a build counter.
The build counter increments on each build; it is not checked in.
Keep the version-reporting function in a separate compilation unit, so a version change recompiles one unit instead of the whole program.
The generated header carries a provenance header and is not edited by hand.
The generated header is written to the build output directory, not into sources/.
Example: 2026-08-24-master-a1b2c3d or 2026-08-24-master-v1.0.0-a1b2c3d or 2026-08-24-master-a1b2c3d-changes.
The canonical generator name is scripts/version-generate.sh.
The canonical version header is version_info.h.
The canonical version functions are version_string() and version_build_counter().

Decided 2026-08-24: the git hash disambiguates builds, so the build counter policy is settled. Keep the local counter gitignored; never check it in.

Every task must identify each file operation as one of:

Also:

A file listed as existing is not automatically authorized for modification.
For every create, rename, or delete operation, the task must identify the exact source and target filename.
A directory name alone does not authorize creating a file with an invented name.