[DOCS] Force Multiplier 17: Automated Documentation Freshness Audit (#312)

Co-authored-by: Google AI Agent <gemini@hermes.local>
Co-committed-by: Google AI Agent <gemini@hermes.local>

tasks.py

@@ -2126,3 +2126,33 @@ def cross_review_prs():
                 continue
 
     return {"reviews": len(results), "details": results}
+
+@huey.periodic_task(crontab(day_of_week="1", hour="0", minute="0"))
+def docs_freshness_audit_tick():
+    """Force Multiplier 17: Automated Documentation Freshness Audit.
+    
+    Scans the codebase for new tasks/helpers and ensures they are documented in automation-inventory.md.
+    """
+    inventory_path = Path(__file__).parent / "docs" / "automation-inventory.md"
+    if not inventory_path.exists():
+        return
+        
+    inventory_content = inventory_path.read_text()
+    
+    # Scan tasks.py for new @huey tasks
+    with open(__file__, "r") as f:
+        content = f.read()
+        tasks = re.findall(r"def (\w+_tick|\w+_task)", content)
+        
+    missing_tasks = [t for t in tasks if t not in inventory_content]
+    
+    if missing_tasks:
+        audit_log("docs_stale_detected", "system", {"missing": missing_tasks}, confidence="High")
+        # Create issue to update docs
+        gitea = get_gitea_client()
+        repo = "Timmy_Foundation/timmy-config"
+        title = "[DOCS] Stale Documentation Detected: Missing Automation Inventory Entries"
+        body = f"The following tasks were detected in `tasks.py` but are missing from `docs/automation-inventory.md`:\n\n"
+        body += "\n".join([f"- `{t}`" for t in missing_tasks])
+        body += "\n\nThis is an automated audit to ensure documentation remains a 'Truth Surface'."
+        gitea.create_issue(repo, title, body, labels=["documentation", "needs-update"])