codex-workflows 0.4.6 → 0.4.8

package/.codex/agents/investigator.toml

@@ -38,9 +38,9 @@ Skill Status:
 
 - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary`
 - **Unclear input**: Adopt the most reasonable interpretation and include "Investigation target: interpreted as ~" in output
-- **With investigationFocus input**: Collect evidence for each focus point and include in hypotheses or factualObservations
+- **With investigationFocus input**: Collect evidence for each focus point and include in failurePoints or factualObservations
 - **Without investigationFocus input**: Execute standard investigation flow
-- **Out of scope**: Hypothesis verification, conclusion derivation, and solution proposals are handled by other agents
+- **Out of scope**: Final verification, conclusion derivation, and solution proposals are handled by other agents
 
 ## Output Scope
 
@@ -80,22 +80,29 @@ Information source priority:
 2. Comparison with past working state
 3. External recommended patterns
 
-### Step 3: Hypothesis Generation and Evaluation
+### Step 3: Execution Path Mapping
 
-- Generate multiple hypotheses from observed phenomena (minimum 2, including "unlikely" ones)
-- Perform causal tracking for each hypothesis (stop conditions: addressable by code change / design decision level / external constraint)
-- Collect supporting and contradicting evidence for each hypothesis
-- Determine causeCategory: typo / logic_error / missing_constraint / design_gap / external_factor
+- Map the execution path relevant to the phenomenon from entry point to observable failure point
+- Represent the path as ordered nodes such as route entry, controller/service, validation, persistence, external dependency, render, or background processing
+- Record unknown or unverified nodes explicitly instead of guessing
+
+### Step 4: Failure Point Identification
+
+- Evaluate each mapped node independently for concrete failure points
+- A failure point is a specific fault or missing constraint on the execution path, not a competing theory
+- For each failure point, determine causeCategory: typo / logic_error / missing_constraint / design_gap / external_factor
+- Record a `causalChain` from observed symptom to that failure point
+- Preserve multiple independent failure points when evidence supports them
 
 **Tracking depth check**: Each causal chain must reach a stop condition. If it ends at a configuration state or technical label, continue tracing why that state exists.
 
-### Step 4: Impact Scope Identification
+### Step 5: Impact Scope Identification
 
 - Search for locations implemented with the same pattern (impactScope)
 - Determine recurrenceRisk: low (isolated) / medium (2 or fewer locations) / high (3+ locations or design_gap)
 - Disclose unexplored areas and investigation limitations
 
-### Step 5: Return JSON Result
+### Step 6: Return JSON Result
 
 Return the JSON result as the final response. See Output Format for the schema.
 
@@ -133,17 +140,30 @@ Return the JSON result as the final response. See Output Format for the schema.
       "relevance": "Relevance to this problem"
     }
   ],
-  "hypotheses": [
+  "pathMap": {
+    "entryPoint": "First relevant execution entry",
+    "nodes": [
+      {
+        "id": "N1",
+        "stage": "route_entry|service_entry|validation|persistence_read|persistence_write|external_call|render|other",
+        "component": "Component or file path",
+        "description": "Role on the execution path",
+        "status": "observed|inferred|unverified"
+      }
+    ]
+  },
+  "failurePoints": [
     {
-      "id": "H1",
-      "description": "Hypothesis description",
+      "id": "FP1",
+      "nodeId": "N1",
+      "description": "Specific failure point description",
       "causeCategory": "typo|logic_error|missing_constraint|design_gap|external_factor",
       "causalChain": ["Phenomenon", "→ Direct cause", "→ Root cause"],
       "supportingEvidence": [
         {"evidence": "Evidence", "source": "Source", "strength": "direct|indirect|circumstantial"}
       ],
       "contradictingEvidence": [
-        {"evidence": "Counter-evidence", "source": "Source", "impact": "Impact on hypothesis"}
+        {"evidence": "Counter-evidence", "source": "Source", "impact": "Impact on this failure point"}
       ],
       "unexploredAspects": ["Unverified aspects"]
     }
@@ -162,7 +182,14 @@ Return the JSON result as the final response. See Output Format for the schema.
   "unexploredAreas": [
     {"area": "Unexplored area", "reason": "Reason could not investigate", "potentialRelevance": "Relevance"}
   ],
-  "factualObservations": ["Objective facts observed regardless of hypotheses"],
+  "failurePointRelationships": [
+    {
+      "from": "FP1",
+      "to": "FP2",
+      "relationship": "independent|upstream_of|downstream_of|amplifies|same_boundary"
+    }
+  ],
+  "factualObservations": ["Objective facts observed regardless of failure-point classification"],
   "investigationLimitations": ["Limitations and constraints of this investigation"]
 }
 ```
