Plan: IP-106 CLI-Backed Harness Reporting

Initial Situation

IP-106 is blocked by IP-105. Once telemetry/reporting persistence exists, CLI reporting can add a focused command, API endpoint, report persistence, and docs/skill guidance.

Solution Shape

Build on IP-105 telemetry primitives. Add report contract, API ingestion, CLI command, telemetry success event, and guidance. Keep GitHub follow-up linkable while deferring full backoffice triage UI to IP-143/M4.5.

Tasks

T106-1: Add report contract and persistence shape

• depends_on: [T105-3]
• location: packages/contract/src, packages/db/src/schema
• description: Add report request/response/status/type/severity schemas and harness_report persistence model tied to ProjectUsage/ObservedRepository.
• validation: Contract and DB typechecks/tests pass; schemas reject invalid status/type/severity.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-133, IP-134
• backlog_item_url: https://linear.app/devpunks/issue/IP-133/agent-can-submit-structured-harness-friction-through-dp
• relation_mode: native
• assigned_skills: [effect-authoring, effect-best-practices, quality-types, tdd, simplify]
• tdd_target: A valid report payload decodes with status new; invalid severity/type fails.
• review_mode: cli

T106-2: Implement API report submission

• depends_on: [T106-1]
• location: apps/api/src
• description: Add authenticated report endpoint and service/layer that stores reports and returns typed created response.
• validation: API tests for unauthenticated 401, valid submit, invalid input, and optional GitHub URL handling.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-133, IP-134
• backlog_item_url: https://linear.app/devpunks/issue/IP-134/systemic-harness-reports-can-become-central-backlog-items
• relation_mode: native
• assigned_skills: [effect-authoring, effect-backend-structure, effect-best-practices, quality-types, tdd, simplify]
• tdd_target: Authenticated POST /api/reports returns a report id, status new, and accepts safe repository context.
• review_mode: cli

T106-3: Add CLI report command

• depends_on: [T106-2]
• location: apps/cli/src
• description: Add top-level report command with title/body/type/severity/json/repo-root options, safe git metadata collection, auth reuse, and human/agent output.
• validation: CLI tests for command payloads, empty title/body rejection, JSON output, safe repo metadata, and unavailable control-plane behavior.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-133
• backlog_item_url: https://linear.app/devpunks/issue/IP-133/agent-can-submit-structured-harness-friction-through-dp
• relation_mode: native
• assigned_skills: [effect-authoring, quality-types, tdd, simplify]
• tdd_target: In a temp git repo, punks report --title ... --body ... --json sends sanitized repo context and prints typed success.
• review_mode: cli

T106-4: Emit report-submitted telemetry and guidance

• depends_on: [T106-3]
• location: apps/cli/src, apps/cli/skills, docs, apps/wiki/content/docs/harness
• description: Emit cli.harness.report.submitted only after successful report submit; update dp-cli skill guidance and docs for report vs backlog routing.
• validation: CLI test proves event only after successful submit; docs mention GitHub follow-up and Linear planning boundary.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-133, IP-134
• backlog_item_url: https://linear.app/devpunks/issue/IP-133/agent-can-submit-structured-harness-friction-through-dp
• relation_mode: native
• assigned_skills: [docs-ingest-phase, quality-types, tdd, simplify]
• tdd_target: Failed report submission does not emit cli.harness.report.submitted; successful one does.
• review_mode: mixed

T106-5: Validate and document IP-106 closeout

• depends_on: [T106-4]
• location: apps/wiki/specs/cli/IP-106-cli-harness-reporting
• description: Update implementation notes, issue matrix, docs ingest artifacts, review, validation, and tracker evidence.
• validation: git diff --check; bun run check; bun run check-types; targeted API/CLI/contract tests; built CLI report --help.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: IP-106
• backlog_item_url: https://linear.app/devpunks/issue/IP-106/support-cli-backed-harness-issue-reporting
• relation_mode: native
• assigned_skills: [review-phase, agent-browser, turborepo, simplify]
• tdd_target: IP-133/IP-134 acceptance table maps to tests, docs, and CLI smoke evidence.
• review_mode: mixed

Dependency Graph

T105-3 -> T106-1 -> T106-2 -> T106-3 -> T106-4 -> T106-5

Validation Gates

• Gate 1: Report schema and persistence are typed.
• Gate 2: API accepts authenticated reports.
• Gate 3: CLI report command works in non-interactive agent mode.
• Gate 4: Report telemetry and guidance are correct.
• Gate 5: Docs/review/validation closeout is complete.

Risks

• GitHub credentials unavailable. Mitigation: store optional GitHub link and document full creation as IP-143/backoffice follow-up unless configured.
• Local path leakage. Mitigation: tests assert cwd paths are not included.

Unresolved Questions

• Automatic GitHub issue creation remains non-blocking pending credentials/config.