git:20260728.312fef9 to git:20260802.aa3bfed

- description: "Verify that an approved work plan is implementable before build execution, resolving readiness gaps through Phase 0 prep tasks when needed."

- 1. [LOAD IF NOT ACTIVE] `coding-rules` -- coding standards

- 2. [LOAD IF NOT ACTIVE] `testing` -- test strategy and quality gates

- 3. [LOAD IF NOT ACTIVE] `ai-development-guide` -- AI development patterns

- 4. [LOAD IF NOT ACTIVE] `documentation-criteria` -- document templates

- 5. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination

- 6. [LOAD IF NOT ACTIVE] `llm-friendly-context` -- clear prompts, handoffs, and generated artifacts

-

- **Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context.

- Run this recipe after work-plan approval and before any build or implementation execution. It verifies that the plan can be executed from Phase 1 onward without missing verification references, test prerequisites, UI render surfaces, or local execution instructions.

-

- The recipe is safe to invoke unconditionally. If all readiness criteria pass, it only updates the work plan readiness marker and report.

- ## Readiness Marker Contract

-

- Use the Implementation Readiness Marker Contract defined in `subagents-orchestration-guide`. If the line is absent, treat the work plan as `pending` and insert it after `Related Issue/PR:` when persisting the report.

-

- ## Readiness Criteria

-

- Each criterion produces `pass`, `fail`, or `not_applicable`, with file:line evidence where possible.

-

- | ID | Criterion | Pass Evidence |

- |----|-----------|---------------|

- | R1 | Verification Strategy and binding references resolve | Every command, file path, function, endpoint, fixture, seed, and test reference in the work plan's Verification Strategies either exists now or is the deliverable of a task in the plan; every Reference Contract Values `covered` row references existing task IDs; every Reference Contract Values `gap` row has Notes with user-confirmation handling; every ADR Bindings source path resolves; every ADR Bindings `covered` row references existing task IDs |

- | R2 | E2E prerequisites are addressed | For each fixture-e2e or service-integration-e2e skeleton, every noted precondition is present in the codebase or covered by a Phase 0 task |

- | R3 | Phase 1 observability exists | The first implementation phase includes at least one operation verification method executable at task completion using existing files, prior Phase 0 deliverables, or the task's own output |

- | R4 | UI rendering surface exists | When the plan implements UI components, a fixture entry, dev route, Storybook story, preview harness, or equivalent render surface exists or is covered by a Phase 0 task |

- | R5 | Local lane procedure exists | The work plan or referenced docs record commands needed to run the relevant local service stack or browser harness, including startup commands, ports, seed steps, and required environment variables |

-

- R4 applies only to UI work. R5 applies when the plan uses a local service stack or browser harness.

-

- ## Execution Flow

-

