create-ai-project 1.20.9 → 1.21.0

package/.claude/agents-en/acceptance-test-generator.md

@@ -71,7 +71,7 @@ For each valid AC from Phase 1:
 
 2. **Classify test level**:
    - Integration test candidate (feature-level interaction)
-   - E2E test candidate (user journey)
+   - E2E test candidate — lane is assigned in Phase 3 (`fixture-e2e` for UI journeys verifiable with mocks; `service-integration-e2e` when real cross-service behavior must be asserted)
    - Property-based test candidate (AC with Property annotation → placed in integration test file)
 
 3. **Annotate metadata**:
@@ -97,12 +97,18 @@ For each valid AC from Phase 1:
 3. **Push-Down Analysis**:
    ```
    Can this be unit-tested? → Remove from integration/E2E pool
-   Already integration-tested? → Keep as E2E candidate IF part of multi-step user journey (see definition in integration-e2e-testing skill)
-   Already integration-tested AND NOT part of multi-step journey? → Remove from E2E pool
+   Already integration-tested AND verifiable in-process? → Remove from E2E pool
    ```
-4. **Sort by ROI** (descending order)
+4. **Lane assignment** (E2E candidates only):
+   - Default to `fixture-e2e` for any UI journey verifiable with mocked backend / fixture-driven state
+   - Promote to `service-integration-e2e` only when the verification depends on real cross-service behavior. A candidate qualifies for `service-integration-e2e` when ANY of the following must be asserted:
+     - Data persists across a real DB write (e.g., row inserted/updated in the actual database under test)
+     - A downstream service receives a real event/message (e.g., topic publish, queue enqueue, webhook call)
+     - An external service receives a real API call with the expected payload
+     - Transactional consistency across services (e.g., two-phase commit, saga compensation)
+5. **Sort by ROI** within each lane (descending) — this is the single ranking step; Phase 4 budget enforcement consumes this ranked list directly without re-sorting.
 
-**Output**: Ranked, deduplicated candidate list
+**Output**: Ranked, deduplicated candidate list with lane assigned per E2E candidate.
 
 ### Phase 4: Over-Generation Prevention
 
@@ -110,28 +116,36 @@ For each valid AC from Phase 1:
 
 **Hard Limits per Feature**:
 - **Integration Tests**: MAX 3 tests
-- **E2E Tests**: MAX 1-2 tests total, composed of:
-  - 1 reserved slot (emitted regardless of ROI) when feature contains a **user-facing** multi-step user journey (see definition and classification in integration-e2e-testing skill)
+- **fixture-e2e**: MAX 3 tests. The reserved slot (highest-ROI journey candidate when the feature contains a **user-facing** multi-step user journey — see definition in integration-e2e-testing skill) is emitted regardless of ROI. Additional slots beyond the reserved slot require ROI ≥ 20 (floor below which slots are intentionally left unfilled)
+- **service-integration-e2e**: MAX 1-2 tests total, composed of:
+  - 1 reserved slot (emitted regardless of ROI) when the journey's correctness depends on real cross-service behavior that fixture-e2e cannot verify
   - Up to 1 additional slot requiring ROI > 50
 
 **Selection Algorithm**:
 
 ```
-1. Reserve must-keep E2E slot:
-   IF feature contains user-facing multi-step user journey (see definition in integration-e2e-testing skill)
-   THEN reserve 1 E2E slot for the highest-ROI journey candidate
-   (This reserved candidate is emitted regardless of ROI threshold)
-
-2. Sort remaining candidates by ROI (descending)
-
-3. Select all property-based tests (excluded from budget calculation)
-
-4. Select top N within budget:
+1. Reserve fixture-e2e slot:
+   IF feature contains user-facing multi-step user journey
+   THEN reserve 1 fixture-e2e slot for the highest-ROI journey candidate
+
+2. Reserve service-integration-e2e slot (only if needed):
+   IF the reserved journey's verification requires ANY of:
+     - data persists across a real DB write
+     - downstream service receives a real event/message
+     - external service receives a real API call with expected payload
+     - transactional consistency across services
+   THEN reserve 1 service-integration-e2e slot for that journey
+
+3. Walk the candidate list (already sorted by ROI within each lane in Phase 3 step 5)
+   and select within budget:
    - Integration: Pick top 3 highest-ROI
-   - E2E (additional beyond reserved): Pick up to 1 more IF ROI score > 50
+   - fixture-e2e (additional beyond reserved): Pick up to remaining budget IF ROI ≥ 20
+   - service-integration-e2e (additional beyond reserved): Pick up to 1 more IF ROI > 50
+
+4. Select all property-based tests (excluded from budget calculation; this step is order-independent — it can be performed at any point in this algorithm without affecting reserved-slot or ROI-based selection in steps 1-3)
 ```
 
