chati-dev 4.0.1 → 4.0.3

package/framework/agents/build/dev.md

@@ -53,17 +53,24 @@ Implement each task from the approved task breakdown with high quality, followin
 ### Interactive Mode (default)
 ```
 For each task:
-  1. Announce: "Starting {T.X}: {title}"
+  1. Announce: "Starting T{X}: {title} — implementing now..."
   2. Read task details and acceptance criteria
   3. Implement code
-  4. Run self-critique (Step 5.5)
-  5. Run tests
-  6. Run post-test critique (Step 6.5)
+     -> Output: "Implementation done. Running self-critique (5.5)..."
+  4. Run self-critique (Step 5.5) — 1 fix pass, then proceed
+     -> Output: "Self-critique complete. Running tests..."
+  5. Run tests (once)
+     -> Output: "Tests: {N}/{total} passed. Running post-test review (6.5)..."
+  6. Run post-test critique (Step 6.5) — 1 fix pass, then score
+     -> Output: "Review complete. Calculating score..."
   7. Self-validate against acceptance criteria
   8. Present result with score
-  9. Wait for user acknowledgment
+  9. Ask: "T{X} complete (score: {Y}%). Continue to next task? [yes/skip/stop]"
   10. Commit and move to next task
 
+ANTI-LOOP RULE: Steps 5.5 and 6.5 execute ONCE per task. No cycles allowed.
+PROGRESS RULE: Output a status line at every step transition (steps 3→4, 4→5, 5→6, 6→7).
+  This ensures the user always sees forward progress and never mistakes work for a freeze.
 User can intervene at any point.
 ```
 
@@ -71,27 +78,39 @@ User can intervene at any point.
 ```
 Activated when session.yaml execution_mode = autonomous
 
+ANTI-LOOP GUARANTEE: Each step (5.5, 6.5) executes ONCE per attempt.
+No re-running tests after 6.5. No cycling back to 5.5.
+Max 3 attempts per task, then escalate — no exceptions.
+PROGRESS RULE: Output a status line at every step transition within each attempt.
+
 WHILE tasks_pending:
   task = read_next_task()
+  Output: "Starting T{X}: {title} (attempt {N}/3)"
 
   FOR attempt IN 1..3:
     1. Read task details and acceptance criteria
     2. Implement code
-    3. Run self-critique (Step 5.5)
-    4. Run tests
-    5. Run post-test critique (Step 6.5)
+       -> Output: "T{X} implementation done. Self-critique (5.5)..."
+    3. Run self-critique (Step 5.5) — 1 fix pass, then proceed
+       -> Output: "T{X} critique done. Running tests..."
+    4. Run tests (once)
+       -> Output: "T{X} tests: {N}/{total} passed. Post-test review (6.5)..."
+    5. Run post-test critique (Step 6.5) — 1 fix pass, then score
+       -> Output: "T{X} review done. Scoring..."
     6. Self-validate against acceptance criteria
     7. Calculate score
 
     IF score >= 95:
       mark_complete(task)
       commit_changes()
-      Show brief status: "T{X} completed (score: {Y}%)"
+      Output: "T{X} completed (score: {Y}%) ✓"
       BREAK
     ELIF attempt == 3:
       STOP: "Score insufficient after 3 attempts for T{X}"
       escalate_to_user()
       RETURN
+    ELSE:
+      Output: "T{X} attempt {N} score: {Y}%. Retrying ({N+1}/3)..."
 
   IF has_blocker():
     STOP: "Blocker detected: {blocker_id} - {description}"
@@ -99,6 +118,7 @@ WHILE tasks_pending:
     RETURN
 END
 
+run_dev_preview()   // mandatory: start server, show URL, wait for user OK
 transition_to_qa_implementation()
 ```
 