- Before Step 1, call `update_plan` with first "Map active rules to this task", Steps 1-6, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`.

-

- ### Step 1: Load Inputs

-

- Read the work plan passed in `$ARGUMENTS`; if absent, select the most recent non-template `docs/plans/*.md`. Extract:

- - Verification Strategies

- - Quality Assurance Mechanisms

- - Design-to-Plan Traceability

- - Reference Contract Values

- - ADR Bindings

- - UI Spec Component -> Task Mapping

- - Connection Map

- - test skeleton references and E2E absence reasons

- - phase structure and task IDs

- - referenced Design Docs, ADRs, and UI Specs

-

- If no work plan exists, stop and report the missing prerequisite.

-

- ### Step 2: Readiness Scan

-

- Evaluate R1-R5 using repository search and the work plan content. Build a `## Implementation Readiness Report` regardless of outcome.

-

- For each `fail`, identify the smallest concrete prep task that closes the gap. Examples:

- - Add fixture data for a UI state

- - Add an API mock handler for fixture-e2e

- - Add a seed script for service-integration-e2e

- - Add a Storybook story, dev route, or equivalent render surface

- - Document local startup commands and required environment variables

- - Add a missing verification helper or script referenced by the plan

-

- ### Step 3: No-Op Success

-

- When all applicable criteria are `pass`:

- 1. Persist `## Implementation Readiness Report` in the work plan immediately after the header block.

- 2. Set `Implementation Readiness: ready`.

- 3. Do not create task files.

- 4. Report `outcome: ready`.

-

- ### Step 4: Create Resolution Tasks

-

- When one or more criteria fail:

- 1. Present the proposed prep tasks to the user and continue only after explicit approval.

- - If the user declines prep execution, persist `Implementation Readiness: escalated` with the current Readiness Report and stop before creating prep task files.

- 2. Create task files in `docs/plans/tasks/` using the task template:

- - Backend prep: `{plan-name}-backend-task-prep-{NN}.md`

- - Frontend prep: `{plan-name}-frontend-task-prep-{NN}.md`

- - Single-layer prep: `{plan-name}-task-prep-{NN}.md`

- 3. Insert the tasks into the work plan's existing Phase 0 when one exists. If no Phase 0 exists, create `Phase 0: Implementation Readiness Prep` before Phase 1. Keep existing Phase 0 task IDs stable; assign prep task IDs after existing Phase 0 tasks or use a clearly labeled `P0-PREP-N` identifier when the plan's numbering would otherwise require renumbering.

- 4. Each prep task must include Investigation Targets, concrete implementation steps, and Operation Verification Methods.

-

- Layer selection:

- - Use frontend prep when every target is UI, browser harness, component, page, or frontend fixture work.

- - Use backend prep when every target is API, server, service, repository, database, seed, or backend fixture work.

- - Use single-layer prep for non-layered repositories.

- - Escalate if the gap crosses layers and cannot be split into separate prep tasks.

-

- ### Step 5: Execute Prep Tasks

-

- Run each prep task through the standard 4-step cycle:

- 1. Capture `diffBase`, then spawn the layer-appropriate task executor with the exact prep task path in the prompt: "Execute implementation-readiness prep task. Task file: [exact prep task path]."

- 2. Check for `blocked` or `escalation_needed`.

- 3. If the executor requires test review, call integration-test-reviewer with changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from task/work-plan references, pass only those paths as `skeletonFiles`; escalate `blocked` or an unrecognized status.

- 4. Spawn the layer-appropriate quality fixer with `task_file` and executor `filesModified`.

- 5. Commit only when the quality fixer returns `approved`.

-

- Append this scope boundary to every subagent prompt:

-

- ```

- [SYSTEM CONSTRAINT]

- This agent operates within implementation-readiness prep scope. Use the task file as the primary instruction source. Do not implement feature behavior beyond the readiness gap described by the task.

- ```

-

- ### Step 6: Re-Scan and Persist

- After prep tasks are complete:

- 1. Re-run the readiness scan.

- 2. Persist or replace `## Implementation Readiness Report` in the work plan.

- 3. Set the header to `Implementation Readiness: ready` when all applicable criteria pass, otherwise `Implementation Readiness: escalated`.

- 4. Collapse completed prep tasks out of active plan execution: remove the Phase 0 readiness prep task entries from the work plan and record their committed evidence under `Resolution Tasks Executed` in the Readiness Report. If Phase 0 becomes empty and was created only by this recipe, remove that Phase 0 section. Preserve any pre-existing Phase 0 content.

- 5. Delete only these files for the current `{plan-name}`:

- - `docs/plans/tasks/{plan-name}-task-prep-*.md`

- - `docs/plans/tasks/{plan-name}-backend-task-prep-*.md`

- - `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`

- - `docs/plans/tasks/{plan-name}-phase0-completion.md`

- 6. Report remaining gaps if any.

- ## Readiness Report Format

- ```markdown

- ## Implementation Readiness Report

- Work plan: [path]

- Outcome: ready | escalated

- Gaps resolved: [N]

- phase0_created_by_recipe: true | false

- ### Readiness Criteria

- | ID | Result | Evidence |

- |----|--------|----------|

- | R1 | pass / fail / not_applicable | [file:line or missing reference] |

- | R2 | ... | ... |

- | R3 | ... | ... |

- | R4 | ... | ... |

- | R5 | ... | ... |

- ### Resolution Tasks Executed

- - [task file path] - [one-line summary] - committed

- ### Remaining Gaps

- - [criterion ID]: [unresolved reference] - Next action: [recommendation]

- ## Completion Criteria

- - [ ] Work plan loaded and relevant sections extracted

- - [ ] Readiness scan completed with evidence per criterion

- - [ ] No-op success handled when all criteria pass

- - [ ] Failing criteria converted to approved prep tasks when needed

- - [ ] Prep tasks executed through executor -> quality-fixer -> commit

- - [ ] Re-scan completed after prep tasks

- - [ ] Work plan readiness marker updated to `ready` or `escalated`

- - [ ] Readiness Report persisted in the work plan

- - [ ] Completed prep task references collapsed into the Readiness Report

- - [ ] Prep task files created by this recipe removed from `docs/plans/tasks/`