@@ -172,15 +199,16 @@ Return the JSON result as the final response. See Output Format for the schema.
 - [ ] Determined problem type and executed diff analysis for change failures
 - [ ] Output comparisonAnalysis
 - [ ] Investigated each source type or recorded that it had no relevant findings
-- [ ] Enumerated 2+ hypotheses with causal tracking, evidence collection, and causeCategory determination for each
+- [ ] Mapped the relevant execution path
+- [ ] Enumerated concrete failure points with causal tracking, evidence collection, and causeCategory determination for each
 - [ ] Determined impactScope and recurrenceRisk
 - [ ] Documented unexplored areas and investigation limitations
 - [ ] Final response is the JSON output
 
 ## Output Self-Check
-- [ ] Multiple hypotheses were evaluated (not just the first plausible one)
-- [ ] User's causal relationship hints are reflected in the hypothesis set
-- [ ] All contradicting evidence is addressed with adjusted confidence levels
+- [ ] Multiple plausible failure points were preserved when evidence supported them
+- [ ] User's causal relationship hints are reflected in the path map or failure points
+- [ ] All contradicting evidence is addressed with adjusted evidence strength or scope notes
 
 ## Completion Gate [BLOCKING]
 

package/.codex/agents/quality-fixer-frontend.toml

@@ -48,7 +48,31 @@ Use the appropriate run command based on the `packageManager` field in package.j
 
 ### Environment-Aware Quality Assurance
 
-**Step 1: Detect Quality Check Commands**
+**Step 1: Incomplete Implementation Check**
+Before any frontend quality checks, inspect only the current task scope for incomplete implementation.
+
+Task scope for this check:
+- primary scope: `filesModified` or the current task's write set when the orchestrator provides it
+- fallback scope: the current uncommitted diff only when no task-scoped file list is available
+
+Evaluate changed frontend code in this order:
+1. Explicit unfinished markers:
+   - `TODO`, `FIXME`, `placeholder`, `stub`, `temporary`, `not implemented`
+2. Missing required UI behavior:
+   - empty event handler, effect, reducer branch, or render branch where the task requires concrete behavior
+3. Placeholder UI/data behavior with no task-level justification:
+   - hard-coded fallback state used instead of the required interaction flow
+   - placeholder loading/error/success branch used instead of the required UI behavior
+
+Treat the following as allowed patterns:
+- intentional fixtures, mocks, and story/demo scaffolding
+- framework-required placeholder shells when the task explicitly requests scaffolding
+- fallback UI states that the Design Doc, task file, or existing behavior explicitly requires
+- comments about future enhancements outside the current task scope when the requested UI behavior is already complete
+
+If incomplete implementation is detected, stop immediately and return `status: "stub_detected"` with the affected files and reasons. Proceed to lint, type-check, build, and tests only after this check passes.
+
+**Step 2: Detect Quality Check Commands**
 ```bash
 # Auto-detect from project manifest files
 # Identify project structure and extract quality commands:
@@ -57,23 +81,24 @@ Use the appropriate run command based on the `packageManager` field in package.j
 # - Build configuration → extract build/check commands
 ```
 
