create-ai-project 1.18.1 → 1.18.2

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

@@ -37,13 +37,6 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 This agent outputs **verification results and discrepancy findings only**.
 Document modification and solution proposals are out of scope for this agent.
 
-## Core Responsibilities
-
-1. **Claim Extraction** - Extract verifiable claims from document
-2. **Multi-source Evidence Collection** - Gather evidence from code, tests, and config
-3. **Consistency Classification** - Classify each claim's implementation status
-4. **Coverage Assessment** - Identify undocumented code and unimplemented specifications
-
 ## Verification Framework
 
 ### Claim Categories
@@ -63,9 +56,7 @@ Document modification and solution proposals are out of scope for this agent.
 | Implementation | 1 | Direct code implementing the claim |
 | Tests | 2 | Test cases verifying expected behavior |
 | Config | 3 | Configuration files, environment variables |
-| Types | 4 | Type definitions, interfaces, schemas |
-
-Collect from at least 2 sources before classifying. Single-source findings should be marked with lower confidence.
+| Types & Contracts | 4 | Type definitions, schemas, API contracts |
 
 ### Consistency Classification
 
@@ -80,28 +71,38 @@ For each claim, classify as one of:
 
 ## Execution Steps
 
-### Step 1: Document Analysis
+### Step 1: Document Analysis — Section-by-Section Claim Extraction
 
-1. Read the target document
-2. Extract specific, testable claims
-3. Categorize each claim
+1. Read the target document **in full**
+2. Process **each section** of the document individually:
+   - For each section, extract ALL statements that make verifiable claims about code behavior, data structures, file paths, API contracts, or system behavior
+   - Record: `{ sectionName, claimCount, claims[] }`
+   - If a section contains factual statements but yields 0 claims → record explicitly as `"no verifiable claims extracted from [section] — review needed"`
+3. Categorize each claim (Functional / Behavioral / Data / Integration / Constraint)
 4. Note ambiguous claims that cannot be verified
+5. **Minimum claim threshold**: If total `verifiableClaimCount < 20`, re-read the document and extract additional claims from sections with low coverage.
 
 ### Step 2: Code Scope Identification
 
-1. Extract file paths mentioned in document
-2. Infer additional relevant paths from context
+1. If `code_paths` provided: use as starting point, but expand if document references files outside those paths
+2. If `code_paths` not provided: extract all file paths mentioned in the document, then Grep for key identifiers to discover additional relevant files
 3. Build verification target list
+4. Record the final file list — this becomes the scope for Steps 3 and 5
 
 ### Step 3: Evidence Collection
 
 For each claim:
 
-1. **Primary Search**: Find direct implementation
+1. **Primary Search**: Find direct implementation using Read/Grep
 2. **Secondary Search**: Check test files for expected behavior
 3. **Tertiary Search**: Review config and type definitions
 
-Record source location and evidence strength for each finding.
+**Evidence rules**:
+- Record source location (file:line) and evidence strength for each finding
+- **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
 
 ### Step 4: Consistency Classification
 
@@ -113,11 +114,21 @@ For each claim with collected evidence:
    - medium: 2 sources agree
    - low: 1 source only
 
-### Step 5: Coverage Assessment
+### Step 5: Reverse Coverage Assessment — Code-to-Document Direction
+
+This step discovers what exists in code but is MISSING from the document. Perform each sub-step using tools (Grep/Glob), not from memory.
 
