chati-dev 4.0.2 → 4.0.4

package/framework/agents/build/dev.md

@@ -53,17 +53,49 @@ Implement each task from the approved task breakdown with high quality, followin
 ### Interactive Mode (default)
 ```
 For each task:
-  1. Announce: "Starting {T.X}: {title}"
-  2. Read task details and acceptance criteria
+  1. Announce: "Starting T{X}: {title} — implementing now..."
+  1.5. Pre-Flight Spec Check (BEFORE any code):
+     a. Validate Given-When-Then criteria:
+        → Are all criteria specific and measurable? (not "works correctly", "looks good")
+        → If ANY criterion is vague/untestable → STOP. Escalate G01: "{criterion} is ambiguous."
+        → If task has NO criteria → STOP. Escalate G01: "T{X} has no testable acceptance criteria."
+     b. Check dependencies:
+        → For each T{x}.{y} in Dependencies: is it marked complete in tasks.md?
+        → If dependency incomplete → STOP. Escalate: "Cannot start T{X}: T{dep} not yet complete."
+     c. Set implementation strategy from task size:
+        → XS/S: standard flow — proceed to Step 2
+        → M (2-4h): output brief implementation outline (files + approach), then proceed
+        → L (4-8h): output full implementation plan, ask "[ready/clarify/skip]", wait for user
+     RULE: NEVER write code before Step 1.5 passes. If spec is unclear, fix the spec first.
+     OUTPUT: "Spec check passed. T{X} is {size} — {strategy}."
+  2. Read task details, acceptance criteria, and verify architectural alignment:
+     Before coding, cross-check against chati.dev/artifacts/3-Architecture/architecture.md:
+     - API tasks → endpoint pattern, response format, error handling contract match Section 4?
+     - Database tasks → table/column names, relationships match Section 5 (Data Model)?
+     - Auth tasks → auth approach matches Section 6 (Authentication)?
+     - New modules/components → file structure matches Section 3 (System Components)?
+     If conflict detected → STOP. Escalate G05:
+     "T{X} conflicts with architecture decision: {specific conflict}.
+      Implement per architecture.md or per task spec?"
+     RULE: architecture.md is the source of truth. NEVER implement against architectural decisions.
+     RULE: Do NOT silently reconcile conflicts — always surface them.
+     If no architecture.md present → proceed with best practices, note in handoff.
   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 +103,49 @@ 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)
+    1.5. Pre-Flight Spec Check:
+         → If ANY criterion is vague/untestable → mark task blocked (G01), skip to next task
+         → If task has no Given-When-Then criteria → mark task blocked (G01), skip to next
+         → If dependency not complete → mark task blocked, skip to next independent task
+         → M-size tasks: output implementation outline before coding
+         → L-size tasks: output full implementation plan before coding (no user confirmation)
+    2. Verify architectural alignment (cross-check architecture.md before coding):
+         → API/DB/Auth/module tasks: verify patterns match architecture.md
+         → If conflict → mark task blocked (G05), skip to next task
+         → If no architecture.md → proceed with best practices
+    3. Implement code
+       -> 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 +153,7 @@ WHILE tasks_pending:
     RETURN
 END
 
+run_dev_preview()   // mandatory: start server, show URL, wait for user OK
 transition_to_qa_implementation()
 ```
 
@@ -109,6 +164,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 +174,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 +187,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 +217,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.
 ```
 
 ---
@@ -257,9 +317,11 @@ Criteria:
 6. No lint errors
 7. Self-critique (5.5 + 6.5) completed
 8. No blockers remaining
+9. Pre-flight spec check passed: criteria were specific and testable before coding started
+10. Architectural alignment verified: no G05 conflicts, or G05 explicitly resolved before coding
 
 Score = criteria met / total criteria
-Threshold: >= 95% per task
+Threshold: >= 95% per task (minimum 9/10)
 ```
 
 ---
@@ -300,14 +362,47 @@ agents:
   dev:
     status: in_progress | completed
     score: {average across all tasks}
-    criteria_count: {total criteria across all tasks}
+    criteria_count: 10
     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
 
@@ -316,12 +411,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
 ```
 
 ---
@@ -392,6 +487,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 |
 
 ---
 
@@ -455,7 +551,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. |
 
@@ -484,11 +580,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.
 ```
 
 ---

package/framework/agents/plan/ux.md

@@ -271,7 +271,7 @@ Criteria (binary pass/fail):
 17. Zero banned placeholder content — no lorem ipsum, no "John Doe", domain-realistic sample data used (Directive 5F)
 18. All animations use GPU-only properties (transform/opacity) with reduced-motion alternatives (Directive 5G)
 19. Motion System defined: library specified by stack, animation tokens in Design System Layer 5, scroll animations + micro-interactions catalogued, reduced-motion alternatives provided (Directive 6)
-20. Component discovery completed for all Molecules and Organisms via 21st.dev: each component shows evidence of discovery (adapted from source OR documented "not found" rationale) (Directive 7)
+20. Component Discovery Log complete: EVERY Molecule and Organism in the component map has an entry in the Discovery Log with status (ADOPTED/ADAPTED/CUSTOM) and source or rationale. Any component with no log entry = FAIL for this criterion. Zero silent skips. (Directive 7)
 
 Score = criteria met / total criteria
 Threshold: >= 90% (standard agent tier, 18/20 target)
@@ -284,6 +284,7 @@ Threshold: >= 90% (standard agent tier, 18/20 target)
 ### Artifacts
 1. Save to: `chati.dev/artifacts/4-UX/ux-specification.md`
 2. Save to: `chati.dev/artifacts/4-UX/reference-analysis.md` (if reference URLs provided)
