diff --git a/rules/common/docs-and-tests.md b/rules/common/docs-and-tests.md index 6b28220..c16382b 100644 --- a/rules/common/docs-and-tests.md +++ b/rules/common/docs-and-tests.md @@ -17,6 +17,29 @@ still blocked (missing trait or function signatures, how to construct core objects). +## Documentation Is Subordinate To The Implementation + +- The implementation, its tests, and the CI configuration are the source of + truth. A document that disagrees is stale by definition, however specific or + authoritative it reads. +- Never change code to satisfy a stale document. In particular, do not restore a + removed mechanism (an old dependency, a session style API, a feature flag, a + backend, an adapter layer) because a design note still describes it. +- When you find a stale statement, fix it in the same change if it is in scope and + name the code reference you used (`file:line`) in the commit or pull request so + the correction is checkable. If it is out of scope, open an issue with that + reference rather than leaving the prose in place. +- Treat these as high risk and verify them before acting: design documents marked + required reading, architecture pages that assign ownership of a module, and any + text stating which crate or package is the source of truth. Ownership drift in + these pages silently misdirects the next change, including the next agent. +- If you cannot tell which side is current, read the tests and the CI jobs for + that area. If they still disagree, ask before acting; do not assume the document + is right. +- When you delete an implementation, delete or rewrite the documents that describe + it in the same change. A removal that leaves the old description behind will be + reverted by a later agent acting on that description. + ## Examples - User-facing examples verify behavior, not just compile. diff --git a/rules/index.md b/rules/index.md index 2658079..efde256 100644 --- a/rules/index.md +++ b/rules/index.md @@ -1,5 +1,17 @@ # Tensor4all Agent Rules Index +## The Implementation Outranks The Documentation + +The code, its tests, and the CI configuration define current behavior. When a +document, design note, guide, code comment, or bundled skill says something the +code no longer does, the code wins. Read the stale sentence as a defect to report +and fix, never as an instruction to restore what it describes. + +Agents are pulled toward whatever a document asserts, so a confident paragraph +about a removed mechanism does more damage than a missing paragraph. Before you +act on any statement about behavior, confirm it against the implementation. If the +two disagree, do not edit code to satisfy the prose. + Read only the files relevant to the task: common rules first, then the applicable workflow and language rules.