ai-report

name	ai-report
description	Reports a reproducible fault in this framework through `ai-eng report issue`: a payload closed to nine allow-listed fields, scanned for machine paths, personal data and secrets, written as a local gitignored draft, and shown as the exact bytes with their SHA-256 before anybody confirms anything. Trigger for "report this bug", "file an issue about ai-engineering", "the framework is broken", "send this upstream". Not for a fault in your own code — use /ai-debug, which finds a cause at file:line. Not for a vulnerability sent anywhere public: that routes to private disclosure and this command refuses the other way.
license	Apache-2.0
compatibility	needs ai-eng
disable-model-invocation	true

Report the framework's own fault, and collect nothing on the way

What it produces

.ai/issue/draft.json — local, gitignored, previewed byte for byte, and sent by nobody but you.

Steps

1. Reproduce it first. A report of something that happened once is a report the person reading it cannot act on, and the steps field is what makes the difference.

2. Decide the kind before you write. --kind security never becomes a public issue: the command refuses that route before it asks you anything, and prints the private one.

3. Write the four fields in your own words: the title, what happened, what you expected, and one --step per step. Never paste a log, a diff, a traceback or a command line — there is no field for any of them, and a pasted command carries the path it ran from.

4. Run it:

   ai-eng report issue --kind bug --title "…" --what-happened "…" \
     --expected "…" --step "…" --step "…"
   

5. Read the refusal if you get one. ACCEPTANCE_MACHINE_PATH_*, ACCEPTANCE_PII_* and ACCEPTANCE_GITLEAKS_SECRET each name what was found, no draft is written, and the fix is to say the same thing without the value it carried.

6. Read the bytes it prints. They are exactly what would leave, and the SHA-256 beside them is of those bytes. If anything in there is not yours to publish, stop.

7. Sending is separate and manual. --submit asks for a phrase carrying that digest at your keyboard, and then says there is nowhere to send: no destination is configured and this package has no transport. Take the previewed bytes to the route your organisation uses.

What this is not

• "The fault is obvious, so the report needs no reproduction steps" — a report of something that happened once is a report the person reading it cannot act on, and the steps field is what makes the difference.

Done when

• Every field is a sentence you wrote, and nothing in the payload was collected.
• The scan came back clean, or you rewrote the field it named rather than working around it.
• A vulnerability went to private disclosure and no public issue exists for it.