-**Output**: Final test set
+**Output**: Final test set with each E2E candidate assigned to a lane.
 
 ## Output Format
 
@@ -147,7 +161,7 @@ The examples below use `//` comment syntax. Adapt to the project's language (e.g
 
 ```typescript
 // [Feature Name] Integration Test - Design Doc: [filename]
-// Generated: [date] | Budget Used: 2/3 integration, 0/2 E2E
+// Generated: [date] | Budget Used: 2/3 integration, 0/3 fixture-e2e, 0/2 service-integration-e2e
 
 import { describe, it } from '[detected test framework]'
 
@@ -170,24 +184,49 @@ describe('[Feature Name] Integration Test', () => {
 })
 ```
 
-### E2E Test File
+### E2E Test Files
+
+Generate **separate files per lane**: `*.fixture-e2e.test.[ext]` for fixture-e2e, `*.service-e2e.test.[ext]` for service-integration-e2e. Each emitted file MUST carry a `@lane:` header so downstream agents (work-planner, task-decomposer, executor) can route correctly.
+
+**fixture-e2e example** (UI journey with mocked backend, runs in CI without infrastructure):
 
 ```typescript
-// [Feature Name] E2E Test - Design Doc: [filename]
-// Generated: [date] | Budget Used: 1/2 E2E
-// Test Type: End-to-End Test
-// Implementation Timing: After all feature implementations complete
+// [Feature Name] fixture-e2e - Design Doc: [filename]
+// Generated: [date] | Budget Used: 1/3 fixture-e2e
+// @lane: fixture-e2e
 
 import { describe, it } from '[detected test framework]'
 
-describe('[Feature Name] E2E Test', () => {
-  // User Journey: Complete purchase flow (browse → add to cart → checkout → payment → confirmation)
-  // ROI: 119 (BV:10 × Freq:10 + Legal:10 + Defect:9) | reserved slot: multi-step journey
-  // Verification: End-to-end user experience from product selection to order confirmation
+describe('[Feature Name] fixture-e2e', () => {
+  // User Journey: Cart → checkout → confirmation with mocked payment backend
+  // ROI: 64 | reserved slot: multi-step journey
+  // Verification: UI transitions and observable state after each step (mocks return canned responses)
   // @category: e2e
+  // @lane: fixture-e2e
+  // @dependency: full-ui (mocked backend)
+  // @complexity: medium
+  it.todo('User Journey: Cart-to-confirmation flow with mocked payment')
+})
+```
+
+**service-integration-e2e example** (against running local stack, final phase only):
+
+```typescript
+// [Feature Name] service-integration-e2e - Design Doc: [filename]
+// Generated: [date] | Budget Used: 1/2 service-integration-e2e
+// @lane: service-integration-e2e
+
+import { describe, it } from '[detected test framework]'
+
+describe('[Feature Name] service-integration-e2e', () => {
+  // User Journey: Complete purchase asserting real DB persistence and downstream event publish
+  // ROI: 119 | reserved slot: real cross-service behavior required
+  // Verification: Order row inserted in DB; OrderCreated event published; receipt email enqueued
+  // @category: e2e
+  // @lane: service-integration-e2e
   // @dependency: full-system
   // @complexity: high
-  it.todo('User Journey: Complete product purchase from browse to confirmation email')
+  it.todo('User Journey: Complete purchase persists order and publishes downstream event')
 })
 ```
 
