refactor: structure (#146)

Author: Gusarich

.github/workflows/strategies-smoke.yml

@@ -226,13 +226,13 @@ jobs:
         if: steps.secrets_ok.outputs.ok == 'true'
         run: |
           set -euo pipefail
-          RUN_DIR=$(ls -td results/run_* 2>/dev/null | head -n1 || true)
+          RUN_DIR=$(ls -td .pitaya/results/run_* 2>/dev/null | head -n1 || true)
           if [ -z "$RUN_DIR" ]; then
             echo "No results directory found" >&2
             exit 1
           fi
           RUN_ID=$(basename "$RUN_DIR")
-          STATE_JSON="pitaya_state/$RUN_ID/state.json"
+          STATE_JSON=".pitaya/state/$RUN_ID/state.json"
 
           echo "Results: $RUN_DIR" >> $GITHUB_STEP_SUMMARY
           if [ ! -f "$STATE_JSON" ]; then

.gitignore

@@ -54,13 +54,6 @@ dmypy.json
 .spyproject
 .ropeproject
 
-# Logs
-logs/
-*.log
-log/
-*.log.*
-test_logs/
-
 # Environment variables
 .env
 .env.*
@@ -81,8 +74,5 @@ desktop.ini
 *.backup
 *.orig
 
-# Output directories
-output/
-results/
-runs/
-pitaya_state/
+# Runtime/output
+.pitaya/

CHANGELOG.md

@@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Persist per-instance metadata to results and logs artifacts. ([#79](https://github.com/tact-lang/pitaya/pull/79))
 - CLI flags: `--override-config` and `--resume-key-policy {strict|suffix}` to control how resume applies overrides and durable key behavior. ([#81](https://github.com/tact-lang/pitaya/pull/81))
-- Persist the effective run configuration to `pitaya_state/<run_id>/config.json` and a redacted copy to `logs/<run_id>/config.json` to improve resume fidelity. ([#81](https://github.com/tact-lang/pitaya/pull/81))
+- Persist the effective run configuration to `.pitaya/state/<run_id>/config.json` and a redacted copy to `logs/<run_id>/config.json` to improve resume fidelity. ([#81](https://github.com/tact-lang/pitaya/pull/81))
 - Strategy: `pr-review` — N reviewers, validator per reviewer, and a composer; CI‑friendly with JSON trailer parsing and fail gating.
 - Workspace: Optional `--include-branches` (CSV/JSON) or config `runner.include_branches` to materialize extra read‑only branches in the isolated workspace for all strategies. Also supported per-task via `workspace_include_branches` metadata. ([#95](https://github.com/tact-lang/pitaya/pull/95))
 

README.md

@@ -117,8 +117,8 @@ CLI overrides config; `-S key=value` only affects the selected strategy.
 
 ## Results & Logs
 
-- Logs: `logs/<run_id>/events.jsonl` and JSONL component logs (orchestration.jsonl, runner.jsonl, tui.jsonl, other.jsonl)
-- Results: `results/<run_id>/` (summary.json, metadata.json, branches.txt, instance_metrics.csv, instances/<id>.json)
+- Logs: `.pitaya/logs/<run_id>/events.jsonl` and JSONL component logs (orchestration.jsonl, runner.jsonl, tui.jsonl, other.jsonl)
+- Results: `.pitaya/results/<run_id>/` (summary.json, metadata.json, branches.txt, instance_metrics.csv, instances/<id>.json)
 - Branches: `pitaya/<strategy>/<run_id>/k<short8>` (hierarchical namespace)
 - Resume: `pitaya --resume <run_id>`
 

docs/cli.md

@@ -169,8 +169,8 @@ pitaya "task" --force-commit                  # force a commit if changes exist
 
 - Precedence: CLI > env > .env > project config > defaults.
 - Directories:
-  - State: `--state-dir ./pitaya_state` (default)
-  - Logs: `--logs-dir ./logs` (default)
+  - State: `--state-dir ./.pitaya/state` (default)
+  - Logs: `--logs-dir .pitaya/logs` (default)
 
 ## Maintenance
 

docs/configuration.md

@@ -38,7 +38,7 @@ strategies:
     iterations: 3
 
 logging:
-  # JSONL component logs under logs/<run_id>/
+  # JSONL component logs under .pitaya/logs/<run_id>/
   max_file_size: 10485760   # 10MB per component file before rotation
   retention_days: 7         # cleanup old run dirs (component logs)
   console_verbose: false    # headless-only: surface agent/tool steps to console (same as --verbose)
@@ -81,22 +81,22 @@ Most strategies leave these at defaults. To force an import even when there are
 
 ## Directories
 
-- State: `pitaya_state/` (can be changed with `--state-dir`)
-- Logs: `logs/<run_id>/` (change with `--logs-dir`)
-- Results: `results/<run_id>/` (summary.json, metadata.json, branches.txt, instance_metrics.csv, instances/<id>.json)
+- State: `.pitaya/state/` (can be changed with `--state-dir`)
+- Logs: `.pitaya/logs/<run_id>/` (change with `--logs-dir`)
+- Results: `.pitaya/results/<run_id>/` (summary.json, metadata.json, branches.txt, instance_metrics.csv, instances/<id>.json)
 
 Structured logs
 
-- Pitaya writes JSON Lines component logs in `logs/<run_id>/` (orchestration.jsonl, runner.jsonl, tui.jsonl, other.jsonl).
+- Pitaya writes JSON Lines component logs in `.pitaya/logs/<run_id>/` (orchestration.jsonl, runner.jsonl, tui.jsonl, other.jsonl).
 - Old log directories are cleaned up periodically; component files rotate by size.
 - Custom redaction patterns from `logging.redaction.custom_patterns` are applied to both logs and emitted events.
 
 ## Effective config persistence and resume
 
 On a fresh run, Pitaya writes the fully merged configuration (CLI + env + .env + file + defaults):
 
-- Unredacted copy to `pitaya_state/<run_id>/config.json` (for fidelity on resume). The `pitaya_state/` directory is git‑ignored by default.
-- Redacted copy to `logs/<run_id>/config.json` (tokens/API keys masked) for auditability alongside logs.
+- Unredacted copy to `.pitaya/state/<run_id>/config.json` (for fidelity on resume). The `.pitaya/state/` directory is git‑ignored by default.
+- Redacted copy to `.pitaya/logs/<run_id>/config.json` (tokens/API keys masked) for auditability alongside logs.
 
 On `--resume <run_id>`, Pitaya loads the saved effective config by default. This preserves durable keys and behavior. CLI overrides on resume are applied as follows:
 

docs/custom-strategies.md

@@ -40,7 +40,7 @@ Create a file `my_strategy.py` in your repo:
 ```python
 from dataclasses import dataclass
 from typing import List
-from pitaya.orchestration.strategies.base import Strategy, StrategyConfig
+from pitaya.orchestration.strategy.base import Strategy, StrategyConfig
 from pitaya.shared import InstanceResult
 
 @dataclass
@@ -80,7 +80,7 @@ Spawn N parallel tasks and wait for all, tolerating failures:
 ```python
 from dataclasses import dataclass
 from typing import List
-from pitaya.orchestration.strategies.base import Strategy, StrategyConfig
+from pitaya.orchestration.strategy.base import Strategy, StrategyConfig
 from pitaya.shared import InstanceResult
 
 @dataclass

docs/quickstart.md

@@ -59,7 +59,7 @@ cd pitaya
 uv run pitaya --version
 
 # Or directly via Python module
-python -m src.cli --version
+python -m pitaya --version
 ```
 
 ## Authenticate
@@ -108,7 +108,7 @@ uv run pitaya "Create a HELLO.txt file with 'Hello from Pitaya' text in it and c
 Tips
 
   - Press Ctrl+C to stop the run. Pitaya shuts down gracefully (containers stopped, state saved) and prints a resume hint with the run ID.
-- After completion, results are written under `results/<run_id>/` and logs under `logs/<run_id>/`.
+- After completion, results are written under `.pitaya/results/<run_id>/` and logs under `.pitaya/logs/<run_id>/`.
 - Branches are created only if the agent commits changes.
 
 ## Explore More
@@ -135,8 +135,8 @@ pitaya "Write the funniest and most original joke possible" --strategy iterative
 
 ## Where to Find Results
 
-- Logs: `logs/<run_id>/events.jsonl` and JSONL component logs (orchestration.jsonl, runner.jsonl, tui.jsonl, other.jsonl)
-- Results: `results/<run_id>/` (summary.json, metadata.json, branches.txt, metrics, instances/<id>.json)
+- Logs: `.pitaya/logs/<run_id>/events.jsonl` and JSONL component logs (orchestration.jsonl, runner.jsonl, tui.jsonl, other.jsonl)
+- Results: `.pitaya/results/<run_id>/` (summary.json, metadata.json, branches.txt, metrics, instances/<id>.json)
 - Branches: `pitaya/<strategy>/<run_id>/k<short8>` (hierarchical namespace)
 
 List branches:

docs/tui.md

@@ -44,7 +44,7 @@ Inspect a previous run without the orchestrator running:
 ```bash
 pitaya-tui --run-id run_20250114_123456
 # or from an events file
-pitaya-tui --events-file logs/run_20250114_123456/events.jsonl --output streaming
+pitaya-tui --events-file .pitaya/logs/run_20250114_123456/events.jsonl --output streaming
 ```
 
 Filters:
@@ -54,5 +54,5 @@ Filters:
 ## Tips
 
 - Cancel with Ctrl+C; a graceful shutdown stops containers, saves state, and prints a resume hint with the run ID.
-- Logs live at `logs/<run_id>/`; results at `results/<run_id>/`.
+- Logs live at `.pitaya/logs/<run_id>/`; results at `.pitaya/results/<run_id>/`.
 - In compact mode, long branches shorten to their unique suffix with a leading `/` so the `k<short8>` tail is visible.

examples/custom_simple.py

@@ -11,9 +11,9 @@
 from dataclasses import dataclass
 from typing import List
 
-from src.orchestration.strategies.base import Strategy, StrategyConfig
-from src.orchestration.strategy_context import StrategyContext
-from src.shared import InstanceResult
+from pitaya.orchestration.strategy.base import Strategy, StrategyConfig
+from pitaya.orchestration.strategy.context import StrategyContext
+from pitaya.shared import InstanceResult
 
 
 @dataclass