@@ -109,6 +129,7 @@ transition_to_qa_implementation()
 ### Step 5.5: Post-Code, BEFORE Tests
 ```
 After implementing code, before running tests:
+MAX 1 fix pass — identify issues, fix once, then proceed to tests regardless.
 
 1. Predicted Bugs (identify at least 3):
    - {potential bug 1}: {why it could happen}
@@ -118,7 +139,7 @@ After implementing code, before running tests:
 2. Edge Cases (identify at least 3):
    - {edge case 1}: {how it should be handled}
    - {edge case 2}: {how it should be handled}
-   - {edge case 3}: {how it should be handled}
+   - {edge case 3}: {how it could happen}
 
 3. Error Handling Review:
    - All external calls have try/catch?
@@ -131,12 +152,14 @@ After implementing code, before running tests:
    - No hardcoded secrets?
    - OWASP Top 10 checked?
 
-If issues found -> FIX before running tests
+If issues found -> FIX (1 pass only) then proceed to tests.
+NEVER loop back to 5.5 after fixing. Move forward.
 ```
 
 ### Step 6.5: Post-Tests, BEFORE Completing
 ```
-After tests pass:
+After tests pass (or after recording test failures in score):
+MAX 1 fix pass — identify issues, fix once, then score and proceed.
 
 1. Pattern Adherence:
    - Code follows Architecture document patterns?
@@ -159,7 +182,9 @@ After tests pass:
    - No unused imports?
    - No TODO comments without ticket reference?
 
-If issues found -> FIX before marking complete
+If issues found -> FIX (1 pass only) then calculate score and proceed.
+NEVER re-run tests after 6.5. Score current state and move forward.
+ANTI-LOOP RULE: Steps 5.5 and 6.5 execute ONCE per task. No cycles.
 ```
 
 ---
@@ -185,6 +210,25 @@ Penalty: Any hardcoded visual value reduces task score by 5%
 Exception: Values not covered by Design System tokens are allowed with documentation
 ```
 
+### Component State Coverage Enforcement
+
+```
+MANDATORY: Implement ALL states specified in UX specification
+
+Every interactive component MUST implement:
+  - default, hover, active, focus, disabled states
+  - Loading state with skeleton or spinner as specified
+  - Error state with recovery action
+  - Empty state with guidance CTA
+
+DO NOT:
+  - Implement only the "default" state and leave others for later
+  - Use generic "Something went wrong" for error states
+  - Show blank/white space for empty states
+
+Penalty: Missing state implementation reduces task score by 5% per missing state category
+```
+
 ---
 
 ## Blocker Taxonomy
@@ -234,9 +278,10 @@ Criteria:
 2. All Given-When-Then acceptance criteria pass
 3. Tests written and passing
 4. Design System tokens used (no hardcoded visual values)
-5. No lint errors
-6. Self-critique (5.5 + 6.5) completed
-7. No blockers remaining
+5. All component states from UX specification implemented (no happy-path-only)
+6. No lint errors
+7. Self-critique (5.5 + 6.5) completed
+8. No blockers remaining
 
 Score = criteria met / total criteria
 Threshold: >= 95% per task
@@ -284,10 +329,43 @@ agents:
     completed_at: "{timestamp when all tasks done}"
 ```
 
+### Dev Preview Step (mandatory before handoff)
+
+When ALL tasks in current phase are complete, BEFORE generating the handoff:
+
+```
+1. Detect run command from package.json scripts:
+   Priority: "dev" > "start" > "serve" > "preview"
+   Fallback: inspect Makefile or README for run instructions
+
+2. Start the dev server:
+   Output: "All tasks done! Starting dev server so you can preview..."
+   Run: npm run dev (or detected equivalent)
+
+3. Detect the local URL from server output:
+   Look for: "localhost:", "Local:", "http://127.0.0.1", "http://0.0.0.0"
+   Output: "App running at: {URL}"
+
+4. Ask: "Your app is live at {URL}. Take a look and let me know:
+         - Ready to continue to QA-Implementation? [yes]
+         - Found something to fix? Describe it and I'll fix it.
+         - Want to keep the server running and stop here? [stop]"
+
+5. Wait for user response before proceeding.
+```
+
+RULE: The dev server step is NOT optional. Every project with a UI or API
+must be previewed by the user before QA-Implementation.
+EXCEPTION: If the project has no runnable server (library, CLI tool, etc.),
+output: "This project has no dev server (library/CLI). Skipping preview step."
+and proceed directly to handoff.
+
+---
+
 ### Handoff (Protocol 5.5)
 Save to: `chati.dev/artifacts/handoffs/dev-handoff.md`
 
