Add reflection improvement loop (codex)

[numnx]

🧩 Task: Add reflection improvement loop

Automated task PR opened by Code UX for T05.

📋 Summary

Sprint: Sprint 149 · Self Reflection & Persisten Skills · Task: T05

Add disabled-by-default persistent skill storage for shareable agent self-enhancement and a configurable self-reflection improvement loop for planning and QA agents, with MCP management/search surfaces, runtime prompt injection, dashboard controls, tests, and docs.

📝 Full Task Prompt

## Objective
Add a disabled-by-default self-reflection loop that asks planning and QA agents to rate their own output against configurable criteria and optionally improve the result until thresholds are met or attempt limits are reached.

## Scope
- `src/services/structured-agent-request-service.ts`
- `src/services/structured-provider-response-service.ts`
- `src/services/planning-prompt-builder.ts`
- `src/services/planning-json-extractor.ts`
- `src/services/planning-payload-validator.ts`
- `src/domain/qa-review/qa-review-runner.ts`
- `src/services/quality-assurance-service.ts`
- `src/repositories/execution-repository.ts`
- `src/repositories/db/app-db-schema.ts` and `src/repositories/db/app-db-migrations.ts` only if T01 did not add reflection run persistence
- `tests/backend/services/structured-agent-request-service.test.ts` (new or existing)
- `tests/backend/services/planning-json-extractor.test.ts`
- `tests/backend/domain/qa-review/qa-review-runner.test.ts` or nearest QA runner suite
- `docs/architecture/quality-assurance-agent.md`
- `docs/sprint-loop/atomic-loop.md`

## Implementation Requirements
1. Add a reusable reflection evaluator that takes invocation purpose, original prompt, parsed output, configurable criteria, thresholds, and max attempts, then asks the same provider session for JSON-only ratings from 1 to 10 with rationale and improvement instructions.
2. Apply the loop only to `purpose: "planning"` and `purpose: "qa_review"` when the relevant `agents.selfReflection` setting is enabled; default settings from T01 must keep the loop off.
3. If any criterion is below threshold and attempts remain, issue an improvement prompt in the same structured flow and re-parse the improved planning or QA JSON using the existing validators.
4. Persist reflection metadata in execution invocation messages or a dedicated reflection run table: criteria, scores, threshold pass/fail, attempt count, and final decision; avoid storing secrets or raw provider credentials.
5. Ensure planning payload validation still enforces DAG shape and prompt sections after improvement, and QA result parsing still enforces normalized QA schema after improvement.
6. Add retry and failure behavior: malformed reflection JSON should not corrupt the accepted original output; provider failure should log and continue with the last valid parsed output unless strict settings later require blocking.
7. Add tests for disabled-by-default behavior, below-threshold improvement, max-attempt stop, malformed reflection response fallback, planning DAG revalidation, and QA schema revalidation.
8. Update docs with configuration semantics, default-off behavior, and the audit trail for reflection ratings.

## Constraints
- Depends on T01 settings contracts; do not require persistent skills to be implemented.
- Do not apply the loop to task coding or other invocation purposes in this sprint.
- Keep criteria user-configurable and do not hardcode acceptance thresholds outside defaults/sanitizers.
- Do not rename the sprint title or change planning output contract expected by `PlanningPayloadValidator`.

## Verification
- Run `pnpm run lint`.
- Run focused tests for structured agent requests, planning JSON validation, and QA runner behavior.
- Run `pnpm run test:backend` if new tests span several backend services.
- Success means planning and QA outputs can self-rate and improve when enabled, remain unchanged when disabled, and never bypass existing JSON validators.

✅ QA Review

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

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.5

⏱️ Timing

Started	2026-07-07 01:09:58 UTC
Finished	2026-07-07 01:18:24 UTC
Duration	8m 26s

📊 Token Usage

Metric	Value
Input tokens	265,336
Cached input tokens	2,869,760
Output tokens	17,931
Total tokens	3,153,027
Invocations	1
Tool calls	62
Active time	7m 44s

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

🌿 Branch Info

Base: feature/CODUX-149-self-reflection-persisten-skills
Head: task/feature-codux-149-self-reflection-persisten-skil-t05-codex-mr9yc2wi

---

🤖 Generated by Code UX