|
| 1 | +# AI Manifest for feedback-o-tron |
| 2 | +# Media-Type: application/vnd.hyperpolymath.ai-manifest+a2ml |
| 3 | +# Version: 1.0.0 |
| 4 | +# Updated: 2026-02-07 |
1 | 5 |
|
2 | | -# AI Assistant Instructions |
| 6 | +## Repository Overview |
3 | 7 |
|
4 | | -## Repository Focus |
5 | | -- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies, maintain `.bot_directives`, and keep `.machines_readable/6scm/` authoritative. |
6 | | -- Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing. |
| 8 | +**feedback-o-tron** is a production-ready autonomous bug reporting system for AI agents. |
7 | 9 |
|
8 | | -## Workflow |
9 | | -1. Inspect `.machines_readable/6scm/STATE.scm` for blockers and next actions. |
10 | | -2. Respect any constraints listed inside `.machines_readable/6scm/AGENTIC.scm` when tooling changes are requested. |
11 | | -3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message. |
| 10 | +- **Status**: Production (v1.0.0) - Validated with 2 real Bugzilla submissions |
| 11 | +- **Language**: Elixir (BEAM VM) |
| 12 | +- **Platforms**: GitHub, GitLab, Bitbucket, Codeberg, Bugzilla, Email |
| 13 | +- **Integration**: MCP server for Claude Code, standalone CLI escript |
| 14 | +- **Formal Verification**: Idris2 ABI definitions with dependent type proofs |
12 | 15 |
|
13 | | -## Delivery Promises |
14 | | -- Mention in summaries whether STATE, `contractiles/`, or `.bot_directives/` changed. |
15 | | -- Keep this file in sync with the repository’s status; update it if the governance changes. |
| 16 | +## Canonical File Locations (CRITICAL INVARIANTS) |
| 17 | + |
| 18 | +### MANDATORY: SCM Files Location |
| 19 | +**ALL** machine-readable state files MUST be in `.machine_readable/` directory ONLY: |
| 20 | + |
| 21 | +``` |
| 22 | +.machine_readable/ |
| 23 | +├── STATE.scm # Current project state (100% complete) |
| 24 | +├── META.scm # Meta-level information |
| 25 | +├── ECOSYSTEM.scm # Ecosystem relationships |
| 26 | +├── AGENTIC.scm # AI agent policies |
| 27 | +├── NEUROSYM.scm # Neurosymbolic integration |
| 28 | +└── PLAYBOOK.scm # Standard operating procedures |
| 29 | +``` |
| 30 | + |
| 31 | +**NEVER** create STATE.scm, META.scm, ECOSYSTEM.scm, AGENTIC.scm, NEUROSYM.scm, or PLAYBOOK.scm in the repository root. |
| 32 | + |
| 33 | +### Source Code Structure |
| 34 | + |
| 35 | +``` |
| 36 | +elixir-mcp/ |
| 37 | +├── lib/feedback_a_tron/ |
| 38 | +│ ├── cli.ex # Main entry point (escript) |
| 39 | +│ ├── submitter.ex # Multi-platform submission |
| 40 | +│ ├── deduplicator.ex # Fuzzy matching, Levenshtein |
| 41 | +│ ├── credentials.ex # Multi-source credential loading |
| 42 | +│ ├── audit_log.ex # JSON-lines event logging |
| 43 | +│ └── mcp/ |
| 44 | +│ └── server.ex # MCP protocol server |
| 45 | +├── test/ # 26/26 tests passing |
| 46 | +└── mix.exs # Build configuration |
| 47 | + |
| 48 | +src/abi/ # Idris2 formal verification |
| 49 | +├── Types.idr # ABI type definitions with proofs |
| 50 | +├── Layout.idr # Memory layout correctness |
| 51 | +└── Foreign.idr # FFI declarations |
| 52 | + |
| 53 | +ffi/zig/ # C ABI bridge (future) |
| 54 | +└── src/main.zig |
| 55 | +``` |
| 56 | + |
| 57 | +### Documentation |
| 58 | + |
| 59 | +``` |
| 60 | +README.adoc # Comprehensive usage guide |
| 61 | +CONTRIBUTING.adoc # Contribution guidelines |
| 62 | +SECURITY.md # Security policy |
| 63 | +LICENSE.txt # PMPL-1.0-or-later |
| 64 | +``` |
| 65 | + |
| 66 | +## Critical Invariants |
| 67 | + |
| 68 | +1. **Production Status**: This is a PRODUCTION system. Real bugs have been filed. Changes must maintain stability. |
| 69 | + |
| 70 | +2. **Platform Support**: Must support all 6 platforms (GitHub, GitLab, Bitbucket, Codeberg, Bugzilla, Email). Do not remove any. |
| 71 | + |
| 72 | +3. **Bugzilla Specifics**: Bugzilla requires `--component` and `--version` flags. These must be exposed in CLI and MCP interface. |
| 73 | + |
| 74 | +4. **Credential Loading Order**: |
| 75 | + - Environment variables (highest priority) |
| 76 | + - CLI configs (~/.config/gh/hosts.yml, ~/.config/glab-cli/config.yml) |
| 77 | + - Never hardcode credentials |
| 78 | + |
| 79 | +5. **Deduplication**: Normalize body BEFORE slicing to avoid binary_part errors. This was a production bug. |
| 80 | + |
| 81 | +6. **Audit Logging**: ALL operations must be logged. Event types: :submission, :submission_success, :submission_error. |
| 82 | + |
| 83 | +7. **No Mix.env() in Escript**: Use `Application.get_env(:feedback_a_tron, :env)` instead. Mix module not available in compiled escript. |
| 84 | + |
| 85 | +8. **Idris2 ABI**: Type definitions in src/abi/ are formal specifications. Changes must maintain dependent type proofs. |
| 86 | + |
| 87 | +## Lifecycle Hooks |
| 88 | + |
| 89 | +### on-enter (Session Start) |
| 90 | + |
| 91 | +1. Read `.machine_readable/STATE.scm` to understand current completion status (100%) |
| 92 | +2. Check `elixir-mcp/` for any uncommitted changes |
| 93 | +3. Review recent session history in STATE.scm |
| 94 | +4. Note production status: Real bugs filed to Bugzilla |
| 95 | + |
| 96 | +### on-exit (Session End) |
| 97 | + |
| 98 | +1. Update STATE.scm with session achievements |
| 99 | +2. Commit changes with clear message: "docs: update X" or "fix: resolve Y" |
| 100 | +3. Run tests if code changed: `cd elixir-mcp && mix test` |
| 101 | +4. Update audit if new platforms or features added |
| 102 | + |
| 103 | +## Development Guidelines |
| 104 | + |
| 105 | +### Adding New Platforms |
| 106 | + |
| 107 | +1. Add platform atom to `@platforms` in submitter.ex |
| 108 | +2. Implement `do_submit/4` function for platform |
| 109 | +3. Add credential loading in credentials.ex |
| 110 | +4. Update CLI parser for platform-specific flags |
| 111 | +5. Add tests in test/submitter_test.exs |
| 112 | +6. Update README.adoc with usage examples |
| 113 | +7. Update STATE.scm completion status |
| 114 | + |
| 115 | +### Testing |
| 116 | + |
| 117 | +- Unit tests: `mix test` |
| 118 | +- Integration: `./feedback-a-tron submit --dry-run ...` |
| 119 | +- Real submission: Use test repos, not production |
| 120 | + |
| 121 | +### Bug Fixes |
| 122 | + |
| 123 | +- Check STATE.scm session history for similar issues |
| 124 | +- Add test case reproducing bug |
| 125 | +- Fix implementation |
| 126 | +- Verify all 26 tests still pass |
| 127 | +- Update STATE.scm with bug fix note |
| 128 | + |
| 129 | +## Integration Points |
| 130 | + |
| 131 | +### MCP Server (Claude Code) |
| 132 | + |
| 133 | +Configure in `~/.config/claude/mcp_servers.json`: |
| 134 | + |
| 135 | +```json |
| 136 | +{ |
| 137 | + "feedback-o-tron": { |
| 138 | + "command": "/path/to/feedback-a-tron", |
| 139 | + "args": ["--mcp-server"], |
| 140 | + "env": { |
| 141 | + "GITHUB_TOKEN": "${GITHUB_TOKEN}", |
| 142 | + "BUGZILLA_API_KEY": "${BUGZILLA_API_KEY}" |
| 143 | + } |
| 144 | + } |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +### Standalone CLI |
| 149 | + |
| 150 | +```bash |
| 151 | +./feedback-a-tron submit --repo "..." --title "..." --body "..." --platform bugzilla --component "..." --version "..." |
| 152 | +``` |
| 153 | + |
| 154 | +### As Library |
| 155 | + |
| 156 | +```elixir |
| 157 | +FeedbackATron.Submitter.submit(%{ |
| 158 | + title: "Bug title", |
| 159 | + body: "Description", |
| 160 | + repo: "owner/repo" |
| 161 | +}, platforms: [:github, :bugzilla]) |
| 162 | +``` |
| 163 | + |
| 164 | +## Real-World Validation |
| 165 | + |
| 166 | +**Production bugs filed on 2026-02-07:** |
| 167 | + |
| 168 | +1. Bug #2437503: maliit-keyboard crash loop (SIGABRT) |
| 169 | + - https://bugzilla.redhat.com/show_bug.cgi?id=2437503 |
| 170 | + - Component: maliit-keyboard, Version: 43 |
| 171 | + |
| 172 | +2. Bug #2437504: xwaylandvideobridge portal error |
| 173 | + - https://bugzilla.redhat.com/show_bug.cgi?id=2437504 |
| 174 | + - Component: plasma-desktop, Version: 43 |
| 175 | + |
| 176 | +Both submissions validated end-to-end workflow including: |
| 177 | +- Crash detection from journalctl |
| 178 | +- Bug report formatting |
| 179 | +- Bugzilla REST API submission |
| 180 | +- Audit log recording |
| 181 | + |
| 182 | +## Dependencies |
| 183 | + |
| 184 | +**Runtime:** |
| 185 | +- Elixir 1.15+ |
| 186 | +- Erlang/OTP 26+ |
| 187 | +- Jason (JSON encoding) |
| 188 | +- Req (HTTP client) |
| 189 | +- YamlElixir (CLI config parsing) |
| 190 | + |
| 191 | +**Build:** |
| 192 | +- mix escript.build (generates standalone binary) |
| 193 | + |
| 194 | +**Optional:** |
| 195 | +- Idris2 (for ABI verification) |
| 196 | +- Zig (for FFI bridge) |
| 197 | +- proven repo (90+ formally verified modules) |
| 198 | + |
| 199 | +## Next Steps (Post-Production) |
| 200 | + |
| 201 | +1. **Proven Integration**: Use SafeMath, SafeString, SafeJSON from proven repo |
| 202 | +2. **ML Deduplication**: Enhance fuzzy matching with semantic embeddings |
| 203 | +3. **MCP Tool Schema**: Expose component/version options in MCP tool definition |
| 204 | +4. **Email Platform**: Complete Swoosh SMTP integration |
| 205 | +5. **Multi-repo Batch**: Add batch mode for analyzing multiple repos |
| 206 | + |
| 207 | +## License |
| 208 | + |
| 209 | +PMPL-1.0-or-later (Palimpsest License) |
| 210 | + |
| 211 | +All original code is licensed under PMPL-1.0-or-later. |
| 212 | +Third-party dependencies maintain their original licenses. |
0 commit comments