convention: counter-prefix file naming across docs/specs/, docs/plans/, design/contracts/, design/models/
All 176 files in the four accumulating directories now use a zero-padded 4-digit counter prefix that reflects creation order (`NNNN-slug.md`). The counter is assigned per directory in strict git-log creation order; ties broken alphabetically by original name. The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is dropped — the date is recoverable from git log and the counter carries the ordering. A file's counter is stable for the life of the file: never reassigned, never reused, never compacted. Deleted files retire their counter; subsequent files do not fill the gap. This is the property that lets cross-references stay literal — refs use the full filename including the counter (`design/contracts/0007-honesty-rule.md`) so they grep cleanly and resolve directly without a glob step. 313 cross-references updated across .md/.rs/.toml/.c/.json files (test pins, include_str! paths, design-INDEX entries, baseline notes, runtime C comments, inter-contract markdown links incl. bare basename and `../models/foo.md` forms). CLAUDE.md gets a new "File-naming convention" section spelling out the rule and rationale. skills/brainstorm/SKILL.md and skills/planner/SKILL.md updated so new spec/plan creation produces counter-prefixed names from the start. The full test suite (cargo test --workspace) passes.
This commit is contained in:
@@ -0,0 +1,29 @@
|
||||
# The honesty rule this ledger holds itself to
|
||||
|
||||
`design/` describes what AILang **is now**: schema, semantics,
|
||||
invariants, runtime contracts. It is present-tense by construction.
|
||||
Two things never belong in a contract or model file:
|
||||
|
||||
- **Forward intent** (anything stated as planned, intended, or
|
||||
expected of a future iteration rather than true today) — that
|
||||
lives in the Gitea issue backlog.
|
||||
- **History and rationale** (how a prior draft read, what changed
|
||||
since, why one option was chosen, why another was rejected, what
|
||||
was dropped in some iteration) — that lives in `git log` (iter
|
||||
and audit commit bodies). Decision-records are commit-body
|
||||
content, not ledger content; this is the honesty rule it holds
|
||||
itself to.
|
||||
|
||||
A cross-reference that does belong stays: it is a formal,
|
||||
file-relative Markdown link into the durable tier (`design/` or
|
||||
source), enforced by the body-link durability gate in
|
||||
[`design_index_pin.rs`](../../crates/ailang-core/tests/design_index_pin.rs).
|
||||
A reference that cannot be expressed as such a link is, by that
|
||||
fact, the history-or-rationale prose the rule above removes.
|
||||
|
||||
The single legitimate exception is a present-tense reserved or
|
||||
deliberately-excluded claim that is explicitly and correctly
|
||||
labelled. The discriminator is not whether a sentence mentions past
|
||||
or future, but whether the document asserts something exists, works, or changed that does not.
|
||||
|
||||
Ratified by: `crates/ailang-core/tests/docs_honesty_pin.rs`.
|
||||
Reference in New Issue
Block a user