@@ -208,49 +247,71 @@ it.todo('[AC#]-property: [invariant in natural language]')
 
 Upon completion, report in the following JSON format. Detailed meta information is included in comments within test skeleton files, extracted by downstream processes reading the files.
 
-**When E2E tests are emitted:**
+**When all lanes emit:**
 ```json
 {
   "status": "completed",
   "feature": "payment",
   "generatedFiles": {
     "integration": "tests/payment.int.test.[ext]",
-    "e2e": "tests/payment.e2e.test.[ext]"
+    "fixtureE2e": "tests/payment.fixture-e2e.test.[ext]",
+    "serviceE2e": "tests/payment.service-e2e.test.[ext]"
+  },
+  "budgetUsage": {
+    "integration": "2/3",
+    "fixtureE2e": "1/3",
+    "serviceE2e": "1/2"
   },
-  "budgetUsage": { "integration": "2/3", "e2e": "1/2" },
-  "e2eAbsenceReason": null
+  "e2eAbsenceReason": { "fixtureE2e": null, "serviceE2e": null }
 }
 ```
 
-**When no E2E tests are emitted:**
+**When only fixture-e2e emits (no real cross-service dependency):**
 ```json
 {
   "status": "completed",
-  "feature": "payment",
+  "feature": "checkout-ui",
   "generatedFiles": {
-    "integration": "tests/payment.int.test.[ext]",
-    "e2e": null
+    "integration": "tests/checkout.int.test.[ext]",
+    "fixtureE2e": "tests/checkout.fixture-e2e.test.[ext]",
+    "serviceE2e": null
+  },
+  "budgetUsage": {
+    "integration": "1/3",
+    "fixtureE2e": "1/3",
+    "serviceE2e": "0/2"
   },
-  "budgetUsage": { "integration": "2/3", "e2e": "0/2" },
-  "e2eAbsenceReason": "no_multi_step_journey"
+  "e2eAbsenceReason": { "fixtureE2e": null, "serviceE2e": "no_real_service_dependency" }
 }
 ```
 
-**When no integration tests are emitted:**
+**When no E2E lane qualifies:**
 ```json
 {
   "status": "completed",
   "feature": "config-update",
   "generatedFiles": {
-    "integration": null,
-    "e2e": null
+    "integration": "tests/config.int.test.[ext]",
+    "fixtureE2e": null,
+    "serviceE2e": null
+  },
+  "budgetUsage": {
+    "integration": "1/3",
+    "fixtureE2e": "0/3",
+    "serviceE2e": "0/2"
   },
-  "budgetUsage": { "integration": "0/3", "e2e": "0/2" },
-  "e2eAbsenceReason": "no_multi_step_journey"
+  "e2eAbsenceReason": { "fixtureE2e": "no_multi_step_journey", "serviceE2e": "no_multi_step_journey" }
 }
 ```
 
-**Contract**: Both `generatedFiles.integration` and `generatedFiles.e2e` are always present as keys. Value is a file path string when generated, `null` when not generated. `e2eAbsenceReason` is `null` when E2E was emitted, otherwise one of: `no_multi_step_journey`, `below_threshold_user_confirmed`.
+**Contract**: `generatedFiles.{integration,fixtureE2e,serviceE2e}` are always present as keys. Each value is a file path string when emitted, `null` when not emitted. `e2eAbsenceReason` is an object with `fixtureE2e` and `serviceE2e` keys; per-lane allowed values:
+
+| Lane | Allowed values |
+|------|---------------|
+| `e2eAbsenceReason.fixtureE2e` | `null` (lane emitted) \| `no_multi_step_journey` \| `below_threshold_user_confirmed` |
+| `e2eAbsenceReason.serviceE2e` | `null` (lane emitted) \| `no_multi_step_journey` \| `below_threshold_user_confirmed` \| `no_real_service_dependency` |
+
+`no_real_service_dependency` is service-lane-only — it indicates that the journey is fully verifiable via fixture-e2e, so no service-integration-e2e was warranted. Fixture-lane never emits this reason.
 
 ## Constraints and Quality Standards
 
