fix: ban phantom Axxxxx codes with guards section 14 (#1489)

## Summary

Closes the recurring class of issues where agents invent error codes in
module docs (`A09104`, `A53007`, …) without catalog entries or emitters,
then we file endless follow-ups.

## Rule (mechanical)

1. **Never** assign an `Axxxxx` number until the check is implemented
**and** registered in `assura-diagnostics` catalog **in the same PR**.
2. Future work is described in prose without a code number.
3. `scripts/guards.sh` **section 14** hard-fails phantom mentions (CI).

## Changes

- guards section 14 + AGENTS.md same-PR rule
- Remove reserved fake codes from taint / quantifier-trigger module docs
- Drop one-off unit test that listed three reserved codes (class-level
guard replaces it)
- Clarify project-check comment (no fake A02000)

## Closes

Closes #1486
Closes #1487

These were symptoms of the class, not separate product features. Partial
taint sanitization or richer trigger validation can return as real
features later **with** catalog+emit+tests in one PR, without
pre-reserving numbers.

## Test plan

- [x] `bash scripts/guards.sh` (green)
- [x] Injected phantom `A09104` is detected by guards
- [x] `cargo test -p assura-diagnostics --locked --lib`
- [ ] CI green

---------

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>

Author: SebTardif

AGENTS.md

@@ -83,9 +83,14 @@ Do not improvise a parallel pipeline. Follow the branch that matches your task.
 
 Full meanings: `docs/SPECIFICATION.md` §7.2 / Appendix D. Do not fix an `A02` in `assura-smt` or an `A01` in `assura-types` unless the index explicitly says cross-phase.
 
-**When you introduce or rely on a code not in the index:** append one row to
-`docs/error-codes.md` in the same PR (high-traffic section is fine). Do not
-regenerate all of Appendix D.
+**When you introduce a new error code:** in the **same PR** (1) implement and
+emit it, (2) add the catalog entry in `assura-diagnostics`, (3) append a row to
+`docs/error-codes.md` (high-traffic section is fine). Do **not** invent `Axxxxx`
+numbers in module docs, comments, or TODOs for unimplemented checks. Describe
+future work in prose without a code number until it is wired. `scripts/guards.sh`
+section 14 hard-fails phantom codes (mentions outside the catalog in
+`crates/**/*.{rs,md}` and `docs/**/*.md`). Sentinels `A00000` / `A88888` /
+`A99999` only. Do not regenerate all of Appendix D.
 
 ### `assura-types` layer map (summary)
 

crates/assura-cli/src/check/project.rs

@@ -48,7 +48,7 @@ pub(crate) fn run_check_project(
                         .iter()
                         .map(|e| {
                             let msg = e.to_string();
-                            // Map to catalog codes (A02000 is not a valid code).
+                            // Map resolve errors onto real catalog codes only.
                             let code = if msg.to_ascii_lowercase().contains("circular") {
                                 "A02005"
                             } else {

crates/assura-diagnostics/src/lib.rs

@@ -447,18 +447,6 @@ mod tests {
         }
     }
 
-    /// Codes mentioned in checker module docs as future work must not
-    /// silently appear in the catalog until they are implemented and wired.
-    #[test]
-    fn reserved_error_codes_not_yet_in_catalog() {
-        for code in ["A09104", "A53007", "A53008"] {
-            assert!(
-                explain(code).is_none(),
-                "{code}: reserved/future code must not be in catalog until implemented"
-            );
-        }
-    }
-
     #[test]
     fn test_explain_all_catalog_codes() {
         let catalog = error_catalog();

crates/assura-types/src/checkers/taint.rs

@@ -90,8 +90,8 @@ pub(crate) fn extract_taint_label(
 /// - **A09102**: Tainted data used as allocation size without validation
 /// - **A09103**: Tainted data flows to trusted sink
 ///
-/// Reserved for future checks (not yet emitted; not in the diagnostics catalog):
-/// - **A09104**: Taint validation incomplete (partial sanitization)
+/// Do not invent further `Axxxxx` numbers here until the check is implemented
+/// and registered in `assura-diagnostics` catalog in the same change.
 #[derive(Debug, Clone)]
 pub(crate) struct TaintChecker {
     /// Maps variable name to its taint label.

crates/assura-types/src/domain/core/quantifier_trigger.rs

@@ -8,12 +8,11 @@ use crate::TypeError;
 
 /// Validates quantifier trigger annotations for verification performance.
 ///
-/// Error codes (currently emitted):
+/// Error codes:
 /// - A53006: quantifier has no trigger annotation
 ///
-/// Reserved for future checks (not yet emitted; not in the diagnostics catalog):
-/// - A53007: trigger references variable not bound by the quantifier
-/// - A53008: trigger term is a sub-expression of the quantifier body (matching loop risk)
+/// Do not invent further `Axxxxx` numbers here until the check is implemented
+/// and registered in `assura-diagnostics` catalog in the same change.
 #[derive(Debug, Clone)]
 pub struct QuantifierTriggerChecker {
     quantifiers: Vec<QuantifierInfo>,

docs/EXPLAINER.md

@@ -303,7 +303,7 @@ graph TD
     subgraph "Pass 2: Checking"
         D["For each function body"] --> E["Track taint through\nexpressions"]
         E --> F{Tainted data at\nsensitive position?}
-        F -->|Yes| G["Error A09101-A09104"]
+        F -->|Yes| G["Error A09101-A09103"]
         F -->|No| H["OK"]
     end
     B --> D
@@ -353,7 +353,6 @@ The fix: wrap `index` in a `validate` block that bounds-checks it:
 | A09101 | Tainted array index | Buffer overflow (CVE-2023-4863) |
 | A09102 | Tainted allocation size | Integer overflow in malloc |
 | A09103 | Tainted data at trusted sink | SQL injection, command injection |
-| A09104 | Incomplete validation | Partial sanitization bypass |
 
 ---
 
@@ -756,7 +755,7 @@ graph TD
 
     NR --> HIR["4. HIR Lowering\nNormalize taint annotation\ninto canonical form"]
 
-    HIR --> TC["5. Type Checker\nRun TaintChecker:\nA09101-A09104 errors"]
+    HIR --> TC["5. Type Checker\nRun TaintChecker:\nA09101-A09103 errors"]
 
     TC --> PW["6. Pipeline Wiring\nEnsure run_taint_checks()\nis called"]
 

scripts/guards.sh

@@ -479,6 +479,71 @@ else
   jsec 13 "IR template single source" "ok" "crate-local IR templates present; root has no pattern bodies"
 fi
 
+# ---------------------------------------------------------------------------
+# 14) No phantom Axxxxx codes outside the diagnostics catalog.
+#     Agents must not invent error codes in module docs, comments, or docs/
+#     before the code is implemented + registered in catalog.rs in the same
+#     change. Allowlist intentional sentinels only (unknown / test).
+#     Scans crates/**/*.{rs,md} and docs/**/*.md (catalog.rs excluded).
+# ---------------------------------------------------------------------------
+s14_fail=0
+if [[ -f crates/assura-diagnostics/src/catalog.rs ]]; then
+  # Extract catalog codes and every Axxxxx mention under crates/ + docs/.
+  # Fail if a mention is not in the catalog and not allowlisted.
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    code="${line%%	*}"
+    file="${line#*	}"
+    case "$code" in
+      A00000|A88888|A99999) continue ;; # unknown / test sentinels
+    esac
+    die "phantom error code $code (not in diagnostics catalog): $file"
+    die "  fix: implement the check + add catalog entry in the same PR, or remove the code number from docs"
+    jfind 14 "$file" "phantom $code not in catalog"
+    s14_fail=1
+  done < <(
+    python3 - <<'PY'
+import re
+from pathlib import Path
+
+catalog = set(
+    re.findall(
+        r'code:\s*"(A\d{5})"',
+        Path("crates/assura-diagnostics/src/catalog.rs").read_text(encoding="utf-8", errors="ignore"),
+    )
+)
+# Intentional non-catalog sentinels (also allowlisted in bash above).
+allow = {"A00000", "A88888", "A99999"}
+seen = set()
+roots = [
+    (Path("crates"), ("*.rs", "*.md")),
+    (Path("docs"), ("*.md",)),
+]
+for root, globs in roots:
+    if not root.is_dir():
+        continue
+    for g in globs:
+        for p in root.rglob(g):
+            if p.name == "catalog.rs" and "assura-diagnostics" in p.parts:
+                continue
+            text = p.read_text(encoding="utf-8", errors="ignore")
+            for code in set(re.findall(r"\bA\d{5}\b", text)):
+                if code in catalog or code in allow:
+                    continue
+                key = (code, str(p))
+                if key in seen:
+                    continue
+                seen.add(key)
+                print(f"{code}\t{p}")
+PY
+  )
+fi
+if [[ $s14_fail -eq 1 ]]; then
+  jsec 14 "no phantom Axxxxx codes" "fail" "Axxxxx mentioned outside catalog without allowlist"
+else
+  jsec 14 "no phantom Axxxxx codes" "ok" "all mentioned Axxxxx are cataloged or allowlisted sentinels"
+fi
+
 # ── Final output ─────────────────────────────────────────────────────────────
 if $json_mode; then
   python3 - "$_jdata" << 'PYEOF'