aether-colony 1.1.0

package/.opencode/commands/ant/continue.md

@@ -0,0 +1,938 @@
+---
+name: ant:continue
+description: "➡️🐜🚪🐜➡️ Detect build completion, reconcile state, and advance to next phase"
+---
+
+You are the **Queen Ant Colony**. Reconcile completed work and advance to the next phase.
+
+## Instructions
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+Parse `$normalized_args`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 0: Initialize Visual Mode (if enabled)
+
+If `visual_mode` is true:
+```bash
+# Generate session ID
+continue_id="continue-$(date +%s)"
+
+# Initialize swarm display
+bash .aether/aether-utils.sh swarm-display-init "$continue_id"
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Phase continuation" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
+```
+
+### Step 0.5: Version Check (Non-blocking)
+
+Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
+
+If the command succeeds and the JSON result contains a non-empty string, display it as a one-line notice. Proceed regardless of outcome.
+
+### Step 1: Read State + Version Check
+
+Read `.aether/data/COLONY_STATE.json`.
+
+**Auto-upgrade old state:**
+If `version` field is missing, "1.0", or "2.0":
+1. Preserve: `goal`, `state`, `current_phase`, `plan.phases`
+2. Write upgraded v3.0 state (same structure as /ant:init but preserving data)
+3. Output: `State auto-upgraded to v3.0`
+4. Continue with command.
+
+Extract: `goal`, `state`, `current_phase`, `plan.phases`, `errors`, `memory`, `events`, `build_started_at`.
+
+**Validation:**
+- If `goal: null` -> output "No colony initialized. Run /ant:init first." and stop.
+- If `plan.phases` is empty -> output "No project plan. Run /ant:plan first." and stop.
+
+### Step 1.5: Load State and Show Resumption Context
+
+Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+
+If successful and goal is not null:
+1. Extract current_phase from state
+2. Get phase name from plan.phases[current_phase - 1].name (or "(unnamed)")
+3. Display brief resumption context:
+   ```
+   🔄 Resuming: Phase X - Name
+   ```
+
+If .aether/HANDOFF.md exists (detected in load-state output):
+- Display "Resuming from paused session"
+- Read .aether/HANDOFF.md for additional context
+- Remove .aether/HANDOFF.md after display (cleanup)
+
+Run: `bash .aether/aether-utils.sh unload-state` to release lock.
+
+**Error handling:**
+- If E_FILE_NOT_FOUND: "No colony initialized. Run /ant:init first." and stop
+- If validation error: Display error details with recovery suggestion and stop
+- For other errors: Display generic error and suggest /ant:status for diagnostics
+
+**Completion Detection:**
+
+If `state == "EXECUTING"`:
+1. Check if `build_started_at` exists
+2. Look for phase completion evidence:
+   - Activity log entries showing task completion
+   - Files created/modified matching phase tasks
+3. If no evidence and build started > 30 min ago:
+   - Display "Stale EXECUTING state. Build may have been interrupted."
+   - Offer: continue anyway or rollback to git checkpoint
+   - Rollback procedure: `git stash list | grep "aether-checkpoint"` to find ref, then `git stash pop <ref>` to restore
+
+If `state != "EXECUTING"`:
+- Normal continue flow (no build to reconcile)
+
+### Step 1.5: Verification Loop Gate (MANDATORY)
+
+**The Iron Law:** No phase advancement without fresh verification evidence.
+
+Before ANY phase can advance, execute the 6-phase verification loop. See `.aether/docs/disciplines/verification-loop.md` for full reference.
+
+#### 1. Command Resolution (Priority Chain)
+
+Resolve each command (build, test, types, lint) using this priority chain. Stop at the first source that provides a value for each command:
+
+**Priority 1 — CLAUDE.md (System Context):**
+Check the CLAUDE.md instructions already loaded in your system context for explicit build, test, type-check, or lint commands. These are authoritative and override all other sources.
+
+**Priority 2 — codebase.md `## Commands`:**
+Read `.aether/data/codebase.md` and look for the `## Commands` section. Use any commands listed there for slots not yet filled by Priority 1.
+
+**Priority 3 — Fallback Heuristic Table:**
+For any commands still unresolved, check for these files in order, use first match:
+
+| File | Build | Test | Types | Lint |
+|------|-------|------|-------|------|
+| `package.json` | `npm run build` | `npm test` | `npx tsc --noEmit` | `npm run lint` |
+| `Cargo.toml` | `cargo build` | `cargo test` | (built-in) | `cargo clippy` |
+| `go.mod` | `go build ./...` | `go test ./...` | `go vet ./...` | `golangci-lint run` |
+| `pyproject.toml` | `python -m build` | `pytest` | `pyright .` | `ruff check .` |
+| `Makefile` | `make build` | `make test` | (check targets) | `make lint` |
+
+If no build system detected, skip build/test/type/lint checks but still verify success criteria.
+
+#### 2. Run 6-Phase Verification Loop
+
+Execute all applicable phases and capture output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+👁️🐜 V E R I F I C A T I O N   L O O P
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase {id} — Checking colony work...
+```
+
+**Phase 1: Build Check** (if command exists):
+```bash
+{build_command} 2>&1 | tail -30
+```
+Record: exit code, any errors. **STOP if fails.**
+
+**Phase 2: Type Check** (if command exists):
+```bash
+{type_command} 2>&1 | head -30
+```
+Record: error count. Report all type errors.
+
+**Phase 3: Lint Check** (if command exists):
+```bash
+{lint_command} 2>&1 | head -30
+```
+Record: warning count, error count.
+
+**Phase 4: Test Check** (if command exists):
+```bash
+{test_command} 2>&1 | tail -50
+```
+Record: pass count, fail count, exit code. **STOP if fails.**
+
+**Coverage Check** (if coverage command exists):
+```bash
+{coverage_command}  # e.g., npm run test:coverage
+```
+Record: coverage percentage (target: 80%+ for new code)
+
+**Phase 5: Security Scan**:
+```bash
+# Check for exposed secrets
+grep -rn "sk-\|api_key\|password\s*=" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | head -10
+
+# Check for debug artifacts
+grep -rn "console\.log\|debugger" --include="*.ts" --include="*.tsx" --include="*.js" src/ 2>/dev/null | head -10
+```
+Record: potential secrets (critical), debug artifacts (warning).
+
+**Phase 6: Diff Review**:
+```bash
+git diff --stat
+```
+Review changed files for unintended modifications.
+
+**Success Criteria Check:**
+Read phase success criteria from `plan.phases[current].success_criteria`.
+For EACH criterion:
+1. Identify what proves it (file exists? test passes? output shows X?)
+2. Run the check
+3. Record evidence or gap
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+👁️🐜 V E R I F I C A T I O N   R E P O R T
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔨 Build        [PASS/FAIL/SKIP]
+🔍 Types        [PASS/FAIL/SKIP] (X errors)
+🧹 Lint         [PASS/FAIL/SKIP] (X warnings)
+🧪 Tests        [PASS/FAIL/SKIP] (X/Y passed)
+   Coverage     {percent}% (target: 80%)
+🔒 Security     [PASS/FAIL] (X issues)
+📋 Diff         [X files changed]
+
+──────────────────────────────────────────────────
+🐜 Success Criteria
+──────────────────────────────────────────────────
+  ✅ {criterion 1}: {specific evidence}
+  ✅ {criterion 2}: {specific evidence}
+  ❌ {criterion 3}: {what's missing}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall: READY / NOT READY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+#### 3. Gate Decision
+
+**If NOT READY (any of: build fails, tests fail, critical security issues, success criteria unmet):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔🐜 V E R I F I C A T I O N   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase {id} cannot advance until issues are resolved.
+
+🚨 Issues Found:
+{list each failure with specific evidence}
+
+🔧 Required Actions:
+  1. Fix the issues listed above
+  2. Run /ant:continue again to re-verify
+
+The phase will NOT advance until verification passes.
+```
+
+**CRITICAL:** Do NOT proceed to Step 2. Do NOT advance the phase.
+Do NOT offer workarounds. Verification is mandatory.
+
+Use AskUserQuestion to confirm they understand what needs to be fixed:
+- Show the specific failures
+- Ask if they want to fix now or need help
+
+**If READY (all checks pass with evidence):**
+
+```
+✅🐜 VERIFICATION PASSED
+
+All checks completed with evidence:
+{list each check and its evidence}
+
+Proceeding to gate checks...
+```
+
+Continue to Step 1.6.
+
+### Step 1.6: Spawn Enforcement Gate (MANDATORY)
+
+**The Iron Law:** No phase advancement without worker spawning for non-trivial phases.
+
+Read `.aether/data/spawn-tree.txt` to count spawns for this phase.
+
+```bash
+grep -c "spawned" .aether/data/spawn-tree.txt 2>/dev/null || echo "0"
+```
+
+Also check for Watcher spawns specifically:
+```bash
+grep -c "watcher" .aether/data/spawn-tree.txt 2>/dev/null || echo "0"
+```
+
+**HARD REJECTION - If spawn_count == 0 and phase had 3+ tasks:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔🐜 S P A W N   G A T E   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This phase had {task_count} tasks but spawn_count: 0
+The Prime Worker violated the spawn protocol.
+
+🐜 The colony requires actual parallelism:
+  - Prime Worker MUST spawn specialists for non-trivial work
+  - A single agent doing everything is NOT a colony
+  - "Justifications" for not spawning are not accepted
+
+🔧 Required Actions:
+  1. Run /ant:build {phase} again
+  2. Prime Worker MUST spawn at least 1 specialist
+  3. Re-run /ant:continue after spawns complete
+
+The phase will NOT advance until spawning occurs.
+```
+
+**CRITICAL:** Do NOT proceed to Step 1.7. Do NOT advance the phase.
+Log the violation:
+```bash
+bash .aether/aether-utils.sh activity-log "BLOCKED" "colony" "Spawn gate failed: {task_count} tasks, 0 spawns"
+bash .aether/aether-utils.sh error-flag-pattern "no-spawn-violation" "Prime Worker completed phase without spawning specialists" "critical"
+```
+
+**HARD REJECTION - If watcher_count == 0 (no testing separation):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔👁️🐜 W A T C H E R   G A T E   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No Watcher ant was spawned for testing/verification.
+Testing MUST be performed by a separate agent, not the builder.
+
+🐜 Why this matters:
+  - Builders verify their own work = confirmation bias
+  - Independent Watchers catch bugs builders miss
+  - "Build passing" ≠ "App working"
+
+🔧 Required Actions:
+  1. Run /ant:build {phase} again
+  2. Prime Worker MUST spawn at least 1 Watcher
+  3. Watcher must independently verify the work
+
+The phase will NOT advance until a Watcher validates.
+```
+
+**CRITICAL:** Do NOT proceed. Log the violation.
+
+**If spawn_count >= 1 AND watcher_count >= 1:**
+
+```
+✅🐜 SPAWN GATE PASSED — {spawn_count} workers | {watcher_count} watchers
+```
+
+Continue to Step 1.7.
+
+### Step 1.7: Anti-Pattern Gate
+
+Scan all modified/created files for known anti-patterns. This catches recurring bugs before they reach production.
+
+```bash
+bash .aether/aether-utils.sh check-antipattern "{file_path}"
+```
+
+Run for each file in `files_created` and `files_modified` from Prime Worker output.
+
+**Anti-Pattern Report:**
+
+```
+🔍🐜 Anti-Pattern Scan — {count} files scanned
+
+{if critical issues:}
+🛑 CRITICAL (must fix):
+{list each with file:line and description}
+
+{if warnings:}
+⚠️ WARNINGS:
+{list each with file:line and description}
+
+{if clean:}
+✅🐜 No anti-patterns detected
+```
+
+**CRITICAL issues block phase advancement:**
+- Swift didSet infinite recursion
+- Exposed secrets/credentials
+- SQL injection patterns
+- Known crash patterns
+
+**WARNINGS are logged but don't block:**
+- TypeScript `any` usage
+- Console.log in production code
+- TODO/FIXME comments
+
+If CRITICAL issues found, display:
+
+```
+⛔🐜 ANTI-PATTERN GATE FAILED
+
+Critical anti-patterns detected:
+{list issues with file paths}
+
+Run /ant:build {phase} again after fixing.
+```
+
+Do NOT proceed to Step 2.
+
+If no CRITICAL issues, continue to Step 1.8.
+
+### Step 1.8: TDD Evidence Gate (MANDATORY)
+
+**The Iron Law:** No TDD claims without actual test files.
+
+If Prime Worker reported TDD metrics (tests_added, tests_total, coverage_percent), verify test files exist:
+
+```bash
+# Check for test files based on project type
+find . -name "*.test.*" -o -name "*_test.*" -o -name "*Tests.swift" -o -name "test_*.py" 2>/dev/null | head -10
+```
+
+**If Prime Worker claimed tests_added > 0 but no test files found:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔🧪🐜 T D D   G A T E   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Prime Worker claimed:
+  tests_added: {claimed_count}
+  tests_total: {claimed_total}
+  coverage: {claimed_coverage}%
+
+But no test files were found in the codebase.
+
+🚨 CRITICAL violation — fabricated TDD metrics.
+
+🔧 Required Actions:
+  1. Run /ant:build {phase} again
+  2. Actually write test files (not just claim them)
+  3. Tests must exist and be runnable
+
+The phase will NOT advance with fabricated metrics.
+```
+
+**CRITICAL:** Do NOT proceed. Log the violation:
+```bash
+bash .aether/aether-utils.sh error-flag-pattern "fabricated-tdd" "Prime Worker reported TDD metrics without creating test files" "critical"
+```
+
+**If tests_added == 0 or test files exist matching claims:**
+
+Continue to Step 1.9.
+
+### Step 1.9: Runtime Verification Gate (MANDATORY)
+
+**The Iron Law:** Build passing ≠ App working.
+
+Before advancing, the user must confirm the application actually runs.
+
+Use AskUserQuestion:
+
+```
+──────────────────────────────────────────────────
+🐜 Runtime Verification Required
+──────────────────────────────────────────────────
+
+Build checks passed — but does the app actually work?
+
+Have you tested the application at runtime?
+```
+
+Options:
+1. **Yes, tested and working** - App runs correctly, features work
+2. **Yes, tested but has issues** - App runs but has bugs (describe)
+3. **No, haven't tested yet** - Need to test before continuing
+4. **Skip (not applicable)** - No runnable app in this phase (e.g., library code)
+
+**If "Yes, tested and working":**
+```
+✅🐜 RUNTIME VERIFIED — User confirmed app works.
+```
+Continue to Step 2.
+
+**If "Yes, tested but has issues":**
+```
+⛔🐜 RUNTIME GATE FAILED — User reported issues.
+
+Please describe the issues so they can be addressed:
+```
+
+Use AskUserQuestion to get issue details. Log to errors.records:
+```bash
+bash .aether/aether-utils.sh error-add "runtime" "critical" "{user_description}" {phase}
+```
+
+Do NOT proceed to Step 2.
+
+**If "No, haven't tested yet":**
+```
+⏸️🐜 RUNTIME PENDING — Test the app, then run /ant:continue again.
+
+  - [ ] App launches without crashing
+  - [ ] Core features work as expected
+  - [ ] UI responds to user interaction
+  - [ ] No freezes or hangs
+```
+
+Do NOT proceed to Step 2.
+
+**If "Skip (not applicable)":**
+
+Only valid for phases that don't produce runnable code (e.g., documentation, config files, library code with no entry point).
+
+```
+⏭️ RUNTIME CHECK SKIPPED
+
+User indicated no runnable app for this phase.
+Proceeding to phase advancement.
+```
+
+Continue to Step 1.10.
+
+### Step 1.10: Flags Gate (MANDATORY)
+
+**The Iron Law:** No phase advancement with unresolved blockers.
+
+First, auto-resolve any flags eligible for resolution now that verification has passed:
+```bash
+bash .aether/aether-utils.sh flag-auto-resolve "build_pass"
+```
+
+Then check for remaining blocking flags:
+```bash
+bash .aether/aether-utils.sh flag-check-blockers {current_phase}
+```
+
+Parse result for `blockers`, `issues`, and `notes` counts.
+
+**If blockers > 0:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔🚩🐜 F L A G S   G A T E   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{blockers} blocker(s) must be resolved first.
+
+🚩 Active Blockers:
+{list each blocker flag with ID, title, and description}
+
+🔧 Required Actions:
+  1. Fix the issues described in each blocker
+  2. Resolve flags: /ant:flags --resolve {flag_id} "resolution message"
+  3. Run /ant:continue again after resolving all blockers
+```
+
+**CRITICAL:** Do NOT proceed to Step 2. Do NOT advance the phase.
+
+**If blockers == 0 but issues > 0:**
+
+```
+⚠️🐜 FLAGS: {issues} issue(s) noted (non-blocking)
+
+{list each issue flag}
+
+Use /ant:flags to review.
+```
+
+Continue to Step 2.
+
+**If all clear (no blockers or issues):**
+
+```
+✅🐜 FLAGS GATE PASSED — No blockers.
+```
+
+Continue to Step 2.
+
+### Step 2: Update State
+
+Find current phase in `plan.phases`.
+Determine next phase (`current_phase + 1`).
+
+**If no next phase (all complete):** Skip to Step 2.6 (commit suggestion), then Step 2.5 (completion).
+
+Update COLONY_STATE.json:
+
+1. **Mark current phase completed:**
+   - Set `plan.phases[current].status` to `"completed"`
+   - Set all tasks in phase to `"completed"`
+
+2. **Extract learnings (with validation status):**
+
+   **CRITICAL: Learnings start as HYPOTHESES until verified.**
+
+   A learning is only "validated" if:
+   - The code was actually run and tested
+   - The feature works in practice, not just in theory
+   - User has confirmed the behavior
+
+   Append to `memory.phase_learnings`:
+   ```json
+   {
+     "id": "learning_<unix_timestamp>",
+     "phase": <phase_number>,
+     "phase_name": "<name>",
+     "learnings": [
+       {
+         "claim": "<specific actionable learning>",
+         "status": "hypothesis",
+         "tested": false,
+         "evidence": "<what observation led to this>",
+         "disproven_by": null
+       }
+     ],
+     "timestamp": "<ISO-8601>"
+   }
+   ```
+
+   **Status values:**
+   - `hypothesis` - Recorded but not verified (DEFAULT)
+   - `validated` - Tested and confirmed working
+   - `disproven` - Found to be incorrect
+
+   **Do NOT record a learning if:**
+   - It wasn't actually tested
+   - It's stating the obvious
+   - There's no evidence it works
+
+2.5. **Record learning observations for threshold tracking:**
+
+   For each learning extracted, record an observation to enable threshold-based wisdom promotion.
+
+   Run using the Bash tool with description "Recording learning observations...":
+   ```bash
+   colony_name=$(jq -r '.session_id | split("_")[1] // "unknown"' .aether/data/COLONY_STATE.json 2>/dev/null || echo "unknown")
+
+   # Get learnings from the current phase
+   current_phase_learnings=$(jq -r --argjson phase "$current_phase" '.memory.phase_learnings[] | select(.phase == $phase)' .aether/data/COLONY_STATE.json 2>/dev/null || echo "")
+
+   if [[ -n "$current_phase_learnings" ]]; then
+     echo "$current_phase_learnings" | jq -r '.learnings[]?.claim // empty' 2>/dev/null | while read -r claim; do
+       if [[ -n "$claim" ]]; then
+         # Default wisdom_type to "pattern" (threshold: 3 observations)
+         bash .aether/aether-utils.sh learning-observe "$claim" "pattern" "$colony_name" 2>/dev/null || true
+       fi
+     done
+     echo "Recorded observations for threshold tracking"
+   else
+     echo "No learnings to record"
+   fi
+   ```
+
+   This records each learning in `learning-observations.json` with:
+   - Content hash for deduplication (same claim across phases increments count)
+   - Observation count (increments if seen before)
+   - Colony name for cross-colony tracking
+
+   When observations reach threshold (default: 3 for "pattern" type), they become eligible for promotion in Step 2.1.5.
+
+3. **Extract instincts from patterns:**
+
+   Read activity.log for patterns from this phase's build.
+
+   For each pattern observed (success, error_resolution, user_feedback):
+
+   **If pattern matches existing instinct:**
+   - Update confidence: +0.1 for success outcome, -0.1 for failure
+   - Increment applications count
+   - Update last_applied timestamp
+
+   **If new pattern:**
+   - Create new instinct with initial confidence:
+     - success: 0.4
+     - error_resolution: 0.5
+     - user_feedback: 0.7
+
+   Append to `memory.instincts`:
+   ```json
+   {
+     "id": "instinct_<unix_timestamp>",
+     "trigger": "<when X>",
+     "action": "<do Y>",
+     "confidence": 0.5,
+     "status": "hypothesis",
+     "domain": "<testing|architecture|code-style|debugging|workflow>",
+     "source": "phase-<id>",
+     "evidence": ["<specific observation that led to this>"],
+     "tested": false,
+     "created_at": "<ISO-8601>",
+     "last_applied": null,
+     "applications": 0,
+     "successes": 0,
+     "failures": 0
+   }
+   ```
+
+   **Instinct confidence updates:**
+   - Success when applied: +0.1, increment `successes`
+   - Failure when applied: -0.15, increment `failures`
+   - If `failures` >= 2 and `successes` == 0: mark `status: "disproven"`
+   - If `successes` >= 2 and tested: mark `status: "validated"`
+
+   Cap: Keep max 30 instincts (remove lowest confidence when exceeded).
+
+4. **Advance state:**
+   - Set `current_phase` to next phase number
+   - Set `state` to `"READY"`
+   - Set `build_started_at` to null
+   - Append event: `"<timestamp>|phase_advanced|continue|Completed Phase <id>, advancing to Phase <next>"`
+
+5. **Cap enforcement:**
+   - Keep max 20 phase_learnings
+   - Keep max 30 decisions
+   - Keep max 30 instincts (remove lowest confidence)
+   - Keep max 100 events
+
+Write COLONY_STATE.json.
+
+### Step 2.3: Update Handoff Document
+
+After advancing the phase, update the handoff document with the new current state:
+
+```bash
+# Determine if there's a next phase
+next_phase_id=$((current_phase + 1))
+has_next_phase=$(jq --arg next "$next_phase_id" '.plan.phases | map(select(.id == ($next | tonumber))) | length' .aether/data/COLONY_STATE.json)
+
+# Write updated handoff
+cat > .aether/HANDOFF.md << 'HANDOFF_EOF'
+# Colony Session — Phase Advanced
+
+## Quick Resume
+Run `/ant:build {next_phase_id}` to start working on the current phase.
+
+## State at Advancement
+- Goal: "$(jq -r '.goal' .aether/data/COLONY_STATE.json)"
+- Completed Phase: {completed_phase_id} — {completed_phase_name}
+- Current Phase: {next_phase_id} — {next_phase_name}
+- State: READY
+- Updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+## What Was Completed
+- Phase {completed_phase_id} marked as completed
+- Learnings extracted: {learning_count}
+- Instincts updated: {instinct_count}
+
+## Current Phase Tasks
+$(jq -r '.plan.phases[] | select(.id == next_phase_id) | .tasks[] | "- [ ] \(.id): \(.description)"' .aether/data/COLONY_STATE.json)
+
+## Next Steps
+- Build current phase: `/ant:build {next_phase_id}`
+- Review phase details: `/ant:phase {next_phase_id}`
+- Pause colony: `/ant:pause-colony`
+
+## Session Note
+Phase advanced successfully. Colony is READY to build Phase {next_phase_id}.
+HANDOFF_EOF
+```
+
+This handoff reflects the post-advancement state, allowing seamless resumption even if the session is lost.
+
+### Step 2.4: Update Changelog
+
+**Append a changelog entry for the completed phase.**
+
+If `CHANGELOG.md` exists in the project root:
+
+1. Read the file
+2. Find the `## [Unreleased]` section
+3. Under the appropriate sub-heading (`### Added`, `### Changed`, or `### Fixed`), append a bullet for the completed phase:
+
+```
+- **Phase {id}: {phase_name}** — {one-line summary of what was accomplished}. ({list of key files modified})
+```
+
+**Determining the sub-heading:**
+- If the phase created new features/commands → `### Added`
+- If the phase modified existing behavior → `### Changed`
+- If the phase fixed bugs → `### Fixed`
+- If unclear, default to `### Changed`
+
+**The one-line summary** should describe the user-visible outcome, not implementation details. Derive it from the phase description and task summaries.
+
+**If no `## [Unreleased]` section exists**, create one at the top of the file (after the header).
+
+**If no `CHANGELOG.md` exists**, skip this step silently.
+
+### Step 2.6: Commit Suggestion (Optional)
+
+**This step is non-blocking. Skipping does not affect phase advancement or any subsequent steps. Failure to commit has zero consequences.**
+
+After the phase is advanced and changelog updated, suggest a commit to preserve the milestone.
+
+1. **Generate the commit message:**
+```bash
+bash .aether/aether-utils.sh generate-commit-message "milestone" {phase_id} "{phase_name}" "{one_line_summary}"
+```
+Parse the returned JSON to extract `message` and `files_changed`.
+
+2. **Check files changed:**
+```bash
+git diff --stat HEAD 2>/dev/null | tail -5
+```
+If not in a git repo or no changes detected, skip this step silently.
+
+3. **Display the suggestion:**
+```
+──────────────────────────────────────────────────
+Commit Suggestion
+──────────────────────────────────────────────────
+
+  Message:  {generated_message}
+  Files:    {files_changed} files changed
+  Preview:  {first 5 lines of git diff --stat}
+
+──────────────────────────────────────────────────
+```
+
+4. **Use AskUserQuestion:**
+```
+Commit this milestone?
+
+1. Yes, commit with this message
+2. Yes, but let me write the message
+3. No, I'll commit later
+```
+
+5. **If option 1 ("Yes, commit with this message"):**
+```bash
+git add -A && git commit -m "{generated_message}"
+```
+Display: `Committed: {generated_message} ({files_changed} files)`
+
+6. **If option 2 ("Yes, but let me write the message"):**
+Use AskUserQuestion to get the user's custom commit message, then:
+```bash
+git add -A && git commit -m "{custom_message}"
+```
+Display: `Committed: {custom_message} ({files_changed} files)`
+
+7. **If option 3 ("No, I'll commit later"):**
+Display: `Skipped. Your changes are saved on disk but not committed.`
+
+8. **Record the suggestion to prevent double-prompting:**
+Set `last_commit_suggestion_phase` to `{phase_id}` in COLONY_STATE.json (add the field at the top level if it does not exist).
+
+**Error handling:** If any git command fails (not a repo, merge conflict, pre-commit hook rejection), display the error output and continue to the next step. The commit suggestion is advisory only -- it never blocks the flow.
+
+Continue to Step 2.7 (Context Clear Suggestion), then to Step 2.5 (Project Completion) or Step 3 (Display Result).
+
+### Step 2.7: Context Clear Suggestion (Optional)
+
+**This step is non-blocking. Skipping does not affect phase advancement.**
+
+After committing (or skipping commit), suggest clearing context to refresh before the next phase.
+
+1. **Display the suggestion:**
+```
+──────────────────────────────────────────────────
+Context Refresh
+──────────────────────────────────────────────────
+
+State is fully persisted and committed.
+Phase {next_id} is ready to build.
+
+──────────────────────────────────────────────────
+```
+
+2. **Use AskUserQuestion:**
+```
+Clear context now?
+
+1. Yes, clear context then run /ant:build {next_id}
+2. No, continue in current context
+```
+
+3. **If option 1 ("Yes, clear context"):**
+
+   **IMPORTANT:** Claude Code does not support programmatic /clear. Display instructions:
+   ```
+   Please type: /clear
+   
+   Then run: /ant:build {next_id}
+   ```
+   
+   Record the suggestion: Set `context_clear_suggested` to `true` in COLONY_STATE.json.
+
+4. **If option 2 ("No, continue in current context"):**
+   Display: `Continuing in current context. State is saved.`
+
+Continue to Step 2.5 (Project Completion) or Step 3 (Display Result).
+
+### Step 2.5: Project Completion
+
+Runs ONLY when all phases complete.
+
+1. Read activity.log and errors.records
+2. Display tech debt report:
+
+```
+🐜 ═══════════════════════════════════════════════════
+   🎉 P R O J E C T   C O M P L E T E 🎉
+═══════════════════════════════════════════════════ 🐜
+
+👑 Goal Achieved: {goal}
+📍 Phases Completed: {total}
+
+{if flagged_patterns:}
+⚠️ Persistent Issues:
+{list any flagged_patterns}
+{end if}
+
+🧠 Colony Learnings:
+{condensed learnings from memory.phase_learnings}
+
+🐜 The colony rests. Well done!
+```
+
+3. Write summary to `.aether/data/completion-report.md`
+4. Display next commands and stop.
+
+### Step 3: Display Result
+
+**If visual_mode is true, render final swarm display:**
+```bash
+bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Phase advanced" "Colony" '{"read":5,"grep":2,"edit":3,"bash":2}' 100 "fungus_garden" 100
+bash .aether/aether-utils.sh swarm-display-render "$continue_id"
+```
+
+Output:
+
+```
+🐜 ═══════════════════════════════════════════════════
+   P H A S E   A D V A N C E M E N T
+═══════════════════════════════════════════════════ 🐜
+
+✅ Phase {prev_id}: {prev_name} -- COMPLETED
+
+🧠 Learnings Extracted:
+{list learnings added}
+
+🐜 Instincts Updated:
+{for each instinct created or updated:}
+   [{confidence}] {domain}: {action}
+{end for}
+
+─────────────────────────────────────────────────────
+
+➡️ Advancing to Phase {next_id}: {next_name}
+   {next_description}
+   📋 Tasks: {task_count}
+   📊 State: READY
+
+🐜 Next Steps:
+   /ant:build {next_id}   🔨 Start building Phase {next_id}: {next_name}
+   /ant:phase {next_id}   📋 Review phase details first
+   /ant:focus "<area>"    🎯 Guide colony attention
+
+💾 State persisted — context clear suggested above
+```
+
+**IMPORTANT:** In the "Next Steps" section above, substitute the actual phase number for `{next_id}` (calculated in Step 2 as `current_phase + 1`). For example, if advancing to phase 4, output `/ant:build 4` not `/ant:build {next_id}`.