From da3d1ff042d7193a697fbf0cfda54c2fe37a4fc9 Mon Sep 17 00:00:00 2001
From: aitbc1 <aitbc1-agent@keisanki.net>
Date: Sun, 15 Mar 2026 21:29:23 +0000
Subject: [PATCH] feat: enforce structured issue creation for agents

- Add Gitea issue template (agent_task.md)
- Provide create_structured_issue.py utility
- Document standards in ai-memory/knowledge/coding-standards.md

This ensures issues are machine-readable and consistently scoped.
---
 .gitea/ISSUE_TEMPLATE/agent_task.md     |  9 +++
 ai-memory/knowledge/coding-standards.md | 27 +++++++++
 scripts/create_structured_issue.py      | 79 +++++++++++++++++++++++++
 3 files changed, 115 insertions(+)
 create mode 100644 .gitea/ISSUE_TEMPLATE/agent_task.md
 create mode 100644 ai-memory/knowledge/coding-standards.md
 create mode 100644 scripts/create_structured_issue.py

diff --git a/.gitea/ISSUE_TEMPLATE/agent_task.md b/.gitea/ISSUE_TEMPLATE/agent_task.md
new file mode 100644
index 00000000..d22c3a82
--- /dev/null
+++ b/.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)
diff --git a/ai-memory/knowledge/coding-standards.md b/ai-memory/knowledge/coding-standards.md
new file mode 100644
index 00000000..c5826f40
--- /dev/null
+++ b/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`.
diff --git a/scripts/create_structured_issue.py b/scripts/create_structured_issue.py
new file mode 100644
index 00000000..06a0fda5
--- /dev/null
+++ b/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"
+    )