aether-colony 5.0.0 → 5.2.1

package/.claude/commands/ant/migrate-state.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/migrate-state.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:migrate-state
 description: "🚚🐜📦🐜🚚 One-time state migration from v1 to v2.0 format"
@@ -113,12 +114,15 @@ Format the JSON with 2-space indentation for readability.
 
 Output header:
 
+
 ```
 🚚🐜📦🐜🚚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    S T A T E   M I G R A T I O N   C O M P L E T E
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚚🐜📦🐜🚚
 ```
 
+
+
 Then output a migration summary:
 
 ```
@@ -152,6 +156,7 @@ All commands now use consolidated state format.
 - All 12+ ant commands will be updated to use the new single-file format
 - The backup directory preserves original files for rollback if needed
 
+
 ---
 
 ## Step 7: Next Up
@@ -163,3 +168,4 @@ current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
 total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
 bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
 ```
+

package/.claude/commands/ant/oracle.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/oracle.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:oracle
 description: "🔮🐜🧠🐜🔮🐜 Oracle Ant - deep research agent using RALF iterative loop pattern"
@@ -25,20 +26,11 @@ Parse `$ARGUMENTS` to determine the action:
 
 2. **If remaining arguments is exactly `stop`** — go to **Step 0b: Stop Oracle**
 3. **If remaining arguments is exactly `status`** — go to **Step 0c: Show Status**
-4. **Otherwise** — go to **Step 0.5: Initialize Visual Mode** then **Step 1: Research Wizard**
+4. **If remaining arguments is exactly `promote`** — go to **Step 0d: Promote Findings**
+5. **Otherwise** — go to **Step 0.5: Initialize Visual Mode** then **Step 1: Research Wizard**
 
 ### Step 0.5: Initialize Visual Mode (if enabled)
 
-If `visual_mode` is true, run using the Bash tool with description "Initializing oracle display...":
-```bash
-# Generate session ID
-oracle_id="oracle-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$oracle_id"
-bash .aether/aether-utils.sh swarm-display-update "Oracle" "oracle" "researching" "Deep research in progress" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
-```
-
 Display visual header:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -75,35 +67,31 @@ Stop here. Do not proceed.
 
 ### Step 0c: Show Status
 
-Check if `.aether/oracle/progress.md` exists using the Read tool.
+Check if `.aether/oracle/research-plan.md` exists using the Read tool.
 
 **If it does NOT exist**, output:
 
 ```
 🔮🐜 Oracle Status: No Research In Progress
 
-   No progress.md found. Start a research session:
+   No active research session. Start one:
    /ant:oracle
 ```
 
 Stop here.
 