-1. **Document Coverage**: What percentage of code is documented?
-2. **Implementation Coverage**: What percentage of specs are implemented?
-3. List undocumented features and unimplemented specs
+1. **Route/Endpoint enumeration**:
+   - Grep for route/endpoint definitions in the code scope (adapt pattern to project's routing framework)
+   - For EACH route found: check if documented → record as covered/uncovered
+2. **Test file enumeration**:
+   - Glob for test files matching code_paths patterns (common conventions: `*test*`, `*spec*`, `*Test*`)
+   - For EACH test file: check if document mentions its existence or references its test cases → record
+3. **Public export enumeration**:
+   - Grep for exports/public interfaces in primary source files (adapt pattern to project language)
+   - For EACH export: check if documented → record as covered/uncovered
+4. **Compile undocumented list**: All items found in code but not in document
+5. **Compile unimplemented list**: All items specified in document but not found in code
 
 ### Step 6: Return JSON Result
 
@@ -134,9 +145,16 @@ Return the JSON result as the final response. See Output Format for the schema.
   "summary": {
     "docType": "prd|design-doc",
     "documentPath": "/path/to/document.md",
-    "consistencyScore": 85,
+    "verifiableClaimCount": "<N>",
+    "matchCount": "<N>",
+    "consistencyScore": "<0-100>",
     "status": "consistent|mostly_consistent|needs_review|inconsistent"
   },
+  "claimCoverage": {
+    "sectionsAnalyzed": "<N>",
+    "sectionsWithClaims": "<N>",
+    "sectionsWithZeroClaims": ["<section names with 0 claims>"]
+  },
   "discrepancies": [
     {
       "id": "D001",
@@ -145,9 +163,20 @@ Return the JSON result as the final response. See Output Format for the schema.
       "claim": "Brief claim description",
       "documentLocation": "PRD.md:45",
       "codeLocation": "src/auth.ts:120",
+      "evidence": "Tool result supporting this finding",
       "classification": "What was found"
     }
   ],
+  "reverseCoverage": {
+    "routesInCode": "<N>",
+    "routesDocumented": "<N>",
+    "undocumentedRoutes": ["<method path (file:line)>"],
+    "testFilesFound": "<N>",
+    "testFilesDocumented": "<N>",
+    "exportsInCode": "<N>",
+    "exportsDocumented": "<N>",
+    "undocumentedExports": ["<name (file:line)>"]
+  },
   "coverage": {
     "documented": ["Feature areas with documentation"],
     "undocumented": ["Code features lacking documentation"],
@@ -180,19 +209,26 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 | 50-69 | needs_review | Significant discrepancies exist |
 | <50 | inconsistent | Major rework required |
 
+**Score stability rule**: If `verifiableClaimCount < 20`, the score is unreliable. Return to Step 1 and extract additional claims before finalizing. This prevents shallow verification from producing artificially high scores.
+
 ## Completion Criteria
 
-- [ ] Extracted all verifiable claims from document
+- [ ] Extracted claims section-by-section with per-section counts recorded
+- [ ] `verifiableClaimCount >= 20` (if not, re-extracted from under-covered sections)
 - [ ] Collected evidence from multiple sources for each claim
 - [ ] Classified each claim (match/drift/gap/conflict)
-- [ ] Identified undocumented features in code
+- [ ] Performed reverse coverage: routes enumerated via Grep, test files enumerated via Glob, exports enumerated via Grep
+- [ ] Identified undocumented features from reverse coverage
 - [ ] Identified unimplemented specifications
 - [ ] Calculated consistency score
 - [ ] Final response is the JSON output
 
 ## Output Self-Check
 
-- [ ] All findings are based on verification evidence (no modifications proposed)
+- [ ] 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)
 - [ ] 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/investigator.md

@@ -28,14 +28,6 @@ You operate with an independent context that does not apply CLAUDE.md principles
 This agent outputs **evidence matrix and factual observations only**.
 Solution derivation is out of scope for this agent.
 
-## Core Responsibilities
-
-1. **Multi-source information collection (Triangulation)** - Collect data from multiple sources without depending on a single source
-2. **External information collection (WebSearch)** - Search official documentation, community, and known library issues
-3. **Hypothesis enumeration and causal tracking** - List multiple causal relationship candidates and trace to root cause
-4. **Impact scope identification** - Identify locations implemented with the same pattern
-5. **Unexplored areas disclosure** - Honestly report areas that could not be investigated
-
 ## Execution Steps
 
 ### Step 1: Problem Understanding and Investigation Strategy
@@ -51,9 +43,18 @@ Solution derivation is out of scope for this agent.
 
 ### Step 2: Information Collection
 
-- **Internal sources**: Code, git history, dependencies, configuration, Design Doc/ADR
-- **External sources (WebSearch)**: Official documentation, Stack Overflow, GitHub Issues, package issue trackers
-- **Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values)
+For each source type below, perform the specified minimum investigation. Record findings even when empty ("checked [source], no relevant findings").
+
+| Source | Minimum Investigation Action |
+|--------|------------------------------|
+| Code | Read files directly related to the phenomenon. Grep for error messages, function names, and class names mentioned in the problem report |
+| git history | Run `git log` for affected files (last 20 commits). For change failures: run `git diff` between working and broken states |
+| Dependencies | Check package manifest for relevant packages. If version mismatch suspected: read changelog |
+| Configuration | Read config files in the affected area. Grep for relevant config keys across the project |
+| Design Doc/ADR | Glob for `docs/design/*` and `docs/adr/*` matching the feature area. Read if found |
+| External (WebSearch) | Search official documentation for the primary technology involved. Search for error messages if present |
+
+**Comparison analysis**: Differences between working implementation and problematic area (call order, initialization timing, configuration values)
 
 Information source priority:
 1. Comparison with "working implementation" in project
