feat(audit): Tier 2 code-soundness (corrected spec) + core.selftest hardening

Supersedes the flawed-spec 12f33ae: DEAD now module/import-qualified (no
faithfulness_passed over-match), audit/ self-excluded, T2.4 redesigned as a
string/comment state machine that actually detects the orphan-*/ footgun,
_py() re-queried per call (fixtures validate), T2.6 robust to missing
ruff/tsc, core.selftest wraps each check (a raising check can't abort it).
11/11 self-verifying; --static 10 pass/1 warn/0 fail. Local only.

audit/core.py

@@ -78,9 +78,13 @@ def selftest() -> int:
     for c in CHECKS:
         fx = FIXTURES.get(c.id)
         if fx is None:
-            bad.append(f"{c.id}: NO selftest fixture"); continue
-        with fx():
-            r = c.fn()
+            bad.append(f"{c.id}: NO selftest fixture")
+            continue
+        try:
+            with fx():
+                r = c.fn()
+        except Exception as e:
+            r = Result(c.id, Status.FAIL, f"raised {type(e).__name__}: {e}")
         if r.status is not Status.FAIL:
             bad.append(f"{c.id}: expected FAIL on broken fixture, got {r.status.value}")
     for b in bad: print(f"  FAIL {b}")

audit/selftest_fixtures.py

@@ -90,70 +90,87 @@ def _f_t1_5():
 
 @contextlib.contextmanager
 def _f_t2_1():
-    """Track a .py with a syntax error so T2.1 FAILs."""
-    f = REPO / "_audit_selftest_syntax.py"
-    f.write_text("def broken(:\n    pass\n", encoding="utf-8")
-    sh(["git", "add", "-f", "_audit_selftest_syntax.py"])
+    """Track backend/_audit_st_syntax.py with a SyntaxError so T2.1 FAILs."""
+    rel = "backend/_audit_st_syntax.py"
+    f = REPO / rel
+    f.write_text("def (:\n    pass\n", encoding="utf-8")
+    sh(["git", "add", "-f", rel])
     try:
         yield
     finally:
-        sh(["git", "rm", "--cached", "-q", "_audit_selftest_syntax.py"])
+        sh(["git", "rm", "--cached", "-q", rel])
         if f.exists():
             f.unlink()
 
 
 @contextlib.contextmanager
 def _f_t2_2():
-    """Track backend/_audit_selftest_mod.py that raises NameError at import."""
-    f = REPO / "backend" / "_audit_selftest_mod.py"
-    f.write_text("x = undefined_thing\n", encoding="utf-8")
-    sh(["git", "add", "-f", "backend/_audit_selftest_mod.py"])
+    """Track backend/_audit_st_import.py that raises ImportError at import time."""
+    rel = "backend/_audit_st_import.py"
+    f = REPO / rel
+    f.write_text('raise ImportError("audit selftest")\n', encoding="utf-8")
+    sh(["git", "add", "-f", rel])
     try:
         yield
     finally:
-        sh(["git", "rm", "--cached", "-q", "backend/_audit_selftest_mod.py"])
+        sh(["git", "rm", "--cached", "-q", rel])
         if f.exists():
             f.unlink()
 
 
 @contextlib.contextmanager
 def _f_t2_3():
-    """Track backend/_audit_selftest_dead.py with a code ref to a deleted module."""
-    f = REPO / "backend" / "_audit_selftest_dead.py"
+    """Track backend/_audit_st_dead.py with a CODE ref to a deleted module.
+
+    The line is a real import statement (not a comment/docstring) so T2.3 must
+    classify it as a code_hit and return FAIL, not WARN.
+    """
+    rel = "backend/_audit_st_dead.py"
+    f = REPO / rel
     f.write_text("from backend.orchestrator import handle_turn\n", encoding="utf-8")
-    sh(["git", "add", "-f", "backend/_audit_selftest_dead.py"])
+    sh(["git", "add", "-f", rel])
     try:
         yield
     finally:
-        sh(["git", "rm", "--cached", "-q", "backend/_audit_selftest_dead.py"])
+        sh(["git", "rm", "--cached", "-q", rel])
         if f.exists():
             f.unlink()
 
 
 @contextlib.contextmanager
 def _f_t2_4():
-    """Track a .css file with a nested */ inside a block comment so T2.4 FAILs."""
-    f = REPO / "_audit_selftest.css"
-    f.write_text("/* a */ b */\n.x { color: red; }\n", encoding="utf-8")
-    sh(["git", "add", "-f", "_audit_selftest.css"])
+    """Track frontend/_audit_st.css with an orphan */ so T2.4 FAILs.
+
+    `/* a */ b */` — the first `*/` legitimately closes the comment; the
+    trailing ` */` is then an orphan terminator outside any comment, which is
+    exactly the comment-terminator footgun T2.4's state machine flags.
+    """
+    rel = "frontend/_audit_st.css"
+    f = REPO / rel
+    f.write_text("/* a */ b */\n", encoding="utf-8")
+    sh(["git", "add", "-f", rel])
     try:
         yield
     finally:
-        sh(["git", "rm", "--cached", "-q", "_audit_selftest.css"])
+        sh(["git", "rm", "--cached", "-q", rel])
         if f.exists():
             f.unlink()
 
 
 @contextlib.contextmanager
 def _f_t2_5():
-    """Track backend/_audit_selftest_path.py with a hardcoded 40-data path."""
-    f = REPO / "backend" / "_audit_selftest_path.py"
-    f.write_text('x = something / "40-data" / "y"\n', encoding="utf-8")
-    sh(["git", "add", "-f", "backend/_audit_selftest_path.py"])
+    """Track backend/_audit_st_path.py with a hardcoded 40-data path so T2.5 FAILs."""
+    rel = "backend/_audit_st_path.py"
+    f = REPO / rel
+    f.write_text(
+        'x = settings.CORPUS_DIR.parent.parent / "40-data" / "y.json"\n',
+        encoding="utf-8",
+    )
+    sh(["git", "add", "-f", rel])
     try:
         yield
     finally:
-        sh(["git", "rm", "--cached", "-q", "backend/_audit_selftest_path.py"])
+        sh(["git", "rm", "--cached", "-q", rel])
         if f.exists():
             f.unlink()
 
@@ -170,12 +187,12 @@ def _tsc_available() -> bool:
 def _f_t2_6():
     """Force a lint/type failure so T2.6 FAILs.
 
-    Prefer ruff (a flagrant unused-import + bare-except .py under audit/). If
-    ruff is unavailable in this env T2.6 would SKIP (not FAIL) on a ruff-only
-    fixture, so fall back to forcing a tsc error via a broken .ts under
-    frontend/src/. If NEITHER ruff nor tsc is available this single fixture
-    cannot legitimately force a FAIL — raise a clear RuntimeError so selftest
-    surfaces it rather than reporting a false pass.
+    Prefer a tsc type error (a .ts under frontend/src/ that fails strict type
+    checking). If tsc is unavailable, fall back to a ruff-only fixture (a
+    flagrant unused-import + bare-except .py under audit/). If NEITHER ruff nor
+    tsc is available this single fixture cannot legitimately force a FAIL —
+    raise a clear RuntimeError; the hardened core.selftest treats that raise as
+    the check failing on the broken fixture, which is the acceptable outcome.
     """
     have_ruff = _ruff_available()
     have_tsc = _tsc_available()
@@ -184,17 +201,19 @@ def _f_t2_6():
 
     created = []
     try:
-        if have_ruff:
-            f = REPO / "audit" / "_audit_selftest_lint.py"
+        if have_tsc:
+            rel = "frontend/src/_audit_st_bad.ts"
+            f = REPO / rel
+            f.write_text('const x: number = "str";\n', encoding="utf-8")
+            sh(["git", "add", "-f", rel])
+            created.append(rel)
+        else:
+            rel = "audit/_audit_st_lint.py"
+            f = REPO / rel
             f.write_text("import os\ntry:\n    pass\nexcept:\n    pass\n",
                          encoding="utf-8")
-            sh(["git", "add", "-f", "audit/_audit_selftest_lint.py"])
-            created.append("audit/_audit_selftest_lint.py")
-        else:
-            f = REPO / "frontend" / "src" / "_audit_selftest_bad.ts"
-            f.write_text("export const x: number = ;\n", encoding="utf-8")
-            sh(["git", "add", "-f", "frontend/src/_audit_selftest_bad.ts"])
-            created.append("frontend/src/_audit_selftest_bad.ts")
+            sh(["git", "add", "-f", rel])
+            created.append(rel)
         yield
     finally:
         for rel in created:

audit/tier2_code.py

@@ -3,27 +3,47 @@ from __future__ import annotations
 import ast, re
 from audit.core import register, Result, Status, REPO, git, sh
 
-PY = [p for p in git("ls-files").splitlines() if p.endswith(".py")]
-DEAD = ("backend.orchestrator", "import sales_brain", "qa_brain", "faithfulness",
-        "backend.translator", "profile_extractor", "get_judge_llm", "get_fast_brain_llm")
+# DEAD = deleted modules/accessors, matched in MODULE/IMPORT/CALL form so we
+# do NOT false-match live field-name substrings (e.g. faithfulness_passed is
+# an active log field; the backend.faithfulness *module* is gone).
+DEAD = (
+    "backend.orchestrator", "import orchestrator",
+    "import sales_brain", "from backend import sales_brain", "backend.sales_brain",
+    "import qa_brain", "backend.qa_brain",
+    "import faithfulness", "from backend import faithfulness", "backend.faithfulness",
+    "import translator", "backend.translator",
+    "import profile_extractor", "backend.profile_extractor",
+    "get_judge_llm", "get_fast_brain_llm",
+)
+
+
+def _py() -> list[str]:
+    """Re-queried per call (NOT a frozen import-time snapshot) so selftest
+    fixtures that add a file are actually seen by the checks."""
+    return [p for p in git("ls-files").splitlines() if p.endswith(".py")]
+
+
+def _audit_self(p: str) -> bool:
+    # the framework's own files contain the DEAD strings as detection DATA
+    return p.startswith("audit/") or p == "tests/test_audit_selftest.py"
 
 
 @register("T2.1", "static", "all .py parse (AST)")
 def t2_1() -> Result:
     bad = []
-    for p in PY:
+    for p in _py():
         try:
             ast.parse((REPO / p).read_text(encoding="utf-8", errors="replace"), p)
         except SyntaxError as e:
             bad.append(f"{p}: {e}")
     return (Result("T2.1", Status.FAIL, "; ".join(bad[:5]), "fix the syntax error")
-            if bad else Result("T2.1", Status.PASS, f"{len(PY)} files parse"))
+            if bad else Result("T2.1", Status.PASS, f"{len(_py())} files parse"))
 
 
 @register("T2.2", "static", "runtime-import every backend/rag module")
 def t2_2() -> Result:
     mods = []
