create-ai-project 1.20.9 → 1.22.0

package/.claude/commands-en/prepare-implementation.md

@@ -0,0 +1,191 @@
+---
+description: Verify implementation readiness and resolve gaps before the build phase begins
+---
+
+**Context**: Optional readiness phase between work-plan approval and the build/implement phase. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps via Phase 0 tasks. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally.
+
+## Orchestrator Definition
+
+**Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill)
+
+**Execution Protocol**:
+1. **Delegate all work through Agent tool** — invoke sub-agents (task-executor / task-executor-frontend / quality-fixer / quality-fixer-frontend), pass deliverable paths between them, and report results
+2. **Self-contained scope**: When gaps are found, this recipe BOTH generates resolution tasks AND executes them through the standard 4-step cycle described in subagents-orchestration-guide "Standard Flow I Manage". Recipe completes only when readiness criteria pass or remaining gaps are escalated.
+3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution tasks and exit immediately. The only file modifications in this branch are to the work plan itself — promoting the `Implementation Readiness:` header to `ready` and persisting the Readiness Report section. No code or test files are touched.
+
+Work plan: $ARGUMENTS
+
+## When This Recipe Applies
+
+Run before any build/implement phase when ANY of the following hold:
+- Work plan was created from a Design Doc whose Verification Strategy references commands, files, functions, or endpoints not yet present in the codebase
+- Work plan includes E2E test skeletons (seed data, auth fixture, environment variables, or external mocks may be unaddressed)
+- Work plan touches UI components without a fixture entry or development route to render their visual states
+- The team has not previously confirmed the local lane runs end-to-end for this feature area
+
+When none of the above hold, the readiness scan in Step 2 will find zero failing criteria and the recipe exits no-op (see Context at the top of this command).
+
+## Readiness Criteria
+
+Each criterion is a measurable check producing `pass`, `fail`, or `not_applicable` with cited evidence.
+
+| ID | Criterion | Pass evidence |
+|----|-----------|---------------|
+| R1 | Verification Strategy references resolve | Every command, file path, function, endpoint, and test referenced in the work plan's Verification Strategy section either exists in the codebase (verified via Glob/Grep) or is the deliverable of a task already in this plan |
+| R2 | E2E preconditions addressed | When E2E skeletons exist: every precondition mentioned in skeleton comments (seed data, auth fixture, env var, external mock) is present in the codebase or covered by a Phase 0 task in this plan |
+| R3 | Phase 1 observability | The first implementation phase contains at least one task whose Operation Verification Methods can execute at task completion using only artifacts that exist before the task starts (existing code, prior Phase 0 task deliverables, or the task's own outputs) |
+| R4 | UI rendering surface | When the plan implements UI components: a fixture entry, dev route, Storybook story, or equivalent rendering surface exists for the impacted components, OR a Phase 0 task adds one |
+| R5 | Local lane procedure | The work plan or a referenced doc records the commands needed to start the system locally for manual verification (start commands, default ports, seed steps) |
+
+R4 and R5 are evaluated only when their triggering signals appear in the work plan; otherwise mark `not_applicable`.
+
+## Pre-execution Prerequisites
+
+```bash
+# Verify the work plan exists
+! ls -la docs/plans/*.md | grep -v template | tail -5
+```
+
+**State check**:
+- Work plan exists → Proceed to Step 1
+- No work plan → Stop and report: "An approved work plan is required. Complete the upstream planning phase first, then re-invoke this recipe."
+
+## Execution Flow
+
+### Step 1: Load Inputs
+
+Read the work plan path passed in `$ARGUMENTS`. Extract:
+- Verification Strategy section (Correctness Proof Method + Early Verification Point)
+- Quality Assurance Mechanisms table
+- Design-to-Plan Traceability table
+- Test skeleton references listed in the plan header
+- Phase structure with each phase's tasks
+- Referenced Design Doc(s) and UI Spec (when present)
+
+### Step 2: Readiness Scan
+
+For each criterion R1–R5:
+1. Execute the scan defined in Readiness Criteria using Read / Glob / Grep
+2. Record the result: `pass` / `fail` / `not_applicable`
+3. Cite evidence: file:line for `pass`, the unresolved reference for `fail`, the missing trigger signal for `not_applicable`
+
+Build the Readiness Report (see Output Format) regardless of outcome.
+
+### Step 3: No-op Check
+
+When every applicable criterion is `pass` (zero `fail`):
+- Append (or replace, if already present) a `## Implementation Readiness Report` section in the work plan immediately after the header block, using the same Readiness Report markdown defined in Output Format below
+- Update the work plan header `Implementation Readiness:` line to `ready` (insert it after `Related Issue/PR:` if absent)
+- Present the Readiness Report to the user
+- Exit with `outcome: ready, gaps_resolved: 0`
+- The work plan modifications above are the only file modifications in this branch
+
+When one or more criteria are `fail` → proceed to Step 4.
+
+### Step 4: Plan Resolution Tasks
+
+For each `fail` criterion:
+1. Determine the smallest concrete task that closes the gap (examples: "Add fixture entry for ComponentX covering loading/empty/error states", "Add seed script for E2E user fixtures", "Document local startup commands in docs/run/local.md")
+2. Decide the task's **layer** by matching every target file path against the markers below:
+   - **backend** when every target file path matches one of: `**/api/**`, `**/server/**`, `**/services/**`, `**/backend/**`, `**/handlers/**`, `**/repositories/**`
+   - **frontend** when every target file path matches one of: `**/components/**`, `**/pages/**`, `**/web/**`, `**/frontend/**`, `**/*.tsx`, `**/*.jsx`
+   - **prep-only** (typical prep targets that are language-/runtime-neutral — readiness setup rather than feature implementation) when every target file path matches one of: `docs/**`, `scripts/**`, `tests/fixtures/**`, `tests/e2e/data/**`, `tests/e2e/fixtures/**`, root-level config files (`*.json`, `*.yml`, `*.config.*`). Route to the **backend** executor / quality-fixer (`task-executor` + `quality-fixer`) since these tasks do not involve React-specific concerns
+   - **mixed** (target files span both backend and frontend markers, OR span feature markers and prep-only markers in a way that requires real implementation alongside readiness setup) → escalate to user; ask the user to split the gap into per-layer tasks
+   - **unrecognized** (any target file matches none of the markers above — e.g., a path under a non-standard top-level directory the project uses) → escalate to user; ask the user to either (a) decide which executor / quality-fixer should run the task, or (b) update the markers if the project uses different paths
+
+   Apply the rules in the order above. The first matching rule wins; "unrecognized" is the final fallback rather than a catch-all that defaults to backend.
+3. Create a Phase 0 task file at `docs/plans/tasks/{plan-name}-backend-task-prep-{NN}.md` (backend or prep-only) or `docs/plans/tasks/{plan-name}-frontend-task-prep-{NN}.md` (frontend) using the task template from documentation-criteria skill. The `-task-prep-` segment lets this recipe distinguish prep tasks from implementation tasks while keeping the existing `{plan-name}-{layer}-task-*` matcher used by other recipes. Prep-only tasks use the `-backend-task-prep-` filename so they route to the backend executor in Step 5
+4. Update the work plan to insert these tasks as Phase 0 (before Phase 1)
+
+Present the proposed resolution task list to the user with AskUserQuestion. Proceed only after explicit approval — this is the single human gate inside this recipe.
+
+### Step 5: Execute Resolution Tasks
+
+For each resolution task, run the 4-step cycle `task-executor → escalation check → quality-fixer → commit` (defined in subagents-orchestration-guide "Standard Flow I Manage", with layer routing per "Layer-Aware Agent Routing"):
+
+1. **Agent tool** — route by filename layer segment (matches the Layer-Aware Agent Routing table in the guide):
+   - `*-backend-task-prep-*` → `subagent_type: "task-executor"`
+   - `*-frontend-task-prep-*` → `subagent_type: "task-executor-frontend"`
+   - Filename without a recognized layer segment → escalate (the file should not exist; Step 4 prevents this)
+2. Check escalation per orchestration-guide
+3. **quality-fixer** — route by the same filename layer segment:
+   - `*-backend-task-prep-*` → `"quality-fixer"`
+   - `*-frontend-task-prep-*` → `"quality-fixer-frontend"`
+4. **Commit** when quality-fixer returns `approved`
+
+Append the Scope Boundary block (below) to every subagent prompt.
+
+### Step 6: Re-scan, Persist Readiness Report, Update Header, Cleanup, Exit
+
+1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution tasks are committed.
+
+2. **Persist Readiness Report into work plan body**: Append (or replace, if already present) a `## Implementation Readiness Report` section in the work plan immediately after the header block. Use the same Readiness Report markdown defined in Output Format below. Downstream build/implement recipes read this section when the header is `escalated` to surface remaining gaps to the user.
+
+3. **Update work plan header**: Locate the line `Implementation Readiness: pending` in the work plan and rewrite it based on the re-scan outcome:
+
+   | Re-scan result | New header value |
+   |----------------|------------------|
+   | All applicable criteria `pass` | `Implementation Readiness: ready` |
+   | One or more `fail` remain | `Implementation Readiness: escalated` |
+
+   If the line is absent (older work plan format), insert it after the `Related Issue/PR:` line.
+
+4. **Final Cleanup**: Delete every prep task file this recipe created for the current `{plan-name}` (`docs/plans/tasks/{plan-name}-backend-task-prep-*.md` and `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`) AND the phase-completion file generated for prep phases (`docs/plans/tasks/{plan-name}-phase0-completion.md` when present, since prep tasks live in Phase 0). Prep task files for other plans are out of scope — this recipe deletes only what it created for the current run. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs. The work plan itself is preserved for the downstream build/implement phase.
+
+5. **Exit**:
+
+   | Re-scan result | Action |
+   |----------------|--------|
+   | All applicable criteria `pass` | Exit with `outcome: ready, gaps_resolved: N` and final Readiness Report |
+   | One or more `fail` remain | Exit with `outcome: escalated` — present remaining failures to the user with the next-action recommendation. Treat the re-scan as the terminal evaluation; further resolution requires the user to re-invoke this recipe with updated inputs. |
+
+## Scope Boundary for Subagents
+
+Append the following block to every subagent prompt invoked from this recipe:
+
+```
+Scope boundary for subagents:
+Operate within the task scope and referenced files in the prompt.
+Use loaded skills to execute that scope.
+Escalate when the required fix or investigation falls outside that scope.
+```
+
+## Output Format
+
+Final report presented to the user at exit:
+
+```
+## Implementation Readiness Report
+
+Work plan: [path]
+Outcome: ready | escalated
+Gaps resolved: [N]
+
+### Readiness Criteria
+
+| ID | Result | Evidence |
+|----|--------|----------|
+| R1 | pass / fail / not_applicable | [file:line OR "missing: <unresolved reference>"] |
+| R2 | ... | ... |
+| R3 | ... | ... |
+| R4 | ... | ... |
+| R5 | ... | ... |
+
+### Resolution Tasks Executed (when gaps_resolved > 0)
+- [task file path] — [one-line summary] — committed
+- ...
+
+### Remaining Gaps (when outcome is escalated)
+- [criterion ID]: [unresolved reference] — Next action: [recommendation]
+```
+
+## Completion Criteria
+
+- [ ] Work plan loaded and Verification Strategy / E2E references / Phase structure extracted
+- [ ] Readiness scan run with per-criterion result and evidence recorded
+- [ ] No-op exit when all `pass`, OR resolution tasks generated, approved, and executed via the 4-step cycle
+- [ ] Re-scan run after the last resolution task commits
+- [ ] `## Implementation Readiness Report` section persisted into the work plan body
+- [ ] Work plan header `Implementation Readiness:` line updated to `ready` or `escalated`
+- [ ] Prep task files (and Phase 0 phase-completion file when generated) deleted from `docs/plans/tasks/`
+- [ ] Final report presented to the user

package/.claude/commands-en/project-inject.md

@@ -1,86 +1,114 @@
 ---
-description: Inject project-specific context into project-context skill
+description: Populate project-context skill via template-driven hearing
 ---
 
-**Command Context**: Collect project-specific prerequisites that improve AI execution accuracy and update project-context SKILL.md.
+**Command Context**: `/project-inject` collects project-specific prerequisites that improve AI execution accuracy and writes them into the `project-context` skill. The hearing is template-driven: the section catalog lives in `references/template.md`, and new dimensions are added by editing that template.
 
 ## Why This Matters
 
-CLAUDE.md's Session Initialization reads `project-context` skill at the start of every session. The information collected here directly affects AI decision-making accuracy across all tasks.
+CLAUDE.md's session initialization loads `project-context/SKILL.md` at the start of every session. Information collected here directly affects AI decision-making accuracy across all tasks. Keep the configured SKILL.md minimal — every line is paid in context budget per session.
 
-**Collect only what improves AI execution accuracy.**
+## Execution Flow
 
-## Execution Process
+Register all steps below using TaskCreate before starting Step 1, and update each task's status as you progress.
 
-Register the following steps with TaskCreate and proceed systematically.
+### Step 1: Load Inputs
 
-### Step 1: Understand Current State
+1. Read `.claude/skills/project-context/SKILL.md` to learn the current state. Distinguish the two cases by the count of catalog section headings (`## Project Overview`, `## Domain Constraints`, `## Development Phase`, `## Directory Conventions`, `## External Resources`) present in the body:
+   - **Unconfigured** — the body has zero catalog section headings.
+   - **Configured** — the body has one or more catalog section headings.
+2. Read `.claude/skills/project-context/references/template.md` to obtain the section catalog.
 
-Read the current project-context skill and package.json:
-- `.claude/skills/project-context/SKILL.md`
-- `package.json` (name, description)
+**Checkpoint**: You hold the section catalog from `template.md` and the configured-or-unconfigured state of `SKILL.md`.
 
-If project-context is already configured (no "Not configured" marker), confirm with user whether to overwrite or update.
+### Step 2: Build Section Plan
 
-### Step 2: Collect Project Context
+Produce a per-section plan (`add` / `keep` / `update` / `remove` / `skip`) covering every section in the catalog.
 
-Use AskUserQuestion to collect information in stages.
+**Unconfigured case**:
+- Project Overview: `add` (mandatory; the section's inclusion rule is "Always").
+- For each remaining catalog section, AskUserQuestion: "Add the `<section name>` section?" Options: "Yes, add it" / "No, skip". Mark `add` or `skip` accordingly.
 
-**Round 1: Project essence**
-- What does this project do? (1-2 sentences)
-- What domain does it belong to? (e.g., fintech, healthcare, developer tools, e-commerce)
+**Configured case**:
+- For each currently populated section, AskUserQuestion: "Action for the existing `<section name>` section?" Options: "Keep as-is" (mark `keep`) / "Update — replace existing content" (mark `update`) / "Remove — drop from rebuilt SKILL.md" (mark `remove`).
+- For each catalog section that is still empty in the existing SKILL.md, AskUserQuestion: "Add the `<section name>` section?" Options: "Yes, add it" (mark `add`) / "No, skip" (mark `skip`).
 
-**Round 2: Domain constraints** (based on Round 1 answers)
-- Are there domain-specific rules that AI must follow? Adapt examples to the domain from Round 1 (e.g., for fintech: "all mutations require audit logs"; for healthcare: "log output uses anonymized patient IDs").
-- Maximum 3 constraints. Only include what would cause bugs or compliance issues if AI ignores them.
+**Checkpoint**: Every catalog section has exactly one disposition: `add`, `keep`, `update`, `remove`, or `skip`.
 
-**Round 3: Development context**
-- Development phase: Prototype / Production / In operation
-- Are there directory conventions or file placement rules AI should follow? (skip if none)
+### Step 3: Run Hearing per Section
 
-### Step 3: Generate and Write
+For each section marked `add` or `update`, run the hearing protocol that `template.md` defines for that section. The catalog specifies the AskUserQuestion text and choices, the inclusion rules, and the per-section output structure.
 
-From collected information, generate project-context SKILL.md following these principles:
+**External Resources section**: follow the routing protocol in `template.md` § External Resources. That section owns the domain multi-select, the domain-to-file slug map, and the per-axis output schema; this command delegates to it.
 
-**Writing principles:**
-1. AI-decidable: Use only measurable and verifiable criteria ("fast" → "within 5 seconds")
-2. Eliminate ambiguity: Include specific numbers, conditions, examples
-3. Positive form: "do this" rather than "don't do that"
-4. Minimal: Only what affects AI execution accuracy
+**Vagueness rejection** (applies to every `add` and `update` section): When a user-provided rule uses subjective phrasing (e.g., "be careful about performance"), follow up with: "How would AI verify this rule passes? Restate it as a measurable check, or reply 'drop' to omit." Keep rules that arrive in measurable form as-is; replace subjective ones with the user's restated version, or omit them when the user replies 'drop'.
 
-**Output targets** (update both):
-1. `.claude/skills/project-context/SKILL.md` (active, read by Claude)
-2. Corresponding `skills-{lang}/project-context/SKILL.md` (check `.claudelang` for current language)
+**Checkpoint**: You hold captured content for every `add` and `update` section, plus the verbatim original content for every `keep` section.
 
-**Structure:**
-```markdown
----
-name: project-context
-description: Provides project-specific prerequisites for AI execution accuracy. Use when checking project structure.
----
+### Step 4: Assemble and Write SKILL.md
+
+Build the rebuilt SKILL.md by concatenating, in this order:
+
+1. Frontmatter — write this canonical block exactly:
+   ```
+   ---
+   name: project-context
+   description: Provides project-specific prerequisites for AI execution accuracy — domain constraints, development phase, directory conventions, external resource access methods. Use when the session starts, when checking project structure, or when a task references domain rules or external resources outside the repository.
+   ---
+   ```
+2. `# Project Context` heading.
+3. Each section in catalog order (Project Overview → Domain Constraints → Development Phase → Directory Conventions → External Resources). The output contains only sections whose disposition is `add`, `keep`, or `update` AND that satisfy their inclusion rule; the body advances directly from one included section to the next.
+
+Write the assembled content to `.claude/skills/project-context/SKILL.md`. This single path is the runtime canonical source read by Claude in every session.
+
+### Step 5: Verify
+
+Apply each check below to the rebuilt `.claude/skills/project-context/SKILL.md`:
+
+- [ ] Frontmatter matches the canonical block in Step 4 verbatim.
+- [ ] Every section heading in the body is followed by captured content from the hearing (concrete values, lists, or sub-blocks).
+- [ ] Every populated section's content matches the output structure that `template.md` defines for it.
+- [ ] Every section in the body has disposition `add`, `keep`, or `update` AND satisfies its inclusion rule.
+- [ ] Domain constraint statements are pass/fail checkable (e.g., "log entries use anonymized IDs" passes; "logs are clean" fails this check).
+- [ ] Project Context content is limited to constraints, phases, conventions, and external resources. Technology stack details belong in the `technical-spec` skill; implementation principles belong in the `coding-standards` skill.
 
-# Project Context
+When any check fails, report the failing check to the user with the specific line and propose either a re-hearing for the affected section or a manual edit. Re-run Step 5 after the fix.
 
-## Project Overview
-- **What this project does**: [concise description]
-- **Domain**: [domain]
+### Step 6: Present Result
 
-## Domain Constraints
-1. [Measurable constraint that affects AI decisions]
-2. [Verifiable requirement]
+Show the rebuilt SKILL.md to the user, list the changes made (added / updated / removed / kept sections), and confirm completion.
 
-## Development Phase
-- **Phase**: [current phase]
+## Output Examples
 
-## Directory Conventions
-[File placement rules, or "No specific conventions" if none]
+**Initial run on an unconfigured skill** (every section freshly captured):
+
+```
+project-context configured:
+- Sections kept: (none — first run)
+- Sections updated: (none — first run)
+- Sections added: Project Overview, Domain Constraints (2 rules captured), Development Phase, Directory Conventions (1 rule), External Resources (Backend domain — Database Schema Source, Secret Store)
+- Sections removed: (none)
+- File written: .claude/skills/project-context/SKILL.md
+```
+
+**Light update on a configured skill** (one section edited, rest preserved):
+
+```
+project-context updated:
+- Sections kept: Project Overview, Development Phase, Directory Conventions
+- Sections updated: Domain Constraints (3 rules captured)
+- Sections added: (none)
+- Sections removed: (none)
+- File written: .claude/skills/project-context/SKILL.md
 ```
 
-### Step 4: Verification
+**Trim run** (an existing section removed, no new ones added):
 
-- [ ] Generated file contains no boilerplate placeholder text ("to be configured", etc.)
-- [ ] All domain constraints are measurable/verifiable (no vague statements)
-- [ ] No technology stack information included (that belongs in technical-spec skill)
-- [ ] No implementation principles included (that belongs in coding-standards skill)
-- [ ] Both output targets updated
-- [ ] Present result to user for confirmation
+```
+project-context updated:
+- Sections kept: Project Overview, Domain Constraints, Development Phase
+- Sections updated: (none)
+- Sections added: (none)
+- Sections removed: Directory Conventions
+- File written: .claude/skills/project-context/SKILL.md
+```

package/.claude/commands-en/review.md

@@ -8,11 +8,10 @@ description: Design Doc compliance and security validation with optional auto-fi
 
 - Compliance validation → performed by code-reviewer
 - Security validation → performed by security-reviewer
-- Fix implementation → performed by task-executor
-- Quality checks → performed by quality-fixer
-- Re-validation → performed by code-reviewer / security-reviewer
+- **Code-side fix path**: Fix implementation → task-executor; Quality checks → quality-fixer; Re-validation → code-reviewer / security-reviewer
+- **Design-side update path**: DD revision → technical-designer (update mode); DD review → document-reviewer; cross-DD consistency → design-sync (when multiple DDs exist); Re-validation → code-reviewer
 
-Orchestrator invokes sub-agents and passes structured JSON between them.
+Orchestrator invokes sub-agents and passes structured JSON between them. The design-side path applies when the discrepancy reflects code that was correct but the Design Doc became stale, rather than code that violated the Design Doc.
 
 Design Doc (uses most recent if omitted): $ARGUMENTS
 
@@ -57,7 +56,24 @@ Invoke security-reviewer using Agent tool:
 - `approved` or `approved_with_notes` → Pass
 - `needs_revision` → Fail
 
-**Report both results independently using subagent output fields only** (do not add fields that are not in the subagent response):
+**Report both results independently using subagent output fields only** (do not add fields that are not in the subagent response).
+
+**Early exit (no findings to route)**: When code-reviewer's `verdict` is `pass` AND every entry in `acceptanceCriteria[]` has `status: "fulfilled"` AND `identifierMismatches[]` is empty AND `qualityFindings[]` is empty AND security-reviewer's `findings[]` is empty, skip Steps 5-10 and proceed directly to Step 11 — there is nothing to route. Present the clean result to the user.
+
+Otherwise, before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal — do not include it in the user-facing prompt). The rule keys off code-reviewer's existing structured fields only — interpretation of "DD intent" is intentionally avoided to prevent unstable inference:
+
+| Finding source | Pattern detectable from existing fields | Recommended route |
+|---------------|-----------------------------------------|-------------------|
+| `acceptanceCriteria[]` with `status: "partially_fulfilled"` or `"unfulfilled"` | The cited `gap` indicates the code does not satisfy the AC — needs additional implementation | `c` (Code-side fix) |
+| `acceptanceCriteria[]` with `status: "partially_fulfilled"` or `"unfulfilled"` | The cited `gap` indicates the AC text itself diverged from the implemented (and team-accepted) behavior — i.e., the DD's AC wording captured the wrong intent rather than the code missing requirements (verify by reading the AC and comparing against the cited `location`) | `d` (Design-side update — AC text outdated) |
+| `identifierMismatches[]` | `codeValue` is a plausible rename of `designDocValue` (camelCase ↔ kebab-case ↔ snake_case, abbreviation expansion/contraction, semantic renaming where both names refer to the same concept) — verify by inspecting the cited `location` to confirm the code uses the new name consistently | `d` (Design-side update — DD likely outdated) |
+| `identifierMismatches[]` | All other identifier mismatches (e.g., wrong type, wrong cardinality, missing entirely) | `c` (Code-side fix) |
+| `qualityFindings[]` | All categories (`dd_violation`, `maintainability`, `reliability`, `coverage_gap`) | `c` (Code-side fix) |
+| security-reviewer `findings[]` | All categories (`confirmed_risk`, `defense_gap`, `hardening`, `policy`) | `c` (Code-side fix) |
+
+The user can override any recommendation per finding. AC items with `status: "fulfilled"` are not routed (no action needed).
+
+Then present to the user (label each finding with its recommended route, grouped by route):
 
 ```
 Code Compliance: [complianceRate from code-reviewer]
@@ -65,30 +81,57 @@ Code Compliance: [complianceRate from code-reviewer]
   Identifier Match Rate: [identifierMatchRate from code-reviewer]
   Acceptance Criteria:
   - [fulfilled] [item] (confidence: [high/medium/low])
-  - [partially_fulfilled] [item]: [gap] — [suggestion]
-  - [unfulfilled] [item]: [gap] — [suggestion]
+  - [partially_fulfilled] [item]: [gap] — [suggestion] [recommended: c | d]
+  - [unfulfilled] [item]: [gap] — [suggestion] [recommended: c | d]
   Identifier Mismatches:
-  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location]
+  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location] [recommended: c | d]
   Quality Findings:
-  - [category] [location]: [description] — [rationale]
+  - [category] [location]: [description] — [rationale] [recommended: c]
 
 Security Review: [status from security-reviewer]
   Findings by category:
-  - [confirmed_risk] [location]: [description] — [rationale]
-  - [defense_gap] [location]: [description] — [rationale]
-  - [hardening] [location]: [description] — [rationale]
-  - [policy] [location]: [description] — [rationale]
+  - [confirmed_risk] [location]: [description] — [rationale] [recommended: c]
+  - [defense_gap] [location]: [description] — [rationale] [recommended: c]
+  - [hardening] [location]: [description] — [rationale] [recommended: c]
+  - [policy] [location]: [description] — [rationale] [recommended: c]
   Notes: [notes from security-reviewer, if present]
 
-Execute fixes? (y/n):
+Resolve discrepancies — confirm or override the recommended route per finding:
+  c) Code-side fix       — code violates Design Doc; modify code to match
+  d) Design-side update  — code is correct; Design Doc is stale, revise it
+  s) Skip                — accept current state without changes
 ```
 
-If both pass and user selects `n`: Skip Steps 5-10, proceed to Step 11.
+Use AskUserQuestion. The default offer is **"accept all recommended routes"** — a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11.
 
 ### 5. Load Task Template
 
 Read documentation-criteria skill to obtain the task file template (references/task-template.md) for Step 6.
 
+### 5d. Design-Side Update
+
+Run this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6.
+
+1. Invoke technical-designer in update mode using Agent tool:
+   - `subagent_type`: "technical-designer"
+   - `description`: "Design Doc update from review findings"
+   - `prompt`: "Update Design Doc at [path] in update mode. The implementation has diverged in the following ways that the team has decided to ratify in the design rather than in the code: [list of `d`-routed findings with codeLocation and designDocValue from $STEP_2_OUTPUT]. Reflect the current code behavior in the relevant sections and add a history entry."
+
+2. Invoke document-reviewer to verify the updated Design Doc:
+   - `subagent_type`: "document-reviewer"
+   - `description`: "Document review of updated Design Doc"
+   - `prompt`: "Review updated Design Doc at [path] for consistency and completeness."
+
+3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync:
+   - `subagent_type`: "design-sync"
+   - `description`: "Cross-DD consistency check"
+   - `prompt`: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update."
+   - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer for affected DDs.
+
+4. After Step 5d completes:
+   - If the user selected zero `c` routes (whether all `d`, all `s`, or a `d` + `s` mix with no `c`) → skip Steps 6-8, proceed to Step 9 for re-validation
+   - If the user selected both `d` and `c` → re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings
+
 ### 6. Create Task File
 
 Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md`
@@ -113,7 +156,7 @@ Invoke quality-fixer using Agent tool:
 Invoke code-reviewer using Agent tool:
 - `subagent_type`: "code-reviewer"
 - `description`: "Re-validate compliance"
-- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved."
+- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)."
 
 ### 10. Re-validate security-reviewer
 
@@ -122,7 +165,15 @@ Invoke security-reviewer using Agent tool (only if security fixes were applied):
 - `description`: "Re-validate security"
 - `prompt`: "Re-validate security after fixes. Prior findings: $STEP_3_OUTPUT. Design Doc: [path]. Implementation files: [file list]."
 
-### 11. Final Report
+### 11. Final Cleanup and Report
+
+Delete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs:
+
+- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists
+
+If the file cannot be deleted (filesystem error), report the failure but do not block the final report.
+
+Then present the final report:
 
 ```
 Code Compliance:
@@ -136,9 +187,11 @@ Security Review:
 
 Remaining issues:
 - [items requiring manual intervention]
+
+Cleanup: review-fixes task file removed
 ```
 
-## Auto-fixable Items
+## Auto-fixable Items (code-side path)
 - Simple unimplemented acceptance criteria
 - Error handling additions
 - Type definition fixes
@@ -148,10 +201,16 @@ Remaining issues:
 ## Non-fixable Items
 - Fundamental business logic changes
 - Architecture-level modifications
-- Design Doc deficiencies
 - Committed secrets (blocked → human intervention)
 
-**Scope**: Design Doc compliance validation, security review, and auto-fixes.
+## Design-Side Update Triggers
+Discrepancies suitable for the design-side path (code is correct, DD became stale):
+- Identifier renames where the new identifier reflects the team's current naming
+- Behavioral changes that match the original requirement intent better than what the DD captured
+- Component splits or merges where the new structure is sound and the DD documented the prior structure
+- New ACs that the implementation already satisfies but the DD never enumerated
+
+**Scope**: Design Doc compliance validation, security review, code-side auto-fixes, and design-side update routing.
 
 ## Scope Boundary for Subagents
 

package/.claude/commands-ja/add-integration-tests.md

@@ -168,6 +168,14 @@ quality-fixer レスポンスをチェック:
 quality-fixer から `approved` の場合:
 - Bash で適切なメッセージを付けてテストファイルをコミット
 
+### ステップ9: 最終クリーンアップ
+
+すべてのタスクファイルが処理されコミットされた後、本レシピが作成したタスクファイルを削除する。作業内容はコミット済みで、`docs/plans/`はレシピ実行間で保持しない一時的な作業状態である:
+
+- 本実行で作成された `docs/plans/tasks/integration-tests-backend-task-*.md` および `docs/plans/tasks/integration-tests-frontend-task-*.md` に該当するすべてのファイルを削除する
+
+タスクファイルを削除できない場合（ファイルシステムエラー）、失敗を報告するが完了をブロックしない。
+
 ## サブエージェントのスコープ境界
 
 本レシピから呼び出すサブエージェントプロンプトの末尾に以下のブロックを必ず付与する: