process: backlog triage tool and report (closes #1459)

docs/backlog-triage-report.md

@@ -0,0 +1,74 @@
+# timmy-home Backlog Triage Report
+
+Generated: 2026-04-14 22:57 UTC
+Total open issues: 50
+Closed in last 30 days (sample): 50
+
+## By Assignee
+- unassigned: 21
+- Rockachopa: 9
+- Timmy: 5
+- allegro: 4
+- ezra: 3
+- perplexity: 2
+- codex-agent: 2
+- claude: 2
+- gemini: 1
+- claw-code: 1
+
+## By Label
+- no-label: 21
+- batch-pipeline: 19
+- fleet: 8
+- progression: 7
+- epic: 2
+- phase-2: 2
+- claw-code-in-progress: 2
+- project: 1
+- phase-6: 1
+- phase-5: 1
+- phase-4: 1
+- phase-3: 1
+- phase-1: 1
+
+## By Age
+- today: 21
+- this-week: 26
+- this-month: 3
+- older: 0
+
+## Triage Recommendations
+
+### Unassigned batch-pipeline issues (19)
+These are auto-generated analysis tasks. Recommend assigning to a single agent or closing if stale.
+- #683: Codebase Genome: wolf — Full Analysis
+- #682: Codebase Genome: timmy-dispatch — Full Analysis
+- #681: Codebase Genome: burn-fleet — Full Analysis
+- #680: Codebase Genome: fleet-ops — Full Analysis
+- #679: Codebase Genome: turboquant — Full Analysis
+- #678: Codebase Genome: timmy-academy — Full Analysis
+- #677: Codebase Genome: evennia-local-world — Full Analysis
+- #676: Codebase Genome: compounding-intelligence — Full Analysis
+- #675: Codebase Genome: the-testament — Full Analysis
+- #674: Codebase Genome: the-beacon — Full Analysis
+- ... and 9 more
+
+### No-label issues (21)
+These need categorization. Recommend adding labels for priority and category.
+- #662 (unassigned): [ops] Burn lane empty — all open issues triaged (2026-04-14)
+- #648 (unassigned): [ops] Session harvest report — 2026-04-14
+- #582 (ezra): [EPIC] Know Thy Father: Multimodal Media Consumption
+- #570 (ezra): [EZRA] MemPalace v3.0.0 Integration — Install, Mine, and Wire MCP (Priority from
+- #568 (perplexity): [EVALUATION] MemPalace v3.0.0 Integration — Before/After Metrics + Recommendatio
+- #567 (ezra): [VISION] Evennia as Agent Mind Palace — Spatial Memory Architecture
+- #545 (claude): [UNREACHABLE HORIZON] 1M Men in Crisis — 1 MacBook, 3B Model, 0 Cloud, 0 Latency
+- #536 (Timmy): [BEZ-P1] Create Bezalel Evennia world with themed rooms and characters
+- #535 (Timmy): [BEZ-P0] Install Tailscale on Bezalel VPS (104.131.15.18) for internal networkin
+- #534 (Timmy): [BEZ-P0] Fix Evennia settings on 104.131.15.18 — remove bad port tuples, DB is r
+- ... and 11 more
+
+## Action Items
+1. Label all no-label issues (21 issues)
+2. Assign or close unassigned batch-pipeline issues
+3. Review stale issues for closure
+4. Consider milestone organization for batch-pipeline work

evennia/timmy_world/GENOME.md

@@ -1,242 +0,0 @@
-# GENOME.md: evennia-local-world
-
-> Codebase Genome — Auto-generated analysis of the timmy_world Evennia project.
-
-## Project Overview
-
-**Name:** timmy_world
-**Framework:** Evennia 6.0 (MUD/MUSH engine)
-**Purpose:** Tower MUD world with spatial memory. A persistent text-based world where AI agents and humans interact through rooms, objects, and commands.
-**Language:** Python 3.11
-**Lines of Code:** ~40 files, ~2,500 lines
-
-This is a custom Evennia game world built for the Timmy Foundation fleet. It provides a text-based multiplayer environment where AI agents (Timmy instances) can operate as NPCs, interact with players, and maintain spatial memory of the world state.
-
-## Architecture
-
-```
-timmy_world/
-+-- server/
-|   +-- conf/
-|       +-- settings.py          # Server configuration
-|       +-- at_initial_setup.py  # First-run setup hook
-|       +-- at_server_startstop.py
-|       +-- inputfuncs.py        # Client input handlers
-|       +-- lockfuncs.py         # Permission lock functions
-|       +-- cmdparser.py         # Command parsing overrides
-|       +-- connection_screens.py # Login/creation screens
-|       +-- serversession.py     # Session management
-|       +-- web_plugins.py       # Web client plugins
-+-- typeclasses/
-|   +-- characters.py            # Player/NPC characters
-|   +-- rooms.py                 # Room containers
-|   +-- objects.py               # Items and world objects (218 lines, key module)
-|   +-- exits.py                 # Room connectors
-|   +-- accounts.py              # Player accounts (149 lines)
-|   +-- channels.py              # Communication channels
-|   +-- scripts.py               # Persistent background scripts (104 lines)
-+-- commands/
-|   +-- command.py               # Base command class (188 lines)
-|   +-- default_cmdsets.py       # Command set definitions
-+-- world/
-|   +-- prototypes.py            # Object spawn templates
-|   +-- help_entries.py          # File-based help system
-+-- web/
-    +-- urls.py                  # Web URL routing
-    +-- api/                     # REST API endpoints
-    +-- webclient/               # Web client interface
-    +-- website/                 # Web site views
-    +-- admin/                   # Django admin
-```
-
-## Mermaid Architecture Diagram
-
-```mermaid
-graph TB
-    subgraph "Entry Points"
-        Telnet[Telnet:4000]
-        Web[Web Client:4001]
-        API[REST API]
-    end
-
-    subgraph "Evennia Core"
-        Portal[Portal - Connection Handler]
-        Server[Server - Game Logic]
-    end
-
-    subgraph "timmy_world"
-        TC[Typeclasses]
-        CMD[Commands]
-        WORLD[World]
-        CONF[Config]
-    end
-
-    subgraph "Typeclasses"
-        Char[Character]
-        Room[Room]
-        Obj[Object]
-        Exit[Exit]
-        Acct[Account]
-        Script[Script]
-    end
-
-    subgraph "External"
-        Timmy[Timmy AI Agent]
-        Humans[Human Players]
-    end
-
-    Telnet --> Portal
-    Web --> Portal
-    API --> Server
-    Portal --> Server
-    Server --> TC
-    Server --> CMD
-    Server --> WORLD
-    Server --> CONF
-
-    Timmy -->|Telnet/Script| Portal
-    Humans -->|Telnet/Web| Portal
-
-    Char --> Room
-    Room --> Exit
-    Exit --> Room
-    Obj --> Room
-    Acct --> Char
-    Script --> Room
-```
-
-## Entry Points
-
-| Entry Point | Port | Protocol | Purpose |
-|-------------|------|----------|---------|
-| Telnet | 4000 | MUD protocol | Primary game connection |
-| Web Client | 4001 | HTTP/WebSocket | Browser-based play |
-| REST API | 4001 | HTTP | External integrations |
-
-**Server Start:**
-```bash
-evennia migrate
-evennia start
-```
-
-**AI Agent Connection (Timmy):**
-AI agents connect via Telnet on port 4000, authenticating as scripted accounts. The `Script` typeclass handles persistent NPC behavior.
-
-## Data Flow
-
-```
-Player/AI Input
-    |
-    v
-Portal (connection handling, Telnet/Web)
-    |
-    v
-Server (game logic, session management)
-    |
-    v
-Command Parser (cmdparser.py)
-    |
-    v
-Command Execution (commands/command.py)
-    |
-    v
-Typeclass Methods (characters.py, objects.py, etc.)
-    |
-    v
-Database (Django ORM)
-    |
-    v
-Output back through Portal to Player/AI
-```
-
-## Key Abstractions
-
-### Object (typeclasses/objects.py) — 218 lines
-The core world entity. Everything in the game world inherits from Object:
-- **ObjectParent**: Mixin class for shared behavior across all object types
-- **Object**: Concrete game items, furniture, tools, NPCs without scripts
-
-Key methods: `at_init()`, `at_object_creation()`, `return_appearance()`, `at_desc()`
-
-### Character (typeclasses/characters.py)
-Puppetable entities. What players and AI agents control.
-- Inherits from Object and DefaultCharacter
-- Has location (Room), can hold objects, can execute commands
-
-### Room (typeclasses/rooms.py)
-Spatial containers. No location of their own.
-- Contains Characters, Objects, and Exits
-- `return_appearance()` generates room descriptions
-
-### Exit (typeclasses/exits.py)
-Connectors between Rooms. Always has a `destination` property.
-- Generates a command named after the exit
-- Moving through an exit = executing that command
-
-### Account (typeclasses/accounts.py) — 149 lines
-The persistent player identity. Survives across sessions.
-- Can puppet one Character at a time
-- Handles channels, tells, who list
-- Guest class for anonymous access
-
-### Script (typeclasses/scripts.py) — 104 lines
-Persistent background processes. No in-game existence.
-- Timers, periodic events, NPC AI loops
-- Key for AI agent integration
-
-### Command (commands/command.py) — 188 lines
-User input handlers. MUX-style command parsing.
-- `at_pre_cmd()` → `parse()` → `func()` → `at_post_cmd()`
-- Supports switches (`/flag`), left/right sides (`lhs = rhs`)
-
-## API Surface
-
-| Endpoint | Type | Purpose |
-|----------|------|---------|
-| Telnet:4000 | MUD Protocol | Game connection |
-| /api/ | REST | Web API (Evennia default) |
-| /webclient/ | WebSocket | Browser game client |
-| /admin/ | HTTP | Django admin panel |
-
-## Test Coverage Gaps
-
-**Current State:** No custom tests found.
-
-**Missing Tests:**
-1. **Object lifecycle**: `at_object_creation`, `at_init`, `delete`
-2. **Room navigation**: Exit creation, movement between rooms
-3. **Command parsing**: Switch handling, lhs/rhs splitting
-4. **Account authentication**: Login flow, guest creation
-5. **Script persistence**: Start, stop, timer accuracy
-6. **Lock function evaluation**: Permission checks
-7. **AI agent integration**: Telnet connection, command execution as NPC
-8. **Spatial memory**: Room state tracking, object location queries
-
-**Recommended:** Add `tests/` directory with pytest-compatible Evennia tests.
-
-## Security Considerations
-
-1. **Telnet is unencrypted** — All MUD traffic is plaintext. Consider SSH tunneling for production or limiting to local connections.
-2. **Lock functions** — Custom lockfuncs.py defines permission checks. Review for bypass vulnerabilities.
-3. **Web API** — Ensure Django admin is restricted to trusted IPs.
-4. **Guest accounts** — Guest class exists. Limit permissions to prevent abuse.
-5. **Script execution** — Scripts run server-side Python. Arbitrary script creation is a security risk if not locked down.
-6. **AI agent access** — Timmy connects as a regular account. Ensure agent accounts have appropriate permission limits.
-
-## Dependencies
-
-- **Evennia 6.0** — MUD/MUSH framework (Django + Twisted)
-- **Python 3.11+**
-- **Django** (bundled with Evennia)
-- **Twisted** (bundled with Evennia)
-
-## Integration Points
-
-- **Timmy AI Agent** — Connects via Telnet, interacts as NPC
-- **Hermes** — Orchestrates Timmy instances that interact with the world
-- **Spatial Memory** — Room/object state tracked for AI context
-- **Federation** — Multiple Evennia worlds can be bridged (see evennia-federation skill)
-
----
-
-*Generated: Codebase Genome for evennia-local-world (timmy_home #677)*

scripts/backlog_triage.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+backlog_triage.py — Triage timmy-home backlog.
+
+Fetches all open issues, categorizes them, and produces a triage report.
+Can also apply labels and comments via --apply flag.
+
+Usage:
+    python3 scripts/backlog_triage.py              # generate report
+    python3 scripts/backlog_triage.py --apply       # apply triage labels/comments
+    python3 scripts/backlog_triage.py --json        # output as JSON
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+REPO = "Timmy_Foundation/timmy-home"
+GITEA_URL = "https://forge.alexanderwhitestone.com"
+
+
+def get_token():
+    token_path = Path.home() / ".config" / "gitea" / "token"
+    return token_path.read_text().strip()
+
+
+def api_get(path, headers):
+    url = f"{GITEA_URL}/api/v1{path}"
+    req = urllib.request.Request(url, headers=headers)
+    resp = urllib.request.urlopen(req)
+    return json.loads(resp.read())
+
+
+def api_post(path, data, headers):
+    url = f"{GITEA_URL}/api/v1{path}"
+    body = json.dumps(data).encode()
+    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    resp = urllib.request.urlopen(req)
+    return json.loads(resp.read())
+
+
+def fetch_all_issues(state="open"):
+    token = get_token()
+    headers = {"Authorization": f"token {token}"}
+    
+    all_issues = []
+    page = 1
+    while True:
+        data = api_get(f"/repos/{REPO}/issues?state={state}&limit=100&page={page}", headers)
+        if not data:
+            break
+        all_issues.extend(data)
+        if len(data) < 100:
+            break
+        page += 1
+    return all_issues
+
+
+def categorize(issues):
+    now = datetime.now(timezone.utc)
+    
+    categories = {
+        "unassigned": [],
+        "no_label": [],
+        "batch_pipeline": [],
+        "has_assignee": [],
+        "stale_unassigned": [],
+    }
+    
+    for issue in issues:
+        # Skip PRs
+        if "pull_request" in issue:
+            continue
+            
+        assignee = issue.get("assignee")
+        labels = [l["name"] for l in issue.get("labels", [])]
+        created = datetime.fromisoformat(issue["created_at"].replace("Z", "+00:00"))
+        age_days = (now - created).days
+        
+        if not assignee:
+            categories["unassigned"].append(issue)
+            if age_days > 7:
+                categories["stale_unassigned"].append({**issue, "_age_days": age_days})
+        else:
+            categories["has_assignee"].append(issue)
+        
+        if not labels:
+            categories["no_label"].append(issue)
+        
+        if "batch-pipeline" in labels:
+            categories["batch_pipeline"].append(issue)
+    
+    return categories
+
+
+def generate_report(issues, categories):
+    now = datetime.now(timezone.utc)
+    lines = []
+    
+    lines.append("# timmy-home Backlog Triage Report")
+    lines.append(f"\nGenerated: {now.strftime('%Y-%m-%d %H:%M UTC')}")
+    lines.append(f"Total open issues: {len(issues)}")
+    lines.append("")
+    
+    # By assignee
+    assignees = Counter()
+    for i in issues:
+        if "pull_request" in i:
+            continue
+        a = i.get("assignee", {})
+        name = a.get("login", "unassigned") if a else "unassigned"
+        assignees[name] += 1
+    lines.append("## By Assignee")
+    for a, c in assignees.most_common():
+        lines.append(f"- {a}: {c}")
+    lines.append("")
+    
+    # By label
+    label_counts = Counter()
+    for i in issues:
+        if "pull_request" in i:
+            continue
+        labels = [l["name"] for l in i.get("labels", [])]
+        if not labels:
+            label_counts["no-label"] += 1
+        for l in labels:
+            label_counts[l] += 1
+    lines.append("## By Label")
+    for l, c in label_counts.most_common(20):
+        lines.append(f"- {l}: {c}")
+    lines.append("")
+    
+    # Triage recommendations
+    lines.append("## Triage Recommendations")
+    lines.append("")
+    
+    if categories["batch_pipeline"]:
+        lines.append(f"### Batch-pipeline issues ({len(categories['batch_pipeline'])})")
+        lines.append("Auto-generated analysis tasks. Assign to burn agent or close if stale.")
+        for i in categories["batch_pipeline"][:10]:
+            lines.append(f"- #{i['number']}: {i['title'][:80]}")
+        lines.append("")
+    
+    if categories["no_label"]:
+        lines.append(f"### No-label issues ({len(categories['no_label'])})")
+        lines.append("Need categorization. Add labels for priority and category.")
+        for i in categories["no_label"][:10]:
+            a = i.get("assignee", {})
+            assignee = a.get("login", "unassigned") if a else "unassigned"
+            lines.append(f"- #{i['number']} ({assignee}): {i['title'][:80]}")
+        lines.append("")
+    
+    if categories["stale_unassigned"]:
+        lines.append(f"### Stale unassigned (>7 days, {len(categories['stale_unassigned'])})")
+        lines.append("Consider closing or assigning.")
+        for i in sorted(categories["stale_unassigned"], key=lambda x: x.get("_age_days", 0), reverse=True)[:10]:
+            lines.append(f"- #{i['number']} ({i['_age_days']}d): {i['title'][:70]}")
+        lines.append("")
+    
+    lines.append("## Action Items")
+    lines.append(f"1. Label {len(categories['no_label'])} no-label issues")
+    lines.append(f"2. Assign or close {len(categories['batch_pipeline'])} batch-pipeline issues")
+    lines.append(f"3. Review {len(categories['stale_unassigned'])} stale issues for closure")
+    lines.append("")
+    
+    return "\n".join(lines)
+
+
+def apply_triage(issues, categories, headers):
+    """Apply triage comments to batch-pipeline issues."""
+    comment_body = (
+        "Backlog triage (auto): This is a batch-pipeline codebase genome analysis. "
+        "Assign to a burn agent when ready or close if analysis is no longer needed."
+    )
+    
+    triaged = 0
+    for issue in categories["batch_pipeline"]:
+        try:
+            api_post(f"/repos/{REPO}/issues/{issue['number']}/comments", 
+                     {"body": comment_body}, headers)
+            triaged += 1
+        except Exception:
+            pass
+    
+    return triaged
+
+
+def main():
+    parser = argparse.ArgumentParser(description="timmy-home backlog triage")
+    parser.add_argument("--apply", action="store_true", help="Apply triage labels/comments")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+    
+    issues = fetch_all_issues()
+    categories = categorize(issues)
+    
+    if args.json:
+        print(json.dumps({
+            "total": len(issues),
+            "unassigned": len(categories["unassigned"]),
+            "no_label": len(categories["no_label"]),
+            "batch_pipeline": len(categories["batch_pipeline"]),
+            "stale_unassigned": len(categories["stale_unassigned"]),
+        }, indent=2))
+    else:
+        report = generate_report(issues, categories)
+        print(report)
+        
+        # Write to docs/
+        docs_dir = Path(__file__).resolve().parent.parent / "docs"
+        docs_dir.mkdir(exist_ok=True)
+        (docs_dir / "backlog-triage-report.md").write_text(report)
+        print(f"\nReport written to {docs_dir / 'backlog-triage-report.md'}")
+    
+    if args.apply:
+        token = get_token()
+        headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+        triaged = apply_triage(issues, categories, headers)
+        print(f"\nTriaged {triaged} issues with comments")
+
+
+if __name__ == "__main__":
+    main()