(CODUX-222) Define planning progress guidance

[numnx]

🧩 Task: Define planning progress guidance

Automated task PR opened by Code UX for T01.

📋 Summary

Sprint: Sprint 222 · Improve planning ETA guidance · Task: T01

Give dashboard-assigned agents immediate, machine-readable planning ETA guidance, enforce one-minute in-progress rechecks without duplicate planning or settings changes, preserve terminal scheduler wakeups, and document the complete asynchronous lifecycle.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-13 19:16:04 UTC
Finished	2026-07-13 19:23:19 UTC
Duration	7m 15s

📊 Token Usage

Metric	Value
Input tokens	101,050
Cached input tokens	1,505,024
Output tokens	17,163
Total tokens	1,623,237
Invocations	1
Tool calls	24
Active time	6m 46s

Included usage estimate (subscription/local login): $1.77

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Add a reusable domain projection for initial and subsequent asynchronous planning guidance, including calculated ETA, one-minute recheck timing, and terminal-state handling.

## Scope
- Create `src/domain/planning/mcp-planning-guidance.ts`
- Edit `src/domain/planning/invocation-metrics.ts`
- Verify compatibility with `src/domain/sprint/composer/eta-estimator.ts`
- Create `tests/backend/domain/planning/mcp-planning-guidance.test.ts`
- Create or update `tests/backend/domain/planning/invocation-metrics.test.ts`

## Implementation Requirements
1. Factor recent-duration selection so both the dashboard composer route and MCP guidance use the latest ten completed `planning` invocations, ignore running/failed/cancelled/non-planning records, and retain the existing three-minute fallback.
2. Export a typed `McpPlanningGuidance` projection with `status` (`in_progress`, `succeeded`, `failed`, `cancelled`, or `paused`), `asynchronous`, `isTerminal`, `invocationId`, `startedAt`, `estimatedDurationMs`, `estimatedCompletionAt`, `nextCheckAt`, `recheckIntervalMs`, `sampleSize`, `isFallbackEstimate`, `message`, and optional `errorMessage`.
3. Build initial guidance with `nextCheckAt` equal to the calculated ETA, and build subsequent `in_progress` guidance with `nextCheckAt` exactly 60,000 milliseconds after the status check even when the original ETA has elapsed.
4. Make in-progress messages state that planning is asynchronous, exceeding ETA is not failure evidence, and callers must not requeue, resubmit, or change settings; make succeeded and failed/cancelled/paused projections terminal with no next check and preserve available failure details.
5. Accept the current time as an explicit input so ETA timestamps and status-check timing remain deterministic in tests.

## Constraints
- Keep the helper pure and free of repository, scheduler, timer, or logging side effects.
- Preserve the existing dashboard ETA response fields and fallback behavior.
- Do not classify elapsed ETA alone as failure or infer terminal state without an invocation terminal status.
- Do not introduce persistence or configuration changes.

## Verification
- Run `pnpm exec vitest run tests/backend/domain/planning/mcp-planning-guidance.test.ts tests/backend/domain/planning/invocation-metrics.test.ts tests/backend/domain/sprint/composer/eta-estimator.test.ts tests/backend/server/routes/sprint-composer.eta.test.ts`.
- Run `pnpm run lint`.
- Confirm initial guidance checks at ETA, unfinished follow-ups check in exactly one minute, and every terminal status has `nextCheckAt: null`.

🌿 Branch Info

Base: feature/CODUX-222-improve-planning-eta-guidance
Head: task/feature-codux-22-t01-codex-a2bbeecd-mrjlrxag

---

🤖 Generated by Code UX