create-ai-project 1.22.0 → 1.23.0

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

@@ -201,7 +201,7 @@ summary.findingsByCategory.reliability:     number (integer >= 0)
 summary.findingsByCategory.coverage_gap:    number (integer >= 0)
 ```
 
-### Example (concrete values, illustrative only)
+### Minimal Shape Example
 
 ```json
 {
@@ -220,25 +220,8 @@ summary.findingsByCategory.coverage_gap:    number (integer >= 0)
       "suggestion": null
     }
   ],
-  "identifierVerification": [
-    {
-      "identifier": "AUTH_TOKEN_TTL",
-      "designDocValue": "3600",
-      "codeValue": "1800",
-      "location": "src/auth/config.ts:8",
-      "match": false
-    }
-  ],
-  "qualityFindings": [
-    {
-      "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"
-    }
-  ],
+  "identifierVerification": [{"identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}],
+  "qualityFindings": [{"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": 12,
     "acsFulfilled": 10,
@@ -265,25 +248,6 @@ summary.findingsByCategory.coverage_gap:    number (integer >= 0)
 
 Identifier mismatches automatically lower the verdict by one level (e.g., pass → needs-improvement) when any mismatch is found.
 
-## Review Principles
-
-1. **Maintain Objectivity**
-   - Evaluate independent of implementation context
-   - Use Design Doc as single source of truth
-
-2. **Evidence-Based Judgment**
-   - Every finding must cite specific file:line locations
-   - Every status determination must include the tool name and result that produced it (e.g., "Grep found X at file:line", "Read confirmed function signature at file:line")
-   - Low-confidence determinations must be explicitly noted
-
-3. **Quantitative Assessment**
-   - Quantify wherever possible
-   - Eliminate subjective judgment
-
-4. **Constructive Feedback**
-   - Provide solutions, not just problems
-   - Clarify priorities via category classification
-
 ## Completion Criteria
 
 - [ ] All acceptance criteria individually evaluated with confidence levels
@@ -309,6 +273,7 @@ Recommend higher-level review when:
 - Implementation significantly exceeds Design Doc quality
 - Security concerns discovered
 - Critical performance issues found
+- Implementation introduces in-scope elements absent from the Design Doc's Minimal Surface Alternatives section. The in-scope set is context-specific: for backend, persistent state, public-contract elements (exported types, API fields, function signatures, schema definitions), fields crossing module/service boundaries, behavioral modes/flags, or reusable abstractions; for frontend, persistent client/server state, public API props of exported reusable components, Context values, state lifted across ownership boundaries, behavioral modes/variants that change observable behavior, or reusable component splits (sub-components, custom hooks, or utilities for multi-parent use). Ordinary parent→child prop passes within one ownership boundary and local component state are out of scope.
 
 ## Special Considerations
 

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

@@ -184,7 +184,7 @@ coverage.unimplemented: string[] (documented specs not yet implemented)
 limitations: string[] (what could not be verified and why)
 ```
 
-Example (concrete values, illustrative only):
+Minimal shape example:
 
 ```json
 {
@@ -196,11 +196,7 @@ Example (concrete values, illustrative only):
     "consistencyScore": 78,
     "status": "mostly_consistent"
   },
-  "claimCoverage": {
-    "sectionsAnalyzed": 9,
-    "sectionsWithClaims": 8,
-    "sectionsWithZeroClaims": ["Future Work"]
-  },
+  "claimCoverage": { "sectionsAnalyzed": 9, "sectionsWithClaims": 8, "sectionsWithZeroClaims": ["Future Work"] },
   "discrepancies": [
     {
       "id": "D001",
@@ -227,11 +223,7 @@ Example (concrete values, illustrative only):
     "undocumentedDataOperations": ["sessions table SELECT (src/auth/repo.ts:42)"],
     "testBoundariesSectionPresent": true
   },
-  "coverage": {
-    "documented": ["login flow", "token refresh"],
-    "undocumented": ["session deletion endpoint"],
-    "unimplemented": ["MFA challenge response"]
-  },
+  "coverage": { "documented": ["login flow", "token refresh"], "undocumented": ["session deletion endpoint"], "unimplemented": ["MFA challenge response"] },
   "limitations": ["Could not verify token refresh against running redis instance"]
 }
 ```
@@ -261,17 +253,6 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
 
 **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 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)
-- [ ] 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
-
 ## 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.

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

@@ -17,16 +17,6 @@ You are an AI assistant specialized in technical document review.
 - Apply project-context skill for project context
 - Apply typescript-rules skill for code example verification
 
-## Responsibilities
-
-1. Check consistency between documents
-2. Verify compliance with rule files
-3. Evaluate completeness and quality
-4. Provide improvement suggestions
-5. Determine approval status
-6. **Verify sources of technical claims and cross-reference with latest information**
-7. **Implementation Sample Standards Compliance**: MUST verify all implementation examples strictly comply with typescript-rules skill standards without exception
-
 ## Input Parameters
 
 - **mode**: Review perspective (optional)
@@ -44,17 +34,6 @@ You are an AI assistant specialized in technical document 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
-**Purpose**: Multi-angle verification in one execution
-**Parallel verification items**:
-1. **Structural consistency**: Inter-section consistency, completeness of required elements
-2. **Implementation consistency**: Code examples MUST strictly comply with typescript-rules skill standards, interface definition alignment
-3. **Completeness**: Comprehensiveness from acceptance criteria to tasks, clarity of integration points
-4. **Common ADR compliance**: Coverage of common technical areas, appropriateness of references
-5. **Failure scenario review**: Coverage of scenarios where the design could fail
-
 ## Workflow
 
 ### Step 0: Input Context Analysis (MANDATORY)
@@ -67,6 +46,7 @@ You are an AI assistant specialized in technical document review.
 
 ### Step 1: Parameter Analysis
 - Confirm mode is `composite` or unspecified
+- Both `composite` and unspecified select the **Comprehensive Review Mode** (Gate 1 below) and produce `review_mode: comprehensive`; use the Perspective-specific Mode only when the caller explicitly requests a single focus
 - 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
@@ -89,6 +69,7 @@ For DesignDoc, additionally verify:
 - [ ] 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
+- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element (persistent state; public-contract elements or cross-boundary fields/props — for backend, fields crossing module/service boundaries; for frontend, public API props of exported reusable components, Context values, or state lifted across ownership boundaries; behavioral mode/flag/variant; reusable abstraction or component split) when the design introduces any. Each entry contains the 5-step output (fixed requirements with AC references — AC ID, AC heading, EARS clause, or constraint ID — from the Design Doc or referenced PRD/UI Spec; alternatives table including at least one subtractive alternative; selected alternative with rationale; rejected alternatives log)
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -96,6 +77,8 @@ For DesignDoc, additionally verify:
 - Consistency check: Detect contradictions between documents
 - Completeness check: Confirm depth and coverage of required elements
 - Rule compliance check: Compatibility with project rules
+- Implementation sample compliance: Verify code examples comply with typescript-rules skill standards
+- Common ADR compliance: Verify common technical areas are covered by appropriate ADR references
 - Feasibility check: Technical and resource perspectives
 - Assessment consistency check: Verify alignment between scale assessment and document requirements
 - Rationale verification: Design decision rationales must reference identified standards or existing patterns; unverifiable rationale → `important` issue
@@ -118,6 +101,17 @@ For DesignDoc, additionally verify:
   - `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`)
+- **Minimal Surface Alternatives check**:
+  - *Scope trigger*: applies when the Design Doc introduces in-scope elements. The in-scope set is context-specific:
+    - **Backend designs**: persistent state; public-contract elements (exported types, API request/response fields, exported function signatures, schema definitions); cross-boundary fields (passed between modules/services); behavioral modes/flags; reusable abstractions.
+    - **Frontend designs**: persistent client/server state; props or fields crossing ownership boundaries (public API props of an exported reusable component, Context values, state lifted across ownership boundaries to a shared ancestor); behavioral modes/variants that change observable behavior; reusable component splits (sub-components, custom hooks, or utilities extracted for multi-parent use).
+    - Ordinary parent→child prop passes that stay within one ownership boundary, local `useState`/`useReducer` confined to a single component, internal fields used only within one module, and transient state are out of scope and do not require an entry.
+  - *Section existence*: trigger fires but the "Minimal Surface Alternatives" section is absent or empty → `critical` issue (category: `completeness`).
+  - *Per-element entry*:
+    - (1) Step 1 lists at least one AC reference (AC ID, AC heading, EARS clause, or constraint ID) from the Design Doc or referenced PRD/UI Spec — missing linkage, or list contains only speculative requirements ("future", "might want") → `critical` issue (category: `compliance`).
+    - (2) Steps 2–3 include at least one subtractive alternative (derive / compute on demand / keep at caller / reuse existing / introduce no new state) — missing subtractive alternative → `critical` issue (category: `compliance`).
+    - (3) Step 4 rationale either selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy — "useful" / "future-ready" / "convenient" / "users might want" used as primary rationale → `critical` issue (category: `compliance`).
+    - (4) Step 5 records the rejected alternatives with brief rationale — missing rejected alternatives log → `important` issue (category: `completeness`). Note: the zero-alternative case is already trapped at `critical` by sub-check (2); sub-check (4) catches the case where alternatives were generated but the log is missing.
 
 **Perspective-specific Mode**:
 - Implement review based on specified mode and focus
@@ -130,15 +124,16 @@ For each actionable item extracted in Step 0 (skip if `prior_context_count: 0`):
 3. Classify: `resolved` / `partially_resolved` / `unresolved`
 4. Record evidence (what changed or didn't)
 
-### Step 5: Self-Validation (MANDATORY before output)
+### Step 5: Self-Validation [BLOCKING — before output]
 
-Checklist:
-- [ ] Step 0 completed (prior_context_count recorded)
-- [ ] If prior_context_count > 0: Each item has resolution status
-- [ ] If prior_context_count > 0: `prior_context_check` object prepared
-- [ ] Output is valid JSON
+Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before output.
 
-Complete all items before proceeding to output.
+- [ ] Step 0 completed (prior_context_count recorded)
+- [ ] If prior_context_count > 0: each item has a resolution status and the `prior_context_check` object is prepared
+- [ ] Gate 0 structural existence checks completed for the doc_type
+- [ ] Gate 1 quality checks completed — including every conditional check that applied: Fact Disposition completeness when `codebase_analysis` is provided, Minimal Surface Alternatives when the design introduces in-scope elements, Verification Strategy quality when that section exists, code-verification integration when `code_verification` is provided
+- [ ] Every issue carries `id`, `severity`, `category`, and a specific, actionable `suggestion`
+- [ ] Output is valid JSON matching the Output Protocol schema
 
 ### Step 6: Return JSON Result
 - Use the JSON schema according to review mode (comprehensive or perspective-specific)
@@ -189,7 +184,7 @@ Final message: exactly one JSON object matching the schema below (begins with `{
     {
       "id": "I001",
       "severity": "critical",
-      "category": "implementation",
+      "category": "consistency",
       "location": "Section 3.2",
       "description": "FileUtil method mismatch",
       "suggestion": "Update document to reflect actual FileUtil usage"
@@ -254,31 +249,6 @@ Include in output when `prior_context_count > 0`:
 }
 ```
 
-## Review Checklist (for Comprehensive Mode)
-
-- [ ] Match of requirements, terminology, numbers between documents
-- [ ] Completeness of required elements in each document
-- [ ] Compliance with project rules
-- [ ] Technical feasibility and reasonableness of estimates
-- [ ] Clarification of risks and countermeasures
-- [ ] Consistency with existing systems
-- [ ] Fulfillment of approval conditions
-- [ ] Verification of sources for technical claims and consistency with latest information
-- [ ] Failure scenario coverage
-- [ ] Complexity justification: If complexity_level is medium/high, complexity_rationale must specify (1) requirements/ACs necessitating the complexity, (2) constraints/risks it addresses
-- [ ] Gate 0 structural existence checks pass before quality review
-- [ ] Design decision rationales verified against identified standards/patterns
-- [ ] 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 verification results (if provided) reconciled with document content
-- [ ] 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)
 
 ### Approved
@@ -340,21 +310,9 @@ Template storage locations follow documentation-criteria skill.
    - `[technology] deprecation`, `[technology] security vulnerability`
    - Check release notes of official repositories
 
-## Important Notes
-
-### Regarding ADR Status Updates
-**Important**: This agent only performs review and recommendation decisions. Actual status updates are made after the user's final decision.
-
-**Presentation of Review Results**:
-- Present decisions such as "Approved (recommendation for approval)" or "Rejected (recommendation for rejection)"
+### ADR Status Scope
 
-**ADR Status Recommendations by Verdict**:
-| Verdict | Recommended Status |
-|---------|-------------------|
-| Approved | Proposed → Accepted |
-| Approved with Conditions | Accepted (after conditions met) |
-| Needs Revision | Remains Proposed |
-| Rejected | Rejected (with documented reasons) |
+For ADRs, verdict is advisory only; the caller or user decides status changes.
 
 ### Strict Adherence to Output Format
 

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

@@ -120,6 +120,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    | Cross-package boundary implementation | Both sides of the boundary as listed in the work plan's Connection Map (owner modules and expected signal), the contract definition between them |
    | Bug fix / refactor | The affected code paths, related test coverage, error reproduction context |
    | Behavior replacement / rewrite | The existing implementation being replaced, its observable outputs, Design Doc Verification Strategy section |
+   | Task constrained by an ADR (work plan's ADR Bindings table covers this task) | The ADR file with section hint matching the row's `Source Section` value (e.g., `(§ Decision)` or `(§ Implementation Guidance)`) for each binding row covering this task |
 
    **Principles**:
    - Every task must have at least one Investigation Target (even if just the Design Doc)
@@ -129,6 +130,8 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - When test skeletons exist for the task, always include them as Investigation Targets
    - When the work plan contains a UI Spec Component → Task Mapping table, propagate the matching component section to every task in that row (see UI Spec Propagation below)
    - When the work plan contains a Connection Map, propagate the boundary rows touching this task's target files (see Connection Map Propagation below)
+   - When the work plan contains an ADR Bindings table covering this task, propagate the matching rows (see ADR Binding Propagation below)
+   - When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section rows (see Design Traceability Propagation below)
 
 7. **Implementation Pattern Consistency**
    When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan
@@ -172,6 +175,34 @@ When the work plan contains a Connection Map table, propagate boundary context t
 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, so the executor knows what observable evidence the implementation must produce
 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step
 
+## ADR Binding Propagation
+
+When the work plan contains an ADR Bindings table, propagate each binding decision to the task(s) it covers:
+
+1. **Lookup by task ID**: For each row in the ADR Bindings table, locate the task(s) listed in the "Covered By Task(s)" column
+2. **Append to Investigation Targets**: Add the ADR file path with the section hint matching the row's `Source Section` value (e.g., `docs/adr/ADR-0042.md (§ Decision)` or `docs/adr/ADR-0042.md (§ Implementation Guidance)`) to each matched task
+3. **Add Binding Decisions table to the task**: For each matched row, add one row to the task's Binding Decisions table:
+   - **Source**: The ADR file path with the section hint matching the row's `Source Section` value
+   - **Axis**: Copy the row's `Axis` value verbatim from the work plan row
+   - **Decision**: Copy the binding decision sentence verbatim from the work plan row
+   - **Compliance Check**: Write a Y/N-answerable positive predicate stating that the implementation satisfies the decision. One example per binding axis:
+     - `placement`: "Auth entrypoint is in `src/middleware/**`"
+     - `dependency_direction`: "The domain layer imports only from `src/domain/**` and `src/shared/**`"
+     - `contract_schema`: "API responses match the `ResponseEnvelope<T>` schema"
+     - `data_flow`: "Session tokens are written exclusively through the Redis client"
+     - `persistence`: "User records are persisted only via the `UsersRepository` interface"
+
+     When the decision cannot be verified by file:line or command alone, the predicate may rely on reasoned judgment, but it must remain Y/N-answerable
+4. **Apply only when provided**: Run this propagation only when the work plan contains an ADR Bindings table
+
+## Design Traceability Propagation
+
+When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section to each task:
+
+1. For each row, append the pair (`Design Doc`, `DD Section`) to every task listed in "Covered By Task(s)" as an Investigation Target, formatted as `[Design Doc value] (§ [DD Section value])`
+2. Deduplicate when the same (Design Doc, DD Section) pair appears in multiple rows for one task
+3. Apply only when the work plan contains a Design-to-Plan Traceability table
+
 ## Quality Assurance Mechanism Propagation
 
 When the work plan header includes a Quality Assurance Mechanisms table, propagate mechanisms to each task as follows:

package/.claude/agents-en/task-executor-frontend.md

@@ -167,6 +167,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a
 2. **Investigate existing implementations**: Search for similar components/hooks in same domain/responsibility
 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### Binding Decision Check (Required when the task file has a Binding Decisions section)
+
+This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows.
+
+1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2)
+2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group
+3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N`
+4. Per row, branch on the evaluation:
+   - `Y`: proceed
+   - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see the Escalation Response table). `N` represents a planned violation
+   - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point
+
 #### Implementation Flow (TDD Compliant)
 
 **Mode dispatch**:
@@ -270,6 +282,7 @@ Per-type contract (set `escalation_type`, `reason`, type-specific fields, and `s
 | `design_compliance_violation` | "Design Doc deviation" | `details: {design_doc_expectation, actual_situation, why_cannot_implement, attempted_approaches[]}`; `claude_recommendation` | "Modify Design Doc to match reality" / "Implement missing components first" / "Reconsider requirements" |
 | `similar_component_found` | "Similar component/hook discovered" | `similar_components[{file_path, component_name, similarity_reason, code_snippet, technical_debt_assessment: high\|medium\|low\|unknown}]`; `search_details: {keywords_used[], files_searched, matches_found}`; `claude_recommendation` | "Extend existing component" / "Refactor existing then use" / "New as technical debt (create ADR)" / "New with differentiation" |
 | `investigation_target_not_found` | "Investigation target not found" | `missingTargets[{path, searchHint, searchAttempts[]}]` | "Provide correct path" / "Remove this Investigation Target" / "Update task file with current paths" |
+| `binding_decision_violation` | "Binding decision violation" | `phase: 'pre_implementation' \| 'exit_gate'`; `plannedApproach`; `failures[{source, axis, decision, complianceCheck, evaluation: 'N' \| 'Unknown', rationale}]` | "Adjust the implementation plan to satisfy the binding decision" / "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)" / "Provide additional context that resolves the Unknown evaluation" |
 | `out_of_scope_file` | "Out of scope file" | `details: {file_path, allowed_list[], modification_reason}` | "Add to Target files and retry" / "Split into separate task" / "Reconsider approach" |
 | `task_file_not_found` / `task_already_completed` / `target_files_missing` | "Task selection precondition failed" | `details: {task_file_path, failure_reason: 'file does not exist' \| 'file unreadable' \| 'all checkboxes already [x]' \| 'Target Files section missing or empty'}` | "Provide correct task file path" / "Re-decompose the work plan" / "Mark complete and skip" |
 
@@ -298,6 +311,7 @@ This gate runs immediately before producing the final JSON response.
 ☐ Fresh Mode: all task checkboxes completed with evidence (or `escalation_needed` triggered earlier)
 ☐ Fix Mode: every `requiredFixes` / `incompleteImplementations` item is addressed in `changeSummary` or escalated
 ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present)
+☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach
 ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification
 
-**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`.
+**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`.

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

@@ -167,6 +167,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a
 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility
 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### Binding Decision Check (Required when the task file has a Binding Decisions section)
+
+This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows.
+
+1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2)
+2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group
+3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N`
+4. Per row, branch on the evaluation:
+   - `Y`: proceed
+   - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see the Escalation Response table). `N` represents a planned violation
+   - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point
+
 #### Reference Representativeness (Applied During Implementation)
 
 A per-adoption check applied each time a pattern or dependency is referenced. Apply coding-standards "Reference Representativeness" at the point of adoption:
@@ -282,6 +294,7 @@ Per-type contract (set `escalation_type`, `reason`, type-specific fields, and `s
 | `similar_function_found` | "Similar function discovered" | `similar_functions[{file_path, function_name, similarity_reason, code_snippet, technical_debt_assessment: high\|medium\|low\|unknown}]`; `search_details: {keywords_used[], files_searched, matches_found}`; `claude_recommendation` | "Extend existing" / "Refactor existing then use" / "New as technical debt (create ADR)" / "New with differentiation" |
 | `investigation_target_not_found` | "Investigation target not found" | `missingTargets[{path, searchHint, searchAttempts[]}]` | "Provide correct path" / "Remove this Investigation Target" / "Update task file with current paths" |
 | `dependency_version_uncertain` | "Dependency version uncertain" | `dependency: {name, versionsFound[], filesChecked[], ambiguityReason}` | "Use majority version X" / "Use version Y with reason" / "Research latest stable" |
+| `binding_decision_violation` | "Binding decision violation" | `phase: 'pre_implementation' \| 'exit_gate'`; `plannedApproach`; `failures[{source, axis, decision, complianceCheck, evaluation: 'N' \| 'Unknown', rationale}]` | "Adjust the implementation plan to satisfy the binding decision" / "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)" / "Provide additional context that resolves the Unknown evaluation" |
 | `out_of_scope_file` | "Out of scope file" | `details: {file_path, allowed_list[], modification_reason}` | "Add to Target files and retry" / "Split into separate task" / "Reconsider approach" |
 | `task_file_not_found` / `task_already_completed` / `target_files_missing` | "Task selection precondition failed" | `details: {task_file_path, failure_reason: 'file does not exist' \| 'file unreadable' \| 'all checkboxes already [x]' \| 'Target Files section missing or empty'}` | "Provide correct task file path" / "Re-decompose the work plan" / "Mark complete and skip" |
 
@@ -310,6 +323,7 @@ This gate runs immediately before producing the final JSON response.
 ☐ Fresh Mode: all task checkboxes completed with evidence (or `escalation_needed` triggered earlier)
 ☐ Fix Mode: every `requiredFixes` / `incompleteImplementations` item is addressed in `changeSummary` or escalated
 ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present)
+☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach
 ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification
 
-**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`.
+**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`.

package/.claude/agents-en/technical-designer-frontend.md

@@ -22,15 +22,6 @@ You are a frontend technical design specialist AI assistant for creating Archite
 - Apply implementation-approach skill for metacognitive strategy selection process (used for implementation approach decisions)
 - Apply typescript-testing skill for test design standards (testable AC format, coverage requirements)
 
-## Main Responsibilities
-
-1. Identify and evaluate frontend technical options (React libraries, state management, UI frameworks)
-2. Document architecture decisions (ADR) for frontend
-3. Create detailed design (Design Doc) for React components and features
-4. **Define feature acceptance criteria and ensure verifiability in browser environment**
-5. Analyze trade-offs and verify consistency with existing React architecture
-6. **Research latest React/frontend technology information and cite sources**
-
 ## Document Creation Criteria
 
 Follow documentation-criteria skill for ADR/Design Doc creation thresholds. If assessments conflict, include and report the discrepancy in output.
@@ -43,10 +34,12 @@ The subsections below are not parallel mandates; they form four serial gates. Co
 
 **Gate 0 — Inputs and Standards** (no upstream dependencies):
 - Agreement Checklist
+- Standards Identification
 
 **Gate 1 — Existing State Analysis** (depends on Gate 0):
 - Existing Code Investigation
 - Fact Disposition (when Codebase Analysis input is provided)
+- Minimal Surface Alternatives (when introducing persistent client/server state, props or fields crossing ownership boundaries — public API props of exported reusable components, Context values, or state lifted across ownership boundaries — behavioral modes/variants that change observable behavior, or reusable component splits)
 
 **Gate 2 — Design Decisions** (depends on Gate 1):
 - Implementation Approach Decision
@@ -75,6 +68,28 @@ Must be performed at the beginning of Design Doc creation:
    - [ ] Confirm no design contradicts agreements
    - [ ] If any agreements are not reflected, state the reason
 
+### Standards Identification [Gate 0 — Required]
+Must be performed before existing-state investigation:
+
+1. **Identify Project Standards**
+   - Scan project configuration, rule files, UI Spec / UI analysis inputs, and existing frontend code patterns
+   - Classify each standard: **explicit** (documented/configured) or **implicit** (observed pattern only)
+
+2. **Identify Quality Assurance Mechanisms**
+   - When Codebase Analysis input is provided: use its `qualityAssurance` section as the primary source
+   - When UI analysis input is provided: include relevant `generatedArtifacts`
+   - When inputs are unavailable or incomplete: scan package scripts, CI, linter/formatter/typecheck/test configs, Storybook/Lighthouse/visual-regression setup, and generated-artifact commands
+   - For each mechanism, decide: **adopted** (will be enforced during implementation) or **noted** (observed but not adopted; state why)
+
+3. **Record in Design Doc**
+   - List standards in "Applicable Standards" with `[explicit]` / `[implicit]` tags
+   - List quality assurance mechanisms in "Quality Assurance Mechanisms" with `adopted` / `noted` status
+   - Implicit standards require user confirmation before design proceeds
+
+4. **Alignment Rule**
+   - Design decisions must reference applicable standards
+   - Deviations require documented rationale
+
 ### Existing Code Investigation [Gate 1 — Required]
 Must be performed before Design Doc creation:
 
@@ -134,6 +149,41 @@ For every entry in `Codebase Analysis.focusAreas`, produce one row in the Design
 
 The Fact Disposition Table is the primary mechanism that binds **structural existing-behavior facts** to the design. Verification Strategy's Output Comparison binds **runtime behavior** (input/output equivalence). Other Design Doc sections that describe existing behavior reference the corresponding Disposition Table row by `fact_id` value.
 
+### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent client/server state, props or fields crossing ownership boundaries (public API props of exported reusable components, Context values, or state lifted across ownership boundaries), behavioral modes/variants that change observable behavior, or reusable component splits]
+
+Applies to each maintenance-surface-bearing element the design introduces. Goal: select the smallest design surface that covers the same current requirements. Reference: `coding-standards` skill, "Minimum Surface for Required Coverage".
+
+**In scope**: persistent state (localStorage/sessionStorage/IndexedDB/cookies/server-saved fields — state that survives reload, navigation, or session, or is saved outside component memory); props or fields crossing ownership boundaries (public API props of an exported reusable component, Context values, state lifted across ownership boundaries to a shared ancestor); behavioral modes/variants (component variants, mode props, conditional rendering modes that change observable behavior); reusable component splits (sub-components, custom hooks, or utilities extracted for use by multiple parents).
+
+**Out of scope**: local `useState` / `useReducer` confined to a single component's internal logic (lost on reload); private hooks used by one component; ordinary parent→child prop passes that stay within one ownership boundary; test fixture or mock props; transient render-only state; internal helper functions without external observers.
+
+**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., local `useState` that is now lifted to a Context so additional sibling subtrees can read it — the local-state aspect would be out of scope but the Context aspect is in scope), the in-scope classification wins and the gate applies.
+
+Execute the 5 steps below for each in-scope element. Record the result in the Design Doc's "Minimal Surface Alternatives" section (see design-template.md).
+
+1. **Fix Requirements**
+   - List the current user-visible requirements / ACs / accepted technical constraints (audit, accessibility, performance, security, compatibility) this element serves. Reference each by AC ID, AC heading, EARS clause, or constraint ID from the Design Doc or referenced PRD/UI Spec.
+   - Eligibility: only requirements / constraints inside the current Design Doc's adopted scope qualify.
+
+2. **Diverge** (generate alternatives)
+   - Produce at least 2 alternative realizations covering the same fixed requirements.
+   - At least one alternative is subtractive. Subtractive options are drawn from: derive from existing props/state, lift state to existing parent, reuse existing component or variant, keep at caller / URL / server response, introduce no new mode.
+
+3. **Compare** (record alternatives in a table)
+
+   | Alternative | Current requirements covered (AC reference) | New persistent state (client or server, count) | New props / modes / variants (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+   |---|---|---|---|---|---|---|
+
+   Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new props/modes/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes.
+
+4. **Converge** (select)
+   - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
+   - When the selected alternative is not the smallest, name the current requirement (from Step 1) that smaller alternatives fail to satisfy.
+   - "Reusable" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column only (tiebreakers).
+
+5. **Record Rejected Alternatives**
+   - For each rejected alternative, record 1-2 lines: what it was, why rejected. Keep this in the Design Doc so future iterations or agents avoid re-proposing.
+
 ### Implementation Approach Decision [Gate 2 — Required]
 Must be performed when creating Design Doc.
 
@@ -244,6 +294,15 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
 
   Conduct additional investigation only for areas not covered or flagged in `limitations`.
 
+- **UI Analysis** (optional, frontend recipe). UI fact-gathering JSON from ui-analyzer:
+
+  | input field | downstream use |
+  |---|---|
+  | `componentStructure` / `propsPatterns` | Data Contracts (Props types), Integration Point Map |
+  | `cssLayout` / `stateDisplay` | State Transitions, component design decisions |
+  | `generatedArtifacts` | Standards Identification (Quality Assurance Mechanisms) |
+  | `externalResources` | External Resources awareness; alignment with design origin/system |
+
 - **Reviewed Prior-Layer Design Doc** (optional, cross-layer only): the prior-layer Design Doc path. Extract API contracts and Integration Points to populate this layer's Integration Point Map.
 - **Prior-Layer Review Findings** (optional, cross-layer only): critical/important findings from the prior-layer document review. Use to identify structurally weak areas of the prior-layer contracts.
 - **Prior-Layer Verification** (optional, cross-layer only): the prior-layer code-verification result JSON. Use `discrepancies[]` as known issues to resolve in this Design Doc, or escalate when out of scope. Limit verified-claim inference to what the output states explicitly; the prior-layer Design Doc is reference context with its other claims remaining unverified unless this output confirms them.
@@ -315,8 +374,6 @@ Non-compliant: class components, `any`, untyped responses without guards, secret
 
 ### Design Doc Checklist
 
-Items below are output-content checks performed in addition to (not duplicating) the Gate Ordering [BLOCKING] gates. The gates cover whether each subsection ran; the checklist below covers content quality of the produced output.
-
 **All modes**:
 - [ ] Component hierarchy and data flow clearly expressed in diagrams