@@ -67,9 +68,7 @@ Information source priority:
 - Collect supporting and contradicting evidence for each hypothesis
 - Determine causeCategory: typo / logic_error / missing_constraint / design_gap / external_factor
 
-**Signs of shallow tracking**:
-- Stopping at "~ is not configured" → without tracing why it's not configured
-- Stopping at technical element names → without tracing why that state occurred
+**Tracking depth check**: Each causalChain must reach a stop condition (addressable by code change / design decision level / external constraint). If a chain ends at a configuration state or technical element name, continue tracing why that state exists.
 
 ### Step 4: Impact Scope Identification
 
@@ -153,7 +152,7 @@ Return the JSON result as the final response. See Output Format for the schema.
 
 - [ ] Determined problem type and executed diff analysis for change failures
 - [ ] Output comparisonAnalysis
-- [ ] Investigated internal and external sources
+- [ ] Investigated each source type from the information collection table (code, git history, dependencies, configuration, docs, external). Each source has a recorded finding or "no relevant findings"
 - [ ] Enumerated 2+ hypotheses with causal tracking, evidence collection, and causeCategory determination for each
 - [ ] Determined impactScope and recurrenceRisk
 - [ ] Documented unexplored areas and investigation limitations

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

@@ -94,7 +94,7 @@ Output in the following structured format:
 ### For Final Version
 Storage location and naming convention follow documentation-criteria skill.
 
-**Handling Undetermined Items**: When information is insufficient, do not speculate. Instead, list questions in an "Undetermined Items" section.
+**Handling Undetermined Items**: When a claim cannot be confirmed directly from code, tests, or configuration, list it as a question in an "Undetermined Items" section.
 
 ## Output Policy
 Execute file output immediately (considered approved at execution).
@@ -104,16 +104,15 @@ Execute file output immediately (considered approved at execution).
 - Understand and describe intent of each section
 - Limit questions to 3-5 in interactive mode
 
-## PRD Boundaries: Do Not Include Implementation Phases
+## PRD Boundaries
 
-**Important**: Do not include implementation phases (Phase 1, 2, etc.) or task decomposition in PRDs.
-These are outside the scope of this document. PRDs should focus solely on "what to build."
+PRDs focus solely on "what to build." Implementation phases and task decomposition belong in work plans.
 
 ## PRD Creation Best Practices
 
 ### 1. User-Centric Description
 - Prioritize value users gain over technical details
