CLI
afa enhance
Generate AI-powered enhancement candidates and validate them through nine quantitative gates.
afa enhance
Generate enhancement candidates for functions and validate them through all nine quantitative gates.
Usage
afa enhance <path> [options]Arguments
| Argument | Required | Description |
|---|---|---|
path | Yes | File or directory to enhance |
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | Show proposed changes without committing |
--provider | anthropic | LLM provider |
--format | table | Output format (table, json, sarif) |
The enhancement loop
AFA runs a convergent loop per function:
Analyze --> Generate Candidates --> Gate Check (9 gates) --> Commit or RedesignFor each function:
- Analyze -- run all four analysis agents to identify improvement opportunities
- Generate -- create up to 3 enhancement candidates (configurable via
enhancement.max_candidates) - Gate check -- evaluate each candidate against all 9 quantitative gates
- Decide:
- All gates pass --> commit the enhancement on an
afa/branch - Near miss (within 1.1x of thresholds) --> redesign and retry (up to 3 times)
- Utility ratio < 1.0 --> skip (cost exceeds value)
- Max retries exhausted --> skip
- All gates pass --> commit the enhancement on an
Dry run mode
Always start with --dry-run to see what AFA would do:
afa enhance src/ --dry-runIn dry-run mode, AFA runs the full pipeline -- analysis, generation, gate evaluation -- but does not create branches or commit changes. You see the proposed diff and gate results for every candidate.
Branch isolation
When not in dry-run mode, AFA creates changes on isolated branches using git worktrees:
- Branch prefix:
afa/(configurable) - Worktree directory: temporary, cleaned up after commit
- Your working tree is never modified directly
- Changes never land on your main branch without a PR
What happens when gates fail
Each gate failure produces a diagnostic message:
| Gate | Failure means |
|---|---|
| Complexity | Enhancement adds too much structural complexity (hard floor: 0.5, non-overridable) |
| Risk/Profit | Change doesn't measurably improve risk or profit metrics |
| Novelty | Change is too trivial to justify pipeline resources |
| Quality | Aggregate quality below 0.7 or a sub-score is zero |
| Utility | Economic cost exceeds the value of the improvement |
| Entropy | Diff has suspiciously low entropy (potential gaming) |
| Supply Chain | Build provenance verification failed |
| KPI | Enhancement doesn't align with business KPIs |
Use afa explain <enhancement-id> to get a detailed breakdown of why a specific enhancement was rejected.
Examples
# Dry-run a single file
afa enhance src/utils.py --dry-run
# Enhance a directory with Gemini
afa --provider gemini enhance src/afa/gates/
# JSON output for CI
afa --format json enhance src/ --dry-run