aether-colony 5.0.0 → 5.1.0

package/.aether/docs/command-playbooks/build-complete.md

@@ -0,0 +1,349 @@
+### Step 5.9: Synthesize Results
+
+**This step runs after all worker tasks have completed (Builders, Watcher, Chaos).**
+
+Collect all worker outputs and create phase summary:
+
+```json
+{
+  "status": "completed" | "failed" | "blocked",
+  "summary": "...",
+  "tasks_completed": [...],
+  "tasks_failed": [...],
+  "files_created": [...],
+  "files_modified": [...],
+  "spawn_metrics": {
+    "spawn_count": {total workers spawned, including archaeologist if Step 4.5 fired, measurer if Step 5.5.1 fired, ambassador if Step 5.1.1 fired},
+    "builder_count": {N},
+    "watcher_count": 1,
+    "chaos_count": 1,
+    "archaeologist_count": {0 or 1, conditional on Step 4.5},
+    "measurer_count": {0 or 1, conditional on Step 5.5.1},
+    "ambassador_count": {0 or 1, conditional on Step 5.1.1},
+    "parallel_batches": {number of waves}
+  },
+  "spawn_tree": {
+    "{Archaeologist-Name}": {"caste": "archaeologist", "task": "pre-build history scan", "status": "completed"},
+    "{Ambassador-Name}": {"caste": "ambassador", "task": "external integration design", "status": "completed"},
+    "{Builder-Name}": {"caste": "builder", "task": "...", "status": "completed"},
+    "{Watcher-Name}": {"caste": "watcher", "task": "verify", "status": "completed"},
+    "{Measurer-Name}": {"caste": "measurer", "task": "performance baseline", "status": "completed"},
+    "{Chaos-Name}": {"caste": "chaos", "task": "resilience testing", "status": "completed"}
+  },
+  "verification": {from Watcher output},
+  "performance": {from Measurer output, or null if Step 5.5.1 was skipped},
+  "resilience": {from Chaos Ant output},
+  "archaeology": {from Archaeologist output, or null if Step 4.5 was skipped},
+  "quality_notes": "..."
+}
+```
+
+**Graveyard Recording:**
+For each worker that returned `status: "failed"`:
+  For each file in that worker's `files_modified` or `files_created`:
+Run using the Bash tool with description "Recording failure grave...": `bash .aether/aether-utils.sh grave-add "{file}" "{ant_name}" "{task_id}" {phase} "{first blocker or summary}" && bash .aether/aether-utils.sh activity-log "GRAVE" "Queen" "Grave marker placed at {file} — {ant_name} failed: {summary}"`
+  Then display a user-visible confirmation line:
+  `⚰️ Grave recorded: {file} — {ant_name} failed ({summary})`
+
+**Success capture: pattern synthesis (MEM-01):**
+
+If `learning.patterns_observed` array in the synthesis JSON is non-empty, capture up to 2 patterns as success events:
+
+Initialize a counter: `success_capture_count=0`
+
+For each pattern in `learning.patterns_observed`:
+- If `success_capture_count >= 2`, stop (cap reached)
+- Run using the Bash tool with description "Capturing synthesis pattern success...":
+```bash
+bash .aether/aether-utils.sh memory-capture \
+  "success" \
+  "${pattern.trigger}: ${pattern.action} (evidence: ${pattern.evidence})" \
+  "pattern" \
+  "worker:builder" 2>/dev/null || true
+```
+- Increment `success_capture_count`
+
+The cap of 2 prevents observation count inflation when builds produce many patterns. Each captured pattern enters learning-observations.json with a content hash for deduplication across builds.
+
+### Step 5.9.1: Persist Builder Claims (MANDATORY)
+
+Write builder file claims to `.aether/data/last-build-claims.json` for verification during /ant:continue.
+
+Collect from each builder worker's output:
+- files_created: [...all files_created from all builders...]
+- files_modified: [...all files_modified from all builders...]
+
+Run using the Bash tool with description "Persisting builder claims...":
+```bash
+echo '{"files_created":[...], "files_modified":[...], "build_phase": N, "timestamp": "ISO8601"}' > .aether/data/last-build-claims.json
+```
+
+Replace the `[...]` placeholders with the actual arrays collected from builder outputs, `N` with the current phase number, and `ISO8601` with the current timestamp.
+
+This file is consumed by verify-claims during /ant:continue.
+
+**Error Handoff Update:**
+If workers failed, update handoff with error context for recovery:
+
+Resolve the build error handoff template path:
+  Check ~/.aether/system/templates/handoff-build-error.template.md first,
+  then .aether/templates/handoff-build-error.template.md.
+
+If no template found: output "Template missing: handoff-build-error.template.md. Run aether update to fix." and stop.
+
+Read the template file. Fill all {{PLACEHOLDER}} values:
+  - {{PHASE_NUMBER}} → current phase number
+  - {{PHASE_NAME}} → current phase name
+  - {{BUILD_TIMESTAMP}} → current ISO-8601 UTC timestamp
+  - {{FAILED_WORKERS}} → formatted list of failed workers (one "- {ant_name}: {failure_summary}" per line)
+  - {{GRAVE_MARKERS}} → formatted list of grave markers (one "- {file}: {caution_level} caution" per line)
+
+Remove the HTML comment lines at the top of the template.
+Write the result to .aether/HANDOFF.md using the Write tool.
+
+Only fires when workers fail. Zero impact on successful builds.
+
+--- SPAWN TRACKING ---
+
+The spawn tree will be visible in `/ant:watch` because each spawn is logged.
+
+--- OUTPUT FORMAT ---
+
+Return JSON:
+{
+  "status": "completed" | "failed" | "blocked",
+  "summary": "What the phase accomplished",
+  "tasks_completed": ["1.1", "1.2"],
+  "tasks_failed": [],
+  "files_created": ["path1", "path2"],
+  "files_modified": ["path3"],
+  "spawn_metrics": {
+    "spawn_count": 7,
+    "watcher_count": 1,
+    "chaos_count": 1,
+    "archaeologist_count": 1,
+    "measurer_count": 1,
+    "ambassador_count": 1,
+    "builder_count": 3,
+    "parallel_batches": 2,
+    "sequential_tasks": 1
+  },
+  "spawn_tree": {
+    "Relic-8": {"caste": "archaeologist", "task": "pre-build history scan", "status": "completed", "children": {}},
+    "Diplomat-7": {"caste": "ambassador", "task": "external integration design", "status": "completed", "children": {}},
+    "Hammer-42": {"caste": "builder", "task": "...", "status": "completed", "children": {}},
+    "Vigil-17": {"caste": "watcher", "task": "...", "status": "completed", "children": {}},
+    "Benchmark-3": {"caste": "measurer", "task": "performance baseline", "status": "completed", "children": {}},
+    "Entropy-9": {"caste": "chaos", "task": "resilience testing", "status": "completed", "children": {}}
+  },
+  "verification": {
+    "build": {"command": "npm run build", "exit_code": 0, "passed": true},
+    "tests": {"command": "npm test", "passed": 24, "failed": 0, "total": 24},
+    "success_criteria": [
+      {"criterion": "API endpoint exists", "evidence": "GET /api/users returns 200", "passed": true},
+      {"criterion": "Tests cover happy path", "evidence": "3 tests in users.test.ts", "passed": true}
+    ]
+  },
+  "debugging": {
+    "issues_encountered": 0,
+    "issues_resolved": 0,
+    "fix_attempts": 0,
+    "architectural_concerns": []
+  },
+  "tdd": {
+    "cycles_completed": 5,
+    "tests_added": 5,
+    "tests_total": 47,
+    "coverage_percent": 85,
+    "all_passing": true
+  },
+  "learning": {
+    "patterns_observed": [
+      {
+        "type": "success",
+        "trigger": "when implementing API endpoints",
+        "action": "use repository pattern with DI",
+        "evidence": "All tests passed first try"
+      }
+    ],
+    "instincts_applied": ["instinct_123"],
+    "instinct_outcomes": [
+      {"id": "instinct_123", "success": true}
+    ]
+  },
+  "quality_notes": "Any concerns or recommendations",
+  "ui_touched": true | false
+}
+```
+
+### Step 6: Visual Checkpoint (if UI touched)
+
+Parse synthesis result. If `ui_touched` is true:
+
+```
+━━━ 🖼️🐜 V I S U A L   C H E C K P O I N T ━━━
+
+UI changes detected. Verify appearance before continuing.
+
+Files touched:
+{list files from files_created + files_modified that match UI patterns}
+
+Options:
+  1. Approve - UI looks correct
+  2. Reject - needs changes (describe issues)
+  3. Skip - defer visual review
+```
+
+Use AskUserQuestion to get approval. Record in events:
+- If approved: `"<timestamp>|visual_approved|build|Phase {id} UI approved"`
+- If rejected: `"<timestamp>|visual_rejected|build|Phase {id} UI rejected: {reason}"`
+
+### Step 6.5: Update Handoff Document
+
+After synthesis is complete, update the handoff document with current state for session recovery:
+
+```bash
+# Update handoff with build results
+jq -n \
+  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --arg goal "$(jq -r '.goal' .aether/data/COLONY_STATE.json)" \
+  --arg phase "$(jq -r '.current_phase' .aether/data/COLONY_STATE.json)" \
+  --arg phase_name "{phase_name}" \
+  --arg status "{synthesis.status}" \
+  --arg summary "{synthesis.summary}" \
+  --argjson tasks_completed '{synthesis.tasks_completed | length}' \
+  --argjson tasks_failed '{synthesis.tasks_failed | length}' \
+  --arg next_action "{if synthesis.status == "completed" then "/ant:continue" else "/ant:flags" end}" \
+  '{
+    "last_updated": $timestamp,
+    "goal": $goal,
+    "current_phase": $phase,
+    "phase_name": $phase_name,
+    "build_status": $status,
+    "summary": $summary,
+    "tasks_completed": $tasks_completed,
+    "tasks_failed": $tasks_failed,
+    "next_recommended_action": $next_action,
+    "can_resume": true,
+    "note": "Phase build completed. Run /ant:continue to advance if verification passed."
+  }' > .aether/data/last-build-result.json
+```
+
+Resolve the build success handoff template path:
+  Check ~/.aether/system/templates/handoff-build-success.template.md first,
+  then .aether/templates/handoff-build-success.template.md.
+
+If no template found: output "Template missing: handoff-build-success.template.md. Run aether update to fix." and stop.
+
+Read the template file. Fill all {{PLACEHOLDER}} values:
+  - {{GOAL}} → colony goal (from COLONY_STATE.json)
+  - {{PHASE_NUMBER}} → current phase number
+  - {{PHASE_NAME}} → current phase name
+  - {{BUILD_STATUS}} → synthesis.status
+  - {{BUILD_TIMESTAMP}} → current ISO-8601 UTC timestamp
+  - {{BUILD_SUMMARY}} → synthesis summary
+  - {{TASKS_COMPLETED}} → count of completed tasks
+  - {{TASKS_FAILED}} → count of failed tasks
+  - {{FILES_CREATED}} → count of created files
+  - {{FILES_MODIFIED}} → count of modified files
+  - {{SESSION_NOTE}} → "Build succeeded — ready to advance." if status is completed, else "Build completed with issues — review before continuing."
+
+Remove the HTML comment lines at the top of the template.
+Write the result to .aether/HANDOFF.md using the Write tool.
+
+This ensures the handoff always reflects the latest build state, even if the session crashes before explicit pause.
+
+### Step 6.5: Update Context Document
+
+Log this build activity to `.aether/CONTEXT.md`:
+
+Run using the Bash tool with description "Updating build context...": `bash .aether/aether-utils.sh context-update activity "build {phase_id}" "{synthesis.status}" "{files_created_count + files_modified_count}" && bash .aether/aether-utils.sh context-update build-complete "{synthesis.status}" "{synthesis.status == 'completed' ? 'success' : 'failed'}"`
+
+Also update safe-to-clear status:
+- If build completed successfully: `context-update safe-to-clear "YES" "Build complete, ready to continue"`
+- If build failed: `context-update safe-to-clear "NO" "Build failed — run /ant:swarm or /ant:flags"`
+
+### Step 5.10: Check for Promotion Proposals
+
+After build completion (success or failure), check if any observations have met promotion thresholds.
+
+Run using the Bash tool with description "Checking for wisdom promotions...":
+```bash
+proposals=$(bash .aether/aether-utils.sh learning-check-promotion 2>/dev/null || echo '{"proposals":[]}')
+proposal_count=$(echo "$proposals" | jq '.proposals | length')
+echo "{\"proposal_count\": $proposal_count}"
+```
+
+Parse the result. If proposal_count > 0:
+- Display: "📚 $proposal_count wisdom proposal(s) ready for review"
+- Run: `bash .aether/aether-utils.sh learning-approve-proposals`
+- This presents the one-at-a-time UI for user review
+
+If proposal_count == 0:
+- Silently continue (no output needed per user decision)
+
+Note: This runs regardless of build success/failure. Failed builds may have recorded failure observations that are ready for promotion.
+
+### Step 7: Display Results
+
+**This step runs ONLY after synthesis is complete. All values come from actual worker results.**
+
+**Display BUILD SUMMARY (always shown, replaces compact/verbose split):**
+
+Calculate `total_tools` by summing `tool_count` from all worker return JSONs (builders + watcher + chaos).
+Calculate `elapsed` using `build_started_at_epoch` (epoch integer captured at Step 5 start by Plan 01): `$(( $(date +%s) - build_started_at_epoch ))` formatted as Xm Ys.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   B U I L D   S U M M A R Y
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase {id}: {name}
+Pattern:  {selected_pattern}
+
+Workers:  {pass_count} passed  {fail_count} failed  ({total} total)
+Tools:    {total_tools} calls across all workers
+Duration: {elapsed}
+
+{if measurer_ran:}
+📊 Measurer: {baseline_count} baselines established, {bottleneck_count} bottlenecks identified
+{end if}
+
+{if ambassador_ran:}
+🔌 Ambassador: Integration plan for {integration_plan.service_name} ready
+{end if}
+
+{if fail_count > 0:}
+Failed:
+  {for each failed worker:}
+  {caste_emoji} {Ant-Name}: {task_description} ✗ ({failure_reason} after {tool_count} tools)
+  {end for}
+
+Retry: /ant:swarm to auto-repair failed tasks, or /ant:flags to review blockers
+{end if}
+```
+
+**If verbose_mode is true**, additionally show the spawn tree and TDD details after the BUILD SUMMARY block (keep the existing verbose-only sections: Colony Work Tree, Tasks Completed, TDD, Patterns Learned, Debugging, Model Routing). Prepend with:
+```
+━━ Details (--verbose) ━━
+```
+
+After displaying the BUILD SUMMARY (and optional verbose details), call the Next Up helper by running using the Bash tool with description "Displaying next steps...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json 2>/dev/null || echo "IDLE")
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json 2>/dev/null || echo "0")
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
+
+**Routing Note:** The state-based Next Up block above routes based on colony state. If verification failed or blockers exist, review `/ant:flags` before continuing.
+
+**IMPORTANT:** Build does NOT update task statuses or advance state. Run `/ant:continue` to:
+- Mark tasks as completed
+- Extract learnings
+- Advance to next phase
+
+### Step 8: Update Session
+
+Update the session tracking file to enable `/ant:resume` after context clear:
+
+Run using the Bash tool with description "Saving build session...": `bash .aether/aether-utils.sh session-update "/ant:build {phase_id}" "/ant:continue" "Phase {phase_id} build completed: {synthesis.status}"`