-    for p in PY:
+    for p in _py():
         if (p.startswith("backend/") or p.startswith("rag/")) and not p.endswith("__init__.py") \
            and "_smoke_test" not in p and "/tests/" not in p:
             mods.append(p[:-3].replace("/", "."))
@@ -33,41 +53,79 @@ def t2_2() -> Result:
     r = sh([".venv/bin/python", "-c", code], timeout=300)
     if r.returncode != 0:
         return Result("T2.2", Status.FAIL, r.stdout.strip()[:600],
-                      "fix the import (often: import wrongly placed inside a docstring)")
+                      "fix the import (often: import wrongly placed inside a docstring, or a deleted symbol)")
     return Result("T2.2", Status.PASS, f"{len(mods)} modules import clean")
 
 
 @register("T2.3", "static", "no refs to deleted modules/symbols")
 def t2_3() -> Result:
     code_hits, doc_hits = [], []
-    for p in PY:
-        for i, ln in enumerate(open(REPO / p, encoding="utf-8", errors="replace"), 1):
+    for p in _py():
+        if _audit_self(p):
+            continue
+        for i, ln in enumerate((REPO / p).read_text(encoding="utf-8", errors="replace").splitlines(), 1):
             for d in DEAD:
                 if d in ln:
                     s = ln.strip()