@@ -262,7 +323,7 @@ Upon completion, report in the following JSON format. Detailed meta information
 - Stay within budget; report to user if budget insufficient for critical tests
 
 **Quality Standards**:
-- Select tests by ROI ranking within budget (integration: top 3 by ROI; E2E: reserved slot for user-facing journeys + additional by ROI > 50)
+- Select tests by ROI ranking within budget (integration: top 3 by ROI; fixture-e2e: reserved journey slot + up to remaining budget by ROI ≥ 20; service-integration-e2e: reserved slot when real cross-service behavior is required + up to 1 more by ROI > 50)
 - Apply behavior-first filtering STRICTLY
 - Eliminate duplicate coverage (use Grep to check existing tests BEFORE generating)
 - Clarify dependencies EXPLICITLY
@@ -273,12 +334,13 @@ Upon completion, report in the following JSON format. Detailed meta information
 ### Auto-processable
 - **Directory Absent**: Auto-create appropriate directory following detected test structure
 - **No High-ROI Integration Tests**: Valid outcome - report "All ACs below ROI threshold or covered by existing tests"
-- **No E2E Tests (no multi-step journey)**: Valid outcome - report "No multi-step user journey detected; E2E tests not applicable"
+- **No E2E Tests in either lane (no multi-step journey)**: Valid outcome - report "No multi-step user journey detected; fixture-e2e and service-integration-e2e not applicable"
+- **fixture-e2e emitted but no service-integration-e2e (no real cross-service dependency)**: Valid outcome - report "Journey verifiable end-to-end against mocked backend; service-integration-e2e absence reason `no_real_service_dependency`"
 - **Budget Exceeded by Critical Test**: Report to user
 
 ### Escalation Required
 1. **Critical**: AC absent, Design Doc absent → Error termination
-2. **High**: No E2E test emitted after budget enforcement, but feature contains user-facing multi-step user journey → Escalate with message: "Feature includes user-facing multi-step journey but no E2E test was emitted. Journey candidates evaluated: [list with ROI scores]. Confirm whether to proceed without E2E." (Note: this escalation fires only when the reserved slot in Phase 4 did not apply — e.g., no journey candidate passed Phase 1-3 filtering. When a reserved slot candidate exists, it is emitted and this escalation does not fire.)
+2. **High**: No E2E test emitted in any lane after budget enforcement, but feature contains user-facing multi-step user journey → Escalate per lane with message: "Feature includes user-facing multi-step journey but neither fixture-e2e nor service-integration-e2e was emitted. Journey candidates evaluated per lane: [list with ROI scores per lane]. Confirm whether to proceed without E2E coverage." (Note: this escalation fires only when the reserved slots in Phase 4 did not apply — e.g., no journey candidate passed Phase 1-3 filtering. When a reserved slot candidate exists in either lane, it is emitted and this escalation does not fire for that lane.)
 3. **High**: All ACs filtered out but feature is business-critical → User confirmation needed
 4. **Medium**: Budget insufficient for critical user journey (ROI > 90) → Present options
 5. **Low**: Multiple interpretations possible but minor impact → Adopt interpretation + note in report
@@ -308,5 +370,5 @@ Upon completion, report in the following JSON format. Detailed meta information
 - **Post-execution**:
   - Completeness of selected tests
   - Dependency validity verified
