Merge pull request 'Enforce structured issue creation for agents' (#28) from structured-issues-template into main

Reviewed-on: #28

.gitea/ISSUE_TEMPLATE/agent_task.md

@@ -0,0 +1,9 @@
+Add structured issue template and coding standards to enforce machine-readable tasks.
+
+This improves agent coordination and reduces ambiguity in issue tracking.
+
+- `.gitea/ISSUE_TEMPLATE/agent_task.md` provides a standard form
+- `scripts/create_structured_issue.py` helps create compliant issues
+- `ai-memory/knowledge/coding-standards.md` documents the requirement
+
+Fixes #?? (part of broader agent quality initiative)

ai-memory/knowledge/coding-standards.md

@@ -0,0 +1,27 @@
+# Coding Standards
+
+## Issue Creation
+All agents must create issues using the **structured template**:
+- Use the helper script `scripts/create_structured_issue.py` or manually follow the `.gitea/ISSUE_TEMPLATE/agent_task.md` template.
+- Include all required fields: Task, Context, Expected Result, Files Likely Affected, Suggested Implementation, Difficulty, Priority, Labels.
+- Prefer small, scoped tasks. Break large work into multiple issues.
+
+## Code Style
+- Follow PEP 8 for Python.
+- Use type hints.
+- Handle exceptions specifically (avoid bare `except:`).
+- Replace `print()` with `logging` in library code.
+
+## Commits
+- Use Conventional Commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`.
+- Reference issue numbers in commit bodies (`Fixes #123`).
+
+## PR Reviews
+- Review for security, performance, and readability.
+- Ensure PR passes tests and lint.
+- Approve according to stability rings (Ring 0 requires manual review by a human; Ring 1+ may auto-approve after syntax validation).
+
+## Memory Usage
+- Record architectural decisions in `ai-memory/decisions/architectural-decisions.md`.
+- Log daily work in `ai-memory/daily/YYYY-MM-DD.md`.
+- Append new failure patterns to `ai-memory/failures/failure-archive.md`.

scripts/create_structured_issue.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""
+Create a structured issue via Gitea API.
+Requires GITEA_TOKEN in environment or /opt/aitbc/.gitea_token.sh.
+"""
+import os, sys, json, subprocess
+
+def get_token():
+    token_file = '/opt/aitbc/.gitea_token.sh'
+    if os.path.exists(token_file):
+        with open(token_file) as f:
+            for line in f:
+                if line.strip().startswith('GITEA_TOKEN='):
+                    return line.strip().split('=', 1)[1].strip()
+    return os.getenv('GITEA_TOKEN', '')
+
+GITEA_TOKEN = get_token()
+API_BASE = os.getenv('GITEA_API_BASE', 'http://gitea.bubuit.net:3000/api/v1')
+REPO = 'oib/aitbc'
+
+def create_issue(title, context, expected, files, implementation, difficulty, priority, labels, assignee=None):
+    body = f"""## Task
+{title}
+
+## Context
+{context}
+
+## Expected Result
+{expected}
+
+## Files Likely Affected
+{files}
+
+## Suggested Implementation
+{implementation}
+
+## Difficulty
+- [{'x' if difficulty == d else ' '}] {d}
+{'' if difficulty != 'medium' else ''}
+
+## Priority
+- [{'x' if priority == p else ' '}] {p}
+
+## Labels
+{', '.join([f'[{l}]' for l in labels])}
+"""
+    data = {
+        "title": title,
+        "body": body,
+        "labels": labels
+    }
+    if assignee:
+        data["assignee"] = assignee
+    url = f"{API_BASE}/repos/{REPO}/issues"
+    cmd = ['curl', '-s', '-H', f'Authorization: token {GITEA_TOKEN}', '-X', 'POST',
+           '-H', 'Content-Type: application/json', '-d', json.dumps(data), url]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        print("API error:", result.stderr)
+        sys.exit(1)
+    try:
+        resp = json.loads(result.stdout)
+        print(f"Created issue #{resp['number']}: {resp['html_url']}")
+    except Exception as e:
+        print("Failed to parse response:", e, result.stdout)
+
+if __name__ == "__main__":
+    # Example usage; in practice, agents will fill these fields.
+    create_issue(
+        title="Add retry logic to Matrix event listener",
+        context="Spurious network failures cause agent disconnects.",
+        expected="Listener automatically reconnects and continues processing events.",
+        files="apps/matrix-listener/src/event_handler.py",
+        implementation="Wrap event loop in retry decorator with exponential backoff.",
+        difficulty="medium",
+        priority="high",
+        labels=["bug", "infra"],
+        assignee="aitbc1"
+    )