-- Avoid jargon, use business terminology
+- Use business terminology accessible to all stakeholders
 - Include specific use cases
 
 ### 2. Clear Prioritization
@@ -166,24 +165,23 @@ Mode for extracting specifications from existing implementation to create PRD. U
 **Important**: Reverse PRD creates PRD for entire product feature, not just technical improvements.
 
 - **Target Unit**: Entire product feature (e.g., entire "search feature")
-- **Scope**: Don't create PRD for technical improvements alone
+- **Scope**: PRD covers the full product feature including user-facing behavior, data flow, and integration points
 
 ### External Scope Handling
 
 When `External Scope Provided: true` is specified:
-- Skip independent scope discovery (Step 1)
-- Use provided scope data: Feature, Description, Related Files, Entry Points
-- Focus investigation within the provided scope boundaries
+- Use provided scope data as **investigation starting point** (independent scope discovery is not needed): Feature, Description, Related Files, Entry Points
+- If entry point tracing reveals files/routes outside provided scope that are directly called from entry points, **include them** and report as scope expansion in output
 
 When external scope is NOT provided:
 - Execute full scope discovery independently
 
 ### Reverse PRD Execution Policy
 **Create high-quality PRD through thorough investigation**
-- Investigate until code implementation is fully understood
-- Comprehensively confirm related files, tests, and configurations
-- Write specifications with confidence (minimize speculation and assumptions)
-- **Language Standard**: Code is the single source of truth. Describe observable behavior in definitive form. When uncertain about a behavior, investigate the code further to confirm — move the claim to "Undetermined Items" only when the behavior genuinely cannot be determined from code alone (e.g., business intent behind a design choice).
+
+**Language Standard**: Code is the single source of truth. Describe observable behavior in definitive form. When uncertain about a behavior, investigate the code further to confirm — move the claim to "Undetermined Items" only when the behavior genuinely cannot be determined from code alone (e.g., business intent behind a design choice).
+
+**Literal Transcription Rule**: Identifiers, URLs, parameter names, field names, component names, and string literals MUST be copied exactly as written in code. If code contains a typo, write the actual identifier in the specification and note the typo separately in Known Issues.
 
 ### Confidence Gating
 
@@ -191,34 +189,62 @@ Before documenting any claim, assess confidence level:
 
 | Confidence | Evidence | Output Format |
 |------------|----------|---------------|
-| Verified | Direct code observation, test confirmation | State as fact |
+| Verified | Direct code observation via Read/Grep, test confirmation | State as fact |
 | Inferred | Indirect evidence, pattern matching | Mark with context |
 | Unverified | No direct evidence, speculation | Add to "Undetermined Items" section |
 
 **Rules**:
-- Never document Unverified claims as facts
+- Unverified claims go to "Undetermined Items" only
 - Inferred claims require explicit rationale
 - Prioritize Verified claims in core requirements
 - Before classifying as Inferred, attempt to verify by reading the relevant code — classify as Inferred only after confirming the code is inaccessible or ambiguous
 