-  - Integration tests and E2E tests generated in separate files
+  - Integration, fixture-e2e, and service-integration-e2e tests generated in separate files (each E2E file carries `@lane:` header)
   - Generation report completeness

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

@@ -77,10 +77,18 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Document design intent and important notes
 
 4. **Task File Generation**
-   - Naming convention: `{plan-name}-task-{number}.md`
-   - Layer-aware naming (when the plan spans multiple layers): `{plan-name}-backend-task-{number}.md`, `{plan-name}-frontend-task-{number}.md`
-   - Layer is determined from the task's Target files paths (refer to project structure defined in technical-spec skill)
-   - Examples: `20250122-refactor-types-task-01.md`, `20250122-auth-backend-task-01.md`, `20250122-auth-frontend-task-02.md`
+
+   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.
+
+   | 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 |
+
+   Layer is determined from the task's Target files paths (refer to project structure defined in technical-spec skill).
+
+   Examples: `20250122-refactor-types-task-01.md` (backend single-layer), `20250122-dashboard-frontend-task-01.md` (frontend single-layer), `20250122-auth-backend-task-01.md` + `20250122-auth-frontend-task-02.md` (multi-layer).
    - **Phase Completion Task Auto-generation (Required)**:
      - Based on "Phase X" notation in work plan, generate after each phase's final task
      - Filename: `{plan-name}-phase{number}-completion.md`
@@ -105,8 +113,11 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    |---|---|
    | Existing code modification | The existing implementation files being modified, their tests, related Design Doc sections |
    | New component/feature | Adjacent implementations in the same layer/domain, Design Doc interface contracts |
+   | Frontend component implementation | UI Spec component section (use the section heading the work plan's UI Spec Component → Task Mapping cites), Design Doc interface contracts, adjacent components in the same layer |
+   | 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 |
    | 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 |
 
@@ -116,6 +127,8 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Be specific with file paths: `src/orders/checkout`, `docs/design/payment.md` — not "the order module" or "related code"
    - When the target is a section within a file, write the file path and add a search hint: `docs/design/payment.md (§ Payment Flow)` or `src/orders/checkout (processOrder function)`
    - When test skeletons exist for the task, always include them as Investigation Targets
+   - When the work plan contains a UI Spec Component → Task Mapping table, propagate the matching component section to every task in that row (see UI Spec Propagation below)
+   - When the work plan contains a Connection Map, propagate the boundary rows touching this task's target files (see Connection Map Propagation below)
 
 7. **Implementation Pattern Consistency**
    When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan
@@ -136,6 +149,29 @@ When the work plan includes a Verification Strategy, derive each task's Operatio
    - **Verification level**: Select L1/L2/L3 per implementation-approach skill
 3. **Investigation Targets**: Include resources needed for verification (e.g., existing implementation for comparison, schema definitions, seed data paths)
 
+## UI Spec Propagation
+
+When the work plan contains a UI Spec Component → Task Mapping table, propagate component references to each implementation task as follows:
+
+1. **Lookup by task ID**: For each row in the mapping table, locate the task(s) listed in the "Covered By Task(s)" column
+2. **Append a single line to Investigation Targets**: Add one line per matched component in the task's Investigation Targets section. The line format is `[ui-spec path] (§ [component heading]<state hint>)`, where `<state hint>` is appended only when the row lists specific states.
+
+   - When no states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard)`
+   - When states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard — verify default + loading + error states)`
+
+   This is the entire entry — do not also add a separate parenthetical line. The state hint is part of the same line.
+3. **One row → one or more tasks**: A component can be split across multiple tasks; propagate the same line to each
+4. **Skip when not provided**: If the work plan has no UI Spec Component → Task Mapping table, skip this propagation step
+
+## Connection Map Propagation
+
+When the work plan contains a Connection Map table, propagate boundary context to each implementation task as follows:
+
+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
+4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step
+
 ## Quality Assurance Mechanism Propagation
 
 When the work plan header includes a Quality Assurance Mechanisms table, propagate mechanisms to each task as follows:

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

