pitchfast/backlog/tasks/task-54 - Orchestrate-audits-with-Convex-Workflow-and-Workpool.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	dependencies	priority	ordinal
TASK-54	Orchestrate audits with Convex Workflow and Workpool	In Progress		2026-06-12 19:45	2026-06-13 05:56			high	56000

Description

Replace the fragile audit scheduler chain with Convex Workflow/Workpool orchestration while keeping agentRuns as the visible product state for progress, retries, dashboard cards, and manual retry.

Acceptance Criteria

• #1 Audit starts create a visible agentRuns-backed card immediately in the audit dashboard
• #2 Convex Workflow and Workpool dependencies and components are registered
• #3 Audit progress exposes step, total, label, and percent in dashboard rows
• #4 Retry behavior is tracked on agentRuns and user-facing errors are hidden until final failure
• #5 Audit dashboard supports a manual retry action for final failed runs
• #6 Existing audit and outreach persistence remains compatible

Implementation Plan

1. Add failing source/UI tests for workflow registration, immediate audit dashboard rows, progress mapping, retry controls, and retry orchestration.
2. Add Convex Workflow/Workpool dependencies and register components.
3. Add agentRun orchestration/progress fields and helper mappings.
4. Start audits through Workflow while preserving existing agentRuns as product state.
5. Surface active audit runs, progress, retry state, and manual retry in the audit dashboard.
6. Adjust quality-review behavior and run verification.

Implementation Notes

Implemented Workflow/Workpool orchestration for root audit runs, progress mapping, dashboard retry UI, parallel PageSpeed strategies, and parallel German copy calls. Ran npx convex codegen and pnpm test successfully (416/416). Task remains In Progress pending user confirmation.

Added workflow-specific wrapper actions so Workpool retries throw on failed PageSpeed/audit-generation steps, while legacy actions remain compatible. Re-ran pnpm test successfully (416/416) after codegen.

User reported runtime regression: root audit workflow fails during 2/6 PageSpeed and jumps to 6/6 with PageSpeed-Analyse konnte nicht abgeschlossen werden. Investigating with systematic debugging before patching.

Fixed runtime regression reported after Workflow migration: the workflow marked root audit runs as running before PageSpeed, while startPageSpeedAuditRun rejected running runs and returned null before any PageSpeed work began. startPageSpeedAuditRun now accepts running root audit runs. The final workflow failure path now preserves the current failing progress step instead of forcing qualityReview/6 of 6. Added regression coverage in tests/audit-workflow-source.test.ts. Verified with pnpm test (418/418), git diff --check, and npx convex dev --once against the dev deployment.

Implemented LLM copy review replacement for the hard German-Copy-Guard gate. qualityReview now supports severity, rewriteRequired, revisedCopy, one automatic rewrite attempt, deterministic guard telemetry, and warning-only copy feedback. Audit/outreach persistence proceeds after copy review warnings; only technical/schema/provider/persistence failures remain fatal. Also deduped audit dashboard rows so child audit_generation runs are hidden behind visible root audit runs for the same lead. Verified with focused tests, pnpm test (420/420), git diff --check, and npx convex dev --once against the dev deployment.