Docs hygiene: enforce in /alignment, add eng-council Documentation seat and beyond-scope notes

2026-08-08 02:02:33 +00:00 · 2026-06-14 23:57:39 +03:00
parent 6fc8c29b50
commit de9dbf3ec8
3 changed files with 79 additions and 28 deletions
@@ -108,6 +108,13 @@ or a major new section was added that should be discoverable. Not for minor addi

 - **Code walkthroughs**: prose that restates the code; goes stale on any rename. (Navigation
  maps that list file roles are fine.)
+- **TS code blocks that copy current implementation**: a snippet mirroring a real module
+  rots on its next rename. An illustrative _shape_ sketch is fine; for real code, point to
+  the file (navigation map) or state the rule it demonstrates.
+- **Stale-prone references**: positional sub-section cross-refs (`arch 07 §4` renumbers when
+  a section is inserted — cite the file `arch 07` or a named section) and exact counts
+  (test/file/LOC counts, one-off timings — state the qualitative fact; `codebase-metrics.md`
+  owns the tracked numbers).
 - **Obvious-from-code patterns**: if reading the file makes it clear, don't add docs.
 - **Session-specific context**: current task details, debugging steps taken.
 - **Speculative patterns**: only document conventions confirmed across multiple instances.