Phase 7A: knowledge copilot reports backend

[RobinOppenstam]

Summary

• Added Phase 7A Knowledge Copilot backend retrieval, citation validation/repair, AI Gateway generation path, deterministic fallback answers, and API/server action entry points.
• Added Phase 7A report generation for postmortem, executive summary, and customer impact reports with persistence in the existing reports table and audit writes.
• Added Pixel UI contract documentation plus unit and DB smoke coverage.

Changed files

• src/modules/knowledge/*
• src/modules/reports/*
• src/app/api/copilot/route.ts
• src/app/api/reports/route.ts
• src/app/api/reports/[id]/route.ts
• scripts/knowledge-reports-smoke.ts
• tests/knowledge-reports.test.ts
• docs/knowledge-copilot-reports-contract.md
• package.json

API contract

• Contract doc: docs/knowledge-copilot-reports-contract.md
• Copilot:
  • GET /api/copilot returns demo prompt suggestions and citation behavior.
  • POST /api/copilot accepts { question, role, organizationId?, actorUserId?, limit? } and returns cited answers over seeded knowledge_documents + knowledge_snippets.
• Reports:
  • GET /api/reports lists persisted reports with role generation capabilities.
  • POST /api/reports generates/persists postmortem, executive-summary, or customer-impact reports.
  • GET /api/reports/[id] returns a persisted report; generated markdown is stored in metadata.markdown until a body/export store is added.

Acceptance criteria

• Knowledge retrieval over seeded knowledge_documents + knowledge_snippets with deterministic ranking.
• Citation assembly/validation: returned citations map to seeded source IDs; unknown AI bracket citations are repaired/dropped.
• Copilot API/service with existing AI Gateway wrapper and deterministic fallback.
• Five predefined demo prompts with fallback answers/citations.
• Report generation for postmortem, executive summary, and customer impact report.
• Generated reports persisted in existing reports table.
• Audit writes for copilot/report actions.
• Contract doc for Pixel UI routes/request/response/role behavior/example payloads.
• Smoke/test coverage added.

Verification

• npm install
• npm run lint
• npm run typecheck
• npm test
• npm run build
• npm run cf:build
• npm run demo:reset && npm run db:check && npm run governance:audit-smoke && npm run demo:reset && npm run knowledge:reports-smoke && npm run demo:reset

Risks / notes

• Report body persistence uses reports.metadata.markdown because the current schema has no dedicated report body/content column.
• R2/PDF export is deferred; generated storageUri uses deterministic commandgrid://reports/... URIs.
• Keyword retrieval is deterministic and intentionally non-vector for Phase 7A.
• Public copilot endpoint has a lightweight demo throttle; production-grade distributed rate limiting can be hardened in a later phase.

Handoff

• /root/ralph/plans/commandgrid/runs/phase-07-knowledge-copilot-reports/node-backend-handoff.md

Ralph, please start Scout review.