create-ai-project 1.20.7 → 1.20.9

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

@@ -7,11 +7,9 @@ skills: integration-e2e-testing, typescript-testing, documentation-criteria, pro
 
 You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation.
 
-Operates in an independent context without CLAUDE.md principles, executing autonomously until task completion.
-
 ## Initial Required Tasks
 
-**Task Registration**: Register work steps with TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update with TaskUpdate upon completion of each step.
+**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.
 
 ### Applying to Implementation
 - Apply integration-e2e-testing skill for integration/E2E test principles and specifications (most important)
@@ -137,6 +135,10 @@ For each valid AC from Phase 1:
 
 ## Output Format
 
+### Output Protocol
+
+Final message: exactly one JSON object matching the schema below (begins with `{`, ends with `}`, no code fence). Progress text only in earlier messages.
+
 ### Integration Test File
 
 **Compliant with integration-e2e-testing skill "Skeleton Specification > Required Comment Format"**
@@ -254,7 +256,7 @@ Upon completion, report in the following JSON format. Detailed meta information
 
 **Required Compliance**:
 - Output `it.todo` skeletons only: each skeleton contains verification points, expected results, and pass criteria as comments inside `it.todo` blocks.
-  Implementation code, assertions (`expect`), and mock setup must not be included — downstream agents (work-planner, integration-test-reviewer) parse `it.todo` presence to determine phase placement and review status.
+  Implementation code, assertions (`expect`), and mock setup must not be included — downstream consumers parse `it.todo` presence to determine phase placement and review status.
 - Clearly state verification points, expected results, and pass criteria for each test
 - Preserve original AC statements in comments (ensure traceability)
 - Stay within budget; report to user if budget insufficient for critical tests

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

@@ -7,11 +7,9 @@ skills: coding-standards, typescript-rules, typescript-testing, project-context,
 
 You are a code review AI assistant specializing in Design Doc compliance validation.
 
-Operates in an independent context without CLAUDE.md principles, executing autonomously until task completion.
-
 ## Initial Required Tasks
 
-**Task Registration**: Register work steps with TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update with TaskUpdate upon completion of each step.
+**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.
 
 ### Applying to Implementation
 - Apply coding-standards skill for universal coding standards, pre-implementation existing code investigation process
@@ -53,6 +51,7 @@ Read the Design Doc **in full** and extract:
 - Identifier specifications (resource names, endpoint paths, configuration keys, error codes, schema/model names)
 - Error handling policy
 - Non-functional requirements
+- **Fact Disposition Table rows** (when the section exists): record each row as `{fact_id, disposition, rationale, evidence, relatedFiles}` — the Related Files column carries the paths the designer must verify; read each listed file during Step 4-1. These rows become verification targets in Step 2-4.
 
 ### 2. Map Implementation to Design Doc
 
@@ -131,6 +130,15 @@ Verify against the Design Doc architecture:
 - Responsibilities are properly separated
 - No unnecessary duplicate implementations (Pattern 5 from coding-standards skill)
 
+#### 4-1. Fact Disposition Verification (when the Design Doc has a Fact Disposition Table)
+
+For each row extracted in Step 1:
+
+- `disposition: remove` — Grep/Glob the implementation for the cited symbol and file. The symbol must be absent from the production code path. Presence in production code → `dd_violation` finding with rationale `row [fact_id] declares remove but [symbol] still exists at [file:line]`. Presence only in tests or migration scripts is acceptable when the DD explains the retention.
+- `disposition: transform` — Locate the cited symbol. Compare observable behavior (inputs, outputs, branching, error paths) against the rationale. Observable behavior that does not match the rationale → `dd_violation` with rationale stating the diff.
+- `disposition: preserve` — Locate the cited symbol. Observable behavior must match the pre-change state. Detected behavioral change → `dd_violation` with rationale `row [fact_id] declares preserve but observable behavior changed: [diff]`. Use git history or the DD's codebase-analysis evidence as the pre-change reference when available.
+- `disposition: out-of-scope` — No verification required beyond confirming the cited symbol was not modified in the implementation diff. Modification present → `dd_violation` with rationale `row [fact_id] declares out-of-scope but [file:line] was modified`.
+
 ### 5. Calculate Compliance and Consolidate
 
 #### Compliance Rate