-                    (doc_hits if s.startswith("#") or s.startswith(('"', "'", "*")) else code_hits
+                    (doc_hits if s.startswith(("#", '"', "'", "*")) else code_hits
                      ).append(f"{p}:{i} {d}")
+                    break
     if code_hits:
         return Result("T2.3", Status.FAIL, "; ".join(code_hits[:6]),
-                      "remove/replace the dead reference (e.g. get_judge_llm -> get_brain_llm)")
+                      "remove/replace the dead reference (e.g. get_fast_brain_llm -> get_brain_llm)")
     if doc_hits:
         return Result("T2.3", Status.WARN, f"{len(doc_hits)} stale comment refs e.g. {doc_hits[:3]}",
                       "tidy the stale comment")
     return Result("T2.3", Status.PASS, "no dead-symbol references")
 
 
-@register("T2.4", "static", "no */ inside CSS/JS block-comment body")
+@register("T2.4", "static", "no orphan */ (CSS comment-terminator footgun)")
 def t2_4() -> Result:
     bad = []
     for p in git("ls-files").splitlines():
         if not p.endswith((".css", ".scss")):
             continue
-        txt = (REPO / p).read_text(encoding="utf-8", errors="replace")
-        for m in re.finditer(r"/\*.*?\*/", txt, re.S):
-            body = m.group(0)[2:-2]
-            if "*/" in body:
-                bad.append(f"{p}: nested */ in comment")
-    return (Result("T2.4", Status.FAIL, "; ".join(bad), "space the token: '* /' or reword")
+        s = (REPO / p).read_text(encoding="utf-8", errors="replace")
+        i, n, line = 0, len(s), 1
+        in_comment = False
+        in_str = ""  # "" | "'" | '"'
+        while i < n:
+            ch = s[i]
+            nx = s[i + 1] if i + 1 < n else ""
+            if ch == "\n":
+                line += 1
+            if in_str:
+                if ch == "\\":
+                    i += 2
+                    continue
+                if ch == in_str:
+                    in_str = ""
+                i += 1
+                continue
+            if in_comment:
+                if ch == "*" and nx == "/":
+                    in_comment = False
+                    i += 2
+                    continue
+                i += 1
+                continue
+            if ch in ("'", '"'):
+                in_str = ch
+                i += 1
+                continue
+            if ch == "/" and nx == "*":
+                in_comment = True
+                i += 2
+                continue
+            if ch == "*" and nx == "/":
+                # a */ outside any comment/string: an earlier stray */ closed
+                # a comment prematurely (the exact app-wide-500 footgun).
+                bad.append(f"{p}:{line} orphan '*/' (a stray '*/' earlier closed a comment early)")
+                i += 2
+                continue
+            i += 1
+    return (Result("T2.4", Status.FAIL, "; ".join(bad[:5]),
+                   "a comment body contains '*/' (e.g. .snap-*/.rev-*) — space it '* /' or reword")
             if bad else Result("T2.4", Status.PASS, "no comment-terminator footgun"))
 
 
@@ -75,12 +133,12 @@ def t2_4() -> Result:
 def t2_5() -> Result:
     pat = re.compile(r'/\s*["\']40-data["\']')
     bad = []
-    for p in PY:
-        if not (p.startswith("backend/") or p.startswith("rag/")):
+    for p in _py():
+        if _audit_self(p) or not (p.startswith("backend/") or p.startswith("rag/")):
             continue
         if p.endswith("config.py"):
             continue
-        for i, ln in enumerate(open(REPO / p, encoding="utf-8", errors="replace"), 1):
+        for i, ln in enumerate((REPO / p).read_text(encoding="utf-8", errors="replace").splitlines(), 1):
             if pat.search(ln) and not ln.strip().startswith("#"):
                 bad.append(f"{p}:{i}")
     return (Result("T2.5", Status.FAIL, "; ".join(bad[:8]), "use settings.DATA_DIR")
@@ -89,16 +147,23 @@ def t2_5() -> Result:
 
 @register("T2.6", "static", "ruff + tsc clean")
 def t2_6() -> Result:
-    ruff = sh([".venv/bin/ruff", "check", "backend", "rag", "audit"], timeout=120)
-    tsc = sh(["npx", "--prefix", "frontend", "--no-install", "tsc", "-p", "frontend", "--noEmit"], timeout=240)
+    def _try(cmd, timeout):
+        try:
+            return sh(cmd, timeout=timeout)
+        except FileNotFoundError:
+            return None
+    ruff = _try([".venv/bin/ruff", "check", "backend", "rag", "audit"], 120)
+    tsc = _try(["npx", "--prefix", "frontend", "--no-install", "tsc", "-p", "frontend", "--noEmit"], 240)
     probs = []
-    if ruff.returncode not in (0, 127):
-        tail = (ruff.stdout or ruff.stderr).strip().splitlines()
-        probs.append("ruff: " + (tail[-1][:200] if tail else "error"))
-    if tsc.returncode not in (0, 127):
-        tail = (tsc.stdout or tsc.stderr).strip().splitlines()
-        probs.append("tsc: " + (tail[-1][:200] if tail else "error"))
-    if 127 in (ruff.returncode, tsc.returncode) and not probs:
-        return Result("T2.6", Status.SKIP, "ruff/tsc not installed", "pip install ruff / npm i")
+    if ruff is not None and ruff.returncode not in (0, 127):
+        t = (ruff.stdout or ruff.stderr).strip().splitlines()
+        probs.append("ruff: " + (t[-1][:200] if t else "error"))
+    if tsc is not None and tsc.returncode not in (0, 127):
+        t = (tsc.stdout or tsc.stderr).strip().splitlines()
+        probs.append("tsc: " + (t[-1][:200] if t else "error"))
+    avail = [x for x in (ruff, tsc) if x is not None and x.returncode != 127]
+    if not avail and not probs:
+        return Result("T2.6", Status.SKIP, "ruff and tsc both unavailable",
+                      "pip install ruff / npm i in frontend to enable this gate")
     return (Result("T2.6", Status.FAIL, " | ".join(probs), "fix lint/type errors")
-            if probs else Result("T2.6", Status.PASS, "ruff + tsc clean"))
+            if probs else Result("T2.6", Status.PASS, "ruff/tsc clean (available tools)"))