aether-colony 3.1.17 → 5.1.0

package/.claude/commands/ant/resume.md

@@ -1,21 +1,12 @@
-# /ant:resume — Resume Previous Session
-
-Resume work from where you left off after a context clear or new session start.
-
-## When to Use
-
-- After running `/clear` and wanting to continue previous work
-- When opening a new Claude Code session with existing colony state
-- To check what you were working on and pick up where you left off
+<!-- Generated from .aether/commands/resume.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:resume
+description: "Resume Previous Session"
+---
 
-## What It Does
+# /ant:resume — Resume Previous Session
 
-1. Reads `.aether/data/session.json` to understand previous activity
-2. Reads `COLONY_STATE.json` to verify colony status
-3. Checks `TO-DOs.md` for relevant pending work
-4. Presents a summary and asks if you want to resume
-5. If yes: Restores context and suggests next step
-6. If no: Offers to start fresh with `/ant:init`
+Resume work after `/clear` or in a new session. Reads colony state, detects codebase drift, and gives you a clear "do this next" recommendation.
 
 ## Usage
 
@@ -23,137 +14,366 @@ Resume work from where you left off after a context clear or new session start.
 /ant:resume
 ```
 
-## Session Recovery Flow
+---
+
+## Implementation
 
-### Step 1: Check for Existing Session
+Execute the following steps in order when the user runs `/ant:resume`.
 
+---
+
+### Step 1: Read Session State
+
+Run using the Bash tool with description "Restoring colony session..."::
 ```bash
 bash .aether/aether-utils.sh session-read
 ```
 
-Check if session exists and whether it's stale (> 24 hours old).
+Parse the JSON result.
 
-### Step 2: If No Session Found
+- If `exists` is `false`: display the following and **stop**:
 
-Display:
 ```
-📋 SESSION RESUME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+RESUME SESSION
 
 No previous session found.
 
-Would you like to:
-1. Start a new colony with /ant:init
-2. Check status with /ant:status
-3. View existing colonies with /ant:history
+Start fresh: /ant:init "your goal"
+Or check: /ant:status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
 ```
 
-Offer to run `/ant:init` to start fresh.
+- If `exists` is `true`: extract from the session data:
+  - `colony_goal`
+  - `current_phase`
+  - `last_command`
+  - `suggested_next`
+  - `baseline_commit`
+  - `session_id`
+
+---
+
+### Step 2: Read COLONY_STATE.json (Authoritative Source)
 
-### Step 3: If Session Exists
+Use the Read tool to read `.aether/data/COLONY_STATE.json`.
 
-Read session data and colony state, then present summary:
+COLONY_STATE.json is the authoritative source for goal and state (session.json may be stale). Extract:
+- `goal` (use this as authoritative, overriding session.json colony_goal)
+- `state` (READY, PLANNING, EXECUTING, PAUSED)
+- `current_phase`
+- `plan.phases` (array with id, name, status for each phase)
+- `plan.generated_at`
+- `memory.decisions` (flat list — do NOT distinguish user vs Claude origin)
+- `events` (last 5 for recent activity context)
+
+If the file is missing or the JSON cannot be parsed, **stop immediately** and display:
 
 ```
-📋 SESSION RESUME
+State file missing or corrupted.
 
