aether-colony 5.0.0 → 5.2.1

package/.aether/docs/command-playbooks/continue-full.md

@@ -0,0 +1,1725 @@
+---
+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
+
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+### Step 1: Read State
+
+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 `milestone` == `"Crowned Anthill"` -> output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." 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 the Bash tool with description "Loading colony state...": `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 using the Bash tool with description "Releasing colony lock...": `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):
+Run using the Bash tool with description "Running build check...": `{build_command} 2>&1 | tail -30`
+Record: exit code, any errors. **STOP if fails.**
+
+**Phase 2: Type Check** (if command exists):
+Run using the Bash tool with description "Running type check...": `{type_command} 2>&1 | head -30`
+Record: error count. Report all type errors.
+
+**Phase 3: Lint Check** (if command exists):
+Run using the Bash tool with description "Running lint check...": `{lint_command} 2>&1 | head -30`
+Record: warning count, error count.
+
+**Phase 4: Test Check** (if command exists):
+Run using the Bash tool with description "Running test suite...": `{test_command} 2>&1 | tail -50`
+Record: pass count, fail count, exit code. **STOP if fails.**
+
+**Coverage Check** (if coverage command exists):
+Run using the Bash tool with description "Checking test coverage...": `{coverage_command}  # e.g., npm run test:coverage`
+Record: coverage percentage (target: 80%+ for new code)
+
+#### Step 1.5.1: Probe Coverage Agent (Conditional)
+
+**Test coverage improvement — runs when coverage < 80% AND tests pass.**
+
+1. **Check coverage threshold condition:**
+   - Coverage data is already available from Phase 4 coverage check
+   - If tests failed: Skip Probe silently (coverage data unreliable)
+   - If coverage_percent >= 80%: Skip Probe silently, continue to Phase 5
+   - If coverage_percent < 80% AND tests passed: Proceed to spawn Probe
+
+2. **If skipping Probe:**
+```
+🧪🐜 Probe: Coverage at {coverage_percent}% — {reason_for_skip}
+```
+Continue to Phase 5: Secrets Scan.
+
+3. **If spawning Probe:**
+
+   a. Generate Probe name and dispatch:
+   Run using the Bash tool with description "Generating Probe name...": `probe_name=$(bash .aether/aether-utils.sh generate-ant-name "probe" | jq -r '.result') && bash .aether/aether-utils.sh spawn-log "Queen" "probe" "$probe_name" "Coverage improvement: ${coverage_percent}%" && echo "{\"name\":\"$probe_name\"}"`
+
+
+   c. Display: `🧪🐜 Probe {probe_name} spawning — Coverage at {coverage_percent}%, generating tests for uncovered paths...`
+
+   d. Determine uncovered files:
+   Run using the Bash tool with description "Getting modified source files...": `modified_source_files=$(git diff --name-only HEAD~1 2>/dev/null || git diff --name-only) && source_files=$(echo "$modified_source_files" | grep -v "\.test\." | grep -v "\.spec\." | grep -v "__tests__") && echo "$source_files"`
+
+   e. Spawn Probe agent:
+
+   Use the Task tool with subagent_type="aether-probe" (if available; otherwise use general-purpose and inject the Probe role from `.opencode/agents/aether-probe.md`):
+
+   ```xml
+   <mission>
+   Improve test coverage for uncovered code paths in the modified files.
+   </mission>
+
+   <work>
+   1. Analyze the modified source files for uncovered branches and edge cases
+   2. Identify which paths lack test coverage
+   3. Generate test cases that exercise uncovered code paths
+   4. Run the new tests to verify they pass
+   5. Report coverage improvements and edge cases discovered
+   </work>
+
+   <context>
+   Current coverage: {coverage_percent}%
+   Target coverage: 80%
+   Modified source files: {modified_source_files}
+   </context>
+
+   <constraints>
+   - Test files ONLY — never modify source code
+   - Follow existing test conventions in the codebase
+   - Do NOT delete or modify existing tests
+   </constraints>
+
+   <output>
+   Provide JSON output matching this schema:
+   {
+     "ant_name": "your probe name",
+     "caste": "probe",
+     "status": "completed" | "failed" | "blocked",
+     "summary": "Brief summary of coverage improvements",
+     "coverage": {
+       "lines": 0,
+       "branches": 0,
+       "functions": 0
+     },
+     "tests_added": ["file1.test.js", "file2.test.js"],
+     "edge_cases_discovered": ["edge case 1", "edge case 2"],
+     "mutation_score": 0,
+     "weak_spots": [],
+     "blockers": []
+   }
+   </output>
+   ```
+
+   f. Parse Probe JSON output and log completion:
+   Extract: `tests_added`, `coverage.lines`, `coverage.branches`, `coverage.functions`, `edge_cases_discovered`, `mutation_score`
+
+   Run using the Bash tool with description "Logging Probe completion...": `bash .aether/aether-utils.sh spawn-complete "$probe_name" "completed" "{\"tests_added\":${#tests_added[@]},\"coverage\":{\"lines\":${coverage_lines},\"branches\":${coverage_branches},\"functions\":${coverage_functions}}}"`
+
+   g. Log findings to midden:
+   Run using the Bash tool with description "Logging Probe findings to midden...": `bash .aether/aether-utils.sh midden-write "coverage" "Probe generated tests, coverage: ${coverage_lines}%/${coverage_branches}%/${coverage_functions}%" "probe"`
+
+   If edge cases found:
+   Run using the Bash tool with description "Logging edge cases to midden...": `bash .aether/aether-utils.sh midden-write "edge_cases" "Found ${#edge_cases_discovered[@]} edge cases" "probe"`
+
+4. **NON-BLOCKING continuation:**
+   Display Probe findings summary:
+   ```
+   🧪🐜 Probe complete — Findings logged to midden, continuing verification...
+      Tests added: {count}
+      Edge cases discovered: {count}
+   ```
+
+   **CRITICAL:** ALWAYS continue to Phase 5 (Secrets Scan) regardless of Probe results. Probe is strictly non-blocking — phase advancement continues even if Probe cannot improve coverage.
+
+5. **Record Probe status for verification report:**
+   Set `probe_status = "ACTIVE"` and store tests_added count and edge_cases count for the verification report.
+
+**Phase 5: Secrets Scan** (basic grep-based secret detection):
+Run using the Bash tool with description "Scanning for exposed secrets...": `grep -rn "sk-\|api_key\|password\s*=" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | head -10`
+Run using the Bash tool with description "Scanning 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).
+
+Note: Professional security scanning happens in Step 1.8 (Gatekeeper for CVEs) and Step 1.9 (Auditor for code quality).
+
+**Phase 6: Diff Review**:
+Run using the Bash tool with description "Reviewing file changes...": `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%)
+   🧪 Probe     [ACTIVE/SKIP] (tests added: X, edge cases: Y)
+🔒 Secrets      [PASS/FAIL] (X issues)
+📦 Gatekeeper   [PASS/WARN/SKIP] (X critical, X high)
+👥 Auditor      [PASS/FAIL] (score: X/100)
+📋 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.
+
+Run using the Bash tool with description "Verifying spawn requirements...": `spawn_count=$(grep -c "spawned" .aether/data/spawn-tree.txt 2>/dev/null || echo "0") && watcher_count=$(grep -c "watcher" .aether/data/spawn-tree.txt 2>/dev/null || echo "0") && echo "{\"spawn_count\": $spawn_count, \"watcher_count\": $watcher_count}"`
+
+**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.
+
+For each file, run using the Bash tool with description "Scanning for anti-patterns...": `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.7.1.
+
+### Step 1.7.1: Proactive Refactoring Gate (Conditional)
+
+**Complexity-based refactoring — runs when code exceeds maintainability thresholds.**
+
+1. **Get modified/created files from recent work:**
+   Run using the Bash tool with description "Getting modified files for complexity check...": `modified_files=$(git diff --name-only HEAD~1 2>/dev/null || git diff --name-only) && echo "$modified_files"`
+
+2. **Check complexity thresholds for each file:**
+
+   For each file, check:
+   - Line count > 300 lines
+   - Long functions > 50 lines (simplified heuristic)
+   - Directory density > 10 new files
+
+   Run using the Bash tool with description "Checking complexity thresholds...":
+   ```bash
+   modified_files=$(git diff --name-only HEAD~1 2>/dev/null || git diff --name-only)
+
+   complexity_trigger=false
+   files_needing_refactor=""
+
+   for file in $modified_files; do
+     if [[ -f "$file" ]]; then
+       # Check line count
+       line_count=$(wc -l < "$file" 2>/dev/null || echo "0")
+       if [[ "$line_count" -gt 300 ]]; then
+         complexity_trigger=true
+         files_needing_refactor="$files_needing_refactor $file"
+         continue
+       fi
+
+       # Check for long functions (simplified heuristic)
+       long_funcs=$(grep -c "^[[:space:]]*[a-zA-Z_][a-zA-Z0-9_]*[[:space:]]*(" "$file" 2>/dev/null || echo "0")
+       if [[ "$long_funcs" -gt 50 ]]; then
+         complexity_trigger=true
+         files_needing_refactor="$files_needing_refactor $file"
+       fi
+     fi
+   done
+
+   # Check directory density
+   if [[ -n "$modified_files" ]]; then
+     dir_counts=$(echo "$modified_files" | xargs -I {} dirname {} 2>/dev/null | sort | uniq -c | sort -rn)
+     high_density_dir=$(echo "$dir_counts" | awk '$1 > 10 {print $2}' | head -1)
+     if [[ -n "$high_density_dir" ]]; then
+       complexity_trigger=true
+     fi
+   fi
+
+   echo "{\"complexity_trigger\": \"$complexity_trigger\", \"files_needing_refactor\": \"$files_needing_refactor\"}"
+   ```
+
+3. **If complexity thresholds NOT exceeded:**
+   ```
+   🔄🐜 Weaver: Complexity thresholds not exceeded — skipping proactive refactoring
+   ```
+   Continue to Step 1.8.
+
+4. **If complexity thresholds exceeded:**
+
+   a. **Establish test baseline before refactoring:**
+   Run using the Bash tool with description "Establishing test baseline...": `test_output_before=$(npm test 2>&1 || echo "TEST_FAILED") && tests_passing_before=$(echo "$test_output_before" | grep -oE '[0-9]+ passing' | grep -oE '[0-9]+' || echo "0") && echo "Baseline: $tests_passing_before tests passing"`
+
+   b. **Generate Weaver name and dispatch:**
+   Run using the Bash tool with description "Generating Weaver name...": `weaver_name=$(bash .aether/aether-utils.sh generate-ant-name "weaver" | jq -r '.result') && bash .aether/aether-utils.sh spawn-log "Queen" "weaver" "$weaver_name" "Proactive refactoring" && echo "{\"name\":\"$weaver_name\"}"`
+
+
+   d. **Display:** `🔄🐜 Weaver {weaver_name} spawning — Refactoring complex code...`
+
+   e. **Spawn Weaver agent:**
+
+   Use the Task tool with subagent_type="aether-weaver" (if available; otherwise use general-purpose and inject the Weaver role from `.opencode/agents/aether-weaver.md`):
+
+   ```xml
+   <mission>
+   Refactor complex code to improve maintainability while preserving behavior.
+   </mission>
+
+   <work>
+   1. Analyze target files for complexity issues
+   2. Plan incremental refactoring steps
+   3. Execute one step at a time
+   4. Run tests after each step
+   5. If tests pass, continue; if fail, revert and try smaller step
+   6. Report all changes made
+   </work>
+
+   <context>
+   Target Files: {files_needing_refactor}
+   Test Baseline: {tests_passing_before} tests passing (MUST maintain after refactor)
+
+   Refactoring Guidelines:
+   - Extract methods/functions over 50 lines
+   - Split files over 300 lines
+   - Remove duplication (DRY)
+   - Improve naming for clarity
+   - Apply Single Responsibility Principle
+   </context>
+
+   <constraints>
+   - NEVER change behavior — only structure
+   - Run tests after each refactoring step
+   - If tests fail, revert immediately
+   - Do NOT modify test expectations to make tests pass
+   - Do NOT modify .aether/ system files
+   </constraints>
+
+   <output>
+   Provide JSON output matching this schema:
+   {
+     "ant_name": "your weaver name",
+     "caste": "weaver",
+     "status": "completed" | "failed" | "blocked",
+     "summary": "Brief summary of refactoring",
+     "files_refactored": [],
+     "complexity_before": 0,
+     "complexity_after": 0,
+     "duplication_eliminated": 0,
+     "methods_extracted": [],
+     "patterns_applied": [],
+     "tests_all_passing": true,
+     "next_recommendations": [],
+     "blockers": []
+   }
+   </output>
+   ```
+
+   f. **Parse Weaver JSON output and verify tests:**
+   Extract: `files_refactored`, `tests_all_passing`, `complexity_before`, `complexity_after`
+
+   Run using the Bash tool with description "Verifying tests after refactoring...":
+   ```bash
+   test_output_after=$(npm test 2>&1 || echo "TEST_FAILED")
+   tests_passing_after=$(echo "$test_output_after" | grep -oE '[0-9]+ passing' | grep -oE '[0-9]+' || echo "0")
+
+   if [[ "$tests_passing_after" -lt "$tests_passing_before" ]]; then
+     echo "REVERT_NEEDED: Tests failed after refactoring"
+     git checkout -- $files_needing_refactor
+     weaver_status="reverted"
+   else
+     echo "PASSING: Tests passing after refactoring ($tests_passing_after)"
+     weaver_status="completed"
+   fi
+   ```
+
+   g. **Log completion:**
+   Run using the Bash tool with description "Logging Weaver completion...": `bash .aether/aether-utils.sh spawn-complete "$weaver_name" "$weaver_status" "Refactoring $weaver_status"`
+
+
+   i. **Log to midden:**
+   Run using the Bash tool with description "Logging refactoring activity to midden...": `bash .aether/aether-utils.sh midden-write "refactoring" "Weaver refactored files, complexity before/after: ${complexity_before}/${complexity_after}" "weaver"`
+
+5. **Display completion:**
+   ```
+   🔄🐜 Weaver: Proactive refactoring {weaver_status}
+      Files refactored: {count} | Complexity: {before} → {after}
+   ```
+
+6. **NON-BLOCKING continuation:**
+   The Weaver step is NON-BLOCKING — continue to Step 1.8 regardless of refactoring results.
+
+Continue to Step 1.8.
+
+### Step 1.8: Gatekeeper Security Gate (Conditional)
+
+**Supply chain security audit — runs only when package.json exists.**
+
+First, check for package.json:
+Run using the Bash tool with description "Checking for package.json...": `test -f package.json && echo "exists" || echo "missing"`
+
+**If package.json is missing:**
+```
+📦🐜 Gatekeeper: No package.json found — skipping supply chain audit
+```
+Continue to Step 1.9.
+
+**If package.json exists:**
+
+1. Generate Gatekeeper name and log spawn:
+Run using the Bash tool with description "Generating Gatekeeper name...": `gatekeeper_name=$(bash .aether/aether-utils.sh generate-ant-name "gatekeeper" | jq -r '.result') && bash .aether/aether-utils.sh spawn-log "Queen" "gatekeeper" "$gatekeeper_name" "Supply chain security audit" && echo "{\"name\":\"$gatekeeper_name\"}"`
+
+2. Display: `📦🐜 Gatekeeper {name} spawning — Scanning dependencies for CVEs and license compliance...`
+
+4. Spawn Gatekeeper agent:
+
+Use the Task tool with subagent_type="aether-gatekeeper" (if available; otherwise use general-purpose and inject the Gatekeeper role from `.opencode/agents/aether-gatekeeper.md`):
+
+```xml
+<mission>
+Perform supply chain security audit on this codebase.
+</mission>
+
+<work>
+1. Inventory all dependencies from package.json
+2. Scan for known CVEs using npm audit or equivalent
+3. Check license compliance for all packages
+4. Assess dependency health (outdated, deprecated, maintenance status)
+5. Report findings with severity levels
+</work>
+
+<output>
+Provide JSON output matching this schema:
+{
+  "ant_name": "your gatekeeper name",
+  "caste": "gatekeeper",
+  "status": "completed" | "failed" | "blocked",
+  "summary": "Brief summary of findings",
+  "security": {
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0
+  },
+  "licenses": {},
+  "outdated_packages": [],
+  "recommendations": [],
+  "blockers": []
+}
+</output>
+```
+
+5. Parse Gatekeeper JSON output and log completion:
+Extract: `security.critical`, `security.high`, `status`
+
+Run using the Bash tool with description "Logging Gatekeeper completion...": `bash .aether/aether-utils.sh spawn-complete "$gatekeeper_name" "completed" "{\"security\":{\"critical\":$critical_count,\"high\":$high_count}}"`
+
+**Gate Decision Logic:**
+
+- **If `security.critical > 0`:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔📦🐜 G A T E K E E P E R   G A T E   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Critical security vulnerabilities detected: {critical_count}
+
+🚨 CRITICAL CVEs must be fixed before phase advancement.
+
+🔧 Required Actions:
+  1. Run `npm audit` to see full details
+  2. Fix or update vulnerable dependencies
+  3. Run /ant:continue again after resolving
+
+The phase will NOT advance with critical CVEs.
+```
+**CRITICAL:** Do NOT proceed to Step 1.9. Stop here.
+
+- **If `security.high > 0`:**
+```
+⚠️📦🐜 Gatekeeper: {high_count} high-severity issues found
+
+Security warnings logged to midden for later review.
+Proceeding with caution...
+```
+Run using the Bash tool with description "Logging high-severity warnings...": `bash .aether/aether-utils.sh midden-write "security" "High CVEs found: $high_count" "gatekeeper"`
+Continue to Step 1.9.
+
+- **If clean (no critical or high):**
+```
+✅📦🐜 Gatekeeper: No critical security issues found
+```
+Continue to Step 1.9.
+
+### Step 1.9: Auditor Quality Gate (MANDATORY)
+
+**Code quality audit — runs on every `/ant:continue` for consistent coverage.**
+
+1. Generate Auditor name and log spawn:
+Run using the Bash tool with description "Generating Auditor name...": `auditor_name=$(bash .aether/aether-utils.sh generate-ant-name "auditor" | jq -r '.result') && bash .aether/aether-utils.sh spawn-log "Queen" "auditor" "$auditor_name" "Code quality audit" && echo "{\"name\":\"$auditor_name\"}"`
+
+2. Display: `👥🐜 Auditor {name} spawning — Reviewing code with multi-lens analysis...`
+
+4. Get modified files for audit context:
+Run using the Bash tool with description "Getting modified files...": `modified_files=$(git diff --name-only HEAD~1 2>/dev/null || git diff --name-only) && echo "$modified_files"`
+
+5. Spawn Auditor agent:
+
+Use the Task tool with subagent_type="aether-auditor" (if available; otherwise use general-purpose and inject the Auditor role from `.opencode/agents/aether-auditor.md`):
+
+```xml
+<mission>
+Perform comprehensive code quality audit on this codebase.
+</mission>
+
+<work>
+1. Review all modified files from the recent commit(s)
+2. Apply all 4 audit lenses: security, performance, quality, maintainability
+3. Score each finding by severity (CRITICAL/HIGH/MEDIUM/LOW/INFO)
+4. Calculate overall quality score (0-100)
+5. Document specific issues with file:line references and fix suggestions
+</work>
+
+<context>
+Phase: {current_phase}
+Modified files: {modified_files}
+</context>
+
+<output>
+Provide JSON output matching this schema:
+{
+  "ant_name": "your auditor name",
+  "caste": "auditor",
+  "status": "completed" | "failed" | "blocked",
+  "summary": "Brief summary of findings",
+  "dimensions_audited": ["security", "performance", "quality", "maintainability"],
+  "findings": {
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0,
+    "info": 0
+  },
+  "issues": [
+    {"severity": "HIGH", "location": "file:line", "issue": "description", "fix": "suggestion"}
+  ],
+  "overall_score": 75,
+  "recommendation": "Top priority fix",
+  "blockers": []
+}
+</output>
+```
+
+6. Parse Auditor JSON output and log completion:
+Extract: `findings.critical`, `findings.high`, `findings.medium`, `findings.low`, `findings.info`, `overall_score`, `dimensions_audited`
+
+Run using the Bash tool with description "Logging Auditor completion...": `bash .aether/aether-utils.sh spawn-complete "$auditor_name" "completed" "{\"findings\":{\"critical\":$critical_count,\"high\":$high_count,\"medium\":$medium_count,\"low\":$low_count,\"info\":$info_count},\"score\":$overall_score}"`
+
+**Gate Decision Logic:**
+
+- **If `findings.critical > 0`:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔👥🐜 A U D I T O R   G A T E   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Critical code quality issues detected: {critical_count}
+
+🚨 CRITICAL findings must be fixed before phase advancement.
+
+🔧 Required Actions:
+  1. Review the critical issues listed below
+  2. Fix each critical finding
+  3. Run /ant:continue again after resolving
+
+Critical Findings:
+{list each critical finding with file:line and description}
+
+The phase will NOT advance with critical quality issues.
+```
+Run using the Bash tool with description "Logging critical quality block...": `bash .aether/aether-utils.sh error-flag-pattern "auditor-critical-findings" "$critical_count critical quality issues found" "critical"`
+**CRITICAL:** Do NOT proceed to Step 1.10. Stop here.
+
+- **Else if `overall_score < 60`:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔👥🐜 A U D I T O R   G A T E   F A I L E D
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Code quality score below threshold: {overall_score}/100 (threshold: 60)
+
+🚨 Quality score must reach 60+ before phase advancement.
+
+🔧 Required Actions:
+  1. Address the top issues preventing score improvement:
+{list top 3-5 issues with severity and location}
+  2. Focus on HIGH severity items first
+  3. Run /ant:continue again after improving quality
+
+The phase will NOT advance with quality score below 60.
+```
+Run using the Bash tool with description "Logging quality score block...": `bash .aether/aether-utils.sh error-flag-pattern "auditor-quality-score" "Score $overall_score below threshold 60" "critical"`
+**CRITICAL:** Do NOT proceed to Step 1.10. Stop here.
+
+- **Else if `findings.high > 0`:**
+```
+⚠️👥🐜 Auditor: Quality score {overall_score}/100 — PASSED with warnings
+
+{high_count} high-severity quality issues found:
+{list high findings}
+
+Quality warnings logged to midden for later review.
+Proceeding with caution...
+```
+Run using the Bash tool with description "Logging high-quality warnings...": `bash .aether/aether-utils.sh midden-write "quality" "High severity issues: $high_count (score: $overall_score)" "auditor"`
+Continue to Step 1.10.
+
+- **If clean (score >= 60, no critical):**
+```
+✅👥🐜 Auditor: Quality score {overall_score}/100 — PASSED
+```
+Continue to Step 1.10.
+
+### Step 1.10: 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:
+
+Run using the Bash tool with description "Locating test files...": `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.11.
+
+### Step 1.11: 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 1.12.
+
+**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.12.
+
+### Step 1.12: 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:
+Run using the Bash tool with description "Auto-resolving flags...": `bash .aether/aether-utils.sh flag-auto-resolve "build_pass"`
+
+Then check for remaining blocking flags:
+Run using the Bash tool with description "Checking for blockers...": `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.4 (commit suggestion), then Step 2.7 (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. **Capture learnings through memory pipeline:**
+
+   For each learning extracted, run the memory pipeline (observation + auto-pheromone + auto-promotion check).
+
+  Run using the Bash tool with description "Recording learning observations...":
+  ```bash
+  # 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
+        bash .aether/aether-utils.sh memory-capture "learning" "$claim" "pattern" "worker:continue"
+      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
+
+   **memory-capture behavior (per learning):**
+   - **Pheromone:** Emits ONE FEEDBACK pheromone per captured learning (emitted here, not again in Step 2.1a)
+   - **Auto-promotion:** Attempts promotion via `learning-promote-auto` using **higher thresholds** (philosophy: 3, pattern/stack/redirect/failure: 2, decree: 0) — only promotes if high-confidence recurrence detected
+   - **Does NOT perform final promotion** — high-threshold auto-promotion is opportunistic; final promotion happens in Step 2.1.5
+
+   **Step 2.1a vs this step:** Step 2.1a emits ONE summary FEEDBACK for the entire phase outcome (different purpose); this step emits per-learning FEEDBACK for each captured observation (captures the individual learning).
+
+   **Step 2.1.5 relationship:** Step 2.1.5 uses **lower thresholds** (all types: 1, decree: 0) to generate promotion proposals and presents them via tick-to-approve UX (`learning-check-promotion` + `learning-approve-proposals`). The higher thresholds here mean auto-promotion only fires for well-established patterns; most promotions go through Step 2.1.5's review flow.
+
+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.7 (base; calibrate with observation count)
+     - error_resolution: 0.8
+     - user_feedback: 0.9
+   - When a learning has observation_count data in learning-observations.json, use formula: min(0.7 + (count-1)*0.05, 0.9) to override the base value.
+
+   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.
+
+Validate the state file:
+Run using the Bash tool with description "Validating colony state...": `bash .aether/aether-utils.sh validate-state colony`
+
+### Step 2.1: Auto-Emit Phase Pheromones (SILENT)
+
+**This entire step produces NO user-visible output.** All pheromone operations run silently — learnings are deposited in the background. If any pheromone call fails, log the error and continue. Phase advancement must never fail due to pheromone errors.
+
+#### 2.1a: Auto-emit FEEDBACK pheromone for phase outcome
+
+After learning extraction completes in Step 2, auto-emit a FEEDBACK signal summarizing the phase:
+
+```bash
+# phase_id and phase_name come from Step 2 state update
+# Take the top 1-3 learnings by evidence strength from memory.phase_learnings
+# Compress into a single summary sentence
+
+# If learnings were extracted, build a brief summary from them (first 1-3 claims)
+# Otherwise use the minimal fallback
+phase_feedback="Phase $phase_id ($phase_name) completed. Key patterns: {brief summary of 1-3 learnings from Step 2}"
+# Fallback if no learnings: "Phase $phase_id ($phase_name) completed without notable patterns."
+
+bash .aether/aether-utils.sh pheromone-write FEEDBACK "$phase_feedback" \
+  --strength 0.6 \
+  --source "worker:continue" \
+  --reason "Auto-emitted on phase advance: captures what worked and what was learned" \
+  --ttl "30d" 2>/dev/null || true
+```
+
+The strength is 0.6 (auto-emitted = lower than user-emitted 0.7). Source is "worker:continue" to distinguish from user-emitted feedback. TTL is 30d so it survives phase transitions and can guide subsequent work.
+
+#### 2.1b: Auto-emit FEEDBACK for phase decisions (PHER-01)
+
+Extract recent decisions from CONTEXT.md "Recent Decisions" table and emit FEEDBACK pheromones for each. This ensures key decisions propagate as signals to guide future phases.
+
+```bash
+decisions=$(awk '
+  /^## .*Recent Decisions/ { in_section=1; next }
+  in_section && /^\| Date / { next }
+  in_section && /^\|[-]+/ { next }
+  in_section && /^---/ { exit }
+  in_section && /^\| [0-9]{4}-[0-9]{2}/ {
+    split($0, fields, "|")
+    decision = fields[3]
+    gsub(/^[[:space:]]+|[[:space:]]+$/, "", decision)
+    if (decision != "") print decision
+  }
+' .aether/CONTEXT.md 2>/dev/null || echo "")
+
+if [[ -n "$decisions" ]]; then
+  emit_count=0
+  while IFS= read -r dec && [[ $emit_count -lt 3 ]]; do
+    [[ -z "$dec" ]] && continue
+    # Deduplication: check if auto:decision or system:decision pheromone with this text already exists
+    existing=$(jq -r --arg text "$dec" '
+      [.signals[] | select(.active == true and (.source == "auto:decision" or .source == "system:decision") and (.content.text | contains($text)))] | length
+    ' .aether/data/pheromones.json 2>/dev/null || echo "0")
+    if [[ "$existing" == "0" ]]; then
+      bash .aether/aether-utils.sh pheromone-write FEEDBACK \
+        "[decision] $dec" \
+        --strength 0.6 \
+        --source "auto:decision" \
+        --reason "Auto-emitted from phase decision during continue" \
+        --ttl "30d" 2>/dev/null || true
+      emit_count=$((emit_count + 1))
+    fi
+  done <<< "$decisions"
+fi
+```
+
+Strength is 0.6 (auto-emitted = lower than user-emitted). Source is `"auto:decision"` to distinguish from manual pheromones. Cap: max 3 decision pheromones per continue run. Both `context-update decision` and Step 2.1b now use the same format (`[decision] ...`, source `auto:decision`, strength 0.6), so the dedup `contains()` check reliably catches signals emitted by either path. The dedup query also checks `system:decision` for backward compatibility with any pre-existing signals from before the format alignment.
+
+#### 2.1c: Auto-emit REDIRECT for midden error patterns (PHER-02)
+
+Query the actual failure store (`midden.json`) for recurring error categories. Categories with 3+ occurrences indicate persistent issues that should steer workers away from known failure modes.
+
+```bash
+midden_result=$(bash .aether/aether-utils.sh midden-recent-failures 50 2>/dev/null || echo '{"count":0,"failures":[]}')
+midden_count=$(echo "$midden_result" | jq '.count // 0')
+
+if [[ "$midden_count" -gt 0 ]]; then
+  # Group by category, find categories with 3+ occurrences
+  recurring_categories=$(echo "$midden_result" | jq -r '
+    [.failures[] | .category]
+    | group_by(.)
+    | map(select(length >= 3))
+    | map({category: .[0], count: length})
+    | .[]
+    | @base64
+  ' 2>/dev/null || echo "")
+
+  emit_count=0
+  for encoded in $recurring_categories; do
+    [[ $emit_count -ge 3 ]] && break
+    [[ -z "$encoded" ]] && continue
+    category=$(echo "$encoded" | base64 -d | jq -r '.category')
+    count=$(echo "$encoded" | base64 -d | jq -r '.count')
+
+    # Deduplication check
+    existing=$(jq -r --arg cat "$category" '
+      [.signals[] | select(.active == true and .source == "auto:error" and (.content.text | contains($cat)))] | length
+    ' .aether/data/pheromones.json 2>/dev/null || echo "0")
+
+    if [[ "$existing" == "0" ]]; then
+      bash .aether/aether-utils.sh pheromone-write REDIRECT \
+        "[error-pattern] Category \"$category\" recurring ($count occurrences)" \
+        --strength 0.7 \
+        --source "auto:error" \
+        --reason "Auto-emitted: midden error pattern recurred 3+ times" \
+        --ttl "30d" 2>/dev/null || true
+      emit_count=$((emit_count + 1))
+
+      # Capture as resolution candidate for promotion tracking
+      bash .aether/aether-utils.sh memory-capture \
+        "resolution" \
+        "Recurring error pattern: $category ($count occurrences)" \
+        "pattern" \
+        "worker:continue" 2>/dev/null || true
+    fi
+  done
+fi
+```
+
+REDIRECT strength is 0.7 (higher than auto FEEDBACK 0.6 — anti-patterns produce stronger signals). Source is `"auto:error"`. Cap: max 3 error pattern pheromones per continue run. Uses `midden-recent-failures` subcommand (actual failure store) instead of `errors.flagged_patterns` (which may be empty). Threshold is 3+ occurrences for high confidence in recurrence.
+
+#### 2.1d: Auto-emit FEEDBACK for recurring success criteria (PHER-03)
+
+Compare success criteria text across all completed phases. Criteria appearing in 2+ completed phases indicate recurring quality patterns worth reinforcing as signals.
+
+```bash
+recurring_criteria=$(jq -r '
+  [.plan.phases[]
+   | select(.status == "completed")
+   | .id as $phase_id
+   | (
+       (.success_criteria // [])[] ,
+       (.tasks // [] | .[].success_criteria // [])[]
+     )
+   | {phase: $phase_id, text: (. | ascii_downcase | gsub("^\\s+|\\s+$"; ""))}
+  ]
+  | group_by(.text)
+  | map(select(length >= 2))
+  | map({text: .[0].text, phases: [.[].phase] | unique, count: length})
+  | .[:2]
+  | .[]
+  | @base64
+' .aether/data/COLONY_STATE.json 2>/dev/null || echo "")
+
+for encoded in $recurring_criteria; do
+  [[ -z "$encoded" ]] && continue
+  text=$(echo "$encoded" | base64 -d | jq -r '.text')
+  count=$(echo "$encoded" | base64 -d | jq -r '.count')
+  phases=$(echo "$encoded" | base64 -d | jq -r '.phases | join(", ")')
+
+  # Deduplication check
+  existing=$(jq -r --arg text "$text" '
+    [.signals[] | select(.active == true and .source == "auto:success" and (.content.text | ascii_downcase | contains($text)))] | length
+  ' .aether/data/pheromones.json 2>/dev/null || echo "0")
+
+  if [[ "$existing" == "0" ]]; then
+    bash .aether/aether-utils.sh pheromone-write FEEDBACK \
+      "[success-pattern] \"$text\" recurs across phases $phases" \
+      --strength 0.6 \
+      --source "auto:success" \
+      --reason "Auto-emitted: success criteria pattern recurred across $count phases" \
+      --ttl "30d" 2>/dev/null || true
+  fi
+done
+```
+
+Strength is 0.6 (auto-emitted). Source is `"auto:success"`. Cap: max 2 success criteria pheromones per continue run (enforced by `.[:2]` in the jq query). Extracts from both phase-level `.success_criteria` and task-level `.tasks[].success_criteria` across all completed phases. Normalizes text with `ascii_downcase` and whitespace trimming for reliable matching.
+
+#### 2.1e: Expire phase_end signals and archive to midden
+
+After auto-emission, expire all signals with `expires_at == "phase_end"`. The FEEDBACK from 2.1a uses a 30d TTL and is not affected by this step.
+
+Run using the Bash tool with description "Maintaining pheromone memory...": `bash .aether/aether-utils.sh pheromone-expire --phase-end-only 2>/dev/null && bash .aether/aether-utils.sh eternal-init 2>/dev/null`
+
+This is idempotent — runs every time continue fires but only creates the directory/file once.
+
+### Step 2.1.5: Check for Promotion Proposals (PHER-EVOL-02)
+
+After extracting learnings, check for observations that have met promotion thresholds and present the tick-to-approve UX.
+
+**Check for --deferred flag:**
+
+If `$ARGUMENTS` contains `--deferred`:
+```bash
+if [[ "$ARGUMENTS" == *"--deferred"* ]] && [[ -f .aether/data/learning-deferred.json ]]; then
+  echo "📦 Reviewing deferred proposals..."
+  bash .aether/aether-utils.sh learning-approve-proposals --deferred ${verbose:+--verbose}
+fi
+```
+
+**Normal proposal flow (MEM-01: Silent skip if empty):**
+
+1. **Check for proposals:**
+   ```bash
+   proposals=$(bash .aether/aether-utils.sh learning-check-promotion 2>/dev/null || echo '{"proposals":[]}')
+   proposal_count=$(echo "$proposals" | jq '.proposals | length')
+   ```
+
+2. **If proposals exist, invoke the approval workflow:**
+
+   Only show the approval UI when there are actual proposals to review:
+
+   ```bash
+   if [[ "$proposal_count" -gt 0 ]]; then
+     verbose_flag=""
+     [[ "$ARGUMENTS" == *"--verbose"* ]] && verbose_flag="--verbose"
+     bash .aether/aether-utils.sh learning-approve-proposals $verbose_flag
+   fi
+   # If no proposals, silently skip without notice (per user decision)
+   ```
+
+   The learning-approve-proposals function handles:
+   - Displaying proposals with checkbox UI
+   - Capturing user selection
+   - Executing batch promotions via queen-promote
+   - Deferring unselected proposals
+   - Offering undo after successful promotions
+   - Logging PROMOTED activity
+
+**Skip conditions:**
+- learning-check-promotion returns empty or fails
+- No proposals to review (silent skip - no output)
+- QUEEN.md does not exist
+
+### Step 2.1.6: Batch Wisdom Auto-Promotion (QUEEN-01)
+
+After learnings extraction and auto-emission, sweep all recorded observations and auto-promote any that meet the higher recurrence thresholds (pattern=2, philosophy=3, etc.) to QUEEN.md. The learning-promote-auto subcommand has an internal grep guard that skips content already in QUEEN.md, so this is safe to run even after memory-capture in Step 2.5 already attempted promotion.
+
+```bash
+# === Batch Wisdom Auto-Promotion (QUEEN-01) ===
+# Sweep all observations and auto-promote any that crossed auto thresholds.
+# The grep guard inside learning-promote-auto prevents double-promotion
+# for observations already promoted by memory-capture in Step 2.5.
+
+obs_file=".aether/data/learning-observations.json"
+if [[ -f "$obs_file" ]]; then
+  obs_count=$(jq '.observations | length' "$obs_file" 2>/dev/null || echo "0")
+  promoted_count=0
+
+  if [[ "$obs_count" -gt 0 ]]; then
+    for encoded in $(jq -r '.observations[] | @base64' "$obs_file" 2>/dev/null); do
+      content=$(echo "$encoded" | base64 -d | jq -r '.content // empty')
+      wisdom_type=$(echo "$encoded" | base64 -d | jq -r '.wisdom_type // "pattern"')
+      colony=$(echo "$encoded" | base64 -d | jq -r '.colonies[0] // "unknown"')
+      [[ -z "$content" ]] && continue
+
+      result=$(bash .aether/aether-utils.sh learning-promote-auto "$wisdom_type" "$content" "$colony" "learning" 2>/dev/null || echo '{}')
+      was_promoted=$(echo "$result" | jq -r '.result.promoted // false' 2>/dev/null || echo "false")
+      if [[ "$was_promoted" == "true" ]]; then
+        promoted_count=$((promoted_count + 1))
+      fi
+    done
+  fi
+fi
+# === END Batch Wisdom Auto-Promotion ===
+```
+
+### Step 2.2: 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}
+- Wisdom promoted to QUEEN.md: {promoted_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.3: Update Changelog
+
+**MANDATORY: Append a changelog entry for the completed phase. This step is never skipped.**
+
+If no `CHANGELOG.md` exists, `changelog-append` creates one automatically.
+
+**Step 2.3.1: Collect plan data**
+
+```bash
+bash .aether/aether-utils.sh changelog-collect-plan-data "{phase_identifier}" "{plan_number}"
+```
+
+Parse the returned JSON to extract `files`, `decisions`, `worked`, and `requirements` arrays.
+
+- `{phase_identifier}` is the full phase name (e.g., `36-memory-capture`)
+- `{plan_number}` is the plan number (e.g., `01`)
+
+If the command fails (e.g., no plan file found), fall back to collecting data manually:
+- Files: from `git diff --stat` of the completed phase
+- Decisions: from COLONY_STATE.json `memory.decisions` (last 5)
+- Worked/requirements: leave empty
+
+**Step 2.3.2: Append changelog entry**
+
+```bash
+bash .aether/aether-utils.sh changelog-append \
+  "$(date +%Y-%m-%d)" \
+  "{phase_identifier}" \
+  "{plan_number}" \
+  "{files_csv}" \
+  "{decisions_semicolon_separated}" \
+  "{worked_semicolon_separated}" \
+  "{requirements_csv}"
+```
+
+This atomically writes the entry. If the project already has a Keep a Changelog format, it adds a "Colony Work Log" separator section to keep both formats clean.
+
+**Error handling:** If `changelog-append` fails, log to midden and continue — changelog failure never blocks phase advancement.
+
+### Step 2.4: 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.
+
+#### Step 2.4.1: Capture AI Description
+
+**As the AI, briefly describe what was accomplished in this phase.**
+
+Look at:
+1. The phase PLAN.md `<objective>` section (what we set out to do)
+2. Tasks that were marked complete
+3. Files that were modified (from git diff --stat)
+4. Any patterns or decisions recorded
+
+**Provide a brief, memorable description** (10-15 words, imperative mood):
+- Good: "Implement task-based model routing with keyword detection and precedence chain"
+- Good: "Fix build timing by removing background execution from worker spawns"
+- Bad: "Phase complete" (too vague)
+- Bad: "Modified files in bin/lib" (too mechanical)
+
+Store this as `ai_description` for the commit message.
+
+#### Step 2.4.2: Generate Enhanced Commit Message
+
+```bash
+bash .aether/aether-utils.sh generate-commit-message "contextual" {phase_id} "{phase_name}" "{ai_description}" {plan_number}
+```
+
+Parse the returned JSON to extract:
+- `message` - the commit subject line
+- `body` - structured metadata (Scope, Files)
+- `files_changed` - file count
+- `subsystem` - derived subsystem name
+- `scope` - phase.plan format
+
+**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.
+
+**Display the enhanced suggestion:**
+```
+──────────────────────────────────────────────────
+Commit Suggestion
+──────────────────────────────────────────────────
+
+  AI Description: {ai_description}
+
+  Formatted Message:
+  {message}
+
+  Metadata:
+  Scope: {scope}
+  Files: {files_changed} files changed
+  Preview: {first 5 lines of git diff --stat}
+
+──────────────────────────────────────────────────
+```
+
+**Use AskUserQuestion:**
+```
+Commit this milestone?
+
+1. Yes, commit with this message
+2. Yes, but let me edit the description
+3. No, I'll commit later
+```
+
+**If option 1 ("Yes, commit with this message"):**
+```bash
+git add -A && git commit -m "{message}" -m "{body}"
+```
+Display: `Committed: {message} ({files_changed} files)`
+
+**If option 2 ("Yes, but let me edit"):**
+Use AskUserQuestion to get the user's custom description:
+```
+Enter your description (or press Enter to keep: '{ai_description}'):
+```
+Then regenerate the commit message with the new description and commit.
+
+**If option 3 ("No, I'll commit later"):**
+Display: `Skipped. Your changes are saved on disk but not committed.`
+
+**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.5 (Context Clear Suggestion), then to Step 2.7 (Project Completion) or Step 3 (Display Result).
+
+### Step 2.5: 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.7 (Project Completion) or Step 3 (Display Result).
+
+### Step 2.6: Update Context Document
+
+After phase advancement is complete, update `.aether/CONTEXT.md`:
+
+**Log the activity:**
+```bash
+bash .aether/aether-utils.sh context-update activity "continue" "Phase {prev_id} completed, advanced to {next_id}" "—"
+```
+
+**Update the phase:**
+```bash
+bash .aether/aether-utils.sh context-update update-phase {next_id} "{next_phase_name}" "YES" "Phase advanced, ready to build"
+```
+
+**Log any decisions from this session:**
+If any architectural decisions were made during verification, also run:
+```bash
+bash .aether/aether-utils.sh context-update decision "{decision_description}" "{rationale}" "Queen"
+```
+
+### Step 2.7: 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}
+
+👑 Wisdom Added to QUEEN.md:
+{count} patterns/redirects/philosophies promoted across all phases
+
+🐜 The colony rests. Well done!
+```
+
+3. Write summary to `.aether/data/completion-report.md`
+4. Display next commands and stop.
+
+### Step 3: Display Result
+
+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}
+
+👑 Wisdom Promoted to QUEEN.md:
+{for each promoted learning:}
+   [{type}] {brief claim}
+{end for}
+
+🐜 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 Up
+──────────────────────────────────────────────────
+   /ant:build {next_id}     🔨 Build next phase
+   /ant:status              📊 Check progress
+
+💾 State persisted — context clear suggested above
+
+📋 Context document updated at `.aether/CONTEXT.md`
+```
+
+**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}`.
+
+### Step 4: Update Session
+
+Update the session tracking file to enable `/ant:resume` after context clear:
+
+```bash
+bash .aether/aether-utils.sh session-update "/ant:continue" "/ant:build {next_id}" "Phase {prev_id} completed, advanced to Phase {next_id}"
+```
+
+Run using the Bash tool with description "Saving session state...": `bash .aether/aether-utils.sh session-update "/ant:continue" "/ant:build {next_id}" "Phase {prev_id} completed, advanced to Phase {next_id}"`