opalacoder 0.1.0__tar.gz → 0.1.3__tar.gz

opalacoder-0.1.3/.claude/settings.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -A 30 \"checkAndEnforceHardFail\\\\|improve.*loop\\\\|composite.*tool\" /tmp/smallcode/bin/smallcode.js | head -60)",
+      "Read(//tmp/smallcode/bin/**)",
+      "Bash(python -c ' *)",
+      "Read(//home/gilzamir/**)",
+      "Bash(sed -n '/DEBUG PLAN JSON/,/\\\\/DEBUG PLAN JSON/p' /home/gilzamir/log.log)",
+      "Read(//home/gilzamir/micalc/**)",
+      "Bash(git stash *)",
+      "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm and asyncio\")",
+      "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm\")",
+      "Bash(python -m pytest tests/test_workflow_pipeline.py tests/test_verification_strategies.py -q -k \"asyncio or \\(not llm\\)\")",
+      "Bash(python -m pytest tests/ -x -q)"
+    ],
+    "additionalDirectories": [
+      "/home/gilzamir"
+    ]
+  }
+}

opalacoder-0.1.3/.gitignore

@@ -0,0 +1,128 @@
+# --- Project-specific ---
+*.env
+.env
+*.env*
+.venv
+*.venv
+node_modules/
+plan.md
+
+# --- Project runtime data ---
+.opalacoder/
+
+# --- Python bytecode & caches ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+
+# --- C extensions ---
+*.so
+
+# --- Distribution / packaging ---
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- PyInstaller ---
+*.manifest
+*.spec
+
+# --- Installer logs ---
+pip-log.txt
+pip-delete-this-directory.txt
+
+# --- Testing & coverage ---
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# --- Translations ---
+*.mo
+*.pot
+
+# --- Databases ---
+*.sqlite
+*.sqlite3
+*.sqlite3-journal
+*.sqlite-shm
+*.sqlite-wal
+
+# --- Logging ---
+*.log
+
+# --- Virtual environments ---
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# --- Jupyter ---
+.ipynb_checkpoints
+
+# --- IPython ---
+profile_default/
+ipython_config.py
+
+# --- PEP 582 ---
+__pypackages__/
+
+# --- Type checkers ---
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# --- Build tools ---
+.pybuilder/
+target/
+cython_debug/
+docs/_build/
+/site
+
+# --- Misc Python tools ---
+.scrapy
+instance/
+.webassets-cache
+celerybeat-schedule
+celerybeat.pid
+*.sage.py
+.spyderproject
+.spyproject
+.ropeproject
+local_settings.py
+
+# --- IDEs / Editors ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+*.db

opalacoder-0.1.0/AGENT.md → opalacoder-0.1.3/AGENTS.md

@@ -1,3 +1,7 @@
+# General Rules
+
+1. Don't make baseless assumptions; before drawing any conclusions, conduct tests and analysis to gather as much information as possible.
+
 # Project Guide
 
 ## Language

opalacoder-0.1.3/ARCH_SUMMARY.md

