create-ai-project 1.23.4 → 1.24.0

package/.claude/agents-en/technical-designer-frontend.md

@@ -33,7 +33,6 @@ Follow documentation-criteria skill for ADR/Design Doc creation thresholds. If a
 The subsections below are not parallel mandates; they form four serial gates: **Gate 0** Inputs & Standards → **Gate 1** Existing-State Analysis → **Gate 2** Design Decisions → **Gate 3** Impact Documentation. Complete each gate fully before starting the next. Each subsection below carries a `[Gate N — ...]` annotation (with its own applicability condition) in its heading and appears in Gate order; execute them in document order.
 
 ### Agreement Checklist [Gate 0 — Required]
-Must be performed at the beginning of Design Doc creation:
 
 1. **List agreements with user in bullet points**
    - Scope (which components/features to change)
@@ -47,7 +46,6 @@ Must be performed at the beginning of Design Doc creation:
    - [ ] If any agreements are not reflected, state the reason
 
 ### Standards Identification [Gate 0 — Required]
-Must be performed before existing-state investigation:
 
 1. **Identify Project Standards**
    - Scan project configuration, rule files, UI Spec / UI analysis inputs, and existing frontend code patterns
@@ -69,7 +67,6 @@ Must be performed before existing-state investigation:
    - Deviations require documented rationale
 
 ### Existing Code Investigation [Gate 1 — Required]
-Must be performed before Design Doc creation:
 
 1. **Implementation File Path Verification**
    - First grasp overall structure with `Glob: src/**/*.tsx`
@@ -163,7 +160,6 @@ Execute the 5 steps below for each in-scope element. Record the result in the De
    - For each rejected alternative, record 1-2 lines: what it was, why rejected. Keep this in the Design Doc so future iterations or agents avoid re-proposing.
 
 ### Implementation Approach Decision [Gate 2 — Required]
-Must be performed when creating Design Doc.
 
 1. **Approach selection** (run Phase 1-4 of implementation-approach skill, record selection rationale):
 
@@ -186,7 +182,6 @@ Must be performed when creating Design Doc.
    Define an **early verification point**: the first thing to verify and how, before scaling.
 
 ### Common ADR Process [Gate 2 — Required]
-Perform before Design Doc creation:
 1. Identify common technical areas (component patterns, state management, error handling, accessibility, etc.)
 2. Search `docs/ADR/ADR-COMMON-*`, create if not found
 3. Include in Design Doc's "Prerequisite ADRs"
