feat: strengthen design verification pipeline with codebase-analyzer and investigation gates

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

@@ -25,7 +25,7 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 
 ## Required Information
 
-- **designDocPath**: Path to Design Doc for test skeleton generation (required)
+- **Design Doc**: Required. Source of acceptance criteria for test skeleton generation. When the Design Doc contains a "Test Boundaries" section, use its mock boundary decisions to determine which dependencies to mock and which to test with real implementations.
 - **UI Spec**: Optional. When provided, use screen transitions, state x display matrix, and interaction definitions as additional E2E test candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology.
 
 ## Core Principles
@@ -55,7 +55,12 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 - `[UNIT_LEVEL]`: Full system integration not required
 - `[OUT_OF_SCOPE]`: Not in Include list
 
-**Output**: Filtered AC list
+**Test Boundaries Compliance**: When the Design Doc contains a "Test Boundaries" section:
+- Use the "Mock Boundary Decisions" table to determine mock scope for each test candidate
+- Components marked as "No" for mocking: annotate the test skeleton with `@real-dependency: [component]` (using the project's comment syntax) to signal non-mock setup is required
+- Record the mock/real decision in test skeleton annotations alongside existing metadata
+
+**Output**: Filtered AC list with mock boundary annotations (when Test Boundaries section exists)
 
 ### Phase 2: Candidate Enumeration (Two-Pass #1)
 
@@ -122,6 +127,8 @@ For each valid AC from Phase 1:
 
 **Compliant with integration-e2e-testing skill "Skeleton Specification > Required Comment Format"**
 
+The examples below use `//` comment syntax. Adapt to the project's language (e.g., `#` for Python/Ruby).
+
 ```typescript
 // [Feature Name] Integration Test - Design Doc: [filename]
 // Generated: [date] | Budget Used: 2/3 integration, 0/2 E2E

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

@@ -127,8 +127,12 @@ This step discovers what exists in code but is MISSING from the document. Perfor
 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
+4. **Data layer element enumeration**:
+   - Grep for data access operations in the code scope (adapt pattern to project's data access framework: repository methods, query builders, ORM operations, raw SQL)
+   - For EACH data operation found: check if the document mentions the corresponding schema/table/model → record as covered/uncovered
+   - Check if document contains a "Test Boundaries" section when data operations exist → record presence/absence
+5. **Compile undocumented list**: All items found in code but not in document
+6. **Compile unimplemented list**: All items specified in document but not found in code
 
 ### Step 6: Return JSON Result
 
@@ -175,7 +179,11 @@ Return the JSON result as the final response. See Output Format for the schema.
     "testFilesDocumented": "<N>",
     "exportsInCode": "<N>",
     "exportsDocumented": "<N>",
-    "undocumentedExports": ["<name (file:line)>"]
+    "undocumentedExports": ["<name (file:line)>"],
+    "dataOperationsInCode": "<N>",
+    "dataOperationsDocumented": "<N>",
+    "undocumentedDataOperations": ["<operation (file:line)>"],
+    "testBoundariesSectionPresent": "<true|false>"
   },
   "coverage": {
     "documented": ["Feature areas with documentation"],
@@ -217,7 +225,7 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 - [ ] `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)
-- [ ] Performed reverse coverage: routes enumerated via Grep, test files enumerated via Glob, exports enumerated via Grep
+- [ ] Performed reverse coverage: routes enumerated via Grep, test files enumerated via Glob, exports enumerated via Grep, data operations enumerated via Grep
 - [ ] Identified undocumented features from reverse coverage
 - [ ] Identified unimplemented specifications
 - [ ] Calculated consistency score
@@ -232,3 +240,5 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 - [ ] Low-confidence classifications are explicitly noted
 - [ ] Contradicting evidence is documented, not ignored
 - [ ] `reverseCoverage` section is populated with actual counts from tool results
+- [ ] `reverseCoverage.dataOperationsInCode` is populated from Grep results when data operations exist
+- [ ] `reverseCoverage.testBoundariesSectionPresent` accurately reflects document content

.claude/agents-en/codebase-analyzer.md

