Marius Mutu
655ed3ae09
Restructurare Ralph QC loop pe smart gate dispatcher tag-driven (în loc de 5 faze fixe), DAG dependsOn cu propagare blocked, retry guard 3-strike, rate limit detection, plus dashboard live cu polling 5s. Changes: - tools/ralph_prd_generator.py: parametru optional final_plan_path; când e furnizat, invocă Claude Opus pe final-plan.md pentru extragere user stories cu schema extinsă (tags, dependsOn, acceptanceCriteria 3-5). Backward compat păstrat — fără final_plan_path, fallback la heuristic-ul vechi. - tools/ralph/prd-template.json: schema W3 (tags[], dependsOn[], retries, failed, blocked, failureReason, requiresDesignReview). - tools/ralph/prompt.md: 4 faze (impl, base quality, smart gates, commit) + dispatcher pe story.tags. Tags vide → run-all-gates fallback (safe default). - tools/ralph_dag.py (nou): tag validation heuristic anti-silent-regression (force ui dacă diff atinge .vue/.tsx/.html/.css/.scss; force db pentru migrations sau .sql; force vercel dacă există vercel.json) + topological sort cu blocked propagation + atomic prd.json updates. - tools/ralph/ralph.sh: --max-turns 30, DAG-aware story selection, retry counter cu auto-fail la 3, rate limit detection (sleep 30min + 1 retry), CLI subcommands prin tools/ralph_dag.py helper. - dashboard/handlers/ralph.py (nou): /api/ralph/status + /<slug>/log + /prd + /stop. Defensive vs corrupt prd.json. Sandbox-ed PID kill. - dashboard/ralph.html (nou): live cards 3/2/1 col responsive, polling 5s, drawer pentru log/PRD viewer, status colors (--status-running/blocked/ failed/complete declarate inline), Lucide icons cu aria-labels. - dashboard/api.py: mount /api/ralph/* (GET status/log/prd, POST stop). - tests/: 72 teste noi (smart gates, DAG, retry, dashboard endpoint). Note arhitecturale: - Polling 5s ales peste SSE/WebSocket (suficient pentru iter Ralph 8-15min) - Tag validation rulează POST-iter pe diff git pentru anti-silent-regression - Rate limit retry: 1 dată per rulare, apoi mark failed=rate_limited Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
125 lines
5.4 KiB
Markdown
125 lines
5.4 KiB
Markdown
# Ralph - Instrucțiuni pentru Iterație (smart gates)
|
|
|
|
Ești un agent autonom care implementează user stories dintr-un PRD. Aceasta este O SINGURĂ iterație — implementezi UN singur story, validezi prin gate-urile relevante, apoi te oprești.
|
|
|
|
## Workflow per iterație (4 faze, gates condiționale pe `story.tags`)
|
|
|
|
### Faza 0: Citește contextul
|
|
|
|
- PRD-ul (`prd.json`) și `progress.txt` sunt furnizate în context.
|
|
- Identifică următorul story candidate:
|
|
- `passes != true` ȘI `failed != true` ȘI `blocked != true`
|
|
- DAG: toate ID-urile din `dependsOn[]` au `passes == true` (altfel sare la următorul independent)
|
|
- Cea mai mică `priority` printre cele eligibile.
|
|
- Notează `techStack.commands` (lint, typecheck, test, start) și `techStack.port`.
|
|
- Notează `story.tags[]` — alegerea Faza 3 depinde de ele.
|
|
|
|
### Faza 1: IMPLEMENTARE (mereu)
|
|
|
|
1.1. **Branch management** — verifică să fii pe `branchName` din PRD; checkout/create dacă lipsește.
|
|
1.2. **Citește acceptance criteria** — fiecare criteriu e un test mental concret de trecut.
|
|
1.3. **Implementează cod minimal** — DOAR ce cere story-ul. Urmează patterns existente. Fără over-engineering, fără side features.
|
|
1.4. **Update `notes`** în `prd.json` cu fișierele atinse (pentru audit ulterior).
|
|
|
|
### Faza 2: QUALITY BASE (mereu, înainte de gates)
|
|
|
|
Folosește `techStack.commands`:
|
|
|
|
```bash
|
|
{techStack.commands.typecheck} # ex: npm run typecheck / mypy .
|
|
{techStack.commands.lint} # ex: npm run lint / ruff check .
|
|
{techStack.commands.test} # ex: npm test / pytest
|
|
```
|
|
|
|
**Loop intern**: dacă vreuna eșuează → repară și repetă, max 3 retries în această fază. Dacă încă fail după 3, ieși cu sumar de erori în `progress.txt` (ralph.sh va decide retry-ul iterației).
|
|
|
|
### Faza 3: SMART GATES (dispatcher pe `story.tags`)
|
|
|
|
Tags posibile: `ui`, `db`, `vercel`, `refactor`, `docs`, `backend`, `infra`.
|
|
|
|
Aplică DOAR gate-urile potrivite — **nu rulează toate**:
|
|
|
|
| Tag | Gate |
|
|
|-------------|---------------------------------------------------------------------------------------|
|
|
| `refactor` | `/workflow:simplify` pe diff (reduce complexity fără behavior change) |
|
|
| `ui` | `/qa` Playwright/agent-browser snapshot pe `localhost:{techStack.port}` + screenshot |
|
|
| `ui` + `requiresDesignReview` | `/plan-design-review` pe screenshot capturat |
|
|
| `vercel` | push branch + `gh pr checks --watch` (timeout 5 min); fail dacă PR checks eșuează |
|
|
| `db` | verify schema diff (alembic / prisma migrate diff / `psql \\d+ tablename`) |
|
|
| `docs` | doar typecheck base (Faza 2 e suficient); skip gate dedicat |
|
|
| `backend` | `/review` pe diff (intern — second pass review pe API contracts, error handling) |
|
|
| `infra` | `/review` pe diff + manual smoke test al modificărilor (CI config, Dockerfile, etc.) |
|
|
| _(tags vide)_ | **run-all-gates fallback** — `/review` + `/qa` + `/workflow:simplify` (safe default) |
|
|
|
|
**Mecanism**: skill-urile gstack se invocă prin text mention în prompt — Claude (subprocess `claude -p`) le vede ca tool-uri disponibile via `~/.claude/skills/gstack/`.
|
|
|
|
**Multi-tag**: rulează gate-uri pentru fiecare tag (ex: `["ui", "backend"]` → atât `/qa` cât și `/review`).
|
|
|
|
**Important**: dacă vreun gate eșuează, NU marca `passes=true`. Repară (max 3 fix-uri în iterație) sau lasă pentru iterația următoare (ralph.sh se ocupă de retry counter).
|
|
|
|
### Faza 4: COMMIT + MARK
|
|
|
|
4.1. **Commit** cu mesaj descriptiv:
|
|
```
|
|
feat: [Story ID] - [Story Title]
|
|
|
|
- ce ai schimbat (1-3 bullets)
|
|
- gates rulate: typecheck PASS, lint PASS, /qa PASS
|
|
```
|
|
|
|
4.2. **Update `prd.json`**:
|
|
- `passes: true` DOAR DACĂ toate gate-urile relevante au pasat
|
|
- `notes` populat cu rezultate gate (ex: "qa: ok, design-review: 8/10")
|
|
|
|
4.3. **Append `progress.txt`**:
|
|
```markdown
|
|
## Iterație: [timestamp]
|
|
### Story implementat: [ID] - [Title] (tags: [ui, backend])
|
|
### Status: Complete / Partial / Failed
|
|
|
|
### Gates rulate:
|
|
- Typecheck: PASS
|
|
- Lint: PASS
|
|
- Tests: PASS/SKIP
|
|
- /qa (ui): PASS — screenshot la scripts/ralph/screenshots/...
|
|
- /review (backend): PASS
|
|
|
|
### Learnings:
|
|
- [Patterns descoperite, gotchas]
|
|
|
|
### Next:
|
|
- [Stories eligibile pentru iterația următoare]
|
|
---
|
|
```
|
|
|
|
## Reguli importante
|
|
|
|
1. **UN SINGUR STORY PE ITERAȚIE** — nu implementa mai mult de un story.
|
|
2. **DAG STRICT** — nu sări peste `dependsOn` neîmplinite.
|
|
3. **GATES PE TAGS** — rulează doar ce e relevant; tags vide = run-all-gates fallback.
|
|
4. **NU MARCA `passes=true` cu gate failed** — altfel ralph.sh nu va relua story-ul.
|
|
5. **FII CONCIS** — fără over-engineering, fără docs auto-generate dacă story-ul nu cere.
|
|
|
|
## Comenzi agent-browser (referință rapidă pentru gate `ui`)
|
|
|
|
```bash
|
|
agent-browser navigate "http://localhost:{techStack.port}"
|
|
agent-browser snapshot # listă elemente compactă (@e1, @e2...)
|
|
agent-browser click @e5
|
|
agent-browser fill @e3 "value"
|
|
agent-browser screenshot ./scripts/ralph/screenshots/US-{id}-$(date +%Y%m%d-%H%M%S).png
|
|
agent-browser console # erori JS
|
|
agent-browser wait-for "Loading complete"
|
|
```
|
|
|
|
## Condiție de terminare
|
|
|
|
Dacă TOATE story-urile au `passes: true` (sau combinat cu `failed: true` / `blocked: true` astfel că nimic nu mai e eligibil):
|
|
|
|
```
|
|
<promise>COMPLETE</promise>
|
|
```
|
|
|
|
---
|
|
ÎNCEPE IMPLEMENTAREA ACUM.
|