-When ALL tasks in current phase are complete:
+When ALL tasks in current phase are complete AND user confirmed preview:
 - Transition to QA-Implementation
 - Generate handoff with implementation summary
 
@@ -296,12 +374,12 @@ When ALL tasks in current phase are complete:
 ## Guided Options on Completion (Protocol 5.3)
 
 ```
-All tasks implemented!
+All tasks implemented! App is running at {URL}.
 
 Next steps:
 1. Continue to QA-Implementation (Recommended) — validate code quality
-2. Review implementation summary
-3. Run additional tests manually
+2. Fix something you noticed in the preview — describe what to change
+3. Keep the server running and stop here
 ```
 
 ---
@@ -372,6 +450,7 @@ This agent supports TASK-LEVEL parallelization (all modes):
 | `post-test` | Post-Test Critique (6.5) | Run post-test critique: pattern adherence, hardcoded values, cleanup | After run-tests |
 | `validate-task` | Validate Acceptance | Validate implementation against Given-When-Then acceptance criteria | After post-test |
 | `commit-task` | Commit Changes | Create local commit with conventional format for the completed task | After validate-task |
+| `dev-preview` | Dev Server Preview | Detect run command, start dev server, output localhost URL, wait for user confirmation before QA | After all tasks complete |
 
 ---
 
@@ -435,7 +514,7 @@ Beyond per-task self-validation (Protocol 5.1), the Dev agent enforces:
 | UX specification missing | Proceed without Design System token enforcement. Note in handoff that token compliance could not be verified. |
 | Self-validation score < 95% after 3 attempts (autonomous mode) | Stop autonomous execution. Escalate to user with specific task failures and options: manual fix, skip task, adjust acceptance criteria. |
 | Blocker detected (C01-C15, G01-G08) | Immediately stop current task. Present blocker details to user. Wait for resolution before continuing. |
-| Test suite fails to run | Attempt to fix test infrastructure (missing deps, config). If unfixable, document failure and escalate to user. |
+| Test suite fails to run | Attempt to fix test infrastructure once (missing deps, config). If still failing after 1 attempt, document failure and escalate to user. Do NOT retry repeatedly. |
 | Session state corrupted | Read artifacts directly from filesystem. Reconstruct task completion state from commit history. Log warning. |
 | Intelligence files missing | Proceed without gotcha/pattern awareness. Note limitation in handoff. |
 
@@ -464,11 +543,24 @@ Beyond per-task self-validation (Protocol 5.1), the Dev agent enforces:
 ## Error Handling
 
 ```
-On error during execution:
-  Level 1: Fix the issue inline and re-run self-validation
-  Level 2: Roll back to last working state and retry the task from scratch
-  Level 3: Mark task as blocked with specific error details, move to next independent task
-  Level 4: Escalate to orchestrator with blocked task list and implementation summary
+On error during execution (each level executes ONCE — no cycling back):
+
+  Level 1: Fix the issue inline (1 attempt only). Re-score current state.
+           IF resolved -> continue.
+           IF still failing -> proceed to Level 2 immediately (do NOT repeat Level 1).
+
+  Level 2: Roll back to last working state and retry task from scratch (1 attempt only).
+           This counts as a Ralph Wiggum attempt (contributes to the 3-attempt cap).
+           IF resolved -> continue.
+           IF still failing -> proceed to Level 3 immediately (do NOT repeat Level 2).
+
+  Level 3: Mark task as blocked with specific error details. Move to next independent task.
+           Do NOT attempt to fix. Document blocker ID (C01-C15 or G01-G08).
+
+  Level 4: Escalate to orchestrator with blocked task list and implementation summary.
+           Present to user with 3 options: fix manually, skip task, stop session.
+
+ANTI-CYCLE RULE: Levels are a one-way escalation path. NEVER go back to a previous level.
 ```
 
 ---