@@ -0,0 +1,201 @@
+# OpalaCoder — Architecture Summary
+
+## Focus
+
+OpalaCoder is designed to work with **small language models** (e.g. Ministral-3 14B, Gemma 4 via Ollama) as its primary target. The core design prioritizes correctness and usability under constrained context windows and limited reasoning capacity. Larger models are supported as an alternative for complex tasks via the `alternative` key in `agents.yaml`.
+
+## Core Idea: Project-Centric Context Management
+
+The central abstraction is the **project**, not the session. Every interaction happens within a named project that has a fixed filesystem path. This design exists for one reason: **context management**.
+
+Small models degrade quickly when context is large, mixed, or unbounded. By anchoring all activity to a project, OpalaCoder can:
+
+- Inject a stable, minimal project header (`[PROJECT: name | PATH: /path]`) into every prompt instead of growing conversation state
+- Load only the skills relevant to that project type (selected at creation, not dynamically per-request)
+- Scope all file reads, writes, and commands to the project directory, eliminating ambiguity
+- Persist history, plan state, and skill configuration per project in SQLite, keeping each LLM call focused
+
+## Architecture
+
+```
+CLI (cli.py)
+ ├── startup_menu()          — load or create project
+ ├── _create_project()       — name + path + description → LLM selects skills
+ └── repl_loop()             — main REPL; loads project-scoped skills once
+      ├── REPLState           — session container; holds chat_agent, intent_classifier,
+      │                         complexity_evaluator (created once, reused per turn)
+      ├── run_pipeline()      — triggers orchestration for planning tasks
+      │    └── get_orchestrator(strategy)     — reads strategy from agents.yaml,
+      │         └── OrchestratorRegistry      looks up registered class, instantiates it
+      │              └── WorkflowOrchestratorStrategy  (default: strategy: workflow)
+      │                   ├── _plan_and_refine()    phase 1+2: panorama + user refinement
+      │                   └── _orchestration_loop() phase 3: Plan→Execute→Verify
+      │                        ├── _oracle(PlanOutput)   — task decomposition
+      │                        ├── _run_worker(task)     — per-command LLMAgentBlock
+      │                        └── _oracle(VerifyOutput) — acceptance check
+      └── chat_agent          — conversational assistant with memory
+
+Orchestrator Registry (orchestrator.py)
+ ├── register_orchestrator(name)  — class decorator; maps name → strategy class
+ ├── get_orchestrator(name, model)— instantiates registered strategy; raises ValueError
+ │                                  for unknown names (fails loudly on misconfiguration)
+ ├── CHECKPOINT_SUBPATH           — shared constant ".opalacoder/session_state.json"
+ └── BaseOrchestratorStrategy     — abstract base; subclasses implement run()
+
+WorkflowOrchestratorStrategy (workflow_orchestrator.py)
+ ├── Task schema (Pydantic)
+ │    ├── id             — short unique identifier (t1, t2, ...)
+ │    ├── goal           — one-sentence objective: what + why
+ │    ├── commands       — ordered list of atomic worker steps
+ │    ├── related_files  — files worker must read before acting
+ │    ├── context        — operational detail: class names, IDs, APIs, contracts
+ │    │                    (field_validator coerces dict/list → JSON string for
+ │    │                    models that generate object-typed context)
+ │    └── depends_on     — explicit ordering between tasks
+ ├── _validate_task()     — semantic guardrail: rejects empty goal/commands/context
+ │                          and CSS/JS tasks without related_files
+ ├── _oracle()            — litellm call with JSON mode + structural + semantic reflection
+ │                          DEBUG prints raw content/reasoning per attempt to stderr
+ ├── _run_worker()        — iterates task.commands; each command = one LLMAgentBlock call
+ │                          with context_block preamble (TASK GOAL / RELATED FILES /
+ │                          CONTEXT / COMMAND) injected into every worker prompt
+ │                          Worker uses termination_tools=["send_message"] so the loop
+ │                          stops immediately when send_message is called
+ └── _planner_system()    — system prompt with full Task schema + field rules + examples
+                            includes hard rule: redeclaration fix = delete the line,
+                            never change const→let
+
+Project (project.py)
+ ├── ProjectData             — name, path, skills, description, history, plan state
+ └── ProjectStore            — SQLite CRUD for projects and message history
+
+Skills (skills.py)
+ ├── load_project_skills()   — loads only skills listed in the project
+ ├── select_skills_for_project() — LLM picks skills from description at creation
+ ├── find_skill_file()       — resolves <name>.md across skill search dirs
+ └── get_relevant_skills_llm()  — semantic router (uses project skills only)
+
+Tools (tools.py)              — file read/write, run_command, search_code, ask_human
+ ├── _PROJECT_PATH global    — all tools resolve paths relative to the project dir
+ ├── write_file              — writes file + runs _auto_lint(); returns lint errors
+ │                             to worker so reflection loop can self-correct
+ └── _auto_lint()            — py_compile for .py, node --check for .js/.ts/.jsx/.tsx
+
+Workflow Tools (workflow_tools.py)
+ ├── find_symbol              — index-backed, all languages, falls back to grep
+ ├── find_callers             — reverse call graph tool exposed to workers
+ ├── edit_file                — atomic find-replace + auto-lint + reindex
+ │                             `line` param resolves ambiguous old_str by proximity
+ │                             new_str="" deletes the matched line
+ └── read_file                — token-aware: full content or AST overview + anchors
+
+Code Index (code_index.py)   — multi-language symbol index, SQLite-backed
+ ├── CODE_INDEX singleton     — one instance shared by all tools and orchestrators
+ ├── set_project(root)        — opens/creates .opalacoder/code_index.sqlite
+ ├── build()                  — full incremental scan (skips unchanged files by mtime)
+ ├── rebuild_file(path)       — called automatically by write_file and edit_file
+ ├── search(query)            — exact → prefix → substring match across all languages
+ ├── find_callers(name)       — reverse call graph: who calls this symbol?
+ ├── symbols_in_file(rel)     — used by get_file_overview for any language
+ └── project_snapshot()       — symbol-enriched file listing fed to oracle prompts
+
+VCS (vcs.py)                 — shadow git strategies
+ ├── _run_shadow_git(cmd, project_path)  — always receives explicit project_path;
+ │                                         never uses get_project_path() global
+ ├── AutoGitStrategy          — setup() + manual_commit() before execution (default)
+ ├── HybridGitStrategy        — same + exposes git tools to workers
+ ├── AgentDrivenGitStrategy   — workers have full git control
+ └── NoGitStrategy            — VCS disabled
+ Auto-checkpoint flow:
+   set_project_context() called first → get_project_path() correct →
+   _vcs.setup() → _vcs.manual_commit("auto-checkpoint before plan execution") →
+   /undo calls undo_last() → reset --hard HEAD~1 on shadow git
+
+Skill search order:
+  1. {project_path}/skills/   (project-local, highest priority)
+  2. {repo_root}/skills/      (OpalaCoder built-in skills)
+  3. ~/.opalacoder/skills/    (user global skills)
+
+Benchmark (scripts/)
+ ├── collect_jsbench.py   — collects JS bug-fix instances from GitHub
+ │                          uses timeline API (not search) to find linked PRs
+ │                          filters: has jest/vitest, pure .js files, ≤3 files changed
+ └── eval_jsbench.py      — evaluates OpalaCoder on collected instances
+                            clone at base_commit → npm test (before) →
+                            run OpalaCoder → npm test (after) → pass/fail
+```
+
+## Adding a New Orchestrator Strategy
+
+1. Create a class that extends `BaseOrchestratorStrategy` and implements `async run()`.
+2. Decorate it with `@register_orchestrator("my_strategy_name")`.
+3. Set `strategy: my_strategy_name` under `agents.orchestrator` in `agents.yaml`.
+
+```python
+@register_orchestrator("my_strategy")
+class MyOrchestratorStrategy(BaseOrchestratorStrategy):
+    async def run(self, user_request: str, history: str, **kwargs) -> str:
+        ...
+```
+
+## Key Decisions
+
+| Decision | Reason |
+|---|---|
+| Project replaces session as primary abstraction | Stable context anchor; avoids unbounded session drift |
+| Skills fixed at project creation | Prevents irrelevant skill injection; reduces prompt size for small models |
+| Orchestrator registry (`register_orchestrator`) | Allows multiple strategies selectable via `agents.yaml`; fails loudly on unknown names |
+| `strategy: workflow` in `agents.yaml` | WorkflowOrchestratorStrategy is the current default |
+| Classifiers instantiated once in `REPLState` | Avoids creating a new `LLMAgentBlock` on every user turn |
+| All tools use `_PROJECT_PATH` as `cwd` | Eliminates path ambiguity; agent does not need to reason about absolute paths |
+| SQLite persistence | Lightweight, zero-dependency, suitable for local-first tooling |
+| Code index in SQLite | Survives session restarts; incremental rebuild by mtime avoids re-parsing unchanged files |
+| `project_snapshot()` replaces plain file listing | Oracle receives symbol names per file → plans tasks at function granularity |
+| Structured `Task` schema with semantic validation | Forces the planner to externalize class names, IDs, and file contracts |
+| `_validate_task()` in oracle reflection loop | Rejects incomplete plans before they reach workers |
+| Commands list in `Task` (not monolithic description) | Each atomic step runs as a separate `LLMAgentBlock` call; shorter prompts, tighter focus |
+| `context_block` preamble injected into every worker prompt | Worker never needs to infer cross-file contracts |
+| `_auto_lint()` called in both `edit_file` and `write_file` | Syntax errors surface as tool return values; worker self-corrects |
+| `reasoning_effort: "none"` for workers and classifiers | Gemma4/Ministral on Ollama leave `tool_calls` empty when thinking is enabled |
+| `max_iterations=None` for workers | Worker bounded by `max_tool_calls` only |
+| `termination_tools=["send_message"]` in LLMAgentBlock | Worker loop stops immediately when send_message is called; requires agenticblocks ≥ commit 98795f3 |
+| `field_validator` on `Task.context` | Coerces dict/list → JSON string for models (e.g. Mistral) that generate object-typed context |
+| `edit_file` `line` param | Resolves ambiguous old_str by picking occurrence closest to given line number |
+| `set_project_context()` before VCS checkpoint | Ensures `get_project_path()` returns the correct user project path, not OpalaCoder's own root |
+| Intent classifier prompt in English only | LLM generalizes to PT-BR from English examples; PT-BR examples in LLM prompts cause confusion |
+| `ministral-3:14b` as default model | Better instruction-following than mistral-nemo for structured JSON; faster than gemma4 |
+
+## Workflow Orchestrator: Plan→Execute→Verify Loop
+
+```
+while heartbeats < max_hb:
+    1. PLAN   — _oracle(PlanOutput) decomposes request into structured Tasks
+                 _validate_task() runs semantic checks; reflection on failure
+    2. EXECUTE — for each task:
+                   for each command in task.commands:
+                     LLMAgentBlock(prompt=context_block + command,
+                                   termination_tools=["send_message"])
+                     worker calls read_file / edit_file / write_file / run_command
+                     lint errors returned as tool output → self-correction loop
+                     loop exits immediately on send_message call
+    3. VERIFY  — _oracle(VerifyOutput) reads actual file contents on disk
+                   done=True → exit
+                   done=False → corrections (structured Tasks) → back to EXECUTE
+```
+
+## Skill Scopes
+
+Skills carry a `scope` frontmatter field:
+
+- `all` — injected into both the intent classifier and the orchestrator
+- `orchestrator` — injected only into the planner/executor
+- `classifier` — injected only into the intent classifier
+
+## Known Removed / Dead Code
+
+- `AutonomousOrchestratorStrategy`, `autonomous_orchestrator.py` — superseded by `WorkflowOrchestratorStrategy`
+- `profile_executor.py`, `profiles.py`, `profiles/` — profile-based execution replaced by skill system
+- `make_confirmation_agent()` — duplicated logic already in `confirm_plan()` in `structured.py`
+- `DeterministicOrchestratorStrategy` — described in prior versions but never implemented
+- `SubplanSchema`, `DecompositionResult`, `decompose_to_subplans()` — belonged to unimplemented deterministic path
+- `Task.description` (string) — replaced by structured `Task` schema (goal + commands + related_files + context + depends_on)