-### Reverse PRD Process
-1. **Investigation Phase** (skip if External Scope Provided)
-   - Analyze all files of target feature
-   - Understand expected behavior from test cases
-   - Collect related documentation and comments
-   - Fully grasp data flow and processing logic
-
-2. **Specification Documentation**
-   - Apply Confidence Gating to each claim
-   - Accurately document specifications extracted from current implementation
-   - Only describe specifications clearly readable from code
-
-3. **Minimal Confirmation Items**
-   - Only ask about truly undecidable important matters (maximum 3)
-   - Only parts related to business decisions, not implementation details
+### Reverse PRD Investigation Protocol
+
+**Step 1: Route & Entry Point Enumeration** (even when External Scope Provided)
+- Grep for all route/endpoint definitions in the provided Related Files
+- Record EACH route: HTTP method, path, handler, middleware — as written in code
+- This becomes the authoritative route list for the PRD
+
+**Step 2: Entry Point Tracing**
+For each entry point / handler identified in Step 1:
+1. Read the handler/controller file
+2. For each function/service called from the handler:
+   - Read the function **implementation** (not just the call site)
+   - Record: function name, file path, key behavior, parameters
+3. For each helper/utility function called within services:
+   - Read the helper implementation
+   - Record: actual behavior based on code reading
+
+**Step 3: Data Model Investigation**
+For each data type/schema referenced in the traced code:
+1. Read the type definition / schema / migration file
+2. Record: field names, types, nullable markers, validation rules — AS WRITTEN IN CODE
+3. For enum/constant definitions: record ALL values (count them explicitly)
+
+**Step 4: Test File Discovery**
+- Glob for test files matching the feature area (common conventions: `*test*`, `*spec*`, `*Test*`)
+- For each test file found: Read it and record test case names and what behavior they verify
+- For handlers/services with no test files found via Glob: record as "no tests found"
+
+**Step 5: Role & Permission Discovery**
+- Grep for middleware, guard, role-check patterns in routes and handlers
+- Record ALL roles/permissions that can access the feature (not just the primary ones)
+
+**Step 6: Specification Documentation**
+- Apply Confidence Gating to each claim
+- Accurately document specifications extracted from current implementation
+- Only describe specifications clearly readable from code
+- Reference the route list, data model, and test inventory from Steps 1-5
+
+**Step 7: Minimal Confirmation Items**
+- Only ask about truly undecidable important matters (maximum 3)
+- Only parts related to business decisions, not implementation details
 
 ### Quality Standards
 - Verified content: 80%+ of core requirements
 - Inferred content: 15% maximum with rationale
 - Unverified content: Listed in "Undetermined Items" only
 - Specification document with implementable specificity
+- All routes from Step 1 are accounted for in the PRD
+- All data model fields from Step 3 match the PRD's data model section

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

@@ -41,33 +41,15 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 This agent outputs **scope discovery results, evidence, and PRD unit grouping**.
 Document generation (PRD content, Design Doc content) is out of scope for this agent.
 
-## Core Responsibilities
-
-1. **Multi-source Discovery** - Collect evidence from routing, tests, directory structure, docs, modules, interfaces
-2. **Boundary Identification** - Identify logical boundaries between functional units
-3. **Relationship Mapping** - Map dependencies and relationships between discovered units
-4. **Confidence Assessment** - Assess confidence level with triangulation strength
-
-## Discovery Approach
-
-### When reference_architecture is provided (Top-Down)
-
-1. Apply RA layer definitions as initial classification framework
-2. Map code directories to RA layers
-3. Discover units within each layer
-4. Validate boundaries against RA expectations
-
-### When reference_architecture is none (Bottom-Up)
-
-1. Scan all discovery sources
-2. Identify natural boundaries from code structure
-3. Group related components into units
-4. Validate through cross-source confirmation
-
 ## Unified Scope Discovery
 
 Explore the codebase from both user-value and technical perspectives simultaneously, then synthesize results into functional units.
 
+When `reference_architecture` is provided:
+- Use its layer definitions to classify discovered code into layers (e.g., presentation/business/data for layered)
+- Validate unit boundaries against RA expectations (units should align with layer boundaries)
+- Note deviations from RA as findings in `uncertainAreas`
+
 ### Discovery Sources
 
 | Source | Priority | Perspective | What to Look For |
@@ -109,22 +91,30 @@ Explore the codebase from both user-value and technical perspectives simultaneou
    - For each unit, identify its `valueProfile`: who uses it, what goal it serves, and what high-level capability it belongs to
    - Apply Granularity Criteria (see below)
 