@@ -103,6 +103,8 @@ 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.
+  - **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/work-planner.md

@@ -44,22 +44,38 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati
 - Final phase is always Quality Assurance
 
 **E2E Gap Check (all strategies)**:
-After determining which test skeletons are available, check whether E2E skeletons are absent. A multi-step user journey exists when: (1) 2+ distinct interaction boundaries are traversed in sequence, (2) state carries across steps, and (3) the journey has a completion point. A journey is **user-facing** when a human user directly triggers and observes the steps (via UI, CLI, or direct API interaction), as opposed to service-internal pipelines.
+After determining which test skeletons are available, check the two E2E lanes (fixture-e2e, service-integration-e2e — see integration-e2e-testing skill) independently. A multi-step user journey exists when: (1) 2+ distinct interaction boundaries are traversed in sequence, (2) state carries across steps, and (3) the journey has a completion point. A journey is **user-facing** when a human user directly triggers and observes the steps (via UI, CLI, or direct API interaction), as opposed to service-internal pipelines.
 
 ```
-IF no E2E test skeleton files were provided
-  AND no e2eAbsenceReason was communicated from upstream
-  AND Design Doc or UI Spec contains user-facing multi-step user journey
-THEN add to work plan header:
-  ⚠ E2E Gap: This feature contains user-facing multi-step journey(s) but no E2E
-  test skeletons were provided. Route this feature back through acceptance-test
-  generation to evaluate E2E test candidates before final phase.
-  Detected journeys: [list journey descriptions and AC references]
+fixture-e2e gap:
+  IF no fixture-e2e skeleton was provided
+    AND e2eAbsenceReason.fixtureE2e was not communicated
+    AND Design Doc or UI Spec contains user-facing multi-step user journey
+  THEN add to work plan header:
+    ⚠ fixture-e2e Gap: This feature contains user-facing multi-step journey(s)
+    but no fixture-e2e skeleton was provided. Route this feature back through
+    acceptance-test generation to evaluate fixture-e2e candidates before the
+    UI implementation phase.
+    Detected journeys: [list journey descriptions and AC references]
+
+service-integration-e2e gap:
+  IF no service-integration-e2e skeleton was provided
+    AND e2eAbsenceReason.serviceE2e was not communicated
+    AND Design Doc indicates the journey requires real cross-service
+        verification (data persistence across services, transactional
+        consistency, external service contract)
+  THEN add to work plan header:
+    ⚠ service-integration-e2e Gap: This feature crosses service boundaries
+    where correctness depends on real cross-service behavior, but no
+    service-integration-e2e skeleton was provided.
+    Detected boundaries: [list crossings and AC references]
 ```
 
-When an `e2eAbsenceReason` is provided (from the acceptance-test Generation Report, e.g., `no_multi_step_journey`, `below_threshold_user_confirmed`), E2E absence is intentional — skip this gap check.
+"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.
 
-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 here — they may still warrant E2E through the normal ROI path.
+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.
+
+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.
 
 **Phase structure**: Select based on implementation approach from Design Doc. See Phase Division Criteria in documentation-criteria skill for detailed definitions. Use plan-template Option A (Vertical) or Option B (Horizontal) accordingly. For hybrid, use Option A as the base and add horizontal foundation phases where needed.
 
@@ -79,6 +95,39 @@ 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.
 
+### 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.
+
+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)
+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)
+
+When the implementation crosses a runtime or deployment boundary, build a Connection Map so task-decomposer can propagate boundary context to each affected task.
+
+**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)
+
+**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)
+- 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
+
+Record the mapping in the **Connection Map** table (see plan template). Omit this section entirely when no qualifying boundary exists.
+
 ### 6. Define Tasks with Completion Criteria
 For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete).
 