opalacoder-0.1.3/CLAUDE.md

@@ -0,0 +1,35 @@
+# General Rules
+
+1. Don't make baseless assumptions; before drawing any conclusions, conduct tests and analysis to gather as much information as possible.
+
+# Project Guide
+
+## Language
+
+All code, comments, and documentation must be written in **English**.
+
+## Architecture
+
+This project uses the **AgenticBlocks.IO** framework.
+Before starting any task, read the library source and documentation at:
+https://github.com/gilzamir/agenticblocks
+
+Key things to understand from that repo:
+- How blocks are structured and composed
+- How agents communicate and dispatch events
+- Naming conventions used throughout the framework
+
+## Project Context
+
+Read `ARCH_SUMMARY.md` before making changes. It contains the current project status,
+known issues, and decisions already made. Do not re-litigate what is documented there.
+
+## Build & Test Commands
+Run tests on tests dir after you implement a new feature.
+
+
+> Fill in your actual commands below — this is the highest-value section.
+
+```bash
+python -m pytest
+```

opalacoder-0.1.3/FLOW_MAP.md

@@ -0,0 +1,230 @@
+# OpalaCoder — Mapa do Fluxo de Execução
+
+> Arquivo gerado para auditoria. Referências de linha apontam para o estado atual do código.
+
+---
+
+## Visão geral (entrada → saída)
+
+```
+User request
+     │
+     ▼
+[WorkflowOrchestrator.run()]           workflow_orchestrator.py:697
+     │
+     ├─ Setup: VCS checkpoint, code index, skill tools/reviewers
+     │
+     ▼
+[_orchestration_loop()]                workflow_orchestrator.py:1157
+     │
+     ├─ PRÉ-PLANNING: skill tool pre-scan  ← NOVO
+     │
+     ▼
+[Planner Oracle]  →  PlanOutput         workflow_orchestrator.py:1245
+     │
+     └─ loop: para cada task pendente
+           │
+           ├─ VCS checkpoint (rollback point)
+           ├─ errors_before = _run_skill_scan()  ← NOVO
+           │
+           ▼
+       [Worker]  →  worker_result        workflow_orchestrator.py:1301
+           │
+           ▼
+       [_review_task()]                  workflow_orchestrator.py:945
+           │
+           ├─ CHECK 1: lint
+           ├─ CHECK 2: arquivos mudaram no disco?
+           ├─ CHECK 3: partial edit (old_str not found)?
+           ├─ CHECK 4: H2 before/after (orchestrator)  ← NOVO
+           ├─ CHECK 5: skill reviewers (plugins)        ← NOVO
+           └─ CHECK 6: LLM reviewer oracle
+                │
+                ├─ done=True  → task.status = "done"
+                └─ done=False → task.failure_count++
+                                └─ se >= MAX_TASK_FAILURES → abort
+                                └─ senão → adiciona correction task ao plano e retenta
+```
+
+---
+
+## Fase 0 — Setup (run, linhas 697–795)
+
+| Passo | O que faz | Onde |
+|---|---|---|
+| VCS auto-checkpoint | Salva estado do projeto em `.opalacoder/.git` antes de qualquer mudança | ~758 |
+| Code index build | Indexa arquivos do projeto para buscas do worker | ~764 |
+| Carregar skill tools | `load_skill_tools()` lê frontmatter `tools:` de cada skill ativa e importa as funções | ~773 |
+| Carregar skill reviewers | `load_skill_reviewers()` lê frontmatter `reviewer:` e importa as funções | ~774 |
+| Montar planner_sys | `_planner_system()` — sistema de prompt do planner LLM | ~787 |
+
+**Skill ativa por padrão para projetos HTML/JS/CSS:** `html_css_js`
+- Tool registrada: `html_css_js_tools.search_html_css_js_bugs`
+- Reviewer registrado: `html_css_js_tools.html_css_js_reviewer`
+
+---
+
+## Fase 1 — Pré-planning (linhas 1195–1243)
+
+### 1a. File snippets
+Extrai conteúdo de arquivos mencionados explicitamente na request do usuário (ex: "corrige o `index.html`").
+
+### 1b. Skill tool pre-scan ← **PONTO CRÍTICO**
+```
+para cada st em _skill_tools:
+    chama st._func(".")          ← sync, direto na função, não via wrapper async
+    filtra linhas com [CONTRACT ERROR] / [SYNTAX ERROR] / [ERROR]
+    injeta no planning_prompt como "Skill tool pre-scan"
+```
+**Por que importa:** sem isso, o planner só vê o sintoma ("botão 9 não funciona") e chuta o arquivo errado (script.js). Com o pre-scan ele vê `[CONTRACT ERROR] index.html:42: botão 9 tem data-value="multiply"` e cria a task no arquivo correto.
+
+**Só linhas de erro bloqueantes são injetadas** — WARNING/INFO causariam tasks desnecessárias.
+
+### 1c. planning_prompt montado
+```
+Project files: <snapshot do diretório>
+Relevant file contents and diagnostics:
+  <file snippets>
+  Skill tool pre-scan:
+    [search_html_css_js_bugs]
+    [CONTRACT ERROR] index.html:42: ...
+Conversation history: ...
+User request: ...
+```
+
+### 1d. Planner oracle
+`_oracle(PlanOutput, planner_sys, planning_prompt)` → retorna lista de `Task` com:
+- `id`, `goal`, `commands[]`, `related_files[]`, `depends_on[]`
+
+O system prompt do planner (`_planner_system`, linha 370) contém instrução crítica:
+> "CRITICAL — when the planning prompt contains a skill tool pre-scan with [CONTRACT ERROR]: create tasks ONLY for the files explicitly named in 'FIX REQUIRED IN <file>'. Do NOT create tasks for files the scan does not flag."
+
+---
+
+## Fase 2 — Loop de execução de tasks (linhas 1263–1380)
+
+Para cada task pendente (respeitando `depends_on`):
+
+### 2a. VCS checkpoint por task (linha 1292)
+`_vcs.manual_commit("pre-task t1: ...")` — permite rollback se a task falhar.
+
+### 2b. errors_before = _run_skill_scan() (linha 1299) ← **NOVO**
+Captura o conjunto de erros bloqueantes **antes** do worker rodar.
+```python
+def _run_skill_scan() -> set[str]:       # linha 920
+    # chama cada st._func(".") de _skill_tools
+    # retorna set de linhas [CONTRACT ERROR]/[SYNTAX ERROR]/[ERROR]
+```
+Este snapshot será comparado com o estado **depois** do worker para detectar se o erro foi de fato corrigido.
+
+### 2c. Worker (linha 1301)
+`_run_worker_safe(task)` → `_run_worker(task, ...)` (linha 540)
+
+O worker é um `LLMAgentBlock` com ferramentas:
+- `read_file`, `edit_file`, `create_file`, `list_dir`, `search_code`
+- + skill tools do projeto (ex: `search_html_css_js_bugs`)
+
+O worker recebe o `task.goal` + `task.commands[]` como prompt e executa.
+Ao final, o footer do resultado anota `[Tools invoked: edit_file, read_file, ...]`.
+
+---
+
+## Fase 3 — Review (`_review_task`, linhas 945–1143)
+
+Os checks são executados **em ordem**. O primeiro que reprovar devolve `VerifyOutput(done=False)` sem executar os seguintes.
+
+### CHECK 1 — Lint (linha 948)
+`_run_lint(task)` verifica sintaxe JS (node --check) / Python (py_compile).
+- Erro de sintaxe → **rejeição automática**, sem chamar LLM.
+
+### CHECK 2 — Arquivos mudaram? (linha 969)
+`_git_changed_files()` usa `git status --porcelain` no shadow git.
+- Worker chamou ferramenta de escrita **mas nenhum arquivo mudou** → **rejeição automática**.
+- Worker não chamou nenhuma ferramenta de escrita e nenhum arquivo mudou → **rejeição automática**.
+
+### CHECK 3 — Partial edit (linha 1034)
+Contabiliza `old_str not found` no worker_result. Se > 0, injeta nota no contexto do LLM reviewer (não rejeita automaticamente, mas avisa).
+
+### CHECK 4 — H2 before/after orchestrator (linha 1051) ← **NOVO**
+```python
+errors_after = _run_skill_scan()
+unresolved = errors_before & errors_after   # erros que existiam antes e ainda existem
+new_errors  = errors_after - errors_before  # erros novos introduzidos pelo worker
+
+if unresolved or new_errors:
+    → rejeição automática, passa as linhas de erro como corrections
+```
+**Por que é genérico:** compara sets de strings — não sabe nada sobre o tipo de erro. Funciona para qualquer ferramenta registrada em `tools:` que emita linhas `[CONTRACT ERROR]` / `[SYNTAX ERROR]` / `[ERROR]`.
+
+### CHECK 5 — Skill reviewers (linha 1080) ← **NOVO**
+Para cada função em `_skill_reviewers`:
+```python
+if "errors_before" in sig.parameters:
+    resultado = reviewer(project_path, task_goal, related_files, errors_before=errors_before)
+else:
+    resultado = reviewer(project_path, task_goal, related_files)
+
+if resultado["done"] == False:
+    → rejeição, corrections = resultado["corrections"]
+```
+O `html_css_js_reviewer` aceita `errors_before` e faz a mesma lógica de before/after, mas com acesso direto ao scanner (pode gerar mensagens mais detalhadas que o CHECK 4).
+
+### CHECK 6 — LLM reviewer oracle (linha 1100)
+Só chega aqui se todos os checks anteriores passaram.
+Manda para o LLM:
+- task JSON, lint summary, arquivos que mudaram, worker_result, conteúdo atual dos `related_files`
+
+Retorna `VerifyOutput(done, summary, corrections[])`.
+
+---
+
+## O que acontece quando review.done=False
+
+```
+task.failure_count += 1
+
+if failure_count >= MAX_TASK_FAILURES:
+    → abort com mensagem de erro para o usuário
+
+else:
+    para cada Task em review.corrections:
+        adiciona ao plan.tasks com id único
+    → próxima iteração do while loop pega a correction task como pending
+```
+
+---
+
+## Arquivos relevantes
+
+| Arquivo | Responsabilidade |
+|---|---|
+| [opalacoder/workflow_orchestrator.py](opalacoder/workflow_orchestrator.py) | Fluxo completo: planner, worker, reviewer |
+| [opalacoder/plugins/html_css_js_tools.py](opalacoder/plugins/html_css_js_tools.py) | Scanner de bugs HTML/JS (`search_html_css_js_bugs`) e reviewer (`html_css_js_reviewer`) |
+| [opalacoder/skills.py](opalacoder/skills.py) | Carregamento de skills, tools e reviewers por frontmatter |
+| [skills/html_css_js.md](skills/html_css_js.md) | Frontmatter: `tools:` e `reviewer:` que ativam o scanner e o reviewer |
+
+---
+
+## O que verificar manualmente para o bug do micalc
+
+1. **O planner viu o erro certo?**
+   Rode: `python tests/test_planner_output.py micalc "botão 9 não funciona"`
+   Procure no output: `Skill tool pre-scan` com `[CONTRACT ERROR]` apontando para `index.html`.
+   Se não aparecer: o scanner `search_html_css_js_bugs` não detectou o bug.
+
+2. **O scanner detecta o bug?**
+   ```bash
+   cd /caminho/do/micalc
+   python -c "
+   import sys; sys.path.insert(0, '/home/gilzamir/projetos/OpalaCoder')
+   from opalacoder.plugins.html_css_js_tools import search_html_css_js_bugs
+   print(search_html_css_js_bugs('.'))
+   "
+   ```
+   Deve aparecer `[CONTRACT ERROR]` para o botão 9.
+
+3. **O H2 rejeita corretamente?**
+   Se o worker mudar o arquivo errado (script.js em vez de index.html), o `errors_before` ainda vai conter o CONTRACT ERROR do botão 9. O `_run_skill_scan()` após o worker vai retornar o mesmo erro. `unresolved = errors_before & errors_after` vai ser não-vazio → rejeição automática no CHECK 4.
+
+4. **O reviewer do plugin foi chamado?**
+   Procure no log do agente por `[skill_reviewer]` ou `[H2-REJECT]`.

{opalacoder-0.1.0 → opalacoder-0.1.3}/GEMINI.md

@@ -1,3 +1,7 @@
+# General Rules
+
+1. Don't make baseless assumptions; before drawing any conclusions, conduct tests and analysis to gather as much information as possible.
+
 # Project Guide
 
 ## Language