-**If it exists**, read `.aether/oracle/progress.md` and `.aether/oracle/research.json` (if present).
-
-Count the number of `## Iteration` headings in progress.md to determine iterations completed.
+**If it exists**, read `.aether/oracle/research-plan.md` and `.aether/oracle/state.json` (if present).
 
 Output:
 
 ```
 🔮🐜 Oracle Status
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Topic:       {topic from research.json, or "unknown"}
-Confidence:  {target_confidence}%
-Iterations:  {completed} / {max_iterations}
-Started:     {started_at}
+Topic:       {topic from state.json, or "unknown"}
+Iteration:   {iteration} of {max_iterations}
+Status:      {status}
 
-Progress:
-{last 50 lines of progress.md}
+{contents of research-plan.md}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   /ant:oracle stop     Halt the loop
@@ -114,6 +102,143 @@ Stop here.
 
 ---
 
+### Step 0d: Promote Findings to Colony
+
+Check if `.aether/oracle/state.json` exists. If it does NOT exist, or if the status is "active", output:
+
+```
+🔮🐜 Oracle Promote: No Completed Research
+
+   No completed research to promote. Run /ant:oracle first, then wait for completion.
+```
+
+Stop here.
+
+**If state.json exists and status is "complete" or "stopped":**
+
+Read `.aether/oracle/plan.json` and extract high-confidence findings. Run using the Bash tool with description "Reading oracle findings for promotion...":
+
+```bash
+ORACLE_DIR=".aether/oracle"
+topic=$(jq -r '.topic // "unknown"' "$ORACLE_DIR/state.json")
+status=$(jq -r '.status // "active"' "$ORACLE_DIR/state.json")
+count=$(jq '[.questions[] | select(.status == "answered" and .confidence >= 80)] | length' "$ORACLE_DIR/plan.json" 2>/dev/null || echo "0")
+total=$(jq '[.questions[]] | length' "$ORACLE_DIR/plan.json" 2>/dev/null || echo "0")
+echo "TOPIC=$topic"
+echo "STATUS=$status"
+echo "QUALIFYING=$count"
+echo "TOTAL=$total"
+```
+
+If qualifying count is 0, output:
+
+```
+🔮🐜 Oracle Promote: No Qualifying Findings
+
+   Topic:    {topic}
+   Status:   {status}
+   Findings: 0 of {total} questions meet the threshold (answered + 80%+ confidence)
+
+   Lower-confidence findings remain in .aether/oracle/synthesis.md for reference.
+```
+
+Stop here.
+
+**If qualifying count > 0**, display the summary and ask for confirmation:
+
+```
+🔮🐜 Oracle Promote: Colony Knowledge Integration
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Oracle Research: {topic}
+   Status: {status}
+   High-confidence findings: {count} (answering {count} of {total} questions)
+
+   These findings will be promoted to:
+   - Colony instincts (COLONY_STATE.json)
+   - Colony learnings (learnings.json)
+   - Observation pipeline (for queen-promote)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use AskUserQuestion to ask:
+
+```
+Promote these findings to colony knowledge?
+```
+
+Options:
+1. **Yes, promote all high-confidence findings** -- Push qualifying findings to colony instincts, learnings, and observations
+2. **No, skip promotion** -- Findings remain in .aether/oracle/ for reference only
+
+**If user selects Yes:**
+
+Run promotion using the Bash tool with description "Promoting oracle findings to colony knowledge...". For each qualifying question, call the colony APIs directly:
+
+```bash
+ORACLE_DIR=".aether/oracle"
+UTILS=".aether/aether-utils.sh"
+topic=$(jq -r '.topic // "unknown"' "$ORACLE_DIR/state.json")
+promoted=0
+
+while IFS= read -r question; do
+  q_text=$(echo "$question" | jq -r '.text')
+  q_confidence=$(echo "$question" | jq -r '.confidence')
+  findings_text=$(echo "$question" | jq -r '[.key_findings[].text // .key_findings[]] | join("; ")' 2>/dev/null | head -c 200)
+  first_finding=$(echo "$question" | jq -r '[.key_findings[].text // .key_findings[]] | first // "No findings"' 2>/dev/null)
+
+  bash "$UTILS" instinct-create \
+    --trigger "researching: $q_text" \
+    --action "Oracle found (${q_confidence}% confidence): $findings_text" \
+    --confidence "$(echo "scale=2; $q_confidence / 100" | bc)" \
+    --domain "research" \
+    --source "oracle:$topic" \
+    --evidence "Oracle research: $q_text" 2>/dev/null || true
+
+  bash "$UTILS" learning-promote \
+    "Oracle: $q_text -- $first_finding" \
+    "oracle" \
+    "oracle-research" \
+    "oracle,research" 2>/dev/null || true
+
+  bash "$UTILS" memory-capture learning \
+    "Oracle research finding: $q_text (${q_confidence}%)" \
+    "pattern" \
+    "oracle:promote" 2>/dev/null || true
+
+  promoted=$((promoted + 1))
+done < <(jq -c '[.questions[] | select(.status == "answered" and .confidence >= 80)] | .[]' "$ORACLE_DIR/plan.json")
+
+echo "Promoted $promoted findings"
+```
+
+Output:
+
+```
+🔮🐜 Oracle Promote: Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Promoted {count} findings to colony knowledge:
+   - Instincts created in COLONY_STATE.json
+   - Learnings stored in learnings.json
+   - Observations tracked for wisdom promotion
+
+   Run /ant:status to see colony knowledge updates.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**If user selects No:**
+
+```
+🔮🐜 Promotion skipped. Findings remain in .aether/oracle/synthesis.md.
+```
+
+Stop here.
+
+---
+
 ### Step 1: Research Wizard
 
 This is the setup phase. The Oracle asks questions to configure the research before launching.
@@ -153,7 +278,22 @@ Describe the research topic in detail. The more specific, the better the Oracle'
 
 (The user will type their topic via the "Other" free-text option.)
 
-**Question 2: Research Depth**
+**Question 2: Research Template**
+
+```
+What type of research is this?
+```
+
+Options:
+1. **Technology evaluation** -- Compare and evaluate a technology, library, or tool
+2. **Architecture review** -- Analyze system design, components, and dependencies
+3. **Bug investigation** -- Track down and understand a specific bug or issue
+4. **Best practices** -- Research recommended approaches for a domain or technique
+5. **Custom research** -- Free-form research (Oracle decomposes the topic as it sees fit)
+
+Map selection to template value: 1->tech-eval, 2->architecture-review, 3->bug-investigation, 4->best-practices, 5->custom
+
+**Question 3: Research Depth**
 
 ```
 How deep should the Oracle go?
