Report Command

punks report and hi report submit reusable Harness friction to the control-plane API. The API validates the report, checks open GitHub issues for duplicates, generates the final issue title/body, and creates the GitHub issue with server credentials.

Use reports for CLI bugs, stale generated guidance, wiki surface problems, skill-pack drift, setup pain, or shared workflow/tooling issues. Keep project product backlog items out of reports unless maintainers intentionally promote the issue.

Inputs

The command accepts raw report text through --message, with deprecated --title and --body only as optional hints. Rich classification fields make the server-generated issue easier to triage:

• --type bug | docs | workflow | tooling | other
• --severity low | medium | high
• --area cli | wiki | skill | docs | workflow | backoffice | other
• --skill-pack <name>
• --command <command>
• --expected <text>
• --actual <text>
• --steps <text>
• --labels <comma-separated-labels>
• --json

Flow

1. Build a safe report draft from raw text, classifiers, CLI version, and observed repository metadata.
2. Submit the draft to /api/reports through the typed control-plane client.
3. Validate relevance and reject trolling, profanity, non-coding, or non-project reports.
4. Generate deterministic public GitHub title/body, with AI SDK + OpenRouter metadata reserved for authenticated backoffice operator sessions.
5. Check open harness-report issues for duplicates before creating a new issue.
6. Create the issue server-side with the API GitHub token, labels, and hidden harness-report.v1 metadata block.
7. Emit cli.harness.report.submitted only after the API accepts the report.

Backoffice Contract

GitHub is the report source of truth. The backoffice reports table fetches harness-report issues from GitHub and uses GitHub open/closed state for current status. The API also persists accepted reports for audit, operator context, and local smoke tests.

Example

hi report \
  --message "Generated guidance created duplicate docs roots after initialization." \
  --type docs \
  --severity high \
  --area wiki \
  --skill-pack docs-ingest-phase \
  --command "hi init" \
  --expected "Generated guidance projects into the existing wiki route tree." \
  --actual "Generated guidance created duplicate wiki/project docs." \
  --steps "Run hi init -o apps/wiki and inspect generated docs roots."