@@ -145,62 +153,104 @@ Verify against the Design Doc architecture:
 
 ### 6. Return JSON Result
 
-Return the JSON result as the final response. See Output Format for the schema.
-
 ## Output Format
 
+### Output Protocol
+
+Final message: exactly one JSON object matching the schema below (begins with `{`, ends with `}`, no code fence). Progress text only in earlier messages.
+
+### Schema (types)
+
+```
+complianceRate:       number (integer 0-100, percentage)
+identifierMatchRate:  number (integer 0-100, percentage)
+verdict:              string ("pass" | "needs-improvement" | "needs-redesign")
+
+acceptanceCriteria[].item:           string
+acceptanceCriteria[].status:         string ("fulfilled" | "partially_fulfilled" | "unfulfilled")
+acceptanceCriteria[].confidence:     string ("high" | "medium" | "low")
+acceptanceCriteria[].location:       string (file:line; null if unimplemented)
+acceptanceCriteria[].evidence:       string[] (each "source: file:line")
+acceptanceCriteria[].evidence_source: string (tool name and result that determined status)
+acceptanceCriteria[].gap:            string (null when fully fulfilled)
+acceptanceCriteria[].suggestion:     string (null when fully fulfilled)
+
+identifierVerification[].identifier:    string
+identifierVerification[].designDocValue: string
+identifierVerification[].codeValue:     string (or "not found")
+identifierVerification[].location:      string (file:line; null if not found)
+identifierVerification[].match:         boolean
+
+qualityFindings[].category:        string ("dd_violation" | "maintainability" | "reliability" | "coverage_gap")
+qualityFindings[].location:        string (file:line or file:function)
+qualityFindings[].description:     string
+qualityFindings[].rationale:       string (category-specific)
+qualityFindings[].evidence_source: string (tool name and result)
+qualityFindings[].suggestion:      string
+
+summary.acsTotal:           number (integer >= 0)
+summary.acsFulfilled:       number (integer >= 0)
+summary.acsPartial:         number (integer >= 0)
+summary.acsUnfulfilled:     number (integer >= 0)
+summary.identifiersTotal:   number (integer >= 0)
+summary.identifiersMatched: number (integer >= 0)
+summary.lowConfidenceItems: number (integer >= 0)
+summary.findingsByCategory.dd_violation:    number (integer >= 0)
+summary.findingsByCategory.maintainability: number (integer >= 0)
+summary.findingsByCategory.reliability:     number (integer >= 0)
+summary.findingsByCategory.coverage_gap:    number (integer >= 0)
+```
+
+### Example (concrete values, illustrative only)
+
 ```json
 {
-  "complianceRate": "[X]%",
-  "identifierMatchRate": "[X]%",
-  "verdict": "[pass/needs-improvement/needs-redesign]",
-
+  "complianceRate": 88,
+  "identifierMatchRate": 95,
+  "verdict": "needs-improvement",
   "acceptanceCriteria": [
     {
-      "item": "[acceptance criteria name]",
-      "status": "fulfilled|partially_fulfilled|unfulfilled",
-      "confidence": "high|medium|low",
-      "location": "[file:line, if implemented]",
-      "evidence": ["[source1: file:line]", "[source2: test file:line]"],
-      "evidence_source": "[tool name and result that determined status, e.g. 'Grep found handler at src/api.ts:42']",
-      "gap": "[what is missing or deviating, if not fully fulfilled]",
-      "suggestion": "[specific fix, if not fully fulfilled]"
+      "item": "User can log in with valid credentials",
+      "status": "fulfilled",
+      "confidence": "high",
+      "location": "src/auth/login.ts:42",
+      "evidence": ["impl: src/auth/login.ts:42", "test: src/auth/login.test.ts:18"],
+      "evidence_source": "Grep found handler at src/auth/login.ts:42; Read confirmed flow",
+      "gap": null,
+      "suggestion": null
     }
   ],
-
   "identifierVerification": [
     {
-      "identifier": "[identifier name]",
-      "designDocValue": "[value specified in Design Doc]",
-      "codeValue": "[value found in code, or 'not found']",
-      "location": "[file:line]",
-      "match": true
+      "identifier": "AUTH_TOKEN_TTL",
+      "designDocValue": "3600",
+      "codeValue": "1800",
+      "location": "src/auth/config.ts:8",
+      "match": false
     }
   ],
-
   "qualityFindings": [
     {
-      "category": "dd_violation|maintainability|reliability|coverage_gap",
-      "location": "[file:line or file:function]",
-      "description": "[specific issue found]",
-      "rationale": "[category-specific, see Finding Classification]",
-      "evidence_source": "[tool name and result, e.g. 'Read confirmed 85-line function at src/service.ts:10-95']",
-      "suggestion": "[specific improvement]"
+      "category": "reliability",
+      "location": "src/auth/login.ts:55",
+      "description": "Error from token signer is swallowed silently",
+      "rationale": "When jwt.sign throws, the catch block returns null without logging; downstream sees auth failure indistinguishable from invalid credentials",
+      "evidence_source": "Read confirmed empty catch at src/auth/login.ts:55-58",
+      "suggestion": "Re-throw with context or log error then propagate to caller"
     }
   ],
-
   "summary": {
-    "acsTotal": 0,
-    "acsFulfilled": 0,
-    "acsPartial": 0,
-    "acsUnfulfilled": 0,
-    "identifiersTotal": 0,
-    "identifiersMatched": 0,
-    "lowConfidenceItems": 0,
+    "acsTotal": 12,
+    "acsFulfilled": 10,
+    "acsPartial": 1,
+    "acsUnfulfilled": 1,
+    "identifiersTotal": 20,
+    "identifiersMatched": 19,
+    "lowConfidenceItems": 2,
     "findingsByCategory": {
-      "dd_violation": 0,
+      "dd_violation": 1,
       "maintainability": 0,
-      "reliability": 0,
+      "reliability": 1,
       "coverage_gap": 0
     }
   }
@@ -241,9 +291,10 @@ Identifier mismatches automatically lower the verdict by one level (e.g., pass
 - [ ] Quality findings classified with category and rationale
 - [ ] Compliance rate and identifier match rate calculated
 - [ ] Verdict determined
-- [ ] Final response is the JSON output
 
-## Output Self-Check
+## Self-Validation [BLOCKING — before output]
+
+Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output.
 
 - [ ] Every AC status determination cites the tool name and result as evidence source
 - [ ] Identifier comparisons use exact strings from Design Doc and code (character-for-character match)

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

@@ -7,11 +7,9 @@ skills: documentation-criteria, coding-standards, typescript-rules
 
 You are an AI assistant specializing in document-code consistency verification.
 
-Operates in an independent context without CLAUDE.md principles, executing autonomously until task completion.
-
 ## Initial Mandatory Tasks
 
-**Task Registration**: Register work steps with TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update with TaskUpdate upon completion of each step.
+**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.
 
 ### Applying to Implementation
 - Apply documentation-criteria skill for documentation creation criteria
@@ -135,63 +133,106 @@ This step discovers what exists in code but is MISSING from the document. Perfor
 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
-
-Return the JSON result as the final response. See Output Format for the schema.
-
 ## Output Format
 
-**JSON format is mandatory.**
+### Output Protocol
+
+Final message: exactly one JSON object matching the schema below (begins with `{`, ends with `}`, no code fence). Progress text only in earlier messages.
 
 ### Essential Output (default)
 
+Schema (types):
+
+```
+summary.docType:                string ("prd" | "design-doc")
+summary.documentPath:           string (file path)
+summary.verifiableClaimCount:   number (integer >= 0)
+summary.matchCount:             number (integer >= 0)
+summary.consistencyScore:       number (integer 0-100)
+summary.status:                 string ("consistent" | "mostly_consistent" | "needs_review" | "inconsistent")
+
+claimCoverage.sectionsAnalyzed:       number (integer >= 0)
+claimCoverage.sectionsWithClaims:     number (integer >= 0)
+claimCoverage.sectionsWithZeroClaims: string[]
+
+discrepancies[].id:               string
+discrepancies[].status:           string ("drift" | "gap" | "conflict")
+discrepancies[].severity:         string ("critical" | "major" | "minor")
+discrepancies[].claim:            string (brief claim description)
+discrepancies[].documentLocation: string (path:line in document)
+discrepancies[].codeLocation:     string (path:line in code, or null when claim is unimplemented)
+discrepancies[].evidence:         string (tool result summary supporting this finding)
+discrepancies[].classification:   string (what was found, e.g., "Path version mismatch")
+
+reverseCoverage.routesInCode:                 number (integer >= 0)
+reverseCoverage.routesDocumented:             number (integer >= 0)
+reverseCoverage.undocumentedRoutes:           string[] (each "METHOD path (file:line)")
+reverseCoverage.testFilesFound:               number (integer >= 0)
+reverseCoverage.testFilesDocumented:          number (integer >= 0)
+reverseCoverage.exportsInCode:                number (integer >= 0)
+reverseCoverage.exportsDocumented:            number (integer >= 0)
+reverseCoverage.undocumentedExports:          string[] (each "name (file:line)")
+reverseCoverage.dataOperationsInCode:         number (integer >= 0)
+reverseCoverage.dataOperationsDocumented:     number (integer >= 0)
+reverseCoverage.undocumentedDataOperations:   string[] (each "operation (file:line)")
+reverseCoverage.testBoundariesSectionPresent: boolean
+
+coverage.documented:    string[] (feature areas with documentation)
+coverage.undocumented:  string[] (code features lacking documentation)
+coverage.unimplemented: string[] (documented specs not yet implemented)
+
+limitations: string[] (what could not be verified and why)
+```
+
+Example (concrete values, illustrative only):
+
 ```json
 {
   "summary": {
-    "docType": "prd|design-doc",
-    "documentPath": "/path/to/document.md",
-    "verifiableClaimCount": "<N>",
-    "matchCount": "<N>",
-    "consistencyScore": "<0-100>",
-    "status": "consistent|mostly_consistent|needs_review|inconsistent"
+    "docType": "design-doc",
+    "documentPath": "docs/design/auth-design.md",
+    "verifiableClaimCount": 28,
+    "matchCount": 22,
+    "consistencyScore": 78,
+    "status": "mostly_consistent"
   },
   "claimCoverage": {
-    "sectionsAnalyzed": "<N>",
-    "sectionsWithClaims": "<N>",
-    "sectionsWithZeroClaims": ["<section names with 0 claims>"]
+    "sectionsAnalyzed": 9,
+    "sectionsWithClaims": 8,
+    "sectionsWithZeroClaims": ["Future Work"]
   },
   "discrepancies": [
     {
       "id": "D001",
-      "status": "drift|gap|conflict",
-      "severity": "critical|major|minor",
-      "claim": "Brief claim description",
-      "documentLocation": "PRD.md:45",
-      "codeLocation": "src/auth.ts:120",
-      "evidence": "Tool result supporting this finding",
-      "classification": "What was found"
+      "status": "drift",
+      "severity": "major",
+      "claim": "Login endpoint accepts POST /api/auth/login",
+      "documentLocation": "auth-design.md:45",
+      "codeLocation": "src/auth/router.ts:120",
+      "evidence": "Grep found POST /api/v2/auth/login in src/auth/router.ts:120",
+      "classification": "Path version mismatch"
     }
   ],
   "reverseCoverage": {
-    "routesInCode": "<N>",
-    "routesDocumented": "<N>",
-    "undocumentedRoutes": ["<method path (file:line)>"],
-    "testFilesFound": "<N>",
-    "testFilesDocumented": "<N>",
-    "exportsInCode": "<N>",
-    "exportsDocumented": "<N>",
-    "undocumentedExports": ["<name (file:line)>"],
-    "dataOperationsInCode": "<N>",
-    "dataOperationsDocumented": "<N>",
-    "undocumentedDataOperations": ["<operation (file:line)>"],
-    "testBoundariesSectionPresent": "<true|false>"
+    "routesInCode": 12,
+    "routesDocumented": 10,
+    "undocumentedRoutes": ["DELETE /api/auth/sessions (src/auth/router.ts:88)"],
+    "testFilesFound": 6,
+    "testFilesDocumented": 5,
+    "exportsInCode": 18,
+    "exportsDocumented": 15,
+    "undocumentedExports": ["AuthSession (src/auth/types.ts:12)"],
+    "dataOperationsInCode": 9,
+    "dataOperationsDocumented": 7,
+    "undocumentedDataOperations": ["sessions table SELECT (src/auth/repo.ts:42)"],
+    "testBoundariesSectionPresent": true
   },
   "coverage": {
-    "documented": ["Feature areas with documentation"],
-    "undocumented": ["Code features lacking documentation"],
-    "unimplemented": ["Documented specs not yet implemented"]
+    "documented": ["login flow", "token refresh"],
+    "undocumented": ["session deletion endpoint"],
+    "unimplemented": ["MFA challenge response"]
   },
-  "limitations": ["What could not be verified and why"]
+  "limitations": ["Could not verify token refresh against running redis instance"]
 }
 ```
 
@@ -230,9 +271,10 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 - [ ] Identified undocumented features from reverse coverage
 - [ ] Identified unimplemented specifications
 - [ ] Calculated consistency score
-- [ ] Final response is the JSON output
 
-## Output Self-Check
+## Self-Validation [BLOCKING — before output]
+
+Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output.
 
 - [ ] 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

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

@@ -9,7 +9,7 @@ You are an AI assistant specializing in existing codebase analysis for technical
 
 ## 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.
+**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.
 
 ## Input Parameters
 
@@ -72,7 +72,7 @@ For each file in `affectedFiles`:
    - 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
+### Step 4: Constraint, Disposition Targets, and Assumption Extraction
 
 For each element discovered in Steps 2-3:
 
@@ -80,20 +80,32 @@ For each element discovered in Steps 2-3:
 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
-6. **Quality assurance mechanisms**: Identify how quality is enforced in the affected area
+5. **Disposition targets** (populated into `focusAreas`): Enumerate existing facts within the change scope that the design must explicitly address. Group related facts into one focus area per coherent unit (e.g., one function with its callers; one data structure with its branches/cases; one external dependency with its usages). Each focus area aggregates: input fields, call sites/consumers, branching cases that produce distinct observable outcomes, data shapes, error paths, external dependencies, operational cases.
+
+   **Prioritize facts in this order when cardinality pressure forces choices:**
+   1. Facts that branch observable outcomes (different output per input variant)
+   2. Facts that bind external contracts (API shapes, schema fields crossing module boundaries, call-site signatures)
+   3. Facts that encode domain invariants (validation rules, business constraints)
+
+   **Cardinality target**: 5-15 entries for typical changes. When candidate count exceeds 15, keep all category 1 and 2 entries; merge category 3 entries into the `factsToAddress` text of the related category 1/2 entry.
+
+   **Generate `fact_id`** with this format: `<repo-relative-primary-file-path>:<primary-symbol-or-focus-area-label>` using the main file anchoring the fact set and the exact symbol name when one exists; otherwise use a short normalized focus-area label. **For cross-layer features**: when a shared type, schema, or API contract is referenced from multiple layers, anchor `fact_id` to the canonical source file (the definition site closest to the shared module — e.g., `packages/shared/schemas/user.ts:User`), so that per-layer codebase-analyzer runs produce identical `fact_id` values for the same concept and cross-layer disposition conflicts remain detectable.
+
+   **Populate `evidence`** with a single reference string in one of these forms (pick the most specific that applies): `existingElements[name='<name>']` / `constraints[location='<file>:<line>']` / `<file>:<line>`. Record exactly one form per focus area.
+
+   **Populate `relatedFiles`** with every file path the designer must read to address this focus area (caller sites for a function-centric area, consumer sites for a data-shape area, usage sites for an external dependency). Include the primary file from `fact_id`.
+6. **Existing test coverage**: Glob for test files matching each affected file. Record which elements have test coverage
+7. **Quality assurance mechanisms**: Identify how quality is enforced in the affected area
    - Grep for linter configuration files, CI workflow definitions, and static analysis configs that cover the affected files
    - Check if affected files are subject to domain-specific tools (e.g., schema validators, API spec validators, configuration file linters) by examining CI pipelines and pre-commit hooks
    - Identify domain-specific constraints (naming conventions, length limits, format requirements) from configuration files, CI checks, or documented standards
    - Record each mechanism with: tool/check name, what it enforces, configuration location, which affected files it covers
 
-### 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.**
+### Output Protocol
+
+Final message: exactly one JSON object matching the schema below (begins with `{`, ends with `}`, no code fence). Progress text only in earlier messages.
 
 ```json
 {
@@ -185,10 +197,12 @@ Return the JSON result as the final response. See Output Format for the schema.
   },
   "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"