@@ -165,7 +305,7 @@ Options:
 3. **Deep dive (30 iterations)** — Exhaustive research, leaves no stone unturned
 4. **Marathon (50 iterations)** — Maximum depth, may take hours
 
-**Question 3: Confidence Target**
+**Question 4: Confidence Target**
 
 ```
 When should the Oracle consider the research complete?
@@ -177,7 +317,7 @@ Options:
 3. **95% confidence (recommended)** — Thorough, few gaps remaining
 4. **99% confidence** — Near-exhaustive, won't stop until almost everything is known
 
-**Question 4: Research Scope** (only if topic involves codebase)
+**Question 5: Research Scope** (only if topic involves codebase)
 
 ```
 Should the Oracle also search the web, or stay within the codebase?
@@ -188,6 +328,37 @@ Options:
 2. **Codebase + web** — Also use WebSearch and WebFetch for docs, best practices, prior art
 3. **Web only** — Focus on external research (libraries, concepts, techniques)
 
+**Question 6: Search Strategy**
+
+(Ask this question for all research types.)
+
+```
+How should the Oracle approach the research?
+```
+
+Options:
+1. **Adaptive (recommended)** -- Oracle decides when to go broad vs deep based on research progress
+2. **Breadth-first** -- Cover all questions with initial findings before going deep on any single one
+3. **Depth-first** -- Pick the most important question and investigate it exhaustively before moving on
+
+**Question 7: Focus Areas** (optional)
+
+```
+Are there specific aspects you want the Oracle to prioritize?
+```
+
+Options:
+1. **No specific focus** -- Let the Oracle decide what to investigate first
+2. **Yes, I have focus areas** -- I want to steer the research toward specific aspects
+
+If the user selects option 2, ask a follow-up AskUserQuestion with free-text:
+
+```
+List your focus areas (comma-separated). Example: "security implications, performance under load, migration path"
+```
+
+Parse the comma-separated response into individual focus area strings.
+
 After collecting all answers, proceed to Step 2.
 
 ---
@@ -238,66 +409,147 @@ Generate an ISO-8601 UTC timestamp.
 
 **Archive previous research if it exists:**
 
-Check if `.aether/oracle/progress.md` exists. If it does, run using the Bash tool with description "Archiving previous research...":
+Check if `.aether/oracle/state.json` exists. If it does, run using the Bash tool with description "Archiving previous research...":
 
 ```bash
-DATE=$(date +%Y-%m-%d)
-TIMESTAMP=$(date +%H%M%S)
-mkdir -p .aether/oracle/archive
-cp .aether/oracle/progress.md ".aether/oracle/archive/${DATE}-${TIMESTAMP}-progress.md" 2>/dev/null || true
-cp .aether/oracle/research.json ".aether/oracle/archive/${DATE}-${TIMESTAMP}-research.json" 2>/dev/null || true
+ARCHIVE_TS=$(date +%Y-%m-%d-%H%M%S)
+mkdir -p .aether/oracle/archive/$ARCHIVE_TS
+for f in state.json plan.json gaps.md synthesis.md research-plan.md; do
+  [ -f ".aether/oracle/$f" ] && cp ".aether/oracle/$f" ".aether/oracle/archive/$ARCHIVE_TS/"
+done
 ```
 
-**Write research.json:**
+**Write state.json** (replaces research.json):
 
