update

2026-04-03 22:35:49 +02:00
parent 0e7ee957cb
commit e95c4967d2
52 changed files with 7430 additions and 631 deletions
--- a/.paul/phases/67-paul-codex-executor/67-01-PLAN.md
+++ b/.paul/phases/67-paul-codex-executor/67-01-PLAN.md
@@ -0,0 +1,310 @@
+---
+phase: 67-paul-codex-executor
+plan: 01
+type: execute
+wave: 1
+depends_on: ["65-01"]
+files_modified:
+  - ~/.claude/paul-framework/references/delegated-apply.md
+  - ~/.claude/paul-framework/workflows/apply-phase.md
+  - ~/.claude/paul-framework/templates/PLAN.md
+autonomous: true
+delegation: auto
+---
+
+<objective>
+## Goal
+Dodać Codex CLI (`codex exec`) jako alternatywny executor w PAUL delegated-apply. Reguła: jeśli plan ma >3 tasków auto, 1/3 z nich MUSI iść przez Codex. Plus: auto-fallback na Codex przy quota error Claude.
+
+## Purpose
+- Oszczędność 5h limitu Claude Code — Codex jest osobno opłacany
+- Rotacja executorów — wymuszenie użycia Codex przy większych planach
+- Fallback — gdy Claude limit się kończy, praca nie staje
+
+## Output
+- Zaktualizowany `delegated-apply.md` z sekcją Codex executor
+- Zaktualizowany `apply-phase.md` z logiką wyboru executor (Claude vs Codex)
+- Zaktualizowany `PLAN.md` template z nowym trybem delegation
+</objective>
+
+<context>
+## Prior Work
+@.paul/phases/65-paul-delegated-apply/65-01-SUMMARY.md
+
+## Research: Codex CLI
+- Komenda: `codex exec -c 'approval_mode="full-auto"' "prompt"`
+- Model: gpt-5.3-codex
+- Synchroniczny, non-interactive, zwraca diff + summary
+- Timeout: ~30s na proste zadanie, max ~5min na złożone
+- Uwagi: pilnować UTF-8 bez BOM, polskie znaki w prompcie
+- Skill warnings (niekrytyczne): ignorować
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Reguła 1/3 Codex przy >3 taskach
+```gherkin
+Given plan z 6 taskami type="auto" i delegation: auto
+When orkiestrator przydziela executory
+Then minimum 2 taski (ceil(6/3)) idą przez Codex
+And pozostałe 4 przez Claude sub-agent
+And wybór tasków dla Codex to te najprostsze (najmniej plików)
+```
+
+## AC-2: Auto-fallback Claude → Codex
+```gherkin
+Given task delegowany do Claude sub-agent
+When Agent tool zwróci błąd quota/rate-limit
+Then orkiestrator automatycznie ponawia ten sam task przez codex exec
+And loguje: "Task N: Claude quota → fallback Codex"
+```
+
+## AC-3: Codex micro-prompt zawiera guard UTF-8
+```gherkin
+Given task przydzielony do Codex
+When orkiestrator buduje mikro-prompt
+Then prompt zawiera instrukcje: "IMPORTANT: All files must remain UTF-8 without BOM. Preserve Polish characters (ą,ć,ę,ł,ń,ó,ś,ź,ż)."
+```
+
+## AC-4: Backward compatible
+```gherkin
+Given plan z delegation: off lub delegation: auto z <=3 taskami
+When orkiestrator wykonuje plan
+Then zachowanie identyczne jak dotychczas (bez Codex)
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Rozszerzenie delegated-apply.md o Codex executor</name>
+  <files>~/.claude/paul-framework/references/delegated-apply.md</files>
+  <action>
+    Przeczytaj plik, potem dodaj nowe sekcje.
+
+    1. Dodaj nową sekcję "## Codex Executor" PO sekcji "## Evaluation Protocol" a PRZED "## Delegation Modes":
+
+    ```markdown
+    ## Codex Executor
+
+    Codex CLI (`codex exec`) służy jako alternatywny executor dla tasków z PLAN.md.
+
+    ### Wywołanie
+
+    ```bash
+    codex exec -c 'approval_mode="full-auto"' "MICRO_PROMPT"
+    ```
+
+    - Synchroniczny, non-interactive
+    - Timeout Bash: 300000ms (5 min)
+    - Output zawiera diff + summary — parsowany przez orkiestratora
+
+    ### Reguła 1/3
+
+    Jeśli plan ma **>3 tasków type="auto"**, minimum `ceil(count/3)` tasków MUSI iść przez Codex:
+
+    | Tasków auto | Min Codex | Min Claude |
+    |-------------|-----------|------------|
+    | 1-3         | 0         | all        |
+    | 4-6         | 2         | reszta     |
+    | 7-9         | 3         | reszta     |
+    | 10+         | ceil(N/3) | reszta     |
+
+    **Wybór tasków dla Codex:** Orkiestrator przydziela Codexowi taski o najmniejszej liczbie plików w `<files>` (najprostsze). Jeśli równe — pierwsze w kolejności.
+
+    **KRYTYCZNE: Brak współdzielenia plików.** Codex i Claude sub-agenty NIE MOGĄ edytować tych samych plików — działają na tym samym working directory. Orkiestrator MUSI sprawdzić `<files>` każdego taska i zapewnić że:
+    - Żaden plik z tasków Codex nie pokrywa się z plikami tasków Claude
+    - Jeśli jest konflikt plików → oba taski idą do tego samego executora
+    - Przy parallel mode: taski z tymi samymi plikami NIE lecą równolegle
+
+    ### Auto-fallback
+
+    Jeśli Claude Agent tool zwróci błąd (quota, rate-limit, timeout):
+    1. Orkiestrator loguje: "Task N: Claude error → fallback Codex"
+    2. Ponawia TEN SAM mikro-prompt przez `codex exec`
+    3. Evaluation protocol identyczny jak dla Claude
+
+    ### Micro-prompt guard
+
+    Każdy mikro-prompt wysyłany do Codex MUSI zawierać na końcu:
+
+    ```
+    ## IMPORTANT
+    - All files must remain UTF-8 without BOM encoding
+    - Preserve all Polish characters: ą,ć,ę,ł,ń,ó,ś,ź,ż,Ą,Ć,Ę,Ł,Ń,Ó,Ś,Ź,Ż
+    - Do NOT convert file encoding
+    - Do NOT add BOM markers
+    ```
+
+    ### Evaluation po Codex
+
+    Identyczny jak po Claude sub-agent:
+    1. git diff --stat
+    2. Sprawdź done criteria
+    3. Sprawdź boundaries
+    4. **Dodatkowe:** `file` command na zmodyfikowanych plikach — potwierdź UTF-8
+    5. Decyzja: accept / retry / escalate
+    ```
+
+    2. W sekcji "## Delegation Modes", zaktualizuj tabelę:
+
+    Dodaj wiersz:
+    ```
+    | codex | `delegation: codex` | Wszystkie taski auto przez Codex exec |
+    ```
+
+    W "Kiedy użyć jakiego" dodaj:
+    ```
+    - **`codex`** — wymuszone użycie Codex dla wszystkich tasków (np. przy niskim limicie Claude)
+    ```
+
+    3. W sekcji "## Constraints", dodaj:
+    ```
+    - Codex exec timeout: 300s (5 min) per task — jeśli task jest większy, rozbij
+    - Codex nie ma dostępu do MCP servers ani Agent tool — tylko filesystem + shell
+    ```
+  </action>
+  <verify>Plik zawiera sekcję "Codex Executor" z regułą 1/3, auto-fallback, micro-prompt guard. Tabela Delegation Modes zawiera tryb codex.</verify>
+  <done>AC-1 spec: reguła 1/3 zdefiniowana. AC-2 spec: auto-fallback zdefiniowany. AC-3 spec: UTF-8 guard zdefiniowany.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Logika executor selection w apply-phase.md</name>
+  <files>~/.claude/paul-framework/workflows/apply-phase.md</files>
+  <action>
+    Przeczytaj plik, potem zmodyfikuj.
+
+    1. W kroku `determine_execution_mode`, ROZSZERZ punkt 2 ("If delegated mode"):
+       Dodaj pod-punkt po identyfikacji task clusters:
+       ```
+       - Determine executor assignment per task:
+         a. Count auto tasks in plan
+         b. If count > 3: assign ceil(count/3) tasks to Codex executor
+            - Select tasks with fewest files in <files> for Codex
+            - Remaining tasks go to Claude Agent tool
+            - CRITICAL: Verify no file overlap between Codex and Claude tasks
+              If overlap detected → move conflicting task to same executor as its peer
+         c. If delegation: codex → all auto tasks to Codex
+         d. If delegation: auto/parallel with <=3 tasks → all to Claude Agent tool
+         e. Log: "Executor assignment: N Claude, M Codex (no file conflicts)"
+       ```
+
+    2. W kroku `execute_tasks`, w bloku "If delegated mode and task type=auto":
+       Dodaj rozgałęzienie na executor:
+       ```
+       **If task assigned to Claude Agent tool:**
+       [existing Agent tool delegation — no changes]
+
+       **If task assigned to Codex executor:**
+       1. Build micro-prompt (same template as Claude)
+       2. Append UTF-8 guard block to prompt
+       3. Execute via Bash:
+          codex exec -c 'approval_mode="full-auto"' "MICRO_PROMPT"
+          Timeout: 300000ms
+       4. Parse output for diff and summary
+       5. Evaluate: git diff + done criteria + boundaries + UTF-8 check
+       6. Decision: accept / retry (max 3) / escalate
+
+       **Auto-fallback (Claude → Codex):**
+       If Agent tool returns error (quota/rate-limit/connection):
+       1. Log: "Task N: [name] → Claude error: [reason] → fallback Codex"
+       2. Re-execute same micro-prompt via codex exec
+       3. Continue evaluation as normal
+       ```
+
+    3. W kroku `finalize`, rozszerz "Delegated execution summary":
+       ```
+       - Tasks via Claude: N
+       - Tasks via Codex: N
+       - Tasks via Codex (fallback): N
+       ```
+
+    4. W sekcji `error_handling`, dodaj:
+       ```
+       **Codex exec timeout:**
+       - If codex exec exceeds 300s timeout: mark as failed
+       - Offer retry via Claude Agent tool (reverse fallback)
+
+       **Codex encoding issue:**
+       - If file check shows non-UTF-8 after Codex: auto-fix encoding
+       - Log warning and continue
+       ```
+
+    WAŻNE: Nie usuwaj istniejącej logiki — rozszerzaj.
+  </action>
+  <verify>apply-phase.md zawiera: executor assignment w determine_execution_mode, rozgałęzienie Claude/Codex w execute_tasks, auto-fallback, Codex w finalize summary, Codex error handling.</verify>
+  <done>AC-1: logika 1/3 w orkiestratorze. AC-2: auto-fallback zaimplementowany. AC-4: <=3 tasków = bez Codex.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Aktualizacja PLAN.md template</name>
+  <files>~/.claude/paul-framework/templates/PLAN.md</files>
+  <action>
+    Przeczytaj plik, potem zmodyfikuj.
+
+    1. W frontmatter YAML, zaktualizuj komentarz przy delegation:
+       Zmień:
+       ```yaml
+       delegation: auto                 # auto (default) | parallel | off — execution mode for /paul:apply
+       ```
+       na:
+       ```yaml
+       delegation: auto                 # auto (default) | parallel | codex | off — execution mode for /paul:apply
+       ```
+
+    2. W tabeli Frontmatter Fields, zaktualizuj opis delegation:
+       Zmień na:
+       ```
+       | `delegation` | No | Execution mode: `auto` (delegated, 1/3 Codex if >3 tasks, default), `parallel` (delegated + parallel), `codex` (all tasks via Codex), `off` (inline, legacy) |
+       ```
+
+    3. W sekcji "## Delegation Mode", dodaj `codex` do tabeli:
+       ```
+       | `codex` | When Claude limit is low or you want to force Codex for all tasks |
+       ```
+
+    WAŻNE: Nie zmieniaj nic innego.
+  </action>
+  <verify>PLAN.md template zawiera tryb codex w frontmatter komentarzu, tabeli i sekcji Delegation Mode.</verify>
+  <done>AC-4 partially: template zaktualizowany o nowy tryb.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- ~/.claude/paul-framework/workflows/plan-phase.md
+- ~/.claude/paul-framework/workflows/unify-phase.md
+- ~/.claude/paul-framework/rules/*
+- ~/.claude/paul-framework/references/subagent-criteria.md
+- .paul/PROJECT.md, .paul/ROADMAP.md
+
+## SCOPE LIMITS
+- Nie tworzymy wrapper script dla codex — wywołanie bezpośrednio z Bash
+- Nie modyfikujemy Codex config (~/.codex/) — używamy -c flag
+- Nie implementujemy monitoring limitu Claude — reaktywny fallback wystarczy
+
+</boundaries>
+
+<verification>
+- [ ] delegated-apply.md zawiera sekcję Codex Executor z regułą 1/3
+- [ ] apply-phase.md zawiera executor assignment + rozgałęzienie Claude/Codex
+- [ ] apply-phase.md zawiera auto-fallback Claude → Codex
+- [ ] PLAN.md template zawiera tryb codex
+- [ ] Reguła 1/3 dotyczy tylko planów >3 tasków auto
+- [ ] UTF-8 guard jest w każdym Codex mikro-prompcie
+</verification>
+
+<success_criteria>
+- Wszystkie 3 taski completed
+- PAUL apply wspiera Codex jako executor
+- Reguła 1/3 wymusza rotację przy większych planach
+- Auto-fallback chroni przed przestojem przy quota error
+- Backward compatible
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/67-paul-codex-executor/67-01-SUMMARY.md`
+</output>
--- a/.paul/phases/67-paul-codex-executor/67-01-SUMMARY.md
+++ b/.paul/phases/67-paul-codex-executor/67-01-SUMMARY.md
@@ -0,0 +1,97 @@
+---
+phase: 67-paul-codex-executor
+plan: 01
+subsystem: infra
+tags: [paul-framework, codex, delegation, executor, fallback]
+
+requires:
+  - phase: 65-paul-delegated-apply
+    provides: Delegated-apply workflow, micro-prompt template, evaluation protocol
+
+provides:
+  - Codex CLI as alternative executor in PAUL delegated-apply
+  - Rule of thirds (1/3 Codex if >3 tasks)
+  - Auto-fallback Claude → Codex on quota error
+  - UTF-8 guard for Codex micro-prompts
+  - File overlap protection between executors
+
+affects: [all future phases using /paul:apply with >3 tasks]
+
+tech-stack:
+  added: [codex-cli]
+  patterns: [multi-executor-delegation, auto-fallback, file-conflict-detection]
+
+key-files:
+  modified:
+    - ~/.claude/paul-framework/references/delegated-apply.md
+    - ~/.claude/paul-framework/workflows/apply-phase.md
+    - ~/.claude/paul-framework/templates/PLAN.md
+
+key-decisions:
+  - "Reguła 1/3: ceil(count/3) tasków do Codex przy >3 taskach auto"
+  - "Codex dostaje najprostsze taski (fewest files)"
+  - "Codex i Claude NIE MOGĄ edytować tych samych plików"
+  - "Auto-fallback Claude→Codex przy quota error, reverse fallback przy Codex timeout"
+  - "UTF-8 guard obowiązkowy w każdym Codex micro-prompt"
+
+patterns-established:
+  - "codex exec -c 'approval_mode=\"full-auto\"' jako non-interactive executor"
+  - "File overlap check przed przydziałem executorów"
+  - "delegation: codex jako tryb wymuszający Codex dla wszystkich tasków"
+
+duration: ~10min
+started: 2026-04-03T21:00:00Z
+completed: 2026-04-03T21:10:00Z
+---
+
+# Phase 67 Plan 01: PAUL Codex Executor
+
+**Integracja Codex CLI jako alternatywny executor w PAUL — reguła 1/3 przy >3 taskach, auto-fallback Claude→Codex, ochrona plików przed współdzieleniem executorów, UTF-8 guard.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~10min |
+| Tasks | 3 completed (delegated, parallel) |
+| Files modified | 3 |
+| Execution mode | Delegated auto (3 sub-agents parallel) |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Reguła 1/3 Codex przy >3 taskach | Pass | Zdefiniowana w delegated-apply.md + apply-phase.md |
+| AC-2: Auto-fallback Claude → Codex | Pass | W execute_tasks + error_handling |
+| AC-3: UTF-8 guard w Codex prompts | Pass | Micro-prompt guard w delegated-apply.md |
+| AC-4: Backward compatible | Pass | <=3 tasków = bez Codex, delegation: off = inline |
+
+## Accomplishments
+
+- Sekcja "Codex Executor" w delegated-apply.md z regułą 1/3, auto-fallback, UTF-8 guard
+- Executor assignment logic w apply-phase.md z file overlap protection
+- Tryb `delegation: codex` w PLAN.md template
+- Error handling: Codex timeout, encoding issues, file conflicts
+- Anti-patterns: mixing executors on same files, Polish text without guard
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `~/.claude/paul-framework/references/delegated-apply.md` | Modified | +Codex Executor section, +codex mode, +constraints |
+| `~/.claude/paul-framework/workflows/apply-phase.md` | Modified | +executor assignment, +Codex path, +fallback, +error handling |
+| `~/.claude/paul-framework/templates/PLAN.md` | Modified | +codex mode w frontmatter, tabeli, sekcji |
+
+## Deviations from Plan
+
+None — plan executed as specified.
+
+## Next Phase Readiness
+
+**Ready:** PAUL wspiera 4 tryby delegation: auto, parallel, codex, off. Codex zintegrowany jako executor z pełną ochroną (file overlap, UTF-8, fallback).
+
+**Blockers:** None
+
+---
+*Phase: 67-paul-codex-executor, Plan: 01*
+*Completed: 2026-04-03*