+3. Save to: `chati.dev/artifacts/4-UX/component-discovery-log.md` **(mandatory — criterion #20)**
 
 ```markdown
 # UX Specification — {Project Name}
@@ -367,6 +368,21 @@ Threshold: >= 90% (standard agent tier, 18/20 target)
 ## 7. Responsive Strategy
 {Breakpoints, layout behavior per breakpoint}
 
+## 8. Component Discovery Log
+<!-- MANDATORY (Directive 7) — every Molecule and Organism must have an entry. -->
+<!-- Missing entry = criterion #20 FAILS. Zero silent skips allowed.             -->
+
+| Component | Level | Status | Source / Rationale |
+|-----------|-------|--------|--------------------|
+| {name} | Molecule | ADOPTED | 21st.dev: {component-name} — {URL} |
+| {name} | Molecule | ADAPTED | 21st.dev: {component-name} — customized {what changed} |
+| {name} | Organism | CUSTOM | Not found on 21st.dev — {reason why custom was needed} |
+
+Status legend:
+- **ADOPTED**: Used as-is with only token/color adaptation
+- **ADAPTED**: Pattern reused, significant structural customization
+- **CUSTOM**: Not found (or <50% match) — designed from scratch with documented rationale
+
 ## Traceability
 | Brief User Need | UX Decision |
 |-----------------|-------------|
@@ -1009,8 +1025,49 @@ Search these categories on 21st.dev FIRST (highest reuse potential):
 
 If 21st.dev is unreachable (offline, network issue):
 - Proceed with component design from scratch
+- Mark ALL components as CUSTOM with rationale: "21st.dev unavailable — {reason}"
 - Note in handoff: "21st.dev lookup skipped — {reason}"
 - Agent MUST NOT block pipeline due to external resource unavailability
+- Criterion #20 still passes if ALL molecules/organisms have entries (even if all are CUSTOM)
+
+#### 7E. Discovery Log Format (save to `component-discovery-log.md`)
+
+```markdown
+# Component Discovery Log — {Project Name}
+
+Generated: {date}
+Total components: {N} ({M} Molecules, {K} Organisms)
+Discovery coverage: {X}/{N} (must be 100%)
+
+## Molecules
+
+### {ComponentName}
+- Status: ADOPTED | ADAPTED | CUSTOM
+- Source: {21st.dev URL} | N/A
+- Patterns observed: {what was reused}
+- Adaptations: {what was changed to match our tokens}
+- Rationale (if CUSTOM): {reason no existing component worked}
+
+## Organisms
+
+### {ComponentName}
+- Status: ADOPTED | ADAPTED | CUSTOM
+- Source: {21st.dev URL} | N/A
+- Patterns observed: {what was reused}
+- Adaptations: {what was changed to match our tokens}
+- Rationale (if CUSTOM): {reason no existing component worked}
+
+## Summary
+| Status | Count | % |
+|--------|-------|---|
+| ADOPTED | {n} | {%} |
+| ADAPTED | {n} | {%} |
+| CUSTOM  | {n} | {%} |
+```
+
+**VALIDATION RULE**: Before marking criterion #20 as PASS, count entries in this log.
+Entry count MUST equal Molecule count + Organism count from the component map.
+If any component is missing an entry → criterion #20 = FAIL → do NOT proceed to handoff.
 
 **RULE**: The goal is quality, not compliance. Adapting a premium component is better than
 designing a mediocre custom component. The minimum bar is: every Organism must show evidence

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.0.2"
+version: "4.0.4"
 installed_at: "2026-02-07T10:00:00Z"
-updated_at: "2026-03-21T00:00:00Z"
-installer_version: "4.0.2"
+updated_at: "2026-03-22T00:00:00Z"
+installer_version: "4.0.4"
 project_type: greenfield
 language: en
 ides: [claude-code]

package/framework/domains/agents/dev.yaml

@@ -48,6 +48,19 @@ rules:
     text: "Iterate on implementation until acceptance criteria are met."
     priority: normal
 
+  - id: dev-spec-intake
+    text: "MUST validate task spec BEFORE writing code: verify all Given-When-Then criteria are specific and testable, check all task dependencies are complete. Escalate G01 immediately for ambiguous criteria, G02 for conflicting criteria — NEVER start coding with unclear spec."
+    priority: critical
+
+  - id: dev-size-strategy
+    text: "MUST adapt implementation approach by task size: XS/S = standard flow; M (2-4h) = output implementation outline before coding; L (4-8h) = output implementation plan and ask user confirmation before starting (autonomous mode: output plan and proceed without confirmation)."
+    priority: high
+
+  - id: dev-arch-coherence
+    text: "MUST verify implementation aligns with architecture.md before coding any API endpoints, database schemas, auth flows, or new modules. Escalate G05 immediately if conflict detected. NEVER implement against architectural decisions — always surface conflicts to user."
+    priority: high
+
   # Provider Preference (v3.0.0)
-  - dev-provider: "Default provider: claude. Can run on gemini for large codebase tasks (1M context window)."
+  - id: dev-provider
+    text: "Default provider: claude. Can run on gemini for large codebase tasks (1M context window)."
     priority: normal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "description": "AI-Powered Multi-Agent Orchestration System — Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {
@@ -70,7 +70,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.0.0",
+    "eslint": "^10.1.0",
     "globals": "^17.3.0"
   }
 }