-Use the Write tool to write `.aether/oracle/research.json`:
+Use the Write tool to create `.aether/oracle/state.json`:
 
 ```json
 {
+  "version": "1.1",
   "topic": "<the research topic>",
   "scope": "<codebase|web|both>",
-  "questions": [
-    "<break the topic into 3-5 specific research questions>"
-  ],
+  "template": "<template from Question 2: tech-eval|architecture-review|bug-investigation|best-practices|custom>",
+  "phase": "survey",
+  "iteration": 0,
   "max_iterations": <number from depth choice>,
   "target_confidence": <number from confidence choice>,
-  "started_at": "<ISO-8601 UTC timestamp>"
+  "overall_confidence": 0,
+  "started_at": "<ISO-8601 UTC timestamp>",
+  "last_updated": "<ISO-8601 UTC timestamp>",
+  "status": "active",
+  "strategy": "<strategy from Question 6: adaptive|breadth-first|depth-first>",
+  "focus_areas": [<array of focus area strings from Question 7, or empty array if no focus>]
+}
+```
+
+**Emit focus area pheromones** (if any focus areas were set):
+
+For each focus area string from Question 7, run using the Bash tool with description "Emitting focus area pheromones...":
+
+```bash
+bash .aether/aether-utils.sh pheromone-write FOCUS "$focus_area" \
+  --strength 0.8 --source "oracle:wizard" \
+  --reason "Focus area set in oracle wizard" --ttl "24h" 2>/dev/null || true
+```
+
+**Write plan.json:**
+
+**If template is NOT `custom`**, pre-populate plan.json with the template's default questions. **If template IS `custom`**, break the topic into 3-8 sub-questions (adapt to topic complexity -- broader topics get more questions, focused topics fewer).
+
+Template default questions:
+
+- **tech-eval**: q1 "What problem does this technology solve and what are its core capabilities?", q2 "How does it compare to alternative solutions?", q3 "What are its known limitations and tradeoffs?", q4 "What is the adoption and community status?", q5 "What is the migration or integration path?"
+- **architecture-review**: q1 "What are the main components and their responsibilities?", q2 "What are the dependency relationships between components?", q3 "Where are the risk areas (coupling, complexity, single points of failure)?", q4 "How does it handle scale and growth?", q5 "What would an expert change about this architecture?"
+- **bug-investigation**: q1 "What is the exact failure behavior?", q2 "What are the reproduction conditions?", q3 "What is the root cause?", q4 "What are possible fixes and their tradeoffs?", q5 "Are there related issues or regression risks?"
+- **best-practices**: q1 "What is current industry best practice for this domain?", q2 "How does our implementation compare to best practice?", q3 "What gaps exist between our approach and best practice?", q4 "What is the recommended improvement path?"
+
+Use the Write tool to create `.aether/oracle/plan.json`:
+
+```json
+{
+  "version": "1.1",
+  "sources": {},
+  "questions": [
+    {
+      "id": "q1",
+      "text": "<question text from template or AI-decomposed>",
+      "status": "open",
+      "confidence": 0,
+      "key_findings": [],
+      "iterations_touched": []
+    }
+  ],
+  "created_at": "<ISO-8601 UTC timestamp>",
+  "last_updated": "<ISO-8601 UTC timestamp>"
 }
 ```
 
-The `questions` array is important — break the user's topic into 3-5 concrete, specific questions that the Oracle should answer. These guide each iteration.
+**Write gaps.md** (initial empty structure):
 
-**Write progress.md:**
+Use the Write tool to create `.aether/oracle/gaps.md`:
+
+```markdown
+# Knowledge Gaps
 
-Use the Write tool to write `.aether/oracle/progress.md`:
+## Open Questions
+(No research conducted yet)
+
+## Contradictions
+(None identified)
+
+## Last Updated
+Iteration 0 -- <ISO-8601 UTC timestamp>
+```
+
+**Write synthesis.md** (initial empty structure):
+
+Use the Write tool to create `.aether/oracle/synthesis.md`:
 
 ```markdown
-# Oracle Research Progress
+# Research Synthesis
 
-**Topic:** <the research topic>
-**Started:** <ISO-8601 UTC timestamp>
-**Target Confidence:** <N>%
-**Max Iterations:** <N>
-**Scope:** <codebase|web|both>
+## Topic
+<the research topic>
 
-## Research Questions
-1. <question 1>
-2. <question 2>
-3. <question 3>
-...
+## Findings by Question
+(No findings yet -- research has not started)
 
----
+## Last Updated
+Iteration 0 -- <ISO-8601 UTC timestamp>
+```
+
+**Generate research-plan.md:**
 
+After writing plan.json, generate research-plan.md as the executive summary. Use the Write tool to create `.aether/oracle/research-plan.md`:
+
+```markdown
+# Research Plan
+
+**Topic:** <topic>
+**Status:** active | **Iteration:** 0 of <max>
+**Overall Confidence:** 0%
+
+## Questions
+| # | Question | Status | Confidence |
+|---|----------|--------|------------|
+| q1 | <question text> | open | 0% |
+| q2 | ... | open | 0% |
+
+## Next Steps
+Next investigation: <text of q1, the first question>
+
+---
+*Generated from plan.json -- do not edit directly*
 ```
 
 #### Step 2.5: Verify Oracle Files Are Fresh
 