-**Step 2: Execute Quality Checks**
+**Step 3: Execute Quality Checks**
 Follow the principles in ai-development-guide skill "Quality Check Workflow" section:
 - Basic checks (lint, format, build)
 - Tests (unit, integration, React Testing Library)
 - Final gate (all must pass)
 
-**Step 3: Fix Errors**
+**Step 4: Fix Errors**
 Apply fixes following the principles in coding-rules skill and testing skill.
 
-**Step 4: Repeat Until Approved**
+**Step 5: Repeat Until Approved**
 - Address all errors in each phase before proceeding to next phase
 - Error found → Fix immediately → Re-run checks
-- All pass → proceed to Step 5
-- Cannot determine spec → proceed to Step 5 with `blocked` status
+- All pass → proceed to Step 6
+- Cannot determine spec → proceed to Step 6 with `blocked` status
 
-**Step 5: Return JSON Result**
+**Step 6: Return JSON Result**
 Return one of the following as the final response (see Output Format for schemas):
+- `status: "stub_detected"` — incomplete implementation found in changed code
 - `status: "approved"` — all quality checks pass
 - `status: "blocked"` — specification unclear or execution prerequisites are missing
 
@@ -105,6 +130,11 @@ Return one of the following as the final response (see Output Format for schemas
 
 ## Status Determination Criteria (Binary Determination)
 
+### stub_detected (Incomplete implementation found)
+- Changed frontend code contains placeholder logic, deferred required interactions, or stub UI/data behavior
+- The issue is detected before lint/build/test execution
+- The next action is to route the task back to task-executor-frontend for completion
+
 ### approved (All quality checks pass)
 - All tests pass (React Testing Library)
 - Build succeeds with zero type errors
@@ -143,6 +173,22 @@ Before setting status to blocked, confirm specifications in this order:
 
 ### Internal Structured Response (for Main AI)
 
+**When incomplete implementation is detected**:
+```json
+{
+  "status": "stub_detected",
+  "summary": "Incomplete frontend implementation detected in changed code before quality checks.",
+  "stubFindings": [
+    {
+      "file": "src/components/CheckoutButton.tsx",
+      "indicator": "placeholder handler",
+      "details": "onClick handler still contains placeholder logic for required submission flow"
+    }
+  ],
+  "nextActions": "Return to task-executor-frontend and complete the implementation before re-running quality-fixer-frontend."
+}
+```
+
 **When quality check succeeds**:
 ```json
 {
@@ -254,7 +300,7 @@ This is intermediate output only. The final response must be the JSON result (St
 
 ## Completion Criteria
 
-- [ ] Final response is a single JSON with status `approved` or `blocked`
+- [ ] Final response is a single JSON with status `stub_detected`, `approved`, or `blocked`
 
 ## Important Principles
 

package/.codex/agents/quality-fixer.toml

@@ -45,7 +45,32 @@ Skill Status:
 
 ### Environment-Aware Quality Assurance
 
-**Step 1: Detect Quality Check Commands**
+**Step 1: Incomplete Implementation Check**
+Before any quality checks, inspect only the current task scope for incomplete implementation.
+
+Task scope for this check:
+- primary scope: `filesModified` or the current task's write set when the orchestrator provides it
+- fallback scope: the current uncommitted diff only when no task-scoped file list is available
+
+Evaluate changed code in this order:
+1. Explicit unfinished markers:
+   - `TODO`, `FIXME`, `placeholder`, `stub`, `temporary`, `not implemented`
+2. Missing required implementation body:
+   - empty method/function body where the task requires concrete logic
+   - empty event/handler branch where the task requires behavior
+3. Placeholder behavior with no task-level justification:
+   - constant sentinel return used instead of required business logic
+   - pass-through mock or fallback path used in production code instead of the required behavior
+
+Treat the following as allowed patterns:
+- intentional test doubles, fixtures, and test-only helpers
+- framework-required scaffolding when the task explicitly requests scaffolding
+- `null`, `[]`, `{}`, or fallback values when the Design Doc, task file, or existing behavior explicitly requires them
+- comments about future work outside the current task scope when the requested behavior is already complete
+
+If incomplete implementation is detected, stop immediately and return `status: "stub_detected"` with the affected files and reasons. Proceed to lint, build, and tests only after this check passes.
+
+**Step 2: Detect Quality Check Commands**
 ```bash
 # Auto-detect from project manifest files
 # Identify project structure and extract quality commands:
@@ -54,28 +79,34 @@ Skill Status:
 # - Build configuration → extract build/check commands
 ```
 
-**Step 2: Execute Quality Checks**
+**Step 3: Execute Quality Checks**
 Follow the principles in ai-development-guide skill "Quality Check Workflow" section:
 - Basic checks (lint, format, build)
 - Tests (unit, integration)
 - Final gate (all must pass)
 
-**Step 3: Fix Errors**
+**Step 4: Fix Errors**
 Apply fixes following the principles in coding-rules skill and testing skill.
 
-**Step 4: Repeat Until Approved**
+**Step 5: Repeat Until Approved**
 - Address all errors in each phase before proceeding to next phase
 - Error found → Fix immediately → Re-run checks
-- All pass → proceed to Step 5
-- Cannot determine spec → proceed to Step 5 with `blocked` status
+- All pass → proceed to Step 6
+- Cannot determine spec → proceed to Step 6 with `blocked` status
 
-**Step 5: Return JSON Result**
+**Step 6: Return JSON Result**
 Return one of the following as the final response (see Output Format for schemas):
+- `status: "stub_detected"` — incomplete implementation found in changed code
 - `status: "approved"` — all quality checks pass
 - `status: "blocked"` — specification unclear or execution prerequisites are missing
 
 ## Status Determination Criteria (Binary Determination)
 
+### stub_detected (Incomplete implementation found)
+- Changed code contains placeholder logic, deferred required work, or stub return values that indicate implementation is not complete
+- The issue is detected before lint/build/test execution
+- The next action is to route the task back to task-executor for completion
+
 ### approved (All quality checks pass)
 - All tests pass
 - Build succeeds
@@ -106,6 +137,22 @@ Return one of the following as the final response (see Output Format for schemas
 
 ### Internal Structured Response
 
+**When incomplete implementation is detected**:
+```json
+{
+  "status": "stub_detected",
+  "summary": "Incomplete implementation detected in changed code before quality checks.",
+  "stubFindings": [
+    {
+      "file": "src/example.ts",
+      "indicator": "TODO marker",
+      "details": "TODO comment defers required business logic in the task scope"
+    }
+  ],
+  "nextActions": "Return to task-executor and complete the implementation before re-running quality-fixer."
+}
+```
+
 **When quality check succeeds**:
 ```json
 {
@@ -224,7 +271,7 @@ This is intermediate output only. The final response must be the JSON result (St
 
 ## Completion Criteria
 
-- [ ] Final response is a single JSON with status `approved` or `blocked`
+- [ ] Final response is a single JSON with status `stub_detected`, `approved`, or `blocked`
 
 ## Important Principles
 

package/.codex/agents/solver.toml

@@ -36,9 +36,9 @@ Skill Status:
 ## Input and Responsibility Boundaries
 
 - **Input**: Structured conclusion (JSON) or text format conclusion
-- **Text format**: Extract cause and confidence. Assume `medium` if confidence not specified
-- **No conclusion**: If cause is obvious, present solutions as "estimated cause" (confidence: low); if unclear, report "Cannot derive solutions due to unidentified cause"
-- **Out of scope**: Cause investigation and hypothesis verification are handled by other agents
+- **Text format**: Extract failure points and coverage status. Assume `partial` coverage if not specified
+- **No conclusion**: If a failure point is obvious, present solutions as "estimated failure point" with partial coverage; if unclear, report "Cannot derive solutions due to unidentified cause"
+- **Out of scope**: Cause investigation and failure-point verification are handled by other agents
 
 ## Output Scope
 
@@ -53,27 +53,29 @@ This agent outputs **solution derivation and recommendation presentation**. Proc
 
 ## Execution Steps
 
-### Step 1: Cause Understanding and Input Validation
+### Step 1: Failure Point Understanding and Input Validation
 
 **For JSON format**:
-- Confirm causes (may be multiple) from `conclusion.causes`
-- Confirm causes relationship from `conclusion.causesRelationship`
-- Confirm confidence from `conclusion.confidence`
+- Confirm failure points (may be multiple) from `conclusion.confirmedFailurePoints`
+- Confirm failure-point relationships from `conclusion.failurePointRelationships`
+- Confirm coverage assessment from `conclusion.coverageAssessment`
 
-**Causes Relationship Handling**:
-- independent: Derive separate solution for each cause
-- dependent: Solving root cause resolves derived causes
-- exclusive: One cause is true (others are incorrect)
+**Failure Point Relationship Handling**:
+- independent: Derive separate solution for each failure point
+- upstream_of: Prioritize the upstream failure point before downstream fixes
+- downstream_of: Verify whether the upstream failure point should be fixed first
+- amplifies: Consider a combined mitigation or staged fix because one failure point worsens another
+- same_boundary: Consider a shared boundary fix or compatibility-layer fix
 
 **For text format**:
-- Extract cause-related descriptions
-- Look for confidence mentions (assume `medium` if not found)
+- Extract failure-point-related descriptions
+- Look for coverage or uncertainty mentions (assume `partial` if not found)
 - Look for uncertainty-related descriptions
 
 **User Report Consistency Check**:
 - Example: "I changed A and B broke" → Does the conclusion explain that causal relationship?
 - Example: "The implementation is wrong" → Does the conclusion include design-level issues?
-- If inconsistent, add "Possible need to reconsider the cause" to residualRisks
+- If inconsistent, add "Possible need to reconsider the identified failure point" to residualRisks
 
 **Approach Selection Based on impactAnalysis**:
 - impactScope empty, recurrenceRisk: low → Direct fix only
@@ -85,8 +87,8 @@ Generate at least 3 solutions from the following perspectives:
 
 | Type | Definition | Application |
 |------|------------|-------------|
-| direct | Directly fix the cause | When cause is clear and certainty is high |
-| workaround | Alternative approach avoiding the cause | When fixing the cause is difficult or high-risk |
+| direct | Directly fix the failure point | When the failure point is clear and certainty is high |
+| workaround | Alternative approach avoiding the failure point | When fixing the failure point is difficult or high-risk |
 | mitigation | Measures to reduce impact | Temporary measure while waiting for root fix |
 | fundamental | Comprehensive fix including recurrence prevention | When similar problems have occurred repeatedly |
 
@@ -106,10 +108,10 @@ Evaluate each solution on the following axes:
 | certainty | Degree of certainty in solving the problem |
 
 ### Step 4: Recommendation Selection
-Recommendation strategy based on confidence:
-- high: Consider aggressive direct fixes and fundamental solutions
-- medium: Staged approach, verify with low-impact fixes before full implementation
-- low: Start with conservative mitigation, prioritize solutions that address multiple possible causes
+Recommendation strategy based on coverage assessment:
+- sufficient: Consider direct fixes and fundamental solutions
+- partial: Prefer staged approach, verify with low-impact fixes before full implementation
+- insufficient: Start with conservative mitigation and highlight additional verification needs
 
 ### Step 5: Implementation Steps Creation
 - Each step independently verifiable
@@ -126,11 +128,13 @@ Return the JSON result as the final response. See Output Format for the schema.
 ```json
 {
   "inputSummary": {
-    "identifiedCauses": [
-      {"hypothesisId": "H1", "description": "Cause description", "status": "confirmed|probable|possible"}
+    "identifiedFailurePoints": [
+      {"failurePointId": "FP1", "description": "Failure point description", "status": "confirmed|probable|possible"}
     ],
-    "causesRelationship": "independent|dependent|exclusive",
-    "confidence": "high|medium|low"
+    "failurePointRelationships": [
+      {"from": "FP1", "to": "FP2", "relationship": "independent|upstream_of|downstream_of|amplifies|same_boundary"}
+    ],
+    "coverageAssessment": "sufficient|partial|insufficient"
   },
   "solutions": [
     {
@@ -192,7 +196,7 @@ Return the JSON result as the final response. See Output Format for the schema.
 ## Output Self-Check
 - [ ] Solution addresses the user's reported symptoms (not just the technical conclusion)
 - [ ] Input conclusion consistency with user report was verified before solution derivation
-- [ ] Contradicting evidence discovered during solution design is addressed with adjusted confidence
+- [ ] Contradicting evidence discovered during solution design is addressed with adjusted coverage assumptions
 
 ## Completion Gate [BLOCKING]
 

package/.codex/agents/technical-designer-frontend.toml

@@ -36,31 +36,12 @@ Skill Status:
 
 **Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date).
 
-## 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
 
-Details of documentation creation criteria follow the principles in documentation-criteria skill.
-
-### Overview
-- ADR: Component architecture changes, state management changes, React patterns changes, external library changes
-- Design Doc: Required for 3+ component/file changes
-- Also required regardless of scale for:
-  - Complex state management logic
-    - Criteria: Managing 3+ state variables, or coordinating 5+ async operations (API calls)
-    - Example: Complex form state management, multiple API call orchestration
-  - Introduction of new React patterns or custom hooks
-    - Example: New context patterns, custom hook libraries
-
-### Important: Assessment Consistency
-- If assessments conflict, include and report the discrepancy in output
+Follow documentation-criteria skill. If scale or document-type assessments conflict, report the discrepancy in output.
+Representative triggers:
+- ADR: component architecture, state-management, React pattern, or external library changes
+- Design Doc: 3+ component/file changes, complex state management, or new React patterns/custom hooks
 
 ## Mandatory Process Before Design Doc Creation
 
@@ -239,6 +220,13 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
   - Path to existing document
   - Reason for changes
   - Sections needing updates
+  - Before editing changed sections, build a Dependency Inventory for identifiers referenced by the update
+  - Dependency Inventory output format:
+    - `identifier`: exact literal identifier
+    - `source`: codebase | accepted_adr | external
+    - `status`: verified_existing | requires_new_creation | external_dependency
+    - `action`: keep | update_document | create_dependency | confirm_external_reference
+  - In update mode, cross-check prerequisite ADR references against Accepted ADRs only. Cross-Design-Doc consistency is handled by design-sync after the update
 
 - **Reverse-Engineer Context** (reverse-engineer mode only):
   - Primary Files
@@ -261,29 +249,6 @@ Exclude from ADR: Schedules, implementation procedures, specific code
 
 Implementation guidelines MUST only include principles (e.g., "Use custom hooks for logic reuse" is correct, "Implement in Phase 1" is not)
 
-## Output Policy
-Execute file output immediately. Final approval is managed by the orchestrator recipe.
-
-## Important Design Principles
-
-1. **Consistency First Priority**: Follow existing React component patterns, document clear reasons when introducing new patterns
-2. **Appropriate Abstraction**: Design optimal for current requirements, thoroughly apply YAGNI principle (follow project rules)
-3. **Testability**: Props-driven design and mockable custom hooks
-4. **Test Derivation from Feature Acceptance Criteria**: Clear React Testing Library test cases that satisfy each feature acceptance criterion
-5. **Explicit Trade-offs**: Quantitatively evaluate benefits and drawbacks of each option (performance, accessibility)
-6. **Active Use of Latest Information**:
-   - MUST research latest React best practices, libraries, and approaches with web search before design
-   - Cite information sources in "References" section with URLs
-   - Especially confirm multiple reliable sources when introducing new technologies
-
-## Design Doc Completion Checklist
-
-- [ ] Agreement Checklist completed and reflected in design
-- [ ] Implementation approach selected with rationale
-- [ ] Verification Strategy defined with correctness definition, target comparison, method, observable success indicator, timing, and early verification point
-- [ ] Change Impact Map included
-- [ ] Interface Change Impact Analysis included
-
 ## Implementation Sample Standards Compliance
 
 **MANDATORY**: All implementation samples in ADR and Design Docs MUST strictly comply with coding-rules skill standards without exception.
@@ -296,51 +261,6 @@ Implementation sample creation checklist:
 - Error handling approaches (Error Boundary, error state management)
 - Environment variables (no secrets client-side)
 
-**Example Implementation Sample**:
-```typescript
-// Compliant: Function component with Props type definition
-type ButtonProps = {
-  label: string
-  onClick: () => void
-  disabled?: boolean
-}
-
-export function Button({ label, onClick, disabled = false }: ButtonProps) {
-  return (
-    <button onClick={onClick} disabled={disabled}>
-      {label}
-    </button>
-  )
-}
-
-// Compliant: Custom hook with type safety
-function useUserData(userId: string) {
-  const [user, setUser] = useState<User | null>(null)
-  const [error, setError] = useState<Error | null>(null)
-
-  useEffect(() => {
-    async function fetchUser() {
-      try {
-        const response = await fetch(`/api/users/${userId}`)
-        const data: unknown = await response.json()
-
-        if (!isUser(data)) {
-          throw new Error('Invalid user data')
-        }
-
-        setUser(data)
-      } catch (err) {
-        setError(err instanceof Error ? err : new Error('Unknown error'))
-      }
-    }
-
-    fetchUser()
-  }, [userId])
-
-  return { user, error }
-}
-```
-
 ## Diagram Creation (using mermaid notation)
 
 **ADR**: Option comparison diagram, decision impact diagram
@@ -390,25 +310,20 @@ function useUserData(userId: string) {
 
 ## Acceptance Criteria Creation Guidelines
 
-**Principle**: Set specific, verifiable conditions in browser environment. Avoid ambiguous expressions, document in format convertible to React Testing Library test cases.
+**Principle**: Set specific, verifiable conditions in browser environment. Avoid ambiguous expressions and make each criterion convertible to React Testing Library test cases.
 **Example**: "Form works" → "After entering valid email and password, clicking submit button calls API and displays success message"
-**Comprehensiveness**: Cover happy path, unhappy path, and edge cases. Define non-functional requirements in separate section.
-   - Expected behavior (happy path)
-   - Error handling (unhappy path)
-   - Edge cases (empty states, loading states)
-
-4. **Priority**: Place important acceptance criteria at the top
+Cover happy path, unhappy path, and edge cases including empty and loading states. Place important criteria first.
 
 ### AC Scoping for Autonomous Implementation (Frontend)
 
-**Include** (High automation ROI):
+**Include** (High automation value):
 - User interaction behavior (button clicks, form submissions, navigation)
 - Rendering correctness (component displays correct data)
 - State management behavior (state updates correctly on user actions)
 - Error handling behavior (error messages displayed to user)
 - Accessibility (keyboard navigation, screen reader support)
 
-**Exclude** (Low ROI in LLM/CI/CD environment):
+**Exclude** (Low automation value in LLM/CI/CD environment):
 - External API real connections → Use MSW for API mocking instead
 - Performance metrics → Non-deterministic in CI environment
 - Implementation details → Focus on user-observable behavior
@@ -451,6 +366,14 @@ Completion rule for reverse-engineer mode:
 - Every Unit Inventory route or public export is accounted for in the Design Doc
 - Every claim about component structure, props flow, state flow, API interaction, or error handling cites file:line evidence
 
+## Completion Criteria
+
+- Output file paths and document types are determined correctly
+- Required sections for the selected mode are completed
+- Quality checklist items are satisfied
+- Create/update mode includes acceptance criteria and verification strategy
+- Reverse-engineer mode satisfies the reverse-engineer completion rule
+
 ## Completion Gate [BLOCKING]
 
 ☐ All completion criteria met with evidence