package/.aether/docs/command-playbooks/build-context.md

@@ -0,0 +1,282 @@
+### Step 4: Load Colony Context (colony-prime)
+
+Call `colony-prime --compact` to get unified worker context (wisdom + context capsule + signals + instincts):
+
+Run using the Bash tool with description "Loading colony context...":
+```bash
+prime_result=$(bash .aether/aether-utils.sh colony-prime --compact 2>/dev/null)
+```
+
+**Parse the JSON response:**
+- If `.ok` is false: This is a FAIL HARD error - display the error message and stop the build
+- If successful: Extract from `.result`:
+  - `signal_count` - number of active pheromone signals
+  - `instinct_count` - number of filtered instincts
+  - `prompt_section` - the formatted markdown to inject into worker prompts
+  - `log_line` - status message for display
+
+Display after constraints:
+```
+{log_line from colony-prime}
+```
+
+Then display the active pheromones table by running:
+```bash
+bash .aether/aether-utils.sh pheromone-display
+```
+
+This shows the user exactly what signals are guiding the colony:
+- 🎯 FOCUS signals (what to pay attention to)
+- 🚫 REDIRECT signals (what to avoid - hard constraints)
+- 💬 FEEDBACK signals (guidance to consider)
+
+**Store for worker injection:** The `prompt_section` variable contains compact formatted context (QUEEN wisdom + context capsule + pheromone signals) ready for injection.
+
+### Step 4.0: Load Territory Survey
+
+Check if territory survey exists and load relevant documents:
+
+Run using the Bash tool with description "Loading territory survey...":
+```bash
+bash .aether/aether-utils.sh survey-load "{phase_name}" 2>/dev/null
+```
+
+**Parse the JSON response:**
+- If `.ok` is false: Set `survey_docs = null` and skip survey loading
+- If successful: Extract `.docs` (comma-separated list) and `.dir`
+
+**Determine phase type from phase name:**
+| Phase Contains | Documents to Load |
+|----------------|-------------------|
+| UI, frontend, component, button, page | DISCIPLINES.md, CHAMBERS.md |
+| API, endpoint, backend, route | BLUEPRINT.md, DISCIPLINES.md |
+| database, schema, model, migration | BLUEPRINT.md, PROVISIONS.md |
+| test, spec, coverage | SENTINEL-PROTOCOLS.md, DISCIPLINES.md |
+| integration, external, client | TRAILS.md, PROVISIONS.md |
+| refactor, cleanup, debt | PATHOGENS.md, BLUEPRINT.md |
+| setup, config, initialize | PROVISIONS.md, CHAMBERS.md |
+| *default* | PROVISIONS.md, BLUEPRINT.md |
+
+**Read the relevant survey documents** from `.aether/data/survey/`:
+- Extract key patterns to follow
+- Note file locations for new code
+- Identify known concerns to avoid
+
+**Display summary:**
+```
+━━━ 🗺️🐜 S U R V E Y   L O A D E D ━━━
+{for each doc loaded}
+  {emoji} {filename} — {brief description}
+{/for}
+
+{if no survey}
+  (No territory survey — run /ant:colonize for deeper context)
+{/if}
+```
+
+**Store for builder injection:**
+- `survey_patterns` — patterns to follow
+- `survey_locations` — where to place files
+- `survey_concerns` — concerns to avoid
+
+### Step 4.0.5: Load Phase Research
+
+Load domain research generated during `/ant:plan` for injection into worker prompts:
+
+Run using the Bash tool with description "Loading phase research...":
+```bash
+phase_id="{phase_number}"
+research_file=".aether/data/phase-research/phase-${phase_id}-research.md"
+
+if [[ -f "$research_file" ]]; then
+  research_content=$(cat "$research_file")
+  research_word_count=$(wc -w < "$research_file" | tr -d ' ')
+
+  # Apply 8K character budget (same size as colony-prime's 8K; skills has its own 8K)
+  research_budget=8000
+  if [[ ${#research_content} -gt $research_budget ]]; then
+    research_content="${research_content:0:$research_budget}"
+    echo "[research] trimmed to ${research_budget} chars" >&2
+  fi
+
+  research_context="--- PHASE RESEARCH (Domain Knowledge) ---
+${research_content}
+--- END PHASE RESEARCH ---"
+
+  echo "Research loaded: phase-${phase_id}-research.md (${research_word_count} words)"
+else
+  research_context=""
+  echo "No phase research found -- plan was generated before research feature"
+fi
+```
+
+**Parse the result:**
+- If file exists: `research_context` contains the wrapped research content, ready for injection
+- If file does NOT exist: `research_context` is empty, build continues without research (backward compatibility)
+
+**Display:**
+```
+Research loaded: phase-{phase_id}-research.md ({research_word_count} words)
+```
+Or if no research file:
+```
+No phase research found -- plan was generated before research feature
+```
+
+**Store for worker injection:** The `research_context` variable is now available for build-wave.md and build-verify.md to inject into worker prompts. This 8K budget matches colony-prime's 8K budget; skills also has its own separate 8K budget.
+
+### Step 4.1: Archaeologist Pre-Build Scan
+
+**Conditional step — only fires when the phase modifies existing files.**
+
+**DEPTH CHECK: Also skip at "light" depth regardless of file modification.**
+
+If `colony_depth` is "light": Skip this step silently, proceed to Step 4.2.
+Otherwise: Apply existing file-modification conditional below.
+
+1. **Detect existing-file modification:**
+   Examine each task in the phase. Look at task descriptions, constraints, and hints for signals:
+   - Keywords: "update", "modify", "add to", "integrate into", "extend", "change", "refactor", "fix"
+   - References to existing file paths (files that already exist in the repo)
+   - Task type: if a task is purely "create new file X" with no references to existing code, it is new-file-only
+
+   **If ALL tasks are new-file-only** (no existing files will be modified):
+   - Skip this step silently — produce no output, no spawn
+   - Proceed directly to Step 4.2
+
+### Step 4.2: Suggest Pheromones
+
+**Conditional step — skipped if `--no-suggest` flag is passed.**
+
+Analyze codebase and suggest pheromone signals based on detected patterns.
+
+Run using the Bash tool with description "Analyzing codebase for suggestions...":
+```bash
+bash .aether/aether-utils.sh suggest-approve --dry-run 2>/dev/null
+```
+
+Parse the JSON result to get `suggestion_count`.
+
+If `suggestion_count` > 0:
+- Display: "💡 {count} pheromone suggestion(s) detected from code analysis"
+- Run: `bash .aether/aether-utils.sh suggest-approve`
+- Parse result for approved/rejected/skipped counts
+- If approved > 0: Display "✓ {approved} FOCUS signal(s) added"
+
+If `suggestion_count` == 0:
+- Skip silently (no output)
+
+**Non-blocking**: This step never stops the build. Even if suggest-approve fails,
+log a warning and continue to Step 5.
+
+**Error handling**:
+- If suggest-analyze returns error: Log warning, continue
+- If suggest-approve returns error: Log warning, continue
+- Never let suggestion failures block the build
+
+### Step 4.3: Skill Detection
+
+**Non-blocking step — failures are logged and skipped.**
+
+Build the skills index and detect which domain skills match the current codebase.
+
+**4.3.1 — Build/read the skills index:**
+
+Run using the Bash tool with description "Building skills index...":
+```bash
+skill_index_result=$(bash .aether/aether-utils.sh skill-index 2>/dev/null)
+```
+
+**Parse the JSON response:**
+- If `.ok` is false or command fails: Set `skill_index_count = 0`, log warning, skip to next step
+- If successful: Extract `.result.skill_count` as `skill_index_count`
+
+**4.3.2 — Detect domain skills matching this codebase:**
+
+Run using the Bash tool with description "Detecting codebase skills...":
+```bash
+skill_detect_result=$(bash .aether/aether-utils.sh skill-detect "$(pwd)" 2>/dev/null)
+```
+
+**Parse the JSON response:**
+- If `.ok` is false or command fails: Set `skill_detections = "[]"`, log warning, continue
+- If successful: Extract `.result.detections` as `skill_detections` (JSON array)
+- Count entries in `skill_detections` as `skill_detection_count`
+
+**4.3.3 — Store cross-stage state and display:**
+
+Store the following variables for use by build-wave.md:
+- `skill_index_count` — total number of skills in the index
+- `skill_detections` — JSON array of matched skills with scores (e.g., `[{"name": "react", "score": 70}]`)
+
+Display to user:
+```
+🧠 Skills: {skill_index_count} indexed, {skill_detection_count} matched to codebase
+```
+
+**Error handling:**
+- If `skill-index` fails: Log `⚠️ Skill index unavailable — continuing without skills`, set defaults, continue
+- If `skill-detect` fails: Log `⚠️ Skill detection failed — continuing without matches`, set defaults, continue
+- Never let skill failures block the build
+
+2. **If existing code modification detected — spawn Archaeologist Scout:**
+
+   Generate archaeologist name and dispatch:
+   Run using the Bash tool with description "Naming archaeologist...": `bash .aether/aether-utils.sh generate-ant-name "archaeologist"` (store as `{archaeologist_name}`)
+   Run using the Bash tool with description "Dispatching archaeologist...": `bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{archaeologist_name}" "Pre-build archaeology scan"`
+
+   Display:
+   ```
+   ━━━ 🏺🐜 A R C H A E O L O G I S T ━━━
+   ──── 🏺🐜 Spawning {archaeologist_name} — Pre-build history scan ────
+   ```
+
+   > **Platform note**: In Claude Code, use `Task tool with subagent_type`. In OpenCode, use the equivalent agent spawning mechanism for your platform (e.g., invoke the agent definition from `.opencode/agents/`).
+
+   Spawn a Scout (using Task tool with `subagent_type="aether-archaeologist"`, include `description: "🏺 Archaeologist {archaeologist_name}: Pre-build history scan"`) with this prompt:
+   # FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are an Archaeologist Ant - git historian that excavates why code exists."
+
+   ```
+   You are {Archaeologist-Name}, a 🏺🐜 Archaeologist Ant.
+
+   Mission: Pre-build archaeology scan
+
+   Files: {list of existing files that will be modified}
+
+   Work:
+   1. Read each file to understand current state
+   2. Run: git log --oneline -15 -- "{file_path}" for history
+   3. Run: git log --all --grep="fix\|bug\|workaround\|hack\|revert" --oneline -- "{file_path}" for incident history
+   4. Run: git blame "{file_path}" | head -40 for authorship
+   5. Note TODO/FIXME/HACK markers
+
+   Log activity: bash .aether/aether-utils.sh activity-log "READ" "{Ant-Name}" "description"
+
+   Report (plain text):
+   - WHY key code sections exist (from commits)
+   - Known workarounds/hacks to preserve
+   - Key architectural decisions
+   - Areas of caution (high churn, reverts, emergencies)
+   - Stable bedrock vs volatile sand sections
+   ```
+
+   **Wait for results** (blocking — use TaskOutput with `block: true`).
+
+   Log completion:
+   Run using the Bash tool with description "Recording archaeologist findings...": `bash .aether/aether-utils.sh spawn-complete "{archaeologist_name}" "completed" "Pre-build archaeology scan"`
+
+3. **Store and display findings:**
+
+   Store the archaeologist's output as `archaeology_context`.
+
+   Display summary:
+   ```
+   ━━━ 🏺🐜 A R C H A E O L O G Y ━━━
+   {summary of findings from archaeologist}
+   ```
+
+4. **Injection into builder prompts:**
+   The `archaeology_context` will be injected into builder prompts in Step 5.1 (see below).
+   If this step was skipped (no existing files modified), the archaeology section is omitted from builder prompts.
+
+---