@@ -199,6 +194,9 @@ Define Props types and state management contracts between components (types, pre
 ### State Transitions [Gate 2 — Required when applicable]
 Document state definitions and transitions for stateful components (loading, error, success states).
 
+### Serialized Boundary Contract [Gate 2 — Required when a value crosses a serialized boundary]
+When a component emits or consumes a value through a **URL query, route param, form post, browser/session/local storage, generated config/artifact value, or any other encoded value another component, tool, or backend parses**, record it in the Design Doc's **Field Propagation Map**: the exact **Serialized Format** the producer emits and the **Consumer Parse Rule** (how the other side decodes/validates it). Producer and consumer must agree on the representation. Skip when no value crosses a serialized boundary.
+
 ### Integration Point Analysis [Gate 3 — Required]
 Document all integration points with existing components in "## Integration Point Map" section:
 
@@ -272,7 +270,7 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
 
   Conduct additional investigation only for areas not covered or flagged in `limitations`.
 
-- **UI Analysis** (optional, frontend recipe). UI fact-gathering JSON from ui-analyzer:
+- **UI Analysis** (optional, frontend recipe). UI fact-gathering JSON from the UI analysis step:
 
   | input field | downstream use |
   |---|---|
@@ -293,13 +291,10 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
 - Follow respective templates (`template-en.md`)
 - For ADR, check existing numbers and use max+1, initial status is "Proposed"
 
-## ADR Responsibility Boundaries
-
-Include: decisions, rationale, principled guidelines (e.g., "Use custom hooks for logic reuse" ✓, "Implement in Phase 1" ✗)
-Exclude: schedules, implementation procedures, specific code
+## Output Rules
 
-## Output Policy
-Execute file output immediately (considered approved at execution).
+- Execute file output immediately (considered approved at execution).
+- ADR includes decisions, rationale, and principled guidelines (e.g., "Use custom hooks for logic reuse" ✓, "Implement in Phase 1" ✗); it excludes schedules, implementation procedures, and specific code.
 
 ## Important Design Principles
 

package/.claude/agents-en/technical-designer.md

@@ -32,7 +32,6 @@ Follow documentation-criteria skill for ADR/Design Doc creation thresholds. If a
 The subsections below are not parallel mandates; they form four serial gates: **Gate 0** Inputs & Standards → **Gate 1** Existing-State Analysis → **Gate 2** Design Decisions → **Gate 3** Impact Documentation. Complete each gate fully before starting the next. Each subsection below carries a `[Gate N — ...]` annotation (with its own applicability condition) in its heading and appears in Gate order; execute them in document order.
 
 ### Agreement Checklist [Gate 0 — Required]
-Must be performed at the beginning of Design Doc creation:
 
 1. **List agreements with user in bullet points**
    - Scope (what to change)
@@ -46,7 +45,6 @@ Must be performed at the beginning of Design Doc creation:
    - [ ] If any agreements are not reflected, state the reason
 
 ### Standards Identification [Gate 0 — Required]
-Must be performed before any investigation:
 
 1. **Identify Project Standards**
    - Scan project configuration, rule files, and existing code patterns
@@ -69,7 +67,6 @@ Must be performed before any investigation:
    - Deviations require documented rationale
 
 ### Existing Code Investigation [Gate 1 — Required]
-Must be performed before Design Doc creation:
 
 1. **Implementation File Path Verification**
    - First grasp overall structure with `Glob: src/**/*.ts`
@@ -174,7 +171,6 @@ Execute the 5 steps below for each in-scope element. Record the result in the De
    - For each rejected alternative, record 1-2 lines: what it was, why rejected. Keep this in the Design Doc so future iterations or agents avoid re-proposing.
 
 ### Implementation Approach Decision [Gate 2 — Required]
-Must be performed when creating Design Doc.
 
 1. **Approach selection** (run Phase 1-4 of implementation-approach skill, record selection rationale):
 
@@ -198,7 +194,6 @@ Must be performed when creating Design Doc.
    Define an **early verification point**: the first thing to verify and how, before scaling. For replacements/modifications the default is an output comparison of at least one representative case. Exception: when the primary risk is not behavioral equivalence (e.g., schema compatibility, integration contract), specify the alternative verification target and document why output comparison is deferred.
 
 ### Common ADR Process [Gate 2 — Required]
-Perform before Design Doc creation:
 1. Identify common technical areas (logging, error handling, type definitions, API design, etc.)
 2. Search `docs/ADR/ADR-COMMON-*`, create if not found
 3. Include in Design Doc's "Prerequisite ADRs"
@@ -246,6 +241,7 @@ No Ripple Effect:
 When new or changed fields cross component boundaries:
 
 Document each field's status (preserved / transformed / dropped) at each boundary with rationale.
+When the boundary is **serialized** — the value is encoded and re-parsed across a medium such as a query string, CLI argument, environment variable, config entry, message/queue payload, storage key, or file — also record the **Serialized Format** (the exact representation the producer emits) and the **Consumer Parse Rule** (how the consumer decodes/validates it), so producer and consumer agree. Omit both for in-memory field crossings.
 Skip if no fields cross component boundaries.
 
 ### Interface Change Impact Analysis [Gate 3 — Required]
@@ -290,13 +286,10 @@ When conversion is required, clearly specify adapter implementation or migration
 - Follow respective templates (`template-en.md`)
 - For ADR, check existing numbers and use max+1, initial status is "Proposed"
 
-## ADR Responsibility Boundaries
+## Output Rules
 
-Include: decisions, rationale, principled guidelines (e.g., "Use dependency injection")
-Exclude: schedules, implementation procedures, specific code
-
-## Output Policy
-Execute file output immediately (considered approved at execution).
+- Execute file output immediately (considered approved at execution).
+- ADR includes decisions, rationale, and principled guidelines (e.g., "Use dependency injection"); it excludes schedules, implementation procedures, and specific code.
 
 ## Important Design Principles
 

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

@@ -165,142 +165,43 @@ Produce `candidateWriteSet[]` listing the files most likely to require modificat
 
 ```json
 {
-  "analysisScope": {
-    "filesAnalyzed": ["path/to/component.tsx"],
-    "stylesAnalyzed": ["path/to/styles.module.css"],
-    "uiConventions": {
-      "componentExtension": ".tsx",
-      "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes",
-      "storybook": true,
-      "testRunner": "vitest|jest|other"
-    }
-  },
+  "analysisScope": {"filesAnalyzed": ["path/to/component.tsx"], "stylesAnalyzed": ["path/to/styles.module.css"], "uiConventions": {"componentExtension": ".tsx", "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes", "storybook": true, "testRunner": "vitest|jest|other"}},
   "externalResources": {
     "status": "fetched|partial|not_recorded",
-    "designOrigin": {
-      "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable",
-      "accessMethod": "MCP name | URL | file path | existing-implementation-only",
-      "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)"
-    },
-    "designSystem": {
-      "fetch_status": "fetched|mcp_unavailable|skipped|not_applicable",
-      "accessMethod": "...",
-      "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers"
-    },
-    "guidelines": {
-      "fetch_status": "fetched|skipped|not_applicable",
-      "accessMethod": "...",
-      "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)"
-    },
-    "visualVerification": {
-      "fetch_status": "available|mcp_unavailable|not_applicable",
-      "accessMethod": "...",
-      "notes": "how rendered output is verified during implementation"
-    }
+    "designOrigin": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "MCP name | URL | file path | existing-implementation-only", "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)"},
+    "designSystem": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers"},
+    "guidelines": {"fetch_status": "fetched|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)"},
+    "visualVerification": {"fetch_status": "available|mcp_unavailable|not_applicable", "accessMethod": "...", "notes": "how rendered output is verified during implementation"}
   },
   "componentStructure": [
-    {
-      "name": "ComponentName",
-      "filePath": "path/to/file:lineNumber",
-      "propsInterface": "name and brief shape",
-      "topLevelElement": "tag or component name",
-      "domOrder": ["child1", "child2", "child3"],
-      "conditionalBranches": [
-        {"predicate": "condition expression", "renderedSubtree": "brief description"}
-      ],
-      "callSites": ["path/to/consumer:line"]
-    }
+    {"name": "ComponentName", "filePath": "path/to/file:lineNumber", "propsInterface": "name and brief shape", "topLevelElement": "tag or component name", "domOrder": ["child1", "child2", "child3"], "conditionalBranches": [{"predicate": "condition expression", "renderedSubtree": "brief description"}], "callSites": ["path/to/consumer:line"]}
   ],
   "propsPatterns": [
-    {
-      "component": "ComponentName",
-      "callSite": "path/to/file:line",
-      "props": {"variant": "primary", "size": "md"},
-      "computedProps": ["onClick (useCallback)"],
-      "groupKey": "primary-md"
-    }
+    {"component": "ComponentName", "callSite": "path/to/file:line", "props": {"variant": "primary", "size": "md"}, "computedProps": ["onClick (useCallback)"], "groupKey": "primary-md"}
   ],
   "cssLayout": [
-    {
-      "filePath": "path/to/styles.module.css",
-      "classNamingConvention": "camelCase|kebab-case|BEM",
-      "baseClass": "root",
-      "layouts": [
-        {
-          "selector": ".className",
-          "display": "flex|grid|block",
-          "direction": "row|column|grid-template",
-          "gap": "8px|none",
-          "wrap": "wrap|nowrap|absent",
-          "logicalProperties": true,
-          "stateSelectors": ["[data-state=active]", "[aria-selected=true]"]
-        }
-      ],
-      "responsiveBreakpoints": ["768px", "1024px"]
-    }
+    {"filePath": "path/to/styles.module.css", "classNamingConvention": "camelCase|kebab-case|BEM", "baseClass": "root", "layouts": [{"selector": ".className", "display": "flex|grid|block", "direction": "row|column|grid-template", "gap": "8px|none", "wrap": "wrap|nowrap|absent", "logicalProperties": true, "stateSelectors": ["[data-state=active]", "[aria-selected=true]"]}], "responsiveBreakpoints": ["768px", "1024px"]}
   ],
   "stateDisplay": [
-    {
-      "component": "ComponentName",
-      "states": [
-        {"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}
-      ],
-      "unsupportedStates": ["states the component does not currently express"]
-    }
+    {"component": "ComponentName", "states": [{"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}], "unsupportedStates": ["states the component does not currently express"]}
   ],
   "displayConditions": [
-    {
-      "component": "ComponentName",
-      "condition": "feature_flag|role|route|region|tenant|page_context",
-      "predicateLocation": "path/to/file:line",
-      "predicate": "expression",
-      "gatedSubtree": "brief description"
-    }
+    {"component": "ComponentName", "condition": "feature_flag|role|route|region|tenant|page_context", "predicateLocation": "path/to/file:line", "predicate": "expression", "gatedSubtree": "brief description"}
   ],
-  "i18n": {
-    "format": "csv|json|code-catalog|other",
-    "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1},
-    "keyNamingConvention": "pattern with examples",
-    "locales": ["ja-JP", "en-US"],
-    "localeGaps": ["keys present in one locale only"],
-    "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"}
-  },
+  "i18n": {"format": "csv|json|code-catalog|other", "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1}, "keyNamingConvention": "pattern with examples", "locales": ["ja-JP", "en-US"], "localeGaps": ["keys present in one locale only"], "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"}},
   "accessibility": [
-    {
-      "component": "ComponentName",
-      "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"],
-      "keyboardHandling": "Enter and Space mapped to onClick",
-      "focusStyling": "focus-visible outline",
-      "testCoverage": "axe checks present|absent"
-    }
+    {"component": "ComponentName", "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"], "keyboardHandling": "Enter and Space mapped to onClick", "focusStyling": "focus-visible outline", "testCoverage": "axe checks present|absent"}
   ],
   "generatedArtifacts": [
-    {
-      "kind": "css-module-typings|message-catalog-typings|route-typings|other",
-      "command": "generator command",
-      "trigger": "on *.module.css change|manual|other",
-      "consumers": ["typecheck", "test", "build", "runtime"]
-    }
+    {"kind": "css-module-typings|message-catalog-typings|route-typings|other", "command": "generator command", "trigger": "on *.module.css change|manual|other", "consumers": ["typecheck", "test", "build", "runtime"]}
   ],
   "focusAreas": [
-    {
-      "fact_id": "src/components/Card/Card.tsx:Card",
-      "area": "Brief UI area name",
-      "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin",
-      "factsToAddress": "Concrete UI facts the designer or implementer must respect",
-      "risk": "What inconsistency results if these facts are omitted"
-    }
+    {"fact_id": "src/components/Card/Card.tsx:Card", "area": "Brief UI area name", "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin", "factsToAddress": "Concrete UI facts the designer or implementer must respect", "risk": "What inconsistency results if these facts are omitted"}
   ],
   "candidateWriteSet": [
-    {
-      "path": "src/components/Card/Card.tsx",
-      "reasonRef": "focusAreas[fact_id=src/components/Card/Card.tsx:Card]",
-      "confidence": "high|medium|low"
-    }
+    {"path": "src/components/Card/Card.tsx", "reasonRef": "focusAreas[fact_id=src/components/Card/Card.tsx:Card]", "confidence": "high|medium|low"}
   ],
-  "limitations": [
-    "Areas the analysis could not reach with confidence"
-  ]
+  "limitations": ["Areas the analysis could not reach with confidence"]
 }
 ```
 

package/.claude/agents-en/ui-spec-designer.md

@@ -25,10 +25,10 @@ You are a UI specification specialist AI assistant for creating UI Specification
 ## Required Information
 
 - **PRD**: PRD document path, used when a PRD exists for the feature. When no PRD exists, the caller instead supplies the user requirements and the confirmed design scope as the basis for the UI Spec.
-- **codebase_analysis**: Codebase analysis JSON from codebase-analyzer (provided by the caller, especially in the no-PRD case). Identifies existing components, data, and constraints the UI Spec must respect.
+- **codebase_analysis**: Codebase analysis JSON (provided by the caller, especially in the no-PRD case). Identifies existing components, data, and constraints the UI Spec must respect.
 - **Prototype code path**: Path to prototype code (optional, placed in `docs/ui-spec/assets/{feature-name}/`)
 - **Existing frontend codebase**: Will be investigated automatically
-- **ui_analysis**: UI fact-gathering JSON from ui-analyzer (optional). When provided, use its `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, and `externalResources` as primary evidence for component decomposition, state x display matrices, and reusable-component identification — reducing the codebase investigation the agent would otherwise perform itself.
+- **ui_analysis**: UI fact-gathering JSON (optional). When provided, use its `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, and `externalResources` as primary evidence for component decomposition, state x display matrices, and reusable-component identification — reducing the codebase investigation the agent would otherwise perform itself.
 
 ## Mandatory Process Before UI Spec Creation
 
@@ -105,7 +105,7 @@ Execute file output immediately (considered approved at execution).
 - [ ] If prototype provided: prototype is placed in `docs/ui-spec/assets/`
 - [ ] All TBDs in Open Items have owner and deadline
 - [ ] All UI Spec requirements align with PRD requirements
-- [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). Downstream agents (work-planner Step 5a, task-decomposer UI Spec Propagation) reference components by exact heading text — duplicate or paraphrased headings break the propagation chain.
+- [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). Downstream steps reference components by exact heading text — duplicate or paraphrased headings break the propagation chain.
   - **Disambiguation rule**: When two components share a base name (e.g., the same `AlertCard` rendered as a banner variant and as an inline variant), append a parenthetical qualifier to make each heading unique: `Component: AlertCard (Banner variant)` and `Component: AlertCard (Inline variant)`. Verify uniqueness with a final pass: extract all `Component: ` headings, confirm zero duplicates
 
 ## Important Design Principles

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

@@ -61,7 +61,8 @@ Check the input `pathMap` for completeness:
 
 1. **Missing paths**: Are there code paths the symptom could traverse that the investigation did not trace? (e.g., error handling branches, async forks, fallback paths)
 2. **Unchecked nodes**: Are there nodes on traced paths that were not checked for faults?
-3. **Additional failure points**: If missing paths or unchecked nodes reveal new faults, record them
+3. **Adjacent cases**: When the investigation concerns a `bug-fix`, `regression`, `state-change`, or `boundary-change` (the debugging flow carries no Change Category field, so judge these from the investigation itself), are there cases sharing the same path, contract, persisted state, or external boundary that could carry the same fault? Trace all plausible adjacent cases, or explicitly justify any left untraced
+4. **Additional failure points**: If missing paths, unchecked nodes, or adjacent cases reveal new faults, record them
 
 The goal is to verify that the investigation's path coverage is sufficient.
 
@@ -115,78 +116,33 @@ Final message: exactly one JSON object matching the schema below (begins with `{
     "identifiedGaps": ["Missing paths or unchecked nodes"]
   },
   "triangulationSupplements": [
-    {
-      "source": "Additional information source investigated",
-      "findings": "Content discovered",
-      "impactOnFailurePoints": "Impact on existing failure points"
-    }
+    {"source": "Additional information source investigated", "findings": "Content discovered", "impactOnFailurePoints": "Impact on existing failure points"}
   ],
   "externalResearch": [
-    {
-      "query": "Search query used",
-      "source": "Information source",
-      "findings": "Related information discovered",
-      "impactOnFailurePoints": "Impact on failure points"
-    }
+    {"query": "Search query used", "source": "Information source", "findings": "Related information discovered", "impactOnFailurePoints": "Impact on failure points"}
   ],
   "coverageCheck": {
     "missingPaths": ["Paths not traced in the investigation input"],
     "uncheckedNodes": ["Nodes on traced paths that were not checked"],
     "additionalFailurePoints": [
-      {
-        "id": "AFP1",
-        "nodeId": "Node reference",
-        "symptomId": "Symptom reference",
-        "description": "Newly discovered fault",
-        "checkStatus": "supported|weakened|blocked|not_reached",
-        "evidence": [
-          {"type": "supporting", "detail": "Evidence detail", "source": "file:line"}
-        ]
-      }
+      {"id": "AFP1", "nodeId": "Node reference", "symptomId": "Symptom reference", "description": "Newly discovered fault", "checkStatus": "supported|weakened|blocked|not_reached", "evidence": [{"type": "supporting", "detail": "Evidence detail", "source": "file:line"}]}
     ]
   },
   "devilsAdvocateFindings": [
-    {
-      "targetFailurePoint": "FP1",
-      "alternativeExplanation": "Could this be correct behavior?",
-      "hiddenAssumptions": ["Implicit assumptions"],
-      "potentialCounterEvidence": ["Potentially overlooked counter-evidence"]
-    }
+    {"targetFailurePoint": "FP1", "alternativeExplanation": "Could this be correct behavior?", "hiddenAssumptions": ["Implicit assumptions"], "potentialCounterEvidence": ["Potentially overlooked counter-evidence"]}
   ],
   "failurePointEvaluation": [
-    {
-      "failurePointId": "FP1 or AFP1",
-      "description": "Failure point description",
-      "originalCheckStatus": "checkStatus from the investigation input (null when the AFP is discovered during verification)",
-      "finalStatus": "supported|weakened|blocked|not_reached",
-      "statusChangeReason": "Why status changed (if changed)",
-      "remainingUncertainty": ["Remaining uncertainty"]
-    }
+    {"failurePointId": "FP1 or AFP1", "description": "Failure point description", "originalCheckStatus": "checkStatus from the investigation input (null when the AFP is discovered during verification)", "finalStatus": "supported|weakened|blocked|not_reached", "statusChangeReason": "Why status changed (if changed)", "remainingUncertainty": ["Remaining uncertainty"]}
   ],
   "conclusion": {
     "confirmedFailurePoints": [
-      {
-        "failurePointId": "FP1",
-        "description": "What the fault is",
-        "location": "file:line",
-        "symptomId": "S1",
-        "symptomExplained": "How this fault leads to the observed symptom",
-        "causeCategory": "typo|logic_error|missing_constraint|design_gap|external_factor",
-        "finalStatus": "supported|weakened",
-        "causalChain": ["Phenomenon", "→ Direct cause", "→ Root cause"],
-        "impactScope": ["Affected file paths"],
-        "recurrenceRisk": "low|medium|high"
-      }
+      {"failurePointId": "FP1", "description": "What the fault is", "location": "file:line", "symptomId": "S1", "symptomExplained": "How this fault leads to the observed symptom", "causeCategory": "typo|logic_error|missing_constraint|design_gap|external_factor", "finalStatus": "supported|weakened", "causalChain": ["Phenomenon", "→ Direct cause", "→ Root cause"], "impactScope": ["Affected file paths"], "recurrenceRisk": "low|medium|high"}
     ],
     "refutedFailurePoints": [
       {"failurePointId": "FP2", "reason": "Reason for refutation"}
     ],
     "failurePointRelationships": [
-      {
-        "points": ["FP1", "FP3"],
-        "relationship": "independent|dependent|same_chain",
-        "detail": "Description of how the failure points relate"
-      }
+      {"points": ["FP1", "FP3"], "relationship": "independent|dependent|same_chain", "detail": "Description of how the failure points relate"}
     ],
     "coverageAssessment": "sufficient|partial|insufficient",
     "unresolvedSymptoms": ["Symptoms not fully explained by confirmed failure points"],

package/.claude/agents-en/work-planner.md

@@ -74,9 +74,9 @@ service-integration-e2e gap:
     Detected boundaries: [list crossings and AC references]
 ```
 
-"Was not communicated" means the upstream planning flow skipped test skeleton generation entirely — in that case the absence reason field is not passed to work-planner, so the gap check still runs. Per acceptance-test-generator's contract, when a skeleton was generated `e2eAbsenceReason.<lane>` is null; when generation ran but produced no skeleton, the reason is one of the strings enumerated in that contract — both cases mean the field WAS communicated, so no gap warning fires.
+"Was not communicated" means the upstream planning flow skipped test skeleton generation entirely — in that case the absence reason field is not provided, so the gap check still runs. Per the test-skeleton generation contract, when a skeleton was generated `e2eAbsenceReason.<lane>` is null; when generation ran but produced no skeleton, the reason is one of the strings enumerated in that contract — both cases mean the field WAS communicated, so no gap warning fires.
 
-When an `e2eAbsenceReason` for a lane carries a string value (e.g., `no_multi_step_journey`, `below_threshold_user_confirmed`, `no_real_service_dependency` — see acceptance-test-generator for the per-lane allowed values), absence in that lane is intentional — skip the gap check for that lane.
+When an `e2eAbsenceReason` for a lane carries a string value (e.g., `no_multi_step_journey`, `below_threshold_user_confirmed`, `no_real_service_dependency` — see the test-skeleton generation contract for the per-lane allowed values), absence in that lane is intentional — skip the gap check for that lane.
 
 This check applies regardless of whether Strategy A or B was selected. Integration-only skeletons being provided does not imply E2E coverage. Service-internal journeys (async pipelines, service-to-service sagas) are not flagged for the reserved-slot rule but may still warrant service-integration-e2e through the normal ROI path.
 
@@ -98,36 +98,38 @@ Map each extracted item to a covering task. Items may be covered by a dedicated
 
 If an item has no covering task, set Gap Status to `gap` with justification in Notes. **When the Traceability table contains any `gap` entry, the plan is in draft status.** Output the plan as draft, but do not finalize it until the user has confirmed each justified gap. Unjustified gaps (no Notes) are errors — add a covering task or provide justification before proceeding.
 
+**Carry binding observable values verbatim.** Identify binding observable values from the Design Doc directly, not from the Traceability table's summarized DD Item, so the exact column/label order and derived-display rules are not lost to a summary. A binding observable value is a column/label set and order (Contract Type `structure-order`), a derived-display rule — a display value derived from another field — (`derived-display`), or a state-lifecycle negative — a condition under which the state must stay unused — (`state-lifecycle-negative`). Copy each value **verbatim from the Design Doc** into the plan's **Reference Contract Values** table (see plan template), one row per value with its Contract Type token, mapped to the covering task(s). Preserve the full value, so the covering task is later checked against this exact value rather than a re-derived summary. This table covers DD-derived observable contracts only; serialized boundaries go in the Connection Map (step 5b) and ADR-derived structural decisions in the ADR Bindings table.
+
 ### 5a. Map UI Spec Components to Tasks (when UI Spec provided)
 
-When a UI Spec is among the inputs, also map components and states to the tasks that implement them. task-decomposer reads this mapping in a downstream step to populate each task's Investigation Targets, so without this step the UI Spec never reaches the executor.
+When a UI Spec is among the inputs, also map components and states to the tasks that implement them. This mapping is read in a downstream step to populate each task's Investigation Targets, so without it the UI Spec never reaches implementation.
 
 For each component documented in the UI Spec:
-1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key — see ui-spec-designer's heading uniqueness rule)
+1. Identify the component's section heading exactly as it appears in the UI Spec (the heading is the reference key, and headings are unique)
 2. Identify which states (default / loading / empty / error / partial) the implementation must cover
 3. Identify the task(s) in this plan that implement the component or its tests
 
 Record the mapping in the **UI Spec Component → Task Mapping** table (see plan template). One row per component. Components with no covering task are flagged as `gap` requiring user confirmation, identical to the Design-to-Plan Traceability rule.
 
-### 5b. Map Cross-Package Boundaries to Tasks (when implementation crosses runtime/deployment boundaries)
+### 5b. Map Boundaries to Tasks (when crossing a runtime/deployment boundary, or passing a serialized value across any boundary)
 
-When the implementation crosses a runtime or deployment boundary, build a Connection Map so task-decomposer can propagate boundary context to each affected task.
+Build a Connection Map when the implementation crosses a runtime or deployment boundary, **or when a value is serialized and re-parsed across any boundary (even within one runtime)**, so boundary context propagates to each affected task in the downstream step.
 
-**A boundary qualifies for the Connection Map only when ALL of the following hold**:
-- The two sides run in separate processes, services, or runtimes (e.g., web client ↔ HTTP server, service A ↔ service B over a network, frontend bundle ↔ backend handler)
-- A serialized contract crosses between them (HTTP request/response, message envelope, RPC call, event payload)
-- A failure on one side produces an observable signal on the other (status code, missing field, timeout, dropped message)
+**A boundary qualifies for the Connection Map when EITHER condition holds**:
+- *Cross-process*: the two sides run in separate processes, services, or runtimes (web client ↔ HTTP server, service A ↔ service B, frontend bundle ↔ backend handler); a serialized contract crosses between them (HTTP request/response, message envelope, RPC, event payload); and a failure on one side produces an observable signal on the other.
+- *Serialized in-runtime*: a value is encoded and re-parsed across a boundary even within a single runtime — through a medium such as a query string, CLI argument, environment variable, config entry, message/queue payload, storage key, or file (e.g., one component encodes a value another component or process later decodes; a value written to storage and read after a transition). Producer and consumer must agree on the exact representation.
 
 **Excluded — these are NOT boundaries for the Connection Map**:
-- A package importing a sibling utility, type definition, or shared constant from the same monorepo (in-process, no serialized contract)
-- Internal layering within the same runtime (e.g., handler → usecase → repository)
+- A package importing a sibling utility, type definition, or shared constant from the same monorepo (in-process, no serialized value)
+- Internal layering within the same runtime where values pass as typed in-memory calls (e.g., handler → usecase → repository)
 - Source code dependencies that compile/bundle into the same artifact
 
 For each qualifying boundary:
-1. Identify the boundary (e.g., `web → API gateway`, `service-A → service-B`, `frontend → shared client → backend handler`)
-2. Identify the owner module/package on each side
-3. Identify the expected signal that confirms the boundary works (e.g., HTTP 200 with schema X, message published to topic Y, row inserted in table Z)
-4. Identify the task(s) that implement either side of the boundary
+1. Identify the boundary (e.g., `service A → service B`, `producer → storage → consumer`, `component A → component B via an encoded parameter`)
+2. Identify the owner on each side (producer and consumer) and record it as concrete file path(s), not a bare module/package/component name, so it resolves as an Investigation Target downstream
+3. For a serialized boundary, record the **Serialized Format** (the exact representation the producer emits) and the **Consumer Parse Rule** (how the consumer decodes/validates it). Set both to "—" when the contract is already captured by the Expected Signal (e.g., a cross-process call whose body matches the agreed schema); fill them when producer and consumer must agree on a specific encoding of a value (query string, storage key, CLI argument, config entry, message field).
+4. Identify the expected signal that confirms the boundary works (e.g., a response matching the agreed schema; the consumer reproducing the producer's values)
+5. Identify the task(s) that implement either side of the boundary
 
 Record the mapping in the **Connection Map** table (see plan template). Omit this section entirely when no qualifying boundary exists.
 
@@ -162,8 +164,8 @@ For each task, derive completion criteria from Design Doc acceptance criteria. A
 ## Input Parameters
 
 - **mode**: `create` (default) | `update`
-- **scale**: `small` | `medium` | `large` (taken from requirement-analyzer; controls output mode — see "Output Mode by Scale" below)
-- **designDoc**: Path to Design Doc(s) (may be multiple for cross-layer features). At `scale: small` Design Doc may be absent; in that case derive the task directly from the requirement-analyzer output and PRD update notes.
+- **scale**: `small` | `medium` | `large` (taken from the requirements-analysis result; controls output mode — see "Output Mode by Scale" below)
+- **designDoc**: Path to Design Doc(s) (may be multiple for cross-layer features). At `scale: small` Design Doc may be absent; in that case derive the task directly from the requirements-analysis output and PRD update notes.
 - **uiSpec** (optional): Path to UI Specification (frontend/fullstack features)
 - **prd** (optional): Path to PRD document
 - **adr** (optional): Path to ADR document
@@ -174,8 +176,8 @@ For each task, derive completion criteria from Design Doc acceptance criteria. A
 
 | scale | Output | Path | Rationale |
 |---|---|---|---|
-| `small` | A single task file in **task-template format** (per documentation-criteria skill) | `docs/plans/tasks/{feature-name}-task-YYYYMMDD.md` | At 1-2 files there is no separate decomposition step; the task file the orchestrator passes to task-executor as `task_file` is produced directly here. |
-| `medium` / `large` | A work plan in **plan-template format** | `docs/plans/{feature-name}-plan.md` | Decomposition into individual task files is performed by task-decomposer in a downstream step. |
+| `small` | A single task file in **task-template format** (per documentation-criteria skill) | `docs/plans/tasks/{feature-name}-task-YYYYMMDD.md` | At 1-2 files there is no separate decomposition step; the task file passed to the execution step as `task_file` is produced directly here. |
+| `medium` / `large` | A work plan in **plan-template format** | `docs/plans/{feature-name}-plan.md` | Decomposition into individual task files is performed in a downstream step. |
 
 In `small` mode, skip the multi-phase composition (Step 4) and the Design-to-Plan Traceability mapping (Step 5); produce the task file with `## Target Files`, `## Investigation Targets`, `## Investigation Notes`, `## Implementation Steps (TDD: Red-Green-Refactor)`, `## Quality Assurance Mechanisms`, `## Operation Verification Methods`, and `## Completion Criteria` sections, plus the `Metadata:` block (`Dependencies:`, `Provides:`, `Size:`). Do not output a separate work plan file at this scale.
 
@@ -352,11 +354,14 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
 - [ ] Design-to-Plan Traceability table complete (all DD technical requirements categorized and mapped)
   - [ ] No `gap` entries without justification
   - [ ] All justified `gap` entries flagged for user confirmation before plan approval
+- [ ] Reference Contract Values table complete (when the Design Doc specifies binding observable values: column/label order, derived-display, state-lifecycle negative)
+  - [ ] Each value copied verbatim from the Design Doc, preserving full wording, and mapped to a covering task
 - [ ] UI Spec Component → Task Mapping table complete (when UI Spec provided)
   - [ ] Every UI Spec component has a covering task, OR an explicit `gap` justification
   - [ ] Component reference uses the UI Spec section heading exactly as it appears in the document
-- [ ] Connection Map table complete (when implementation crosses packages/services)
-  - [ ] Every boundary lists owner modules and expected signal
+- [ ] Connection Map table complete (when crossing packages/services, or passing a serialized value across any boundary)
+  - [ ] Every boundary lists owner file path(s) and expected signal
+  - [ ] Serialized boundaries record Serialized Format and Consumer Parse Rule
   - [ ] Every boundary maps to at least one covering task on each side
 - [ ] ADR Bindings table complete (when ADR provided or referenced from Design Doc)
   - [ ] Each row represents one implementation-binding decision (placement, dependency, contract, data flow, or persistence)