-Verify that progress.md and research.json were created successfully by running using the Bash tool with description "Verifying oracle files...":
+Verify that state.json, plan.json, gaps.md, synthesis.md, and research-plan.md were created successfully by running using the Bash tool with description "Verifying oracle files...":
 ```bash
 verify_result=$(bash .aether/aether-utils.sh session-verify-fresh --command oracle "" "$ORACLE_START")
 fresh_count=$(echo "$verify_result" | jq -r '.fresh | length')
 
-if [[ "$fresh_count" -lt 2 ]]; then
+if [[ "$fresh_count" -lt 5 ]]; then
   echo "Warning: Oracle files not properly initialized"
 fi
 ```
@@ -308,21 +560,24 @@ Proceed to Step 3.
 
 ### Step 3: Launch
 
-Output the research configuration summary:
+Output the research configuration summary, showing the sub-questions from plan.json:
 
 ```
 🔮 Research Configured
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📍 Topic:       <topic>
+📐 Template:    <template type, e.g. "tech-eval" or "custom">
 🔄 Iterations:  <max_iterations>
 🎯 Confidence:  <target_confidence>%
 🔍 Scope:       <scope>
+📐 Strategy:    <strategy>
+🎯 Focus:       <focus areas comma-separated, or "None">
 
-📋 Research Questions:
-   1. <question>
-   2. <question>
-   3. <question>
+📋 Sub-Questions:
+   q1. <question text from plan.json>
+   q2. <question text from plan.json>
+   q3. <question text from plan.json>
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -332,7 +587,7 @@ Now launch the loop. Try tmux first, fall back to manual.
 **Try tmux** by running using the Bash tool with description "Launching oracle in tmux...":
 
 ```bash
-tmux new-session -d -s oracle "cd $(pwd) && bash .aether/oracle/oracle.sh; echo ''; echo '🔮🐜 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
+tmux new-session -d -s oracle "cd $(pwd) && bash .aether/utils/oracle/oracle.sh; echo ''; echo '🔮🐜 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
 ```
 
 **If TMUX_OK:**
@@ -347,7 +602,7 @@ tmux new-session -d -s oracle "cd $(pwd) && bash .aether/oracle/oracle.sh; echo
    📊 Check status:   /ant:oracle status
    🛑 Stop early:     /ant:oracle stop
 
-   Results will accumulate in .aether/oracle/progress.md
+   Research progress visible at .aether/oracle/research-plan.md
    The Oracle will stop when it reaches {target_confidence}% confidence
    or completes {max_iterations} iterations.
 
@@ -367,7 +622,7 @@ Stop here.
    tmux not available. Run this in a separate terminal:
 
    cd {current_working_directory}
-   bash .aether/oracle/oracle.sh
+   bash .aether/utils/oracle/oracle.sh
 
    Then come back here:
    📊 Check status:   /ant:oracle status

package/.claude/commands/ant/organize.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/organize.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:organize
 description: "🧹🐜🏛️🐜🧹 Run codebase hygiene report - archivist ant scans for stale files, dead code, orphaned configs (report-only)"
@@ -9,6 +10,10 @@ You are the **Queen Ant Colony**. Spawn an archivist to analyze codebase hygiene
 
 ## 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
 
 Use the Read tool to read these files (in parallel):
@@ -18,7 +23,6 @@ Use the Read tool to read these files (in parallel):
 From COLONY_STATE.json, extract:
 - `goal` from top level
 - `plan.phases` for phase data
-- `signals` for pheromone data
 - `errors.records` for error patterns
 - `memory` for decisions/learnings
 - `events` for activity
@@ -27,11 +31,12 @@ From COLONY_STATE.json, extract:
 
 ### Step 2: Compute Active Pheromones
 
-Read active signals from COLONY_STATE.json `signals` array (already loaded in Step 1).
+Run using the Bash tool with description "Loading active pheromones...":
+```bash
+bash .aether/aether-utils.sh pheromone-read
+```
 
-Filter signals where:
-- `expires_at` is null (permanent signals like INIT), OR
-- `expires_at` > current timestamp (not expired)
+Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
 
 Format as the standard ACTIVE PHEROMONES block:
 ```