Runbook: Project Import & Auto-Improvement (Phase 6)¶

Import a codebase, analyze it, review it, and apply improvements — safely on a copy.

Prerequisites¶

aop diagnose            # Ollama up (for LLM review/improve)
# git on PATH (for git-URL imports)

Workflow¶

# 1. Import (path, .zip, or git URL) → isolated copy under data/projects/<id>/project
aop project import ./path/to/repo
aop project import project.zip
aop project import https://github.com/org/repo.git

# 2. Analyze (static ruff/mypy + AST + deps + data-leakage [+ LLM review])
aop project analyze <id>              # full (includes LLM review)
aop project analyze <id> --no-review  # fast, deterministic only
aop project report <id> --json        # machine-readable report

# 3. Improve a file (LLM rewrite → unified diff preview)
aop project improve <id> --file src/module.py

# 4. Apply (writes to the imported copy ONLY, after you confirm)
aop project apply <id> --file src/module.py --yes

What gets checked¶

Category	Tool	Examples
static	ruff	unused imports, bugs (F), style (E/W), bugbear, simplify
static	mypy	type errors (lenient: `--ignore-missing-imports`)
ast	built-in	high cyclomatic complexity, too many params, very long functions
deps	built-in	unpinned dependencies
leakage	built-in	fit/fit_transform before `train_test_split`; split w/o `random_state`
review	LLM	anti-patterns, missing error handling, semantic leakage

Safety¶

Everything operates on the imported copy (data/projects/<id>/project). apply writes only there, and only after a diff preview + explicit --yes. Your original is never touched.

Troubleshooting¶

Symptom	Cause	Fix
many E501 findings	`ruff --isolated` uses width 88	expected baseline; configure your project's ruff for its own runs.
`git clone failed`	bad URL / no network / private repo	check the URL; private repos need credentials in the URL.
review findings sparse	tiny local model formatting	use a larger/cloud model via `AOP_DEFAULT_CHAT_*`.
`no proposal` on apply	improve not run	run `project improve` first.

Tuning¶

AOP_PROJECTS_DIR, AOP_PROJECT_REVIEW_MAX_FILES.