feat(directives): add 15 engagement-specific directives + tags.toml entries

2026-07-05 14:17:51 -04:00
parent 9434e4c6e9
commit 0c4a7621d4
31 changed files with 499 additions and 0 deletions
@@ -0,0 +1,24 @@
+# Audit scripts walk the filesystem fresh on every run — never pin to a historical snapshot
+
+## What it says
+
+Audit scripts MUST walk the filesystem fresh on every invocation. They MUST NOT cache the file list, pin to a historical snapshot, or read from a stale index. Each run is a fresh walk of `src/`, `tests/`, `scripts/`, or whatever directory the audit targets.
+
+## Why
+
+A stale audit misses regressions. If the audit reads from a cached file list (e.g., a JSON index written last session), it will not see files added, renamed, or deleted since. The audit's value is "what does the codebase look like RIGHT NOW." A historical snapshot answers the wrong question.
+
+## The pattern
+
+```python
+# WRONG: read from a cached index
+files = json.loads(Path("tests/artifacts/file_index.json").read_text())
+
+# RIGHT: walk fresh
+files = list(Path("src").rglob("*.py"))
+```
+
+## See also
+
+- `conductor/directives/generation_script_walks_filesystem_fresh_each_run` — the same rule for generation/index scripts
+- `conductor/directives/audit_script_as_gate` — the `--strict` gate companion