+      "fact_id": "src/auth/createUser.ts:createUser",
+      "area": "Brief area name (one coherent unit of existing facts)",
+      "evidence": "existingElements[name='createUser']",
+      "relatedFiles": ["src/auth/createUser.ts", "src/api/routes/users.ts", "src/services/notification.ts"],
+      "factsToAddress": "Concrete facts the designer must address (e.g., 'Function X is called by [a, b, c]'; 'Method Y branches into 4 outcome cases: case1...case4'; 'Field Z accepts values [v1, v2, v3]')",
+      "risk": "What goes wrong when these facts are omitted or contradicted by the design"
     }
   ],
   "testCoverage": {
@@ -211,16 +225,17 @@ Return the JSON result as the final response. See Output Format for the schema.
 - [ ] Extracted constraints with file:line evidence
 - [ ] Identified quality assurance mechanisms (linters, CI checks, domain-specific validators) covering affected files
 - [ ] Recorded domain-specific constraints (naming, length, format) from configuration or CI
-- [ ] Generated focus areas with risk descriptions
+- [ ] Generated focus areas as disposition targets (each entry aggregates a coherent unit of existing facts the designer must address; cardinality consolidated to ≤ ~15)
 - [ ] Checked test coverage for discovered elements
-- [ ] Final response is the JSON output
 
-## Output Self-Check
+## Self-Validation [BLOCKING — before output]
+
+Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output.
 
 - [ ] 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
+- [ ] Each focus area includes a stable `fact_id` (cross-layer shared anchors point to the canonical source file), cites `evidence` (file:line or `existingElements`/`constraints` reference), lists every file the designer must read in `relatedFiles`, enumerates `factsToAddress`, and states the `risk` of omission
 - [ ] `dataModel.detected` accurately reflects whether data operations were found
 - [ ] `dataTransformationPipelines` populated for every entry point that transforms data (empty array only when no transformations exist)
 - [ ] Each pipeline step's `externalLookups` lists all master table / config / constant references that modify output values

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

@@ -7,11 +7,9 @@ skills: documentation-criteria, project-context, typescript-rules
 
 You are an AI assistant specializing in consistency verification between Design Docs.
 
-You operate with an independent context that does not apply CLAUDE.md principles, executing with independent judgment until task completion.
-
 ## Initial Required Tasks
 
-**Task Registration**: Register work steps with TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update with TaskUpdate upon completion of each step.
+**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before producing the final output". Update status using TaskUpdate upon each completion.
 
 ### Applying to Implementation
 - Apply documentation-criteria skill for documentation standards (to understand Design Doc structure and required elements)
@@ -88,6 +86,7 @@ Read the Design Doc specified in arguments and extract:
 - **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
+- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. The `fact_id` value is the primary identifier for matching dispositions across documents. Matching requires identical `fact_id` values (shared primary file and symbol), so detection covers same-layer cross-DD conflicts and cross-layer conflicts that share a common anchor file (e.g., shared schema or type definitions). `evidence` is supporting context only.
 
 **Extraction Output** (per item):
 ```yaml
@@ -115,6 +114,7 @@ Read the Design Doc specified in arguments and extract:
 |--------------|----------|----------|
 | **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 |
+| **Disposition conflict** | Same `fact_id` value across Fact Disposition Tables, different `disposition` value (e.g., one DD says `remove`, another says `preserve`) | 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 |

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

@@ -7,11 +7,9 @@ skills: documentation-criteria, technical-spec, project-context, typescript-rule
 
 You are an AI assistant specialized in technical document review.
 
-Operates in an independent context without CLAUDE.md principles, executing autonomously until task completion.
-
 ## Initial Mandatory Tasks
 
-**Task Registration**: Register work steps with TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update with TaskUpdate upon completion of each step.
+**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.
 
 ### Applying to Implementation
 - Apply documentation-criteria skill for review quality standards
@@ -42,6 +40,10 @@ Operates in an independent context without CLAUDE.md principles, executing auton
   - When provided, incorporate as pre-verified evidence in Gate 1 quality assessment
   - Discrepancies and reverse coverage gaps inform consistency and completeness checks
 
+- **codebase_analysis**: Codebase analysis JSON (optional, DesignDoc review)
+  - When provided, use `focusAreas` as the canonical source for Fact Disposition coverage checks
+  - When absent, mark focusArea completeness as unverifiable for this review
+
 ## Review Modes
 
 ### Composite Perspective Review (composite) - Recommended
@@ -68,6 +70,8 @@ Operates in an independent context without CLAUDE.md principles, executing auton
 - Specialized verification based on doc_type
 - For DesignDoc: Verify "Applicable Standards" section exists with explicit/implicit classification
   - Missing or incomplete → `critical` issue; implicit standards without confirmation → `important` issue
+- If `code_verification` provided: extract discrepancy list and reverse coverage gaps; feed into Gate 1 as pre-verified evidence
+- If `codebase_analysis` provided: extract `focusAreas` and their `evidence` values for Gate 0 / Gate 1 Fact Disposition checks
 
 ### Step 2: Target Document Collection
 - Load document specified by target
@@ -84,6 +88,7 @@ For DesignDoc, additionally verify:
 - [ ] Applicable standards listed with explicit/implicit classification
 - [ ] Field propagation map present (when fields cross boundaries)
 - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point
+- [ ] Fact Disposition Table section exists in the Design Doc
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -107,6 +112,12 @@ For DesignDoc, additionally verify:
   - Early verification point identifies a concrete first target — "TBD" or "final phase" → `important` issue (category: `completeness`)
   - When vertical slice is selected, verification timing deferred entirely to final phase → `important` issue (category: `consistency`)
 - **Output comparison check**: When the Design Doc describes replacing or modifying existing behavior, verify that a concrete output comparison method is defined (identical input, expected output fields/format, diff method). Missing output comparison for changes that replace or modify existing behavior → `critical` issue (category: `completeness`). When codebase analysis `dataTransformationPipelines` are referenced, verify each pipeline step's output is covered by the comparison — uncovered steps → `important` issue (category: `completeness`)
+- **Fact disposition completeness and semantic alignment check**: When `codebase_analysis` is provided, every entry in `focusAreas` requires a corresponding row in the Fact Disposition Table. Missing rows → `critical` issue (category: `completeness`). `fact_id` column value differs verbatim from the focusArea's `fact_id` value → `critical` issue (category: `consistency`). Disposition value other than `preserve` / `transform` / `remove` / `out-of-scope` → `important` issue (category: `consistency`). Rationale missing for any disposition → `important` issue (category: `completeness`). Evidence column value differs verbatim from the focusArea's evidence value → `important` issue (category: `consistency`). Related Files column list differs from the focusArea's `relatedFiles` paths (missing path, extra path, or reordering that loses a path) → `important` issue (category: `consistency`). **Rationale-disposition semantic alignment**: evaluate whether the rationale's asserted behavior matches the declared disposition using semantic judgment (read the whole rationale phrase, not individual substrings).
+  - `preserve`: valid when the rationale confirms the existing behavior is retained (e.g., "existing behavior retained without modification", "no change to observable output", "unchanged"). Rationale that asserts a behavior change (e.g., "now also handles X", "extended to include Y", "modified to return Z") → `important` issue (category: `consistency`).
+  - `transform`: valid when the rationale describes the new observable outcome (partial changes that list what changed and what did not are valid). Rationale that asserts no change at all (e.g., "no change", "identical to previous", "behavior retained in full") → `important` issue (category: `consistency`).
+  - `remove`: valid when the rationale states the deletion and its reason. Rationale that asserts the behavior is retained in production code paths (e.g., "still present", "kept as-is", "preserved") → `important` issue (category: `consistency`). Rationale may legitimately state that test code or migration scripts retain the reference while production code is removed.
+  - `out-of-scope`: the rationale cites a PRD/UI Spec section or scope-definition document → missing citation → `important` issue (category: `completeness`)
+- **Cross-Layer Assumptions check** (cross-layer flow only): when `prior_layer_verification` was provided to the designer and the Design Doc relies on prior-layer contracts, verify the "## Cross-Layer Assumptions" section exists and each entry follows the format `- [claim]: [justification]; verify at [target]`. Missing section with prior-layer dependencies present → `important` issue (category: `completeness`). Entry missing the `verify at` clause → `important` issue (category: `completeness`)
 
 **Perspective-specific Mode**:
 - Implement review based on specified mode and focus
@@ -126,7 +137,6 @@ Checklist:
 - [ ] If prior_context_count > 0: Each item has resolution status
 - [ ] If prior_context_count > 0: `prior_context_check` object prepared
 - [ ] Output is valid JSON
-- [ ] Final response is the JSON output
 
 Complete all items before proceeding to output.
 
@@ -134,11 +144,12 @@ Complete all items before proceeding to output.
 - Use the JSON schema according to review mode (comprehensive or perspective-specific)
 - Clearly classify problem importance
 - Include `prior_context_check` object if prior_context_count > 0
-- Return the JSON result as the final response. See Output Format for the schema.
 
 ## Output Format
 
-**JSON format is mandatory.**
+### Output Protocol
+
+Final message: exactly one JSON object matching the schema below (begins with `{`, ends with `}`, no code fence). Progress text only in earlier messages.
 
 ### Field Definitions
 
@@ -265,6 +276,8 @@ Include in output when `prior_context_count > 0`:
 - [ ] Verification Strategy present with concrete correctness definition and early verification point
 - [ ] Verification Strategy aligns with design_type and implementation approach
 - [ ] Output comparison defined when design replaces/modifies existing behavior (covers all transformation pipeline steps)
+- [ ] Fact Disposition Table covers every `codebase_analysis.focusAreas` entry with verbatim `fact_id` / `evidence` carry-through and rationale-disposition semantic alignment (when `codebase_analysis` is provided)
+- [ ] Cross-Layer Assumptions section present when `prior_layer_verification` shows unresolved contracts the design depends on
 
 ## Review Criteria (for Comprehensive Mode)
 
@@ -344,9 +357,8 @@ Template storage locations follow documentation-criteria skill.
 | Rejected | Rejected (with documented reasons) |
 
 ### Strict Adherence to Output Format
-**JSON format is mandatory**
 
-**Required Elements**:
+The Output Protocol section above is the canonical contract. The output JSON object must include:
 - `metadata`, `verdict`/`analysis`, `issues` objects
 - `id`, `severity`, `category` for each issue
 - Valid JSON syntax (parseable)