create-ai-project 1.20.4 → 1.20.6

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

@@ -99,7 +99,8 @@ For each valid AC from Phase 1:
 3. **Push-Down Analysis**:
    ```
    Can this be unit-tested? → Remove from integration/E2E pool
-   Already integration-tested? → Don't create E2E version
+   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
    ```
 4. **Sort by ROI** (descending order)
 
@@ -109,14 +110,27 @@ For each valid AC from Phase 1:
 
 **Apply integration-e2e-testing skill "Test Types and Limits"**
 
+**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)
+  - Up to 1 additional slot requiring ROI > 50
+
 **Selection Algorithm**:
 
 ```
-1. Sort candidates by ROI (descending)
-2. Select all property-based tests (excluded from budget calculation)
-3. Select top N within budget:
+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:
    - Integration: Pick top 3 highest-ROI
-   - E2E: Pick top 1-2 IF ROI score > 50
+   - E2E (additional beyond reserved): Pick up to 1 more IF ROI score > 50
 ```
 
 **Output**: Final test set
@@ -136,17 +150,17 @@ The examples below use `//` comment syntax. Adapt to the project's language (e.g
 import { describe, it } from '[detected test framework]'
 
 describe('[Feature Name] Integration Test', () => {
-  // AC: "After successful payment, order is created and persisted"
-  // ROI: 85 | Business Value: 10 | Frequency: 9
-  // Behavior: User completes payment → Order created in DB → Payment recorded
+  // AC1: "After successful payment, order is created and persisted"
+  // ROI: 98 (BV:10 × Freq:9 + Legal:0 + Defect:8)
+  // Behavior: User completes payment → Order created in DB + Payment recorded
   // @category: core-functionality
   // @dependency: PaymentService, OrderRepository, Database
   // @complexity: high
   it.todo('AC1: Successful payment creates persisted order with correct status')
 
-  // AC: "Payment failure shows user-friendly error message"
-  // ROI: 72 | Business Value: 8 | Frequency: 2
-  // Behavior: Payment fails → User sees actionable error → Order not created
+  // AC1-error: "Payment failure shows user-friendly error message"
+  // ROI: 23 (BV:8 × Freq:2 + Legal:0 + Defect:7)
+  // Behavior: Payment fails → User sees actionable error + Order not created
   // @category: core-functionality
   // @dependency: PaymentService, ErrorHandler
   // @complexity: medium
@@ -166,8 +180,8 @@ 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: 95 | Business Value: 10 | Frequency: 10 | Legal: true
-  // Behavior: Product selection → Add to cart → Payment complete → Order confirmation screen displayed
+  // 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
   // @category: e2e
   // @dependency: full-system
   // @complexity: high
@@ -192,21 +206,50 @@ 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:**
 ```json
 {
   "status": "completed",
-  "feature": "[feature name]",
+  "feature": "payment",
   "generatedFiles": {
-    "integration": "[path]/[feature].int.test.ts",
-    "e2e": "[path]/[feature].e2e.test.ts"
+    "integration": "tests/payment.int.test.[ext]",
+    "e2e": "tests/payment.e2e.test.[ext]"
   },
-  "testCounts": {
-    "integration": 2,
-    "e2e": 1
-  }
+  "budgetUsage": { "integration": "2/3", "e2e": "1/2" },
+  "e2eAbsenceReason": null
 }
 ```
 
+**When no E2E tests are emitted:**
+```json
+{
+  "status": "completed",
+  "feature": "payment",
+  "generatedFiles": {
+    "integration": "tests/payment.int.test.[ext]",
+    "e2e": null
+  },
+  "budgetUsage": { "integration": "2/3", "e2e": "0/2" },
+  "e2eAbsenceReason": "no_multi_step_journey"
+}
+```
+
+**When no integration tests are emitted:**
+```json
+{
+  "status": "completed",
+  "feature": "config-update",
+  "generatedFiles": {
+    "integration": null,
+    "e2e": null
+  },
+  "budgetUsage": { "integration": "0/3", "e2e": "0/2" },
+  "e2eAbsenceReason": "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`.
+
 ## Constraints and Quality Standards
 
 **Required Compliance**:
@@ -217,7 +260,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**:
-- Generate tests for high-ROI ACs ONLY
+- Select tests by ROI ranking within budget (integration: top 3 by ROI; E2E: reserved slot for user-facing journeys + additional by ROI > 50)
 - Apply behavior-first filtering STRICTLY
 - Eliminate duplicate coverage (use Grep to check existing tests BEFORE generating)
 - Clarify dependencies EXPLICITLY
@@ -227,14 +270,16 @@ 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 Tests**: Valid outcome - report "All ACs below ROI threshold or covered by existing tests"
+- **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"
 - **Budget Exceeded by Critical Test**: Report to user
 
 ### Escalation Required
 1. **Critical**: AC absent, Design Doc absent → Error termination
-2. **High**: All ACs filtered out but feature is business-critical → User confirmation needed
-3. **Medium**: Budget insufficient for critical user journey (ROI > 90) → Present options
-4. **Low**: Multiple interpretations possible but minor impact → Adopt interpretation + note in report
+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.)
+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
 
 ## Technical Specifications
 

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

@@ -102,7 +102,8 @@ For each claim:
 - **Existence claims** (file exists, test exists, function exists, route exists): verify with Glob or Grep before reporting. Include tool result as evidence
 - **Behavioral claims** (function does X, error handling works as Y): Read the actual function implementation. Include the observed behavior as evidence
 - **Identifier claims** (names, URLs, parameters): compare the exact string in code against the document. Flag any discrepancy
-- Collect from at least 2 sources before classifying. Single-source findings should be marked with lower confidence
+- **Literal identifier referential integrity**: When the document contains concrete identifiers (URL paths, API endpoints, config keys, type/interface names, table/column names, event names), verify each has a corresponding definition or implementation in the codebase. A documented identifier with no code counterpart → gap. An identifier whose code definition contradicts the document's description → conflict
+- Collect from at least 2 sources before classifying. Single-source findings should be marked with lower confidence. **Exception**: For identifier existence verification (does this path/type/config key exist in code?), a single authoritative definition is sufficient for high confidence. A definition plus a reference site elevates to highest confidence
 
 ### Step 4: Consistency Classification
 
@@ -236,7 +237,8 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 - [ ] All existence claims (file exists, test exists, function exists) are backed by Glob/Grep tool results
 - [ ] All behavioral claims are backed by Read of the actual function implementation
 - [ ] Identifier comparisons use exact strings from code (no spelling corrections)
-- [ ] Each classification cites multiple sources (not single-source)
+- [ ] Literal identifiers in document (paths, endpoints, config keys, type names) verified against codebase definitions
+- [ ] Each classification cites multiple sources, except identifier existence verification where a single authoritative definition is sufficient
 - [ ] Low-confidence classifications are explicitly noted
 - [ ] Contradicting evidence is documented, not ignored
 - [ ] `reverseCoverage` section is populated with actual counts from tool results

package/.claude/agents-en/design-sync.md

@@ -20,14 +20,32 @@ You operate with an independent context that does not apply CLAUDE.md principles
 
 ## Detection Criteria (The Only Rule)
 
-**Detection Target**: Items explicitly documented in the source file that have different values in other files
-**Not Detection Target**: Everything else
+**Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope.
 
-**Reason**: Inference-based detection (e.g., "if A is B, then C should be D") risks destroying design intent. By detecting only explicit conflicts, we protect content agreed upon in past design sessions and maximize accuracy in future discussions.
+**Rationale**: design-sync serves as a high-recall candidate generator. The downstream consumer (orchestrator or human) filters the results. Prioritize catching real conflicts over avoiding false positives.
 
-**Same Concept Criteria**:
-- Defined within the same section
-- Or explicitly noted as "= [alias]" or "alias: [xxx]"
+### Match Basis Rules
+
+Each detected conflict must specify its `match_basis` and `confidence`. Medium confidence conflicts must also include `reason` with structural evidence.
+
+**high confidence** (confirmed conflict):
+
+| match_basis | Definition |
+|-------------|-----------|
+| `exact_string` | Identical identifier string in both documents |
+| `explicit_alias` | One document notes "= [alias]" or "alias: [xxx]" linking to the other |
+
+**medium confidence** (candidate conflict — requires `reason` with structural evidence):
+
+| match_basis | Structural evidence required | Example |
+|-------------|---------------------------|---------|
+| `same_endpoint_role` | Same service/module name + same HTTP method or route pattern (differing in version, path segment, or parameter name) | `POST /api/v1/orders` vs `POST /api/v2/orders` on same OrderService |
+| `same_integration_role` | Same service/class name + same flow stage (differing in method name, parameters, or return type) | `AuthService.authenticate()` vs `AuthService.login()` both at authentication entry point |
+| `same_ac_slot` | Same user action or trigger + same expected outcome category (differing in specific conditions or thresholds) | Both define "successful login" behavior but with different session/token requirements |
+
+**Matching scope**:
+- Match across any section — section name differences are irrelevant
+- Report only high and medium confidence matches. Matches lacking structural evidence are outside scope
 
 ## Responsibilities
 
@@ -67,9 +85,18 @@ Read the Design Doc specified in arguments and extract:
 - **Type definitions**: TypeScript interfaces, type aliases
 - **Numeric parameters**: Configuration values, thresholds, timeout values
 - **Component names**: Service names, class names, function names
-- **Integration points**: Connection points with other components
+- **Path identifiers**: URL paths, route definitions, API endpoints, config keys, file paths
+- **Integration points**: References to components, endpoints, or resources defined in other documents (e.g., service method calls, shared type imports, referenced route destinations)
 - **Acceptance criteria**: Specific conditions for functional requirements
 
+**Extraction Output** (per item):
+```yaml
+- identifier: "[exact string from document]"
+  category: "[category from above]"
+  section: "[section where found]"
+  context: "[how it is used: definition / reference / constraint]"
+```
+
 ### 2. Survey All Design Docs
 
 - Search docs/design/*.md (excluding template)
@@ -78,38 +105,38 @@ Read the Design Doc specified in arguments and extract:
 
 ### 3. Conflict Classification and Severity Assessment
 
-**Explicit Conflict Detection Process**:
-1. Extract each item (terms, types, numbers, names) from source file
-2. Search for same item names in other files
-3. Record as conflict only if values differ
+**Conflict Detection Process**:
+1. Extract each item from source file using extraction output format
+2. For each extracted item, search other files for matches using Match Basis Rules
+3. Record as conflict if values, definitions, or referents differ. Include `match_basis`, `confidence`, and `reason`
 4. Items not in source file are not detection targets
 
 | Conflict Type | Criteria | Severity |
 |--------------|----------|----------|
-| **Type definition mismatch** | Different properties in same interface | critical |
-| **Numeric parameter mismatch** | Different values for same config item | high |
-| **Term inconsistency** | Different notation for same concept | medium |
-| **Integration point conflict** | Mismatch in connection target/method | critical |
-| **Acceptance criteria conflict** | Different conditions for same feature | high |
-| **No conflict** | Item not in source file | - |
+| **Type definition mismatch** | Same type/interface name, different properties or field types | critical |
+| **Path/integration point conflict** | Same or equivalent path/integration identifier, different target/method/handler | critical |
+| **Numeric parameter mismatch** | Same config key, different value | high |
+| **Acceptance criteria conflict** | Same AC identifier or slot, different conditions or thresholds | high |
+| **Term definition mismatch** | Same term string, different definition text | medium |
 
 ### 4. Decision Flow
 
 ```
-Documented in source file?
+Item extracted from source file?
   ├─ No → Not a detection target (end)
-  └─ Yes → Value differs from other files?
-              ├─ No → No conflict (end)
-              └─ Yes → Proceed to severity assessment
+  └─ Yes → Match found in other files via Match Basis Rules?
+              ├─ No → No comparison target (end)
+              └─ Yes → Value/definition/referent differs?
+                          ├─ No → No conflict (end)
+                          └─ Yes → Assign match_basis, confidence, severity, reason
+                                   → Record conflict
 
 Severity Assessment:
-  - Type/integration point → critical (implementation error)
+  - Type/integration point/path identifier → critical (implementation error risk)
   - Numeric/acceptance criteria → high (behavior impact)
-  - Term → medium (confusion)
+  - Term → medium (confusion risk)
 ```
 
-**When in doubt**: Ask only "Is there explicit documentation for this item in the source file?" If No, do not detect.
-
 ## Output Format
 
 ### Structured Markdown Format
@@ -130,9 +157,11 @@ medium: [medium count]
 sync_status: [CONFLICTS_FOUND | NO_CONFLICTS]
 [/SUMMARY]
 
-[CONFLICTS]
+[CONFIRMED_CONFLICTS]
 ## Conflict-001
 severity: critical
+confidence: high
+match_basis: exact_string
 type: Type definition mismatch
 source_file: [source file]
 source_location: [section/line]
@@ -144,10 +173,27 @@ target_value: |
   [conflicting content]
 recommendation: |
   [Recommend unifying to source file's value]
-
-## Conflict-002
-...
-[/CONFLICTS]
+[/CONFIRMED_CONFLICTS]
+
+[CANDIDATE_CONFLICTS]
+## Candidate-001
+severity: [severity]
+confidence: medium
+match_basis: [same_endpoint_role | same_integration_role | same_ac_slot]
+type: [conflict type]
+source_file: [source file]
+source_location: [section/line]
+source_value: |
+  [content in source file]
+target_file: [file with conflict]
+target_location: [section/line]
+target_value: |
+  [conflicting content]
+reason: |
+  [Structural evidence: what shared context links these items]
+recommendation: |
+  [Recommend reviewing whether these describe the same design item]
+[/CANDIDATE_CONFLICTS]
 
 [NO_CONFLICTS]
 ## [filename]
@@ -167,48 +213,93 @@ suggested_action: |
 [/RECOMMENDATIONS]
 ```
 
-## Detection Pattern Details
+## Detection Pattern Examples
 
-### Type Definition Mismatch
-```typescript
-// Source Design Doc
-interface User {
-  id: string;
-  email: string;
-  role: 'admin' | 'user';
+### High confidence: exact_string (type definition, cross-section)
+```
+// Source Design Doc — Section: "Data Contracts"
+OrderItem {
+  quantity: number
+  unitPrice: number
 }
 
-// Other Design Doc (conflict)
-interface User {
-  id: number;  // different type
-  email: string;
-  userRole: string;  // different property name and type
+// Other Design Doc — Section: "API Response Schema"
+OrderItem {
+  quantity: string    // different type
+  unitPrice: number
+  discount: number   // extra property
 }
 ```
+→ confidence: high, match_basis: exact_string. Same identifier `OrderItem`, different definition. Section name difference is irrelevant.
 
-### Numeric Parameter Mismatch
-```yaml
+### High confidence: exact_string (path identifier)
+```
+# Source Design Doc — Section: "Endpoints"
+POST /api/orders/submit → handler: OrderController.submit
+
+# Other Design Doc — Section: "Integration Points"
+POST /api/orders/submit → handler: OrderService.createOrder
+```
+→ confidence: high, match_basis: exact_string. Same path, different handler.
+
+### High confidence: exact_string (numeric parameter)
+```
 # Source Design Doc
-Session timeout: 30 minutes
+Max retry count: 3
 
-# Other Design Doc (conflict)
-Session timeout: 60 minutes
+# Other Design Doc
+Max retry count: 5
 ```
 
-### Integration Point Conflict
-```yaml
+### Medium confidence: same_endpoint_role
+```
+# Source Design Doc
+POST /api/v2/orders → handler: OrderController.create
+
+# Other Design Doc
+POST /api/v1/orders → handler: OrderController.submit
+```
+→ confidence: medium, match_basis: same_endpoint_role, reason: "Same service (OrderController), same HTTP method (POST), same resource path (/orders) with differing version prefix and handler method."
+
+### Medium confidence: same_integration_role
+```
+# Source Design Doc — Section: "Authentication Flow"
+Entry point: AuthService.authenticate(credentials) → Session
+
+# Other Design Doc — Section: "Login Integration"
+Entry point: AuthService.login(email, password) → Token
+```
+→ confidence: medium, match_basis: same_integration_role, reason: "Same service (AuthService), same flow stage (authentication entry point) with different method names and return types."
+
+### Medium confidence: same_ac_slot
+```
+# Source Design Doc — AC-003
+When user submits valid credentials, the system shall create a session with 30-minute expiry
+
+# Other Design Doc — AC-012
+When user submits valid credentials, the system shall issue a JWT token with 60-minute expiry
+```
+→ confidence: medium, match_basis: same_ac_slot, reason: "Same user action (submit valid credentials), same outcome category (grant access) with different mechanism (session vs JWT) and timeout (30 vs 60 min)."
+
+### Not reported (no structural evidence)
+```
 # Source Design Doc
-Integration point: UserService.authenticate() → SessionManager.create()
+Endpoint: POST /api/users/register
 
-# Other Design Doc (conflict)
-Integration point: UserService.login() → TokenService.generate()
+# Other Design Doc
+Endpoint: POST /api/accounts/signup
 ```
+→ Not reported: Different services, different paths. No shared service name or route pattern to establish structural evidence.
 
 ## Quality Checklist
 
 - [ ] Correctly read source_design
 - [ ] Surveyed all Design Docs (excluding template)
-- [ ] Detected only explicit conflicts (avoided inference-based detection)
+- [ ] Extracted items using extraction output format
+- [ ] Applied Match Basis Rules across all sections
+- [ ] Every detected conflict includes confidence and match_basis
+- [ ] Every high-confidence conflict uses exact_string or explicit_alias match_basis
+- [ ] Every medium-confidence conflict includes structural evidence in reason field
 - [ ] Correctly assigned severity to each conflict
 - [ ] Output in structured markdown format