@@ -87,6 +136,8 @@ For each task, derive completion criteria from Design Doc acceptance criteria. A
 - **`scale: medium` / `scale: large`**: Write a work plan following the **plan-template** from documentation-criteria skill. Include Phase Structure Diagram and Task Dependency Diagram (mermaid).
 - **`scale: small`**: Write a single task file following the **task-template** from documentation-criteria skill (see "Output Mode by Scale" below). Skip Phase Structure / Task Dependency diagrams; the task file's `## Implementation Steps` section drives execution.
 
+For `scale: medium` / `scale: large`, the plan header MUST include the line `Implementation Readiness: pending`. The marker contract: it takes one of three values — `pending` (initial, set here by work-planner), `ready` (verification completed with no remaining gaps), or `escalated` (verification completed with remaining gaps). The producer that promotes the marker beyond `pending` and the consumer that reads it before execution are external orchestration concerns owned outside this agent.
+
 ## Input Parameters
 
 - **mode**: `create` (default) | `update`
@@ -144,10 +195,11 @@ Include completion conditions in task names (e.g., "Service implementation and u
 #### Phase 0: Test Preparation (Unit Tests Only)
 Create Red state tests based on unit test definitions provided from previous process.
 
-**Test Implementation Timing**:
+**Test Implementation Timing and Placement**:
 - Unit tests: Phase 0 Red → Green during implementation
-- Integration tests: Create and execute at completion of implementation (Red-Green-Refactor not applied)
-- E2E tests: Execute only in final phase (Red-Green-Refactor not applied)
+- Integration tests: Create and execute at completion of relevant feature implementation (include in phase tasks like "[Feature name] implementation with integration test creation")
+- fixture-e2e tests: Create and execute alongside the UI feature phase (include in phase tasks like "[Feature name] UI implementation with fixture-e2e creation"). These run in CI without infrastructure setup.
+- service-integration-e2e tests: Execute only in the final phase (these depend on local stack and tend to be too slow/heavy for per-task cycles)
 
 #### Meta Information Utilization
 Analyze meta information (@category, @dependency, @complexity, etc.) included in test definitions,
@@ -193,22 +245,29 @@ Read test skeleton files (integration tests, E2E tests) with the Read tool and e
 
 #### Step 3: Extract Environment Prerequisites from E2E Skeletons
 
-When E2E test skeletons are provided, scan for environment prerequisites in two stages:
+When E2E test skeletons are provided, scan for environment prerequisites in two stages. Apply the lane-aware rules below — fixture-e2e and service-integration-e2e have very different prerequisite shapes.
 
-**Stage 1: Detect precondition patterns** — scan all E2E skeletons and list every detected precondition:
-- `Preconditions:` or `Arrange:` comment annotations mentioning seed data, test users, subscriptions, or specific DB state
-- `@dependency: full-system` combined with auth/login setup code
+**Stage 1: Detect precondition patterns** — scan each E2E skeleton (read its `@lane` header to know which lane applies) and list every detected precondition:
+- `Preconditions:` or `Arrange:` comment annotations mentioning seed data, test users, fixtures, or specific UI/DB state
+- `@dependency: full-ui (mocked backend)` combined with fixture loaders or API mock handlers (MSW route handlers — fixture-e2e)
+- `@dependency: full-system` combined with auth/login setup code (service-integration-e2e)
 - References to environment variables (`E2E_*`, `TEST_*`)
-- External service references requiring HTTP mock/intercept patterns in test code
+- External service references requiring HTTP mock/intercept patterns
+
+**Stage 2: Generate setup tasks** — for each detected precondition, create a corresponding Phase 0 task. Common categories by lane:
+
+For **fixture-e2e**:
+- **Fixture data** → "Create fixture data files for [feature] UI states"
+- **Mock backend** → "Configure MSW handlers for fixture-e2e (browser-runtime mocks for the project's API surface)"
+- **Browser harness** → "Set up the Playwright harness for fixture-e2e (no live services required)"
 
-**Stage 2: Generate setup tasks** — for each detected precondition, create a corresponding Phase 0 task. Common categories include:
-- **Seed data** → "Create E2E seed data script (test users, required records)"
-- **Auth fixture** → "Implement E2E auth fixture using application's login flow"
-- **External service mocks** → "Configure external service mocks for E2E tests"
-- **Environment configuration** → "Define E2E environment variables and document setup"
-- **Other detected preconditions** → Create a setup task matching the detected category
+For **service-integration-e2e**:
+- **Seed data** → "Create seed data script for service-integration-e2e (test users, required records)"
+- **Auth fixture** → "Implement auth fixture using application's login flow"
+- **External service stubs** → "Configure external service stubs for service-integration-e2e"
+- **Environment configuration** → "Define service-integration-e2e environment variables and document local startup"
 
-Place all environment setup tasks in Phase 0 (before any implementation tasks). Mark with `@category: e2e-setup` for traceability.
+Place all environment setup tasks in Phase 0 (before any implementation tasks). Mark with `@category: e2e-setup` and `@lane:` matching the target lane for traceability.
 
 #### Step 4: Structure Analysis and Classification of it.todo
 
@@ -216,7 +275,8 @@ Place all environment setup tasks in Phase 0 (before any implementation tasks).
    - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1
    - Unit tests (individual functions) → Start from Phase 0 with Red-Green-Refactor
    - Integration tests → Place as create/execute tasks when relevant feature implementation is complete
-   - E2E tests → Place as execute-only tasks in final phase
+   - fixture-e2e tests → Place as create/execute tasks alongside the relevant UI feature implementation
+   - service-integration-e2e tests → Place as execute-only tasks in final phase
    - Non-functional requirement tests (performance, UX, etc.) → Place in quality assurance phase
    - Risk levels ("high risk", "required", etc.) → Move to earlier phases
 
@@ -238,7 +298,8 @@ Place all environment setup tasks in Phase 0 (before any implementation tasks).
 ### Test Placement Principles
 **Phase Placement Rules**:
 - Integration tests: Include in relevant phase tasks like "[Feature name] implementation with integration test creation"
-- E2E tests: Place "E2E test execution" in final phase (implementation not needed, execution only)
+- fixture-e2e tests: Include alongside the UI feature phase (creation + execution in CI-friendly browser harness)
+- service-integration-e2e tests: Place "service-integration-e2e execution" in final phase (implementation not needed, execution only against the local stack)
 
 ### Implementation Approach Application
 Decompose tasks based on implementation approach and technical dependencies decided in Design Doc, following verification levels (L1/L2/L3) from implementation-approach skill.
@@ -270,6 +331,13 @@ 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
+- [ ] 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
+  - [ ] Every boundary maps to at least one covering task on each side
+- [ ] Plan header includes `Implementation Readiness: pending` (medium / large only)
 - [ ] Verification Strategy extracted from Design Doc and included in plan header
 - [ ] Adopted Quality Assurance Mechanisms extracted from Design Doc and included in plan header
 - [ ] Phase structure matches implementation approach (vertical → value unit phases, horizontal → layer phases)
@@ -278,7 +346,8 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
 - [ ] Quality assurance exists in final phase
 - [ ] Test skeleton file paths listed in corresponding phases (when provided)
 - [ ] E2E environment prerequisites addressed (when E2E skeletons provided)
-  - [ ] Seed data, auth fixture, and external service mock tasks generated
+  - [ ] fixture-e2e prerequisites: fixture data, mocked backend, browser harness tasks generated when applicable
+  - [ ] service-integration-e2e prerequisites: seed data, auth fixture, external service stub tasks generated when applicable
   - [ ] Environment setup tasks placed in Phase 0
 - [ ] Test design information reflected (only when provided)
   - [ ] Setup tasks placed in first phase