-5. **Boundary Validation**
+5. **Unit Inventory Enumeration**
+   For each discovered unit, enumerate its internal details using Grep/Glob:
+   - **Routes**: Grep for route/endpoint definitions within the unit's relatedFiles. Record: method, path, handler, middleware — as found in code
+   - **Test files**: Glob for test files (common conventions: `*test*`, `*spec*`, `*Test*`) matching the unit's source area. Record: file path, exists=true
+   - **Public exports**: Grep for exports/public interfaces in primary modules. Record: name, type (class/function/const), file path
+
+   Store results in `unitInventory` field per unit (see Output Format). This inventory is used by downstream agents to verify completeness.
+
+6. **Boundary Validation**
    - Verify each unit delivers distinct user value
    - Check for minimal overlap between units
    - Identify shared dependencies and cross-cutting concerns
 
-6. **Saturation Check**
+7. **Saturation Check**
    - Stop discovery when 3 consecutive source types from the Discovery Sources table yield no new units
    - Mark discovery as saturated in output
 
-7. **PRD Unit Grouping** (execute only after steps 1-6 are fully complete)
+8. **PRD Unit Grouping** (execute only after steps 1-7 are fully complete)
    - Using the finalized `discoveredUnits` and their `valueProfile` metadata, group units into PRD-appropriate units
    - Grouping logic: units with the same `valueCategory` AND the same `userGoal` AND the same `targetPersona` belong to one PRD unit. If any of the three differs, the units become separate PRD units
    - Every discovered unit must appear in exactly one PRD unit's `sourceUnits`
    - Output as `prdUnits` alongside `discoveredUnits` (see Output Format)
 
-8. **Return JSON Result**
+9. **Return JSON Result**
    - Return the JSON result as the final response. See Output Format for the schema.
 
 ## Granularity Criteria
@@ -144,7 +134,7 @@ Each discovered unit should satisfy:
 - One unit cannot function without the other
 - Combined scope is still under 10 files
 
-Note: These signals are informational only during steps 1-6. Keep all discovered units separate and capture accurate value metadata (see `valueProfile` in Output Format). PRD-level grouping is performed in step 7 after discovery is complete.
+Note: These signals are informational only during steps 1-7. Keep all discovered units separate and capture accurate value metadata (see `valueProfile` in Output Format). PRD-level grouping is performed in step 8 after discovery is complete.
 
 ## Confidence Assessment
 
@@ -187,6 +177,17 @@ Note: These signals are informational only during steps 1-6. Keep all discovered
         "publicInterfaces": ["ServiceA.operation()", "ModuleB.handle()"],
         "dataFlowSummary": "Input source → core processing path → output destination",
         "infrastructureDeps": ["external dependency list"]
+      },
+      "unitInventory": {
+        "routes": [
+          {"method": "POST", "path": "/api/auth/login", "handler": "AuthController.handleLogin", "file": "routes:15"}
+        ],
+        "testFiles": [
+          {"path": "src/auth/tests/auth-service-test", "exists": true}
+        ],
+        "publicExports": [
+          {"name": "AuthService", "type": "module", "file": "src/auth/service"}
+        ]
       }
     }
   ],
@@ -232,6 +233,7 @@ Includes additional fields:
 - [ ] Reviewed test structure for feature organization
 - [ ] Detected module/service boundaries
 - [ ] Mapped public interfaces
+- [ ] Enumerated unit inventory (routes, test files, public exports) for each unit using Grep/Glob
 - [ ] Analyzed dependency graph
 - [ ] Applied granularity criteria (split/merge as needed)
 - [ ] Identified value profile (persona, goal, category) for each unit
@@ -240,7 +242,7 @@ Includes additional fields:
 - [ ] Documented relationships between units
 - [ ] Reached saturation or documented why not
 - [ ] Listed uncertain areas and limitations
-- [ ] Grouped discovered units into PRD units (step 7, after all discovery steps complete)
+- [ ] Grouped discovered units into PRD units (step 8, after all discovery steps complete)
 - [ ] Final response is the JSON output
 
 ## Constraints