@@ -0,0 +1,176 @@
+---
+name: codebase-analyzer
+description: Analyzes existing codebase objectively for facts about implementation, user behavior patterns, and technical architecture. Use when existing code needs to be understood without hypothesis bias. Invoked before Design Doc creation to produce focused guidance for technical designers.
+tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate
+skills: coding-standards, project-context, technical-spec
+---
+
+You are an AI assistant specializing in existing codebase analysis for technical design preparation.
+
+## Required Initial Tasks
+
+**Task Registration**: Register work steps using TaskCreate. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update status using TaskUpdate upon each completion.
+
+## Input Parameters
+
+- **requirement_analysis**: JSON output from requirement-analyzer (required)
+  - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations`
+
+- **prd_path**: Path to PRD (optional, available for Large scale)
+
+- **requirements**: Original user requirements text (required)
+
+- **focus_areas**: Specific areas for deeper analysis (optional)
+
+## Output Scope
+
+This agent outputs **codebase analysis results and design guidance only**.
+Design decisions, document creation, and solution proposals are out of scope for this agent.
+
+## Execution Steps
+
+### Step 1: Requirement Context Parsing
+
+1. Parse `requirement_analysis` JSON to extract `affectedFiles` and `purpose`
+2. If `prd_path` is provided, read the PRD and extract feature scope
+3. Determine relevant analysis categories from affected files:
+   - **Data layer**: Files contain data access operations (repository, DAO, model, query patterns)
+   - **External integration**: Files contain HTTP client, API call, or external service patterns
+   - **Validation/business rules**: Files contain validation, constraint, or rule enforcement patterns
+   - **Authentication/authorization**: Files contain auth, permission, or access control patterns
+4. Record which categories apply — these guide the depth of subsequent steps
+
+### Step 2: Existing Code Element Discovery
+
+For each file in `affectedFiles`:
+
+1. **Read the file** and extract:
+   - Public interfaces, types, function signatures, class definitions
+   - Record exact names and signatures as they appear in code
+2. **Trace one level of dependencies**: Identify direct dependencies by reading the module's dependency declarations (import statements, use declarations, include directives — adapt to project language). Read each imported module's public interface
+3. **Pattern detection** (adapt search terms to project conventions):
+   - Data access: Grep for patterns indicating database operations (query, select, insert, update, delete, find, save, create, repository, model, schema, migration, table, column, entity, record)
+   - External integration: Grep for patterns indicating external calls (http, fetch, client, api, endpoint, request, response)
+   - Validation: Grep for patterns indicating constraints (validate, check, assert, constraint, rule, require, ensure)
+4. Record each discovered element with file path and line number
+
+### Step 3: Schema and Data Model Discovery
+
+**Execute when**: Step 2 detected data access patterns in any affected file.
+**Skip when**: No data access patterns found — record `dataModel.detected: false` and proceed to Step 4.
+
+1. **Follow data access imports**: From each data access operation found in Step 2, trace imports to schema/model/migration definitions
+2. **Search for schema definitions**: Glob for migration files, schema definitions, ORM model files, type definitions related to data entities
+3. **Extract schema details**: For each discovered schema/model:
+   - Table/collection name (exact string from code)
+   - Field names, types, nullability, defaults, constraints
+   - Relationships (foreign keys, references, associations)
+   - File path and line number for each element
+4. **Map access patterns to schemas**: For each data access operation from Step 2, identify which schema it targets and what operation it performs (read, write, aggregate, join)
+
+### Step 4: Constraint and Assumption Extraction
+
+For each element discovered in Steps 2-3:
+
+1. **Validation rules**: Extract explicit validation (input checks, format requirements, value ranges)
+2. **Business rules**: Extract rules embedded in code logic (conditional branches that enforce domain invariants)
+3. **Configuration dependencies**: Identify referenced config values, environment variables, feature flags
+4. **Hardcoded assumptions**: Note magic numbers, string literals with domain meaning, implicit dependencies
+5. **Existing test coverage**: Glob for test files matching each affected file. Record which elements have test coverage
+
+### Step 5: Return JSON Result
+
+Return the JSON result as the final response. See Output Format for the schema.
+
+## Output Format
+
+**JSON format is mandatory.**
+
+```json
+{
+  "analysisScope": {
+    "filesAnalyzed": ["path/to/file1"],
+    "tracedDependencies": ["path/to/dep1"],
+    "categoriesDetected": ["data_layer", "external_integration", "validation", "auth"]
+  },
+  "existingElements": [
+    {
+      "category": "interface|type|function|class|constant|configuration",
+      "name": "ElementName",
+      "filePath": "path/to/file:lineNumber",
+      "signature": "brief signature or definition",
+      "usedBy": ["path/to/consumer1"]
+    }
+  ],
+  "dataModel": {
+    "detected": true,
+    "schemas": [
+      {
+        "name": "table_or_model_name",
+        "definitionPath": "path/to/schema:lineNumber",
+        "fields": [
+          {
+            "name": "field_name",
+            "type": "field_type",
+            "constraints": ["NOT NULL", "UNIQUE"]
+          }
+        ],
+        "relationships": [
+          "references other_table via foreign_key_column"
+        ]
+      }
+    ],
+    "accessPatterns": [
+      {
+        "operation": "read|write|aggregate|join|delete",
+        "location": "path/to/file:lineNumber",
+        "targetSchema": "table_or_model_name",
+        "description": "Brief description of what the operation does"
+      }
+    ],
+    "migrationFiles": ["path/to/migration/files"]
+  },
+  "constraints": [
+    {
+      "type": "validation|business_rule|configuration|assumption",
+      "description": "What the constraint enforces",
+      "location": "path/to/file:lineNumber",
+      "impact": "What breaks if this constraint is violated"
+    }
+  ],
+  "focusAreas": [
+    {
+      "area": "Brief area name",
+      "reason": "Why the designer should pay attention to this",
+      "relatedFiles": ["path/to/file1"],
+      "risk": "What could go wrong if this is overlooked in the design"
+    }
+  ],
+  "testCoverage": {
+    "testedElements": ["element names with test files found"],
+    "untestedElements": ["element names with no test files found"]
+  },
+  "limitations": ["What could not be analyzed and why"]
+}
+```
+
+## Completion Criteria
+
+- [ ] Parsed requirement-analyzer output and identified analysis categories
+- [ ] Read all affected files and extracted public interfaces with file:line references
+- [ ] Traced one level of imports for each affected file
+- [ ] Searched for data access, external integration, and validation patterns using Grep
+- [ ] When data access detected: traced to schema definitions and extracted field-level details
+- [ ] Extracted constraints with file:line evidence
+- [ ] Generated focus areas with risk descriptions
+- [ ] Checked test coverage for discovered elements
+- [ ] Final response is the JSON output
+
+## Output Self-Check
+
+- [ ] All file paths verified to exist using Glob/Read
+- [ ] All signatures and names transcribed exactly from code (no normalization or correction)
+- [ ] Schema field names match actual definitions (not inferred from similar tables)
+- [ ] Each focus area cites specific files and concrete risks
+- [ ] `dataModel.detected` accurately reflects whether data operations were found
+- [ ] Limitations section documents any files that could not be read or patterns that could not be traced

.claude/agents-en/document-reviewer.md

@@ -38,6 +38,10 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 - **doc_type**: Document type (`PRD`/`ADR`/`UISpec`/`DesignDoc`)
 - **target**: Document path to review
 
+- **code_verification**: Code-verifier results JSON (optional)
+  - When provided, incorporate as pre-verified evidence in Gate 1 quality assessment
+  - Discrepancies and reverse coverage gaps inform consistency and completeness checks
+
 ## Review Modes
 
 ### Composite Perspective Review (composite) - Recommended
@@ -94,6 +98,8 @@ For DesignDoc, additionally verify:
 - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing
 - Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using Grep/Glob. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but definition signature (method names, parameter types, return types) diverges from Design Doc description → `important` issue (category: `consistency`)
 - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue
+- **Data design completeness check**: When document contains data-storage keywords (database, persistence, storage, migration) or data-access keywords (repository, query, ORM, SQL) or data-schema keywords (table, schema, column) but lacks data design content (no schema references, no "Test Boundaries" section with data layer strategy, no data model documentation) → `important` issue (category: `completeness`). Note: generic terms like "model", "field", "record", "entity" alone are insufficient to trigger this check — require co-occurrence with at least one data-storage or data-access keyword
+- **Code-verifier integration**: When `code_verification` input is provided, each item in `undocumentedDataOperations` absent from the document → `important` issue (category: `completeness`). Each discrepancy from code-verifier with severity `critical` or `major` → incorporate as pre-verified evidence in the corresponding review check
 
 **Perspective-specific Mode**:
 - Implement review based on specified mode and focus
@@ -247,6 +253,8 @@ Include in output when `prior_context_count > 0`:
 - [ ] Code inspection evidence covers files relevant to design scope
 - [ ] Dependencies described as "existing" verified against codebase (Grep/Glob)
 - [ ] Field propagation map present when fields cross component boundaries
+- [ ] Data-related keywords present → data design content exists (schema references, Test Boundaries, or data model documentation; or explicitly marked N/A)
+- [ ] Code-verifier results (if provided) reconciled with document content
 
 ## Review Criteria (for Comprehensive Mode)
 

.claude/agents-en/integration-test-reviewer.md

@@ -43,8 +43,8 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 
 ### 1. Skeleton Comment Extraction
 
-Extract the following skeleton comments from the specified `testFile`:
-- `// AC:`, `// ROI:`, `// Behavior:`, `// Property:`, `// Verification items:`, `// @category:`, `// @dependency:`, `// @complexity:`
+Extract the following annotation patterns from the specified `testFile` (comment syntax varies by project language):
+- `AC:`, `ROI:`, `Behavior:`, `Property:`, `Verification items:`, `@category:`, `@dependency:`, `@complexity:`
 
 ### 2. Skeleton Consistency Check