-You were working on: {colony_goal}
-Current Phase: {current_phase} ({current_milestone})
-Last Command: {last_command}
-Last Active: {hours_ago} hours ago
-Suggested Next: {suggested_next}
+Options:
+1. Start fresh with /ant:init "goal"
+2. Try to recover (I'll look for backup files)
+
+What would you like to do?
+```
+
+Do NOT proceed with stale or fabricated data.
+
+---
+
+### Step 3: Read Pheromone Signals
+
+
+Use the Read tool to read `.aether/data/constraints.json`.
+
+Extract the following top-level keys:
+- `focus` array — active focus signals (if key missing, treat as empty array)
+- `constraints` array — active redirect/constraint signals (if key missing, treat as empty array)
+
+If the file is missing: skip silently (no pheromones active).
+
+Pheromones persist until explicitly cleared — no decay.
+
+
+
+---
+
+### Step 4: Read CONTEXT.md
+
+Use the Read tool to read `.aether/CONTEXT.md` if it exists.
+
+If missing: fall back to COLONY_STATE.json for narrative context. Note: "Context document not found — reconstructing from state."
+
+---
+
+### Step 5: Drift Detection
+
+Extract `baseline_commit` from the session.json data read in Step 1.
+
+```bash
+current_commit=$(git rev-parse HEAD 2>/dev/null || echo "")
+```
+
+If `baseline_commit` is non-empty and differs from `current_commit`:
+
+```bash
+commit_count=$(git rev-list --count "$baseline_commit..HEAD" 2>/dev/null || echo "0")
+changed_count=$(git diff --stat "$baseline_commit" HEAD 2>/dev/null | tail -1 | grep -oE '[0-9]+ file' | grep -oE '[0-9]+' || echo "0")
+```
+
+Store `drift_detected=true`, `commit_count`, `changed_count` for dashboard rendering.
+
+If `baseline_commit` is empty or matches `current_commit`: set `drift_detected=false`.
+
+Restore identically regardless of time elapsed — no warnings about session age.
+
+---
+
+### Step 6: Compute Workflow Position and Next-Step Guidance
+
+Compute `suggested_next` dynamically from COLONY_STATE.json data. Do not use the static value from session.json.
+
+Use this decision tree:
+
+```
+Case 1 — No plan created yet:
+  Check: plan.phases is empty AND plan.generated_at is null
+  recommended = "/ant:plan"
+  reason = "No plan created yet"
+  alternatives = ["/ant:colonize — analyze codebase first"]
+
+Case 2 — Plan ready, first phase not started:
+  Check: plan.phases is not empty AND state == "READY" AND current_phase == 0
+  recommended = "/ant:build 1"
+  reason = "Plan ready, first phase not started"
+  alternatives = ["/ant:plan — review or regenerate plan"]
+
+Case 3 — Build in progress:
+  Check: state == "EXECUTING"
+  recommended = "/ant:continue"
+  reason = "Build in progress"
+  alternatives = ["/ant:build {current_phase} — rebuild current phase", "/ant:flags — check for blockers"]
+
+Case 4 — Phase complete, next phase available:
+  Check: state == "READY" AND current_phase > 0 AND current_phase < plan.phases.length
+  next = current_phase + 1
+  recommended = "/ant:build {next}"
+  reason = "Phase {current_phase} complete, ready for next"
+  alternatives = ["/ant:plan — regenerate plan", "/ant:phase {next} — preview next phase"]
+
+Case 5 — All phases complete:
+  Check: state == "READY" AND current_phase > 0 AND current_phase >= plan.phases.length
+  recommended = "/ant:seal"
+  reason = "All phases complete"
+  alternatives = ["/ant:status — view final state"]
+
+Case 6 — Colony paused:
+  Check: state == "PAUSED"
+  recommended = "/ant:resume-colony"
+  reason = "Colony is paused"
+  alternatives = ["/ant:status — check state first"]
+
+Default:
+  recommended = "/ant:status"
+  reason = "Check colony status"
+  alternatives = []
+```
 
-Active TODOs:
-- {todo1}
-- {todo2}
+---
 
-Would you like to resume this work?
+### Step 7: Workflow-Step Blocking (Early-Return Guards)
+
+Run these guards BEFORE rendering the dashboard. If a blocking condition is detected, output the block message and STOP. Do not render the dashboard. Do not offer alternative commands.
+
+**BLOCK CONDITION 1: No plan exists**
+
+Check: plan.phases is empty AND plan.generated_at is null
+
+Output and STOP:
+
+```
+BLOCKED: No plan exists yet.
+Required: Run /ant:plan to create a build plan.
+Goal: {goal}
+```
+
+Stop here — do not continue to Step 8 or render the dashboard.
+
+---
+
+**BLOCK CONDITION 2: Plan attempted but failed**
+
+Check: plan.phases is empty AND plan.generated_at is not null
+
+Output and STOP:
+
+```
+BLOCKED: Plan was attempted but has no phases.
+Required: Run /ant:plan to regenerate the plan.
+Goal: {goal}
 ```
 
-Use `AskUserQuestion` to present options:
-- **Yes, resume** — Continue where you left off
-- **Show details** — See full colony state first
-- **No, start fresh** — Clear session and start new
+Stop here — do not continue to Step 8 or render the dashboard.
+
+---
 
-### Step 4: If User Chooses "Yes, resume"
+**BLOCK CONDITION 3: Build interrupted**
 
-1. Mark session as resumed:
-   ```bash
-   bash .aether/aether-utils.sh session-mark-resumed
-   ```
+Check: state == "EXECUTING" AND the last 3 events show no recent build activity
 
-2. Present context summary:
-   ```
-   🔄 Resuming Session
+Output and STOP:
 
-   Colony: {goal}
-   Phase: {phase} - {milestone}
-   Context restored.
+```
+BLOCKED: Build may have been interrupted.
+Required: Run /ant:continue to check and advance.
+Goal: {goal}
+```
 
-   Next suggested step: {suggested_next}
-   ```
+Stop here — do not continue to Step 8 or render the dashboard.
 
-3. Run the suggested command or present further options based on state.
+---
 
-### Step 5: If User Chooses "Show details"
+### Step 8: Render Dashboard
+
+Lead with the next-step recommendation. Context follows underneath ("straight to action" ordering).
 
-Display:
 ```
-📊 Colony Details
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+RESUME SESSION
+
+Next: {recommended}
+      {reason}
+{if alternatives exist:}
+Also: {alternatives, comma-separated}
+{end}
+
+{if drift_detected:}
+Note: Codebase changed since last session ({commit_count} commit(s), {changed_count} file(s) modified)
+{end}
 
 Goal: {goal}
 State: {state}
-Phase: {phase}
-Milestone: {milestone}
+Phase: {current_phase}/{total_phases}
 
-Recent Activity (from activity.log):
-{last 5 entries}
+Phase Progress:
+{for each phase in plan.phases:}
+  [{status_icon}] Phase {id}: {name}
+{end}
+```
 
-Pending TODOs:
-{todos}
+Status icons:
+- completed: `v` (checkmark)
+- in_progress: `~` (tilde)
+- pending: ` ` (space)
 
-[Present Yes/No choice to resume]
 ```
+{if memory.decisions is not empty:}
+Recent Decisions:
+{for each of the last 5 decisions:}
+  - {decision text}
+{end}
+{end}
 
-### Step 6: If User Chooses "No, start fresh"
+{if signals array from Step 3 is not empty:}
+Active Signals:
 
-1. Clear the session:
-   ```bash
-   bash .aether/aether-utils.sh session-clear
-   ```
+{for each focus signal:}
+  FOCUS: {focus text}
+{end}
+{for each constraint signal:}
+  REDIRECT: {constraint text}
+{end}
 
-2. Offer:
-   ```
-   Session cleared.
 
-   Start fresh with:
-   - /ant:init "your new goal"
-   - /ant:status (to check other colonies)
-   ```
+{end}
+```
 
-## Integration with Colony Commands
+---
 
-All `/ant:*` commands should update the session after execution:
+### Step 8.5: Display Memory Health (Secondary)
 
+Run using the Bash tool with description "Loading memory health..."::
 ```bash
-# Example: After /ant:build completes
-bash .aether/aether-utils.sh session-update "/ant:build $phase" "/ant:continue" "Completed phase $phase"
+bash .aether/aether-utils.sh resume-dashboard
 ```
 
-This ensures session.json is always current for resume functionality.
+Extract memory_health from the JSON result:
+- wisdom_count
+- pending_promotions
+- recent_failures
 
-## Session File Location
+Display after the main dashboard:
+```
+📊 Memory Health
+   Wisdom: {wisdom_count} entries | Pending: {pending_promotions} promotions | Failures: {recent_failures} recent
 
-`.aether/data/session.json`
+   Run /ant:memory-details for full breakdown
+```
 
-This file persists across context clears and Claude Code sessions.
+If all counts are 0, show:
+```
+📊 Memory Health
+   No accumulated wisdom yet. Complete phases to build colony memory.
+```
 
-## Stale Session Detection
+Last Command: {last_command}
+Session: {session_id}
+```
 
-Sessions older than 24 hours are marked "stale":
-- User is warned: "This session is X days old"
-- Given option to resume anyway or start fresh
-- Helps prevent accidentally resuming ancient work
+---
+
+### Step 9: Mark Session Resumed
+
+Run using the Bash tool with description "Marking session as resumed..."::
+```bash
+bash .aether/aether-utils.sh session-mark-resumed
+```
+
+### Step 10: Next Up
+
+Generate the state-based Next Up block by Run using the Bash tool with description "Generating Next Up suggestions..."::
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+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"
+```
+
+---
+
+## Error Handling Reference
+
+| Condition | Response |
+|-----------|----------|
+| session.json missing (exists=false) | "No previous session found" — offer /ant:init and /ant:status |
+| COLONY_STATE.json missing or corrupted | Pause, ask user: start fresh or recover |
+
+| constraints.json missing | Skip silently (no pheromones) |
+
+
+| CONTEXT.md missing | Fall back to COLONY_STATE.json narrative |
+| No plan phases, no generated_at | BLOCK — redirect to /ant:plan |
+| Plan attempted but no phases | BLOCK — redirect to /ant:plan |
+| State EXECUTING, events show no activity | BLOCK — redirect to /ant:continue |
+| baseline_commit matches current HEAD | No drift warning shown |
+| baseline_commit differs from current HEAD | Show informational drift note |
+
+---
+
+## Key Constraints
+
+
+- Use Read tool for COLONY_STATE.json and constraints.json (not bash cat/jq).
 
-## Implementation
 
-Execute this flow when user runs `/ant:resume`.
+- Use Bash tool only for aether-utils.sh commands and git commands
+- Handle ALL missing/corrupted file cases gracefully
+- Time-agnostic: restore identically regardless of how long ago the session was
+- Decisions shown as flat list — no user vs Claude distinction
+- Blocking guards run BEFORE dashboard rendering (early-return pattern)
+- Drift detection is informational only — not alarming, not a blocker

package/.claude/commands/ant/run.md

@@ -0,0 +1,195 @@
+<!-- Generated from .aether/commands/run.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:run
+description: "Autopilot — builds, verifies, learns, and advances through phases automatically with smart pausing"
+---
+
+You are the **Queen**. Execute `/ant:run` — the adaptive autopilot loop.
+
+The arguments are: `$ARGUMENTS`
+
+## Purpose
+
+This command automates the build-continue-advance cycle across multiple phases.
+It reads and executes the same playbooks used by `/ant:build` and `/ant:continue`,
+chaining them in a loop with intelligent pause conditions.
+
+## Rules
+
+1. Do **not** invoke nested slash commands (`/ant:build`, `/ant:continue`, etc.).
+2. Use the Read tool to load each playbook file, then execute it inline.
+3. Preserve variables/results from prior stages and pass them forward.
+4. Stop immediately on any pause condition (defined below).
+5. Keep existing behavior and output format from the playbooks.
+6. Log `autopilot_advance` events after each successful phase transition.
+
+## Arguments
+
+Parse `$ARGUMENTS` for:
+- `--max-phases N` — Max phases to process (default: all remaining)
+- `--replan-interval N` — Pause for replan suggestion every N phases (default: 2)
+- `--continue` — Resume after a replan pause without replanning
+- `--dry-run` — Preview plan without executing
+- `--verbose` / `-v`, `--no-visual`, `--no-suggest` — Pass through to playbooks
+
+```
+/ant:run                       Run all remaining phases
+/ant:run --max-phases 2        Run at most 2 phases then stop
+/ant:run --replan-interval 3   Suggest replan every 3 phases instead of 2
+/ant:run --continue            Resume after replan pause without replanning
+/ant:run --dry-run             Preview the autopilot plan
+/ant:run --max-phases 3 -v     Run 3 phases with verbose output
+```
+
+## Dry Run Mode
+
+If `--dry-run`: read COLONY_STATE.json, list remaining incomplete phases
+(applying `--max-phases` cap), display the plan, then stop without executing.
+
+```
+━━━ A U T O P I L O T   P R E V I E W ━━━
+Goal: {goal} | Current: Phase {N} | Remaining: {count} | Max: {max or "all"}
+
+  Phase {id}: {name} ({task_count} tasks) -> build -> continue -> advance
+  ...
+
+Pause triggers: test failures, critical Chaos findings, new blockers,
+security gate failures, quality gate failures, runtime verification needed,
+replan suggestion (every {replan_interval} phases)
+```
+
+## Autopilot Loop
+
+### Step 0: Initialize
+
+1. Read `.aether/data/COLONY_STATE.json`; validate goal + plan.phases exist
+2. Determine remaining incomplete phases; apply `--max-phases` cap
+3. Set `phases_completed = 0`, `autopilot_start = $(date +%s)`
+4. Record pre-build blocker count: `bash .aether/aether-utils.sh flag-check-blockers {phase}`
+5. Display: `AUTOPILOT ENGAGED | Goal: {goal} | Phase {N} | Max: {max or "all"}`
+
+### Step 1: Build Phase
+
+Execute build playbooks in order, carrying cross-stage state
+(`phase_id`, `visual_mode`, `verbose_mode`, `suggest_enabled`,
+`prompt_section`, `wave_results`,
+`verification_status`, `synthesis_status`, `next_action`):
+
+1. `.aether/docs/command-playbooks/build-prep.md`
+2. `.aether/docs/command-playbooks/build-context.md`
+3. `.aether/docs/command-playbooks/build-wave.md`
+4. `.aether/docs/command-playbooks/build-verify.md`
+5. `.aether/docs/command-playbooks/build-complete.md`
+
+Capture the synthesis result for pause evaluation.
+
+### Step 2: Build Pause Check
+
+**PAUSE if ANY of these are true** (display reason, log event, STOP):
+
+| # | Condition | Source |
+|---|-----------|--------|
+| 1 | Watcher `verification_passed == false` | build-verify synthesis |
+| 2 | Any Chaos finding severity `critical` or `high` | build-verify synthesis |
+| 3 | New blocker flags created (count increased since Step 0.4) | flag-check-blockers |
+
+On pause, display the AUTOPILOT PAUSED banner with reason, affected phase,
+specific issues, and instruction: "Fix issues, then run /ant:run to resume."
+Log: `"<timestamp>|autopilot_paused|run|Paused at Phase {id}: {reason}"`
+
+**If no pause:** proceed to Step 3.
+
+### Step 3: Continue (Verify + Advance)
+
+Execute continue playbooks in order, carrying cross-stage state
+(`visual_mode`, `state`, `current_phase`, `verification_results`,
+`gate_results`, `advancement_result`, `next_phase_id`, `completion_state`):
+
+1. `.aether/docs/command-playbooks/continue-verify.md`
+2. `.aether/docs/command-playbooks/continue-gates.md`
+3. `.aether/docs/command-playbooks/continue-advance.md`
+4. `.aether/docs/command-playbooks/continue-finalize.md`
+
+**Autopilot override for runtime verification (Step 1.11 in continue-gates):**
+Skip the AskUserQuestion prompt. Instead, auto-PAUSE with reason
+"Runtime verification required" so the user can test manually before resuming.
+
+### Step 4: Continue Pause Check
+
+**PAUSE if ANY of these are true:**
+
+| # | Condition | Source |
+|---|-----------|--------|
+| 4 | Verification loop reported NOT READY | continue-verify |
+| 5 | Gatekeeper found critical CVEs | continue-gates |
+| 6 | Auditor critical findings or score < 60 | continue-gates |
+| 7 | Unresolved blocker flags remain | continue-gates |
+| 8 | Runtime verification needed | continue-gates Step 1.11 |
+| 9 | All phases complete (no next phase) | continue-advance |
+| 10 | Replan trigger fires (unless `--continue`) | autopilot-check-replan (Step 5.5) |
+
+For condition 9: jump to Step 6 (celebration). For condition 10: PAUSE with
+replan suggestion (see Step 5.5). For all others: PAUSE with reason, log event, STOP.
+
+**If no pause:** proceed to Step 5.
+
+### Step 5: Auto-Advance and Loop
+
+1. Increment `phases_completed`
+2. Update autopilot state: `bash .aether/aether-utils.sh autopilot-update --action advance --phase {next} --result success`
+3. Log: `"<timestamp>|autopilot_advance|run|Phase {prev} -> {next} ({phases_completed}/{max})"`
+4. Display: `--- Autopilot: Phase {prev} done -> Phase {next} ({N}/{max}) ---`
+5. **Replan check** (see Step 5.5)
+6. If `phases_completed >= max_phases` or no incomplete phases: go to Step 6
+7. Otherwise: update `current_phase`, return to Step 1
+
+### Step 5.5: Replan Trigger Check
+
+After each successful phase advance, check if a replan pause should fire:
+
+```bash
+bash .aether/aether-utils.sh autopilot-check-replan --interval {replan_interval}
+```
+
+If `--continue` flag was passed: skip this check entirely (user dismissed replan).
+
+If `result.should_replan == true`: **PAUSE** with replan suggestion banner:
+
+```
+━━━ R E P L A N   S U G G E S T E D ━━━
+Phases auto-completed: {N} | Learnings accumulated: {learnings_since_last}
+
+The colony has completed {N} phases since the last plan review.
+New learnings may have changed the optimal path forward.
+
+Options:
+  /ant:plan              Regenerate phases with current learnings
+  /ant:run --continue    Dismiss and continue without replanning
+```
+
+Log: `"<timestamp>|autopilot_replan_pause|run|Replan suggested after {N} phases ({learnings} learnings)"`
+
+If `result.should_replan == false`: proceed normally (no pause).
+
+### Step 6: Final Summary
+
+```
+━━━ A U T O P I L O T   C O M P L E T E ━━━
+Phases completed: {N} | Elapsed: {Xm Ys} | Now at: Phase {current}
+
+{all complete}  -> Colony goal achieved! Run /ant:seal
+{max reached}   -> Run /ant:run to continue
+{replan}        -> Run /ant:plan to replan, or /ant:run --continue to dismiss
+{paused}        -> Fix {reason}, then /ant:run to resume
+```
+
+Update session:
+`bash .aether/aether-utils.sh session-update "/ant:run" "/ant:run" "Autopilot: {N} phases, now Phase {current}"`
+
+## Execution Contract
+
+For each playbook stage: Read file, execute inline, track `{stage_name, status, key_outputs}`.
+If `status == failed`: evaluate pause conditions. Pause = graceful stop with saved state.
+Hard failure (e.g., state corruption) = halt immediately, no recovery attempt.
+
+On every pause: save COLONY_STATE.json, log event, update session, display resume instructions.