create-ai-project 1.23.4 → 1.24.0

package/.claude/agents-en/quality-fixer-frontend.md

@@ -199,11 +199,7 @@ Final message: exactly one JSON object matching the schema below (begins with `{
 All responses share `status` plus a `taskFileMechanisms` object when `task_file` is provided:
 
 ```json
-"taskFileMechanisms": {
-  "provided": true,
-  "executed": ["mechanism names that were found and executed"],
-  "skipped": [{"mechanism": "mechanism name", "reason": "tool not found | config not found | not executable"}]
-}
+"taskFileMechanisms": {"provided": true, "executed": ["mechanism names that were found and executed"], "skipped": [{"mechanism": "mechanism name", "reason": "tool not found | config not found | not executable"}]}
 ```
 When `task_file` is not provided, set `"provided": false` and omit `executed`/`skipped`.
 

package/.claude/agents-en/quality-fixer.md

@@ -163,11 +163,7 @@ Final message: exactly one JSON object matching the schema below (begins with `{
 All responses share `status` plus a `taskFileMechanisms` object when `task_file` is provided:
 
 ```json
-"taskFileMechanisms": {
-  "provided": true,
-  "executed": ["mechanism names that were found and executed"],
-  "skipped": [{"mechanism": "mechanism name", "reason": "tool not found | config not found | not executable"}]
-}
+"taskFileMechanisms": {"provided": true, "executed": ["mechanism names that were found and executed"], "skipped": [{"mechanism": "mechanism name", "reason": "tool not found | config not found | not executable"}]}
 ```
 When `task_file` is not provided, set `"provided": false` and omit `executed`/`skipped`.
 

package/.claude/agents-en/requirement-analyzer.md

@@ -116,23 +116,12 @@ Final message: exactly one JSON object matching the schema below (begins with `{
   "fileCount": 3,
   "adrRequired": true,
   "adrReason": "specific condition met, or null if not required",
-  "technicalConsiderations": {
-    "constraints": ["list"],
-    "risks": ["list"],
-    "dependencies": ["list"]
-  },
+  "technicalConsiderations": {"constraints": ["list"], "risks": ["list"], "dependencies": ["list"]},
   "scopeDependencies": [
-    {
-      "question": "specific question that affects scale",
-      "impact": { "if_yes": "large", "if_no": "medium" }
-    }
+    {"question": "specific question that affects scale", "impact": {"if_yes": "large", "if_no": "medium"}}
   ],
   "questions": [
-    {
-      "category": "boundary|existing_code|dependencies",
-      "question": "specific question",
-      "options": ["A", "B", "C"]
-    }
+    {"category": "boundary|existing_code|dependencies", "question": "specific question", "options": ["A", "B", "C"]}
   ]
 }
 ```

package/.claude/agents-en/rule-advisor.md

@@ -59,24 +59,11 @@ Return structured JSON:
 
 ```json
 {
-  "taskAnalysis": {
-    "taskType": "implementation|fix|refactoring|design|quality-improvement",
-    "essence": "Fundamental purpose", "estimatedFiles": 3, "scale": "small|medium|large",
-    "extractedTags": ["implementation", "testing", "security"]
-  },
+  "taskAnalysis": {"taskType": "implementation|fix|refactoring|design|quality-improvement", "essence": "Fundamental purpose", "estimatedFiles": 3, "scale": "small|medium|large", "extractedTags": ["implementation", "testing", "security"]},
   "selectedSkills": [
-    {
-      "skill": "coding-standards",
-      "sections": [{"title": "Section Name", "content": "## Section content..."}],
-      "reason": "Why needed", "priority": "high"
-    }
+    {"skill": "coding-standards", "sections": [{"title": "Section Name", "content": "## Section content..."}], "reason": "Why needed", "priority": "high"}
   ],
-  "metaCognitiveGuidance": {
-    "taskEssence": "Understanding fundamental purpose, not surface work",
-    "pastFailures": ["error-fixing impulse", "large changes at once", "insufficient testing"],
-    "potentialPitfalls": ["No root cause analysis", "No phased approach", "No tests"],
-    "firstStep": {"action": "First action", "rationale": "Why first"}
-  },
+  "metaCognitiveGuidance": {"taskEssence": "Understanding fundamental purpose, not surface work", "pastFailures": ["error-fixing impulse", "large changes at once", "insufficient testing"], "potentialPitfalls": ["No root cause analysis", "No phased approach", "No tests"], "firstStep": {"action": "First action", "rationale": "Why first"}},
   "metaCognitiveQuestions": ["Most important quality criterion?", "Past problems in similar tasks?", "Which part first?"],
   "warningPatterns": [
     {"pattern": "Large changes at once", "risk": "High complexity", "mitigation": "Split into phases"},

package/.claude/agents-en/scope-discoverer.md

@@ -164,17 +164,8 @@ Final message: exactly one JSON object matching the schema below (begins with `{
       "entryPoints": ["/path1", "/path2"],
       "relatedFiles": ["src/feature/*"],
       "dependencies": ["UNIT-002"],
-      "valueProfile": {
-        "targetPersona": "Who this feature serves (e.g., 'end user', 'admin', 'developer')",
-        "userGoal": "What the user is trying to accomplish with this feature",
-        "valueCategory": "High-level capability this belongs to (e.g., 'Authentication', 'Content Management', 'Reporting')"
-      },
-      "technicalProfile": {
-        "primaryModules": ["src/<feature>/module-a.ts", "src/<feature>/module-b.ts"],
-        "publicInterfaces": ["ServiceA.operation()", "ModuleB.handle()"],
-        "dataFlowSummary": "Input source → core processing path → output destination",
-        "infrastructureDeps": ["external dependency list"]
-      },
+      "valueProfile": {"targetPersona": "Who this feature serves (e.g., 'end user', 'admin', 'developer')", "userGoal": "What the user is trying to accomplish with this feature", "valueCategory": "High-level capability this belongs to (e.g., 'Authentication', 'Content Management', 'Reporting')"},
+      "technicalProfile": {"primaryModules": ["src/<feature>/module-a.ts", "src/<feature>/module-b.ts"], "publicInterfaces": ["ServiceA.operation()", "ModuleB.handle()"], "dataFlowSummary": "Input source → core processing path → output destination", "infrastructureDeps": ["external dependency list"]},
       "unitInventory": {
         "routes": [
           {"method": "POST", "path": "/api/auth/login", "handler": "AuthController.handleLogin", "file": "routes:15"}
@@ -189,28 +180,13 @@ Final message: exactly one JSON object matching the schema below (begins with `{
     }
   ],
   "relationships": [
-    {
-      "from": "UNIT-001",
-      "to": "UNIT-002",
-      "type": "depends_on|extends|shares_data"
-    }
+    {"from": "UNIT-001", "to": "UNIT-002", "type": "depends_on|extends|shares_data"}
   ],
   "uncertainAreas": [
-    {
-      "area": "Area name",
-      "reason": "Why uncertain",
-      "suggestedAction": "What to do"
-    }
+    {"area": "Area name", "reason": "Why uncertain", "suggestedAction": "What to do"}
   ],
   "prdUnits": [
-    {
-      "id": "PRD-001",
-      "name": "PRD unit name (user-value level)",
-      "description": "What this capability delivers to the user",
-      "sourceUnits": ["UNIT-001", "UNIT-003"],
-      "combinedRelatedFiles": ["src/feature-a/*", "src/feature-b/*"],
-      "combinedEntryPoints": ["/path1", "/path2", "/path3"]
-    }
+    {"id": "PRD-001", "name": "PRD unit name (user-value level)", "description": "What this capability delivers to the user", "sourceUnits": ["UNIT-001", "UNIT-003"], "combinedRelatedFiles": ["src/feature-a/*", "src/feature-b/*"], "combinedEntryPoints": ["/path1", "/path2", "/path3"]}
   ],
   "limitations": ["What could not be discovered and why"]
 }

package/.claude/agents-en/security-reviewer.md

@@ -100,22 +100,11 @@ Final message: exactly one JSON object matching the schema below (begins with `{
   "summary": "[1-2 sentence summary]",
   "filesReviewed": 5,
   "findings": [
-    {
-      "category": "confirmed_risk|suspected_risk|defense_gap|hardening|policy",
-      "confidence": "high|medium|low",
-      "location": "[file:line]",
-      "description": "[specific issue found]",
-      "rationale": "[category-specific, see Category-Specific Rationale]",
-      "suggestion": "[specific fix]"
-    }
+    {"category": "confirmed_risk|suspected_risk|defense_gap|hardening|policy", "confidence": "high|medium|low", "location": "[file:line]", "description": "[specific issue found]", "rationale": "[category-specific, see Category-Specific Rationale]", "suggestion": "[specific fix]"}
   ],
   "notes": "[summary of hardening/policy findings for completion report, present when status is approved_with_notes]",
   "requiredFixes": [
-    {
-      "location": "[file:line — parseable as file[:line] for Fix Mode allowed-list expansion]",
-      "issue": "[specific issue to fix — drawn from the corresponding finding]",
-      "fix": "[specific fix instruction]"
-    }
+    {"location": "[file:line — parseable as file[:line] for Fix Mode allowed-list expansion]", "issue": "[specific issue to fix — drawn from the corresponding finding]", "fix": "[specific fix instruction]"}
   ]
 }
 ```

package/.claude/agents-en/skill-creator.md

@@ -152,17 +152,14 @@ Return results as structured JSON:
 {
   "mode": "creation|modification",
   "skillName": "...",
-  "frontmatter": {
-    "name": "...",
-    "description": "..."
-  },
+  "frontmatter": {"name": "...", "description": "..."},
   "body": "full markdown content after frontmatter",
   "references": [
-    { "filename": "...", "content": "..." }
+    {"filename": "...", "content": "..."}
   ],
   "optimizationReport": {
     "issuesFound": [
-      { "pattern": "BP-XXX", "severity": "P1/P2/P3", "location": "...", "transform": "..." }
+      {"pattern": "BP-XXX", "severity": "P1/P2/P3", "location": "...", "transform": "..."}
     ],
     "researchFindings": [],
     "lineCount": 0,

package/.claude/agents-en/skill-reviewer.md

@@ -87,56 +87,20 @@ Return results as structured JSON:
   "grade": "A|B|C",
   "summary": "1-2 sentence overall assessment",
   "patternIssues": [
-    {
-      "pattern": "BP-XXX",
-      "severity": "P1|P2|P3",
-      "location": "section heading",
-      "original": "quoted text",
-      "suggestedFix": "replacement text"
-    }
+    {"pattern": "BP-XXX", "severity": "P1|P2|P3", "location": "section heading", "original": "quoted text", "suggestedFix": "replacement text"}
   ],
   "patternExceptions": [
-    {
-      "pattern": "BP-XXX",
-      "location": "section heading",
-      "original": "quoted text",
-      "conditions": {
-        "singleStepDestruction": "true|false + evidence",
-        "callerCannotRecover": "true|false + evidence",
-        "operationalNotPolicy": "true|false + evidence",
-        "positiveFormBlursScope": "true|false + evidence"
-      }
-    }
+    {"pattern": "BP-XXX", "location": "section heading", "original": "quoted text", "conditions": {"singleStepDestruction": "true|false + evidence", "callerCannotRecover": "true|false + evidence", "operationalNotPolicy": "true|false + evidence", "positiveFormBlursScope": "true|false + evidence"}}
   ],
   "principlesEvaluation": [
-    {
-      "principle": "1: Context efficiency",
-      "status": "pass|partial|fail",
-      "detail": "explanation if not pass"
-    }
+    {"principle": "1: Context efficiency", "status": "pass|partial|fail", "detail": "explanation if not pass"}
   ],
-  "progressiveDisclosure": {
-    "tier1": "pass|fail (description quality)",
-    "tier2": "pass|fail (body structure)",
-    "tier3": "pass|fail (reference organization)",
-    "details": "specific issues if any"
-  },
+  "progressiveDisclosure": {"tier1": "pass|fail (description quality)", "tier2": "pass|fail (body structure)", "tier3": "pass|fail (reference organization)", "details": "specific issues if any"},
   "crossSkillIssues": [
-    {
-      "overlappingSkill": "skill-name",
-      "description": "what overlaps",
-      "recommendation": "reference or deduplicate"
-    }
+    {"overlappingSkill": "skill-name", "description": "what overlaps", "recommendation": "reference or deduplicate"}
   ],
-  "balanceAssessment": {
-    "overOptimization": "none|minor|major",
-    "lostExpertise": "none|minor|major",
-    "clarityTradeOff": "none|minor|major",
-    "descriptionQuality": "pass|needs fix"
-  },
-  "actionItems": [
-    "Prioritized list of fixes (P1 first, then P2, then principles)"
-  ]
+  "balanceAssessment": {"overOptimization": "none|minor|major", "lostExpertise": "none|minor|major", "clarityTradeOff": "none|minor|major", "descriptionQuality": "pass|needs fix"},
+  "actionItems": ["Prioritized list of fixes (P1 first, then P2, then principles)"]
 }
 ```
 

package/.claude/agents-en/solver.md

@@ -73,6 +73,10 @@ Generate at least 3 solutions from the following perspectives:
 | mitigation | Measures to reduce impact | Temporary measure while waiting for root fix |
 | fundamental | Comprehensive fix including recurrence prevention | When similar problems have occurred repeatedly |
 
+**Adjacent Case Coverage**:
+- When the confirmed failure point concerns a `bug-fix`, `regression`, `state-change`, or `boundary-change` (the debugging flow carries no Change Category field, so judge these from the failure point itself), evaluate whether cases sharing the same path, contract, persisted state, or external boundary need the same fix
+- Include those adjacent cases in the solution scope when they share the same class of defect; record in residualRisks why any are excluded
+
 **Generated Solution Verification**:
 - Check if project rules have applicable guidelines
 - For areas without guidelines, research current best practices via WebSearch to verify solutions align with standard approaches
@@ -116,24 +120,10 @@ Final message: exactly one JSON object matching the schema below (begins with `{
   },
   "solutions": [
     {
-      "id": "S1",
-      "name": "Solution name",
-      "type": "direct|workaround|mitigation|fundamental",
-      "description": "Detailed solution description",
-      "implementation": {
-        "approach": "Implementation approach description",
-        "affectedFiles": ["Files requiring changes"],
-        "dependencies": ["Affected dependencies"]
-      },
-      "tradeoffs": {
-        "cost": {"level": "low|medium|high", "details": "Details"},
-        "risk": {"level": "low|medium|high", "details": "Details"},
-        "scope": {"level": "low|medium|high", "details": "Details"},
-        "maintainability": {"level": "low|medium|high", "details": "Details"},
-        "certainty": {"level": "low|medium|high", "details": "Details"}
-      },
-      "pros": ["Advantages"],
-      "cons": ["Disadvantages"]
+      "id": "S1", "name": "Solution name", "type": "direct|workaround|mitigation|fundamental", "description": "Detailed solution description",
+      "implementation": {"approach": "Implementation approach description", "affectedFiles": ["Files requiring changes"], "dependencies": ["Affected dependencies"]},
+      "tradeoffs": {"cost": {"level": "low|medium|high", "details": "Details"}, "risk": {"level": "low|medium|high", "details": "Details"}, "scope": {"level": "low|medium|high", "details": "Details"}, "maintainability": {"level": "low|medium|high", "details": "Details"}, "certainty": {"level": "low|medium|high", "details": "Details"}},
+      "pros": ["Advantages"], "cons": ["Disadvantages"]
     }
   ],
   "recommendation": {
@@ -144,12 +134,7 @@ Final message: exactly one JSON object matching the schema below (begins with `{
   },
   "implementationPlan": {
     "steps": [
-      {
-        "order": 1,
-        "action": "Specific action",
-        "verification": "How to verify this step",
-        "rollback": "Rollback procedure if problems occur"
-      }
+      {"order": 1, "action": "Specific action", "verification": "How to verify this step", "rollback": "Rollback procedure if problems occur"}
     ],
     "criticalPoints": ["Points requiring special attention"]
   },

package/.claude/agents-en/task-decomposer.md

@@ -79,13 +79,13 @@ Decompose tasks based on implementation strategy patterns determined in implemen
 
 4. **Task File Generation**
 
-   Naming follows the layer routing convention in subagents-orchestration-guide "Layer-Aware Agent Routing". The bare `{plan-name}-task-*.md` form routes exclusively to `task-executor` (backend) and must NOT be used for frontend tasks.
+   Naming follows the layer routing convention in subagents-orchestration-guide "Layer-Aware Agent Routing". The bare `{plan-name}-task-*.md` form is reserved for backend and must NOT be used for frontend tasks.
 
-   | Plan classification | Task filename | Routes to |
-   |---------------------|---------------|-----------|
-   | Single-layer **backend** | `{plan-name}-task-{number}.md` (preferred) OR `{plan-name}-backend-task-{number}.md` | `task-executor` + `quality-fixer` |
-   | Single-layer **frontend** | `{plan-name}-frontend-task-{number}.md` (REQUIRED — bare `*-task-*` form is reserved for backend) | `task-executor-frontend` + `quality-fixer-frontend` |
-   | Multi-layer (spans backend + frontend) | `{plan-name}-backend-task-{number}.md` AND `{plan-name}-frontend-task-{number}.md` (one file per layer per task slice) | per filename layer segment |
+   | Plan classification | Task filename |
+   |---------------------|---------------|
+   | Single-layer **backend** | `{plan-name}-task-{number}.md` (preferred) OR `{plan-name}-backend-task-{number}.md` |
+   | Single-layer **frontend** | `{plan-name}-frontend-task-{number}.md` (REQUIRED — bare `*-task-*` form is reserved for backend) |
+   | Multi-layer (spans backend + frontend) | `{plan-name}-backend-task-{number}.md` AND `{plan-name}-frontend-task-{number}.md` (one file per layer per task slice) |
 
    Layer is determined from the task's Target files paths (refer to project structure defined in technical-spec skill).
 
@@ -102,6 +102,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Task overview
    - Target files
    - **Investigation Targets** (what the executor must read and understand before implementing)
+   - **Change Category** (when the task is a bug fix / regression / state-change / boundary-change — see Change Category Classification below)
    - Concrete implementation steps
    - **Quality Assurance Mechanisms** (derived from work plan header — see Quality Assurance Mechanism Propagation below)
    - **Operation Verification Methods** (derived from Verification Strategy in work plan)
@@ -119,7 +120,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    | Frontend integration / fixture-e2e test | UI Spec component section including the State x Display Matrix and Interaction Definition tables, the implemented component code, fixture data files |
    | Test implementation | Test skeleton comments/annotations, the target code being tested, actual API/auth flows |
    | E2E environment setup | Current environment config (startup scripts, docker-compose or equivalent), seed scripts, existing fixture patterns, application auth flow |
-   | Cross-package boundary implementation | Both sides of the boundary as listed in the work plan's Connection Map (owner modules and expected signal), the contract definition between them |
+   | Cross-package boundary implementation | The Connection Map owner file path(s) on both sides of the boundary, plus the contract definition file between them (the expected signal and any serialized format/parse rule are recorded in the task's Boundary Context note, not as Investigation Targets) |
    | Bug fix / refactor | The affected code paths, related test coverage, error reproduction context |
    | Behavior replacement / rewrite | The existing implementation being replaced, its observable outputs, Design Doc Verification Strategy section |
    | Task constrained by an ADR (work plan's ADR Bindings table covers this task) | The ADR file with section hint matching the row's `Source Section` value (e.g., `(§ Decision)` or `(§ Implementation Guidance)`) for each binding row covering this task |
@@ -182,7 +183,7 @@ When the work plan contains a Connection Map table, propagate boundary context t
 
 1. **Lookup by task ID**: For each row in the Connection Map, locate the task(s) listed in the "Covered By Task(s)" column
 2. **Append to Investigation Targets**: Add the boundary's owner module file paths on both sides to each matched task's Investigation Targets
-3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, so the executor knows what observable evidence the implementation must produce
+3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, so the executor knows what observable evidence the implementation must produce. When the row carries a **Serialized Format** and **Consumer Parse Rule** (a serialized boundary), copy both verbatim into the note and state the roundtrip check the task must satisfy: the value the producer emits parses to the value the consumer expects.
 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step
 
 ## ADR Binding Propagation
@@ -205,6 +206,19 @@ When the work plan contains an ADR Bindings table, propagate each binding decisi
      When the decision cannot be verified by file:line or command alone, the predicate may rely on reasoned judgment, but it must remain Y/N-answerable
 4. **Apply only when provided**: Run this propagation only when the work plan contains an ADR Bindings table
 
+## Reference Contract Propagation
+
+When the work plan contains a **Reference Contract Values** table, propagate each binding observable value to the task(s) it covers, so the executor is checked against the exact value rather than a back-pointer it must re-derive:
+
+1. **Lookup by task ID**: For each row, locate the task(s) listed in "Covered By Task(s)"
+2. **Append to Investigation Targets**: Add the row's `Design Doc (§ Section)` to each matched task (deduplicate against Design Traceability Propagation entries)
+3. **Add a Reference Contracts table row to the task**: For each matched row, add one row to the task's Reference Contracts table:
+   - **Source**: the `Design Doc (§ Section)` value
+   - **Contract Type**: copy the `Contract Type` value verbatim (structure-order / derived-display / state-lifecycle-negative)
+   - **Required Observable Value**: copy the value **verbatim** from the work plan row, preserving its exact wording and detail
+   - **Compliance Check**: write a Y/N-answerable positive predicate stating the final implementation reproduces the value (e.g., "the listed fields render in the specified order"; "the label shows the looked-up name in place of the raw code"; "the persisted state is applied only when the restore signal is present")
+4. **Apply only when provided**: Run this propagation only when the work plan contains a Reference Contract Values table. Serialized boundaries are propagated by Connection Map Propagation above, not here.
+
 ## Design Traceability Propagation
 
 When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section to each task:
@@ -222,6 +236,21 @@ When the work plan header includes a Quality Assurance Mechanisms table, propaga
 3. **Include all if coverage is unspecified**: If a mechanism has no specific file coverage (applies project-wide), include it in every task
 4. **Omit when no match**: If no mechanisms match a task's target files, omit the "Quality Assurance Mechanisms" section from that task
 
+## Change Category Classification
+
+When a task corrects observed behavior or alters how state or a boundary behaves, classify it so the executor and downstream reviewers run a scoped adjacent-case sweep from the field value, rather than re-inferring the task's intent:
+
+1. **Classify from the work plan and Design Doc**. A task can match more than one category (e.g., a regression fix that changes a persisted-state boundary); record every value that applies:
+   - `bug-fix`: corrects observed incorrect behavior
+   - `regression`: restores behavior a prior change broke
+   - `state-change`: alters how state is written, transitioned, or persisted
+   - `boundary-change`: changes a published or consumed contract at an external, cross-package, or persisted boundary
+2. **Populate the task's `Change Category` field** with all matched values, comma-separated (see task template).
+3. **Extend Investigation Targets with the adjacent cases**. For every matched category, add the files sharing the same path, contract, persisted state, or external boundary as the change — including the owner module on both sides of an affected boundary — so the executor can sweep them for the same class of defect. Union the targets across all matched categories.
+4. **Apply only on a match**. Purely additive, config, or scaffolding tasks default to no `Change Category` field and skip this propagation.
+
+This is distinct from per-AC boundary-path proof (which proves a boundary path *within* an AC): Change Category drives a sweep of cases that sit *outside* the task's ACs but share its path, contract, state, or boundary.
+
 ## Task File Template
 
 See task template in documentation-criteria skill for details.
@@ -359,6 +388,8 @@ Please execute decomposed tasks according to the order.
 - [ ] Implementation efficiency and rework prevention (pre-identification of common processing, clarification of impact scope)
 - [ ] Investigation Targets specified for every task (specific file paths, not vague categories)
 - [ ] Proof Obligations recorded for each claim-implementing task (primary failure mode + boundary to exercise)
+- [ ] Change Category set for bug-fix / regression / state-change / boundary-change tasks, with adjacent path/boundary owners added to Investigation Targets
+- [ ] Reference Contract Values rows propagated to matching tasks as Reference Contracts, value copied verbatim (when work plan has the table)
 - [ ] Quality Assurance Mechanisms from work plan header propagated to relevant tasks
 
 ## Task Design Principles

package/.claude/agents-en/task-executor-frontend.md

@@ -183,6 +183,17 @@ This gate runs only when the task file's "Investigation Targets" section lists a
 2. **Investigate existing implementations**: Search for similar components/hooks in same domain/responsibility
 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`)
+
+Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies.
+
+1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback rendering, stale state, retries, and external calls related to the change.
+2. Check each for the same class of defect this task corrects.
+3. Disposition each residual by scope:
+   - **Within Target Files scope** → fold the residual into this task's failing tests and implementation.
+   - **A confirmed out-of-scope sibling that needs the same fix** → raise the `out_of_scope_file` escalation (the standard path for a file outside Target Files), letting the user expand Target Files or split off a follow-up task. This routes a confirmed adjacent defect to an explicit decision.
+   - **A related residual not confirmed to need the same fix** → record it in the task file's Investigation Notes so the downstream review's adjacent-case check verifies it against the implementation.
+
 #### Binding Decision Check (Required when the task file has a Binding Decisions section)
 
 This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows.
@@ -195,6 +206,18 @@ This check runs after Pre-implementation Verification and before the TDD cycle.
    - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see the Escalation Response table). `N` represents a planned violation
    - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point
 
+#### Reference Contract Check (Required when the task file has a Reference Contracts section)
+
+Runs after Pre-implementation Verification, alongside the Binding Decision Check.
+
+1. Confirm each Source in the Reference Contracts table has been read (Sources are listed in Investigation Targets and were read at Step 2)
+2. Record the planned approach in Investigation Notes — one sentence per row stating how the implementation reproduces the Required Observable Value
+3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject
+4. Per row, branch on the evaluation:
+   - `Y`: proceed
+   - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "design_compliance_violation"`, populated per the Escalation Response table — `details.design_doc_expectation` = the Reference Contract row's Required Observable Value, `details.actual_situation` = the planned approach, and `details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` per the table. `N` represents a planned violation
+   - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every deferred row against the final implementation and escalates if any remains `N` or `Unknown` at that point
+
 #### Reference Representativeness (Applied During Implementation)
 
 A per-adoption check applied each time a pattern, hook, or library is referenced. Apply coding-standards "Reference Representativeness" at the point of adoption:
@@ -278,20 +301,8 @@ Report in the following JSON format upon task completion (**without executing qu
   "testsAdded": ["src/components/Button/Button.test.tsx"],
   "requiresTestReview": false,
   "newTestsPassed": true,
-  "progressUpdated": {
-    "taskFile": "5/8 items completed",
-    "workPlan": "Relevant sections updated",
-    "designDoc": "Progress section updated or N/A"
-  },
-  "runnableCheck": {
-    "level": "L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test",
-    "executed": true,
-    "command": "test -- Button.test.tsx",
-    "result": "passed / failed / skipped",
-    "substance": "substantive | non_substantive | null (non-test verification)",
-    "substanceIssue": "null when substantive or non-test; cause and location when non_substantive",
-    "reason": "Test execution reason/verification content"
-  },
+  "progressUpdated": {"taskFile": "5/8 items completed", "workPlan": "Relevant sections updated", "designDoc": "Progress section updated or N/A"},
+  "runnableCheck": {"level": "L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test", "executed": true, "command": "test -- Button.test.tsx", "result": "passed / failed / skipped", "substance": "substantive | non_substantive | null (non-test verification)", "substanceIssue": "null when substantive or non-test; cause and location when non_substantive", "reason": "Test execution reason/verification content"},
   "readyForQualityCheck": true,
   "nextActions": "Overall quality verification by quality assurance process"
 }
@@ -334,11 +345,7 @@ Minimal example (out_of_scope_file):
   "reason": "Out of scope file",
   "taskName": "[task name]",
   "escalation_type": "out_of_scope_file",
-  "details": {
-    "file_path": "[path attempted]",
-    "allowed_list": ["[union of Target Files, task file, work plan, Provides]"],
-    "modification_reason": "[why modification was attempted]"
-  },
+  "details": {"file_path": "[path attempted]", "allowed_list": ["[union of Target Files, task file, work plan, Provides]"], "modification_reason": "[why modification was attempted]"},
   "user_decision_required": true,
   "suggested_options": ["Add to Target files and retry", "Split into separate task", "Reconsider approach"]
 }
@@ -352,7 +359,9 @@ This gate runs immediately before producing the final JSON response.
 ☐ Fix Mode: every `requiredFixes` / `incompleteImplementations` item is addressed in `changeSummary` or escalated
 ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present)
 ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach
+☐ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed
+☐ A test exercises the roundtrip — the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map)
 ☐ When test evidence is cited (the task ran tests), `runnableCheck.substance` and `runnableCheck.substanceIssue` are populated per the field spec
 ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification
 
-**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`.
+**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other unchecked gate items use `escalation_type: "design_compliance_violation"`, populated per the Escalation Response table at the same granularity as the pre-implementation mapping: for a Reference Contracts failure, `details.design_doc_expectation` = the Required Observable Value and `details.actual_situation` = the final implementation's behavior; for a missing roundtrip test, `details.design_doc_expectation` = the required roundtrip (the producer's emitted value parses to the consumer's expected value) and `details.actual_situation` = the absent or failing roundtrip coverage; in both, set `details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` per the table.

package/.claude/agents-en/task-executor.md

@@ -183,6 +183,17 @@ This gate runs only when the task file's "Investigation Targets" section lists a
 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility
 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`)
+
+Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies.
+
+1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback behavior, stale state, retries, and external calls related to the change.
+2. Check each for the same class of defect this task corrects.
+3. Disposition each residual by scope:
+   - **Within Target Files scope** → fold the residual into this task's failing tests and implementation.
+   - **A confirmed out-of-scope sibling that needs the same fix** → raise the `out_of_scope_file` escalation (the standard path for a file outside Target Files), letting the user expand Target Files or split off a follow-up task. This routes a confirmed adjacent defect to an explicit decision.
+   - **A related residual not confirmed to need the same fix** → record it in the task file's Investigation Notes so the downstream review's adjacent-case check verifies it against the implementation.
+
 #### Binding Decision Check (Required when the task file has a Binding Decisions section)
 
 This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows.
@@ -195,6 +206,18 @@ This check runs after Pre-implementation Verification and before the TDD cycle.
    - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see the Escalation Response table). `N` represents a planned violation
    - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point
 
+#### Reference Contract Check (Required when the task file has a Reference Contracts section)
+
+Runs after Pre-implementation Verification, alongside the Binding Decision Check.
+
+1. Confirm each Source in the Reference Contracts table has been read (Sources are listed in Investigation Targets and were read at Step 2)
+2. Record the planned approach in Investigation Notes — one sentence per row stating how the implementation reproduces the Required Observable Value
+3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject
+4. Per row, branch on the evaluation:
+   - `Y`: proceed
+   - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "design_compliance_violation"`, populated per the Escalation Response table — `details.design_doc_expectation` = the Reference Contract row's Required Observable Value, `details.actual_situation` = the planned approach, and `details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` per the table. `N` represents a planned violation
+   - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every deferred row against the final implementation and escalates if any remains `N` or `Unknown` at that point
+
 #### Reference Representativeness (Applied During Implementation)
 
 A per-adoption check applied each time a pattern or dependency is referenced. Apply coding-standards "Reference Representativeness" at the point of adoption:
@@ -281,20 +304,8 @@ Report in the following JSON format upon task completion (**without executing qu
   "testsAdded": ["created/test/file/path"],
   "requiresTestReview": true,
   "newTestsPassed": true,
-  "progressUpdated": {
-    "taskFile": "5/8 items completed",
-    "workPlan": "Relevant sections updated",
-    "designDoc": "Progress section updated or N/A"
-  },
-  "runnableCheck": {
-    "level": "L1: Unit test / L2: Integration test / L3: E2E test",
-    "executed": true,
-    "command": "Executed test command",
-    "result": "passed / failed / skipped",
-    "substance": "substantive | non_substantive | null (non-test verification)",
-    "substanceIssue": "null when substantive or non-test; cause and location when non_substantive",
-    "reason": "Test execution reason/verification content"
-  },
+  "progressUpdated": {"taskFile": "5/8 items completed", "workPlan": "Relevant sections updated", "designDoc": "Progress section updated or N/A"},
+  "runnableCheck": {"level": "L1: Unit test / L2: Integration test / L3: E2E test", "executed": true, "command": "Executed test command", "result": "passed / failed / skipped", "substance": "substantive | non_substantive | null (non-test verification)", "substanceIssue": "null when substantive or non-test; cause and location when non_substantive", "reason": "Test execution reason/verification content"},
   "readyForQualityCheck": true,
   "nextActions": "Overall quality verification by quality assurance process"
 }
@@ -337,11 +348,7 @@ Minimal example (out_of_scope_file):
   "reason": "Out of scope file",
   "taskName": "[task name]",
   "escalation_type": "out_of_scope_file",
-  "details": {
-    "file_path": "[path attempted]",
-    "allowed_list": ["[union of Target Files, task file, work plan, Provides]"],
-    "modification_reason": "[why modification was attempted]"
-  },
+  "details": {"file_path": "[path attempted]", "allowed_list": ["[union of Target Files, task file, work plan, Provides]"], "modification_reason": "[why modification was attempted]"},
   "user_decision_required": true,
   "suggested_options": ["Add to Target files and retry", "Split into separate task", "Reconsider approach"]
 }
@@ -355,7 +362,9 @@ This gate runs immediately before producing the final JSON response.
 ☐ Fix Mode: every `requiredFixes` / `incompleteImplementations` item is addressed in `changeSummary` or escalated
 ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present)
 ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach
+☐ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed
+☐ A test exercises the roundtrip — the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map)
 ☐ When test evidence is cited (the task ran tests), `runnableCheck.substance` and `runnableCheck.substanceIssue` are populated per the field spec
 ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification
 
-**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`.
+**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other unchecked gate items use `escalation_type: "design_compliance_violation"`, populated per the Escalation Response table at the same granularity as the pre-implementation mapping: for a Reference Contracts failure, `details.design_doc_expectation` = the Required Observable Value and `details.actual_situation` = the final implementation's behavior; for a missing roundtrip test, `details.design_doc_expectation` = the required roundtrip (the producer's emitted value parses to the consumer's expected value) and `details.actual_situation` = the absent or failing roundtrip coverage; in both, set `details.why_cannot_implement` / `details.attempted_approaches[]` / `claude_recommendation` per the table.