aether-colony 5.0.0 → 5.1.0

package/.aether/docs/known-issues.md

@@ -4,118 +4,51 @@ Documented issues from Oracle research findings. These are known limitations and
 
 ---
 
-## Fixed Issues
-
-### Checkpoint Allowlist System (Fixed 2026-02-15)
-
-**Issue:** Build checkpoint could stash user work (TO-DOs.md, dreams, Oracle specs)
-
-**Root Cause:** `git stash` touched files outside system allowlist, stashing 1,145 lines of user work
-
-**Fix:** Explicit allowlist system implemented
-- Created `.aether/data/checkpoint-allowlist.json` defining safe system files
-- Added `checkpoint-check` helper to `.aether/aether-utils.sh`
-- Updated `build.md` (Claude and OpenCode) to use allowlist
-- User data (`.aether/data/`, `.aether/dreams/`, `TO-DOs.md`) is never touched
-- Warning displayed if user files are present during checkpoint
-
-**System Files (Safe):**
-- `.aether/aether-utils.sh`, `.aether/workers.md`, `.aether/docs/**/*.md`
-- `.claude/commands/ant/**/*.md`, `.claude/commands/st/**/*.md`
-- `.opencode/commands/ant/**/*.md`, `.opencode/agents/**/*.md`
-- `bin/**/*`
-
-**User Data (Never Touch):**
-- `.aether/data/`, `.aether/dreams/`, `.aether/oracle/`
-- `TO-DOs.md`, `COLONY_STATE.json`, `.env`, `*.log`
-
----
-
-## Critical Issues (Fix Immediately)
-
-### BUG-005: Missing lock release in flag-auto-resolve — FIXED (Phase 16)
-**Location:** `.aether/aether-utils.sh:1022`
-**Severity:** HIGH
-**Status:** FIXED — Fixed in Phase 16: unified trap pattern (`trap 'release_lock 2>/dev/null || true' EXIT`) applied across all flag commands ensures lock release on all exit paths including jq failure.
-**Symptom:** If jq command fails during flag resolution, lock is never released
-**Impact:** Deadlock on flags.json if jq fails (malformed JSON, disk full, etc.)
-**Workaround:** ~~Restart the colony session if commands hang on flag operations~~ — no longer needed
-**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_flag_auto_resolve_jq_failure_releases_lock
-
-### BUG-011: Missing error handling in flag-auto-resolve jq — FIXED (Phase 16)
-**Location:** `.aether/aether-utils.sh:1022`
-**Severity:** HIGH
-**Status:** FIXED — Fixed in Phase 16: unified trap pattern across all flag commands. See BUG-005.
-**Symptom:** jq failure during auto-resolve not handled
-**Impact:** Combined with BUG-005, causes deadlock
-**Fix:** ~~Add `|| { release_lock; json_err ... }` pattern~~ — implemented via EXIT trap
-
----
-
 ## Medium Priority Issues
 
-### BUG-002: Missing release_lock in flag-add error path — FIXED (Phase 16)
-**Location:** `.aether/aether-utils.sh:814`
-**Severity:** MEDIUM
-**Status:** FIXED — Fixed in Phase 16: trap-based EXIT cleanup (`trap 'release_lock 2>/dev/null || true' EXIT`) ensures lock release on all exit paths including jq failure. Trap is cleared on the success path.
-**Symptom:** If acquire_lock succeeds but jq fails, lock is never released
-**Impact:** Potential deadlock on file operations
-**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_flag_add_jq_failure_releases_lock
-
-### BUG-003: Race condition in backup creation — FIXED (Phase 16)
-**Location:** `.aether/utils/atomic-write.sh:75`
-**Severity:** MEDIUM
-**Status:** FIXED — Backup is now created BEFORE JSON validation in both `atomic_write` and `atomic_write_from_file`. Verified in Phase 16 with regression tests confirming backup contains pre-write content.
-**Symptom:** Backup created AFTER temp file validation but BEFORE atomic move
-**Impact:** If process crashes between validation and backup, inconsistent state
-**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_atomic_write_backup_before_validate, test_atomic_write_from_file_backup_before_validate
-
 ### BUG-004: Missing error code in flag-acknowledge
-**Location:** `.aether/aether-utils.sh:930`
+**Location:** `flag-acknowledge` subcommand in `.aether/utils/flag.sh`
 **Severity:** MEDIUM
-**Symptom:** Uses hardcoded string instead of `$E_VALIDATION_FAILED`
-**Impact:** Inconsistent error handling
-**Fix:** Change to `json_err "$E_VALIDATION_FAILED" "Usage: ..."`
+**Status:** [FIXED in v2.1 -- Phase 10 error triage + Phase 13 modularization]
+`flag-acknowledge` now uses `$E_VALIDATION_FAILED`, `$E_FILE_NOT_FOUND`, `$E_LOCK_FAILED`, and `$E_JSON_INVALID` appropriately.
 
 ### BUG-006: No lock release on JSON validation failure
-**Location:** `.aether/utils/atomic-write.sh:66`
+**Location:** `atomic_write` in `.aether/utils/atomic-write.sh`
 **Severity:** MEDIUM
-**Symptom:** If JSON validation fails, temp file cleaned but lock not released
-**Impact:** Lock remains held if caller had acquired it
-**Fix:** Document lock ownership contract clearly
+**Symptom:** If JSON validation fails in `atomic_write`, temp file is cleaned but any lock held by the caller is not released
+**Impact:** Lock remains held if caller had acquired it before calling `atomic_write`
+**Fix:** Document lock ownership contract clearly -- callers must use trap-based cleanup
+**Status:** Open -- `atomic_write` itself does not manage locks; callers are responsible for lock release via EXIT traps
 
 ### BUG-007: 17+ instances of missing error codes
-**Location:** `.aether/aether-utils.sh` various lines
+**Location:** Various subcommands across `.aether/aether-utils.sh` and domain modules
 **Severity:** MEDIUM
-**Symptom:** Commands use hardcoded strings instead of error constants
-**Impact:** Inconsistent error handling, harder programmatic processing
-**Fix:** Standardize all to use `json_err "$E_*" "message"` pattern
+**Status:** [Mostly FIXED in v2.1 -- Phase 10 error triage]
+Phase 10 replaced ~110 lazy error suppressions with proper fallbacks and added `$E_*` constants to ~48 dangerous paths. A small number of uncommented `2>/dev/null` idioms remain (SUPPRESS:OK annotated).
 
 ### BUG-008: Missing error code in flag-add jq failure
-**Location:** `.aether/aether-utils.sh:856`
+**Location:** `flag-add` subcommand in `.aether/utils/flag.sh`
 **Severity:** HIGH
-**Symptom:** Lock released but error code missing on jq failure
-**Impact:** Error response lacks proper error code
-**Fix:** Change to `json_err "$E_JSON_INVALID" "Failed to add flag"`
+**Status:** [FIXED in v2.1 -- Phase 10 error triage + Phase 13 modularization]
+`flag-add` now uses `$E_VALIDATION_FAILED`, `$E_JSON_INVALID`, and proper error handling throughout.
 
 ### BUG-009: Missing error codes in file checks
-**Location:** `.aether/aether-utils.sh:899, 933`
+**Location:** `flag-acknowledge` and related subcommands in `.aether/utils/flag.sh`
 **Severity:** MEDIUM
-**Symptom:** File not found errors use hardcoded strings
-**Impact:** Inconsistent with other file not found errors
-**Fix:** Use `json_err "$E_FILE_NOT_FOUND" "..."`
+**Status:** [FIXED in v2.1 -- Phase 10 error triage + Phase 13 modularization]
+File-not-found errors now use `json_err "$E_FILE_NOT_FOUND" "..."` consistently.
 
 ### BUG-010: Missing error codes in context-update
-**Location:** `.aether/aether-utils.sh:1758+`
+**Location:** `context-update` subcommand in `.aether/aether-utils.sh`
 **Severity:** MEDIUM
-**Symptom:** Various error paths lack error code constants
-**Impact:** Inconsistent error handling
+**Status:** [FIXED in v2.1 -- Phase 10 error triage]
+All error paths now use `$E_FILE_NOT_FOUND`, `$E_LOCK_FAILED`, and `$E_VALIDATION_FAILED` consistently.
 
 ### BUG-012: Missing error code in unknown command
-**Location:** `.aether/aether-utils.sh:2947`
+**Location:** Default case (`*`) in `.aether/aether-utils.sh` dispatch
 **Severity:** LOW
-**Symptom:** Unknown command handler uses bare string
-**Impact:** Inconsistent error response
+**Status:** [FIXED in v2.1 -- Phase 10 error triage]
+Unknown command handler now uses `json_err "$E_VALIDATION_FAILED" "Unknown command: $cmd"`.
 
 ---
 
@@ -125,109 +58,37 @@ Documented issues from Oracle research findings. These are known limitations and
 **Location:** Multiple locations
 **Severity:** MEDIUM
 **Description:** Some `json_err` calls use hardcoded strings instead of constants
-**Pattern:** Commands added early use strings; later commands use constants
-
-### ISSUE-002: Missing exec error handling — FIXED (Phase 18-02)
-**Location:** `.aether/aether-utils.sh:2132-2144`
-**Severity:** LOW
-**Description:** `model-get` and `model-list` use `exec` without fallback
-**Impact:** If exec fails, script continues to unknown command handler
-**Status:** FIXED — Phase 18-02: subprocess error handling added to model-get and model-list with structured E_* error codes on failure.
-
-### ISSUE-003: Incomplete help command — FIXED (Phase 18-03)
-**Location:** `.aether/aether-utils.sh:106-111`
-**Severity:** LOW
-**Description:** Help command missing newer commands like queen-*, view-state-*, swarm-timing-*
-**Impact:** Users cannot discover all available commands
-**Status:** FIXED — Phase 18-03: help command sections key added with all command groups including Queen Commands, Model Routing, Swarm Operations, and all newer commands.
-
-### ISSUE-004: Template path hardcoded to staging directory — FIXED (Phase 20)
-**Location:** `.aether/aether-utils.sh:2689`
-**Severity:** MEDIUM
-**Status:** FIXED — Phase 20: stale staging template path removed from queen-init lookup array. Template is now found via hub path (`~/.aether/system/templates/`) or dev repo path (`.aether/templates/`) or legacy hub fallback.
-**Description:** queen-init used a staging directory path that did not exist in npm installs
-**Impact:** ~~queen-init will fail when Aether is installed as npm package~~
-**~~Workaround:~~** ~~Use git clone instead of npm install~~ — no longer needed
+**Status:** [Mostly FIXED in v2.1 -- Phase 10 error triage]
+The majority of error paths now use `$E_*` constants. Remaining intentional suppressions are annotated with SUPPRESS:OK comments.
 
 ### ISSUE-005: Potential infinite loop in spawn-tree
-**Location:** `.aether/aether-utils.sh:402-448`, `spawn-tree.sh:222-263`
+**Location:** `spawn-tree-depth` in `.aether/utils/spawn.sh`
 **Severity:** LOW
 **Description:** Edge case with circular parent chain could cause issues
 **Mitigation:** Safety limit of 5 exists
+**Status:** Open -- low risk due to safety limit; code extracted to `spawn.sh` during Phase 13 modularization
 
 ### ISSUE-006: Fallback json_err incompatible
-**Location:** `.aether/aether-utils.sh:65-72`
+**Location:** `.aether/aether-utils.sh` (lines ~65-72, fallback error handler)
 **Severity:** LOW
 **Description:** Fallback json_err doesn't accept error code parameter
 **Impact:** If error-handler.sh fails to load, error codes are lost
-
-### ISSUE-007: Feature detection race condition — FIXED (Phase 18-01)
-**Location:** `.aether/aether-utils.sh:33-45`
-**Severity:** LOW
-**Description:** Feature detection runs before error handler fully sourced
-**Status:** FIXED — Phase 18-01 (ARCH-09): feature detection block moved after fallback json_err definition (line 68 -> 81) so all fallback infrastructure available when feature detection runs.
+**Status:** Open -- low risk since error-handler.sh is a stable infrastructure module
 
 ---
 
 ## Architecture Gaps
 
-### GAP-001: No schema version validation — FIXED (Phase 18-04)
-**Description:** Commands assume state structure without validating version
-**Impact:** Silent failures when state structure changes
-**Status:** FIXED — Phase 18-04: `_migrate_colony_state` added to validate-state colony; auto-migrates pre-3.0 state files to v3.0 (additive only), notifies via W_MIGRATED warning; corrupt state files backed up before error.
-
-### GAP-002: No cleanup for stale spawn-tree entries — FIXED (Phase 18-01)
-**Description:** spawn-tree.txt grows indefinitely
-**Impact:** File could grow very large over many sessions
-**Status:** FIXED — Phase 18-01: `_rotate_spawn_tree` added to session-init; rotates spawn-tree.txt on each session start with timestamped archives; 5-archive cap; in-place truncation preserves tail -f file handles.
-
-### GAP-003: No retry logic for failed spawns — RESOLVED (Phase 18-02)
-**Description:** Task tool calls don't have retry logic
-**Impact:** Transient failures cause build failures
-**Status:** RESOLVED — User decision: fail-fast with rich error context (Phase 18-02). Retry logic adds complexity without clear benefit; subprocess errors now emit structured E_* codes with actionable Try: suggestions, allowing callers to decide on retry strategy.
-
-### GAP-004: Missing queen-* documentation — FIXED (Phase 18-03)
-**Description:** No docs for queen-init, queen-read, queen-promote
-**Impact:** Users cannot discover wisdom feedback loop
-**Status:** FIXED — Phase 18-03: queen-commands.md created in .aether/docs/; help command sections key added with Queen Commands section listing all three commands with descriptions.
-
-### GAP-005: No validation of queen-read JSON output — FIXED (Phase 18-04)
-**Description:** queen-read builds JSON but doesn't validate before returning
-**Impact:** Could return malformed response
-**Status:** FIXED — Phase 18-04: Two validation gates added to queen-read: Gate 1 validates METADATA JSON before --argjson use; Gate 2 validates assembled result before json_ok. Both emit E_JSON_INVALID with actionable Try: suggestion.
-
-### GAP-006: Missing queen-* command documentation — FIXED (Phase 18-03)
-**Description:** Duplicate of GAP-004 - no documentation exists
-**Impact:** Commands are undiscoverable
-**Status:** FIXED — Phase 18-03: See GAP-004.
-
 ### GAP-007: No error code standards documentation
-**Description:** Error codes exist but aren't documented
+**Description:** Error codes exist but aren't documented for external consumers
 **Impact:** Developers don't know which codes to use
+**Status:** Partially addressed -- `_aether_log_error` infrastructure added in Phase 10, but no standalone error code reference doc exists yet
 
 ### GAP-008: Missing error path test coverage
-**Description:** Error handling paths not tested
+**Description:** Error handling paths not fully tested
 **Impact:** Bugs in error handling go undetected
-
-### GAP-009: context-update has no file locking — FIXED (Phase 16)
-**Description:** Race condition possible during concurrent context updates
-**Status:** FIXED — Fixed in Phase 16: context-update wraps all 11 action handlers in a single acquire_lock/release_lock pair. Lock is held for the duration of the update and released on both success and error paths via EXIT trap. force-unlock subcommand added for emergency recovery.
-**Impact:** Potential data corruption
-**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_context_update_acquires_lock, test_force_unlock_clears_locks
-
-### GAP-010: Missing error code standards documentation
-**Description:** Duplicate of GAP-007
-
----
-
-## Workarounds Summary
-
-| Issue | Workaround |
-|-------|------------|
-| ~~Lock-related deadlocks (BUG-005, BUG-002)~~ | ~~Restart colony session~~ — FIXED in Phase 16 |
-| ~~Template path issue (ISSUE-004)~~ | ~~Use git clone instead of npm~~ — FIXED in Phase 20 |
-| Missing command docs (GAP-004) | Read source code directly |
+**Status:** Partially addressed -- Phase 12 added state-api tests; 580+ tests now pass, but error-specific path coverage remains incomplete
 
 ---
 
-*Generated from Oracle Research findings - 2026-02-15*
+*Generated from Oracle Research findings -- Updated 2026-03-24 during v2.1 documentation accuracy phase*

package/.aether/docs/pheromones.md

@@ -10,17 +10,31 @@ Pheromones are how you communicate with the colony. Instead of micromanaging ind
 - **Optional TTL** -- use `--ttl` flag for wall-clock expiration (e.g., `--ttl 2h` for 2 hours)
 - **Priority levels** determine worker attention: high (REDIRECT), normal (FOCUS), low (FEEDBACK)
 - **Expired signals** are filtered on read -- no cleanup process needed
+- **Compact priming path** (`pheromone-prime --compact`) injects only top signals by priority/strength for low token usage
 
 Run `/ant:status` at any time to see all active pheromones.
 
 ---
 
+## How Signals Reach Workers
+
+Workers do not independently read or query pheromone files. Instead, colony-prime handles signal delivery:
+
+1. **colony-prime assembles signals** via `pheromone-prime --compact`, collecting all active signals sorted by priority and strength
+2. **Signals are injected into the `prompt_section`** of the worker spawn context -- they become part of the worker's prompt, not something the worker looks up
+3. **Workers see signals as part of their instructions**, not by reading `.aether/data/pheromones.json` directly
+4. **Builder, Watcher, and Scout** have `pheromone_protocol` sections in their agent definitions (`.claude/agents/ant/`) that instruct them how to act on the injected signals
+
+This injection model means pheromones influence worker behavior through prompt context, the same way any other instruction reaches a worker.
+
+---
+
 ## FOCUS -- Guide Attention
 
 **Command:** `/ant:focus "<area>"`
 **Priority:** normal | **Default expiration:** end of phase
 
-**What it does:** Tells the colony "pay extra attention here." Workers read FOCUS signals and weight this area higher in their task execution.
+**What it does:** Tells the colony "pay extra attention here." FOCUS signals are injected into worker prompts via colony-prime, weighting the indicated area higher in task execution.
 
 ### When to use FOCUS
 
@@ -146,16 +160,16 @@ Auto-emitted signals have their `source` field set to indicate origin: `"worker:
 
 ## Signal Combinations
 
-Pheromones combine. Workers check all active signals and respond accordingly:
+Pheromones combine. colony-prime injects all active signals into worker prompts, ordered by priority:
 
 | Combination | Effect |
 |-------------|--------|
-| FOCUS + FEEDBACK | Workers concentrate on the focused area and adjust approach based on feedback |
-| FOCUS + REDIRECT | Workers prioritize the focused area while avoiding the redirected pattern |
-| FEEDBACK + REDIRECT | Workers adjust approach (feedback) and avoid specific patterns (redirect) |
+| FOCUS + FEEDBACK | The focused area is weighted higher and approach is adjusted based on feedback |
+| FOCUS + REDIRECT | The focused area is prioritized while the redirected pattern is flagged for avoidance |
+| FEEDBACK + REDIRECT | Approach adjustments (feedback) and avoidance patterns (redirect) are both injected |
 | All three | Full steering: attention (FOCUS), avoidance (REDIRECT), and adjustment (FEEDBACK) |
 
-**Priority processing:** Workers check high priority signals first, then normal, then low.
+**Priority processing:** High priority signals appear first in the injected context, then normal, then low.
 
 ---
 
@@ -188,6 +202,70 @@ This ensures signals don't expire while you're away from the project.
 
 ---
 
+## Viewing Active Pheromones
+
+**Command:** `/ant:pheromones [filter]`
+
+Displays all active signals in a formatted table with:
+- Signal type (FOCUS/REDIRECT/FEEDBACK)
+- Current strength percentage (accounting for decay)
+- Elapsed time since creation
+- Remaining time before expiration
+
+**Filters:**
+- `/ant:pheromones` — Show all active signals
+- `/ant:pheromones focus` — Show only FOCUS signals
+- `/ant:pheromones redirect` — Show only REDIRECT signals
+- `/ant:pheromones feedback` — Show only FEEDBACK signals
+- `/ant:pheromones clear` — Clear expired/inactive signals
+
+---
+
+## Automatic Suggestions
+
+The colony can analyze your codebase and suggest pheromones worth capturing.
+
+**During builds:** At Step 4.2, the colony automatically analyzes the codebase and proposes relevant signals:
+- Detects hardcoded values that should be configurable
+- Finds error-prone patterns from the midden
+- Identifies architectural constraints from directory structure
+- Suggests FOCUS areas based on file modification patterns
+- Proposes REDIRECT signals for anti-patterns
+
+**Tick-to-approve UI:** When suggestions are found, the build pauses to show:
+
+```
+🎯 Proposed Pheromone 1 of 3
+
+Type: FOCUS
+Content: "Audio processing — maintain thread safety"
+Confidence: High (3 similar patterns found)
+
+[A]pprove  [R]eject  [S]kip  [D]ismiss All
+```
+
+**Actions:**
+- **A**pprove — Creates the pheromone signal
+- **R**eject — Discards this suggestion (logs reason)
+- **S**kip — Defer decision (shown again next build)
+- **D**ismiss All — Skip all remaining suggestions
+
+---
+
+## Signal Decay
+
+Pheromones lose strength over time (natural decay):
+
+| Signal Type | Half-life | Full decay |
+|-------------|-----------|------------|
+| FOCUS | 15 days | 30 days |
+| REDIRECT | 30 days | 60 days |
+| FEEDBACK | 45 days | 90 days |
+
+Signals below 10% strength are considered inactive but remain in history.
+
+---
+
 ## Quick Reference
 
 | Signal | Command | Priority | Default Expiration | Use for |
@@ -203,3 +281,5 @@ This ensures signals don't expire while you're away from the project.
 - For gentle nudges: FEEDBACK (low priority)
 - For attention: FOCUS (normal priority)
 - For short-lived signals: use `--ttl` flag
+- To see current signals: `/ant:pheromones`
+- To clear expired: `/ant:pheromones clear`

package/.aether/docs/plans/pheromone-display-plan.md

@@ -0,0 +1,257 @@
+# Pheromone Display Enhancement Plan
+
+**Created:** 2026-02-21
+**Status:** ✅ COMPLETED
+**Priority:** High - User-requested feature gap
+
+---
+
+## Problem Statement
+
+The pheromone system works but is invisible:
+
+1. **Council command exists** - `/ant:council` proposes pheromones via multiple choice
+2. **Pheromone signals exist** - Stored in `.aether/data/pheromones.json`
+3. **Colony-prime loads them** - But only shows a count like "Primed: 2 signals"
+4. **User never sees them** - The actual content is hidden
+
+**User's exact words:** "I think it's important to create a significant plan here for how to display the pheromones that are being injected."
+
+---
+
+## What Exists (Don't Rebuild)
+
+| Component | Location | Status |
+|-----------|----------|--------|
+| Council command | `.claude/commands/ant/council.md` | ✅ Works - multi-choice pheromone proposal |
+| Focus command | `.claude/commands/ant/focus.md` | ✅ Works - emits FOCUS signal |
+| Redirect command | `.claude/commands/ant/redirect.md` | ✅ Works - emits REDIRECT signal |
+| Feedback command | `.claude/commands/ant/feedback.md` | ✅ Works - emits FEEDBACK signal |
+| Pheromone storage | `.aether/data/pheromones.json` | ✅ Works - stores signals |
+| Pheromone-prime | `aether-utils.sh:6211` | ✅ Works - loads signals with decay |
+| Colony-prime | `aether-utils.sh:6337` | ✅ Works - combines wisdom + signals |
+| Pheromone-count | `aether-utils.sh:6036` | ✅ Works - counts active signals |
+
+---
+
+## What's Missing
+
+### 1. **Pheromone Display Function** (aether-utils.sh)
+
+A new `pheromone-display` function that outputs a formatted table:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   A C T I V E   P H E R O M O N E S
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 FOCUS (Pay attention here)
+   1. [85%] "security" — injected 2d ago
+   2. [72%] "performance optimization" — injected 5d ago
+
+🚫 REDIRECT (Hard constraints - DO NOT do this)
+   1. [90%] "use ORM" — injected 1d ago
+   2. [68%] "jQuery" — injected 7d ago
+
+💬 FEEDBACK (Guidance to consider)
+   1. [65%] "prefer composition over inheritance" — injected 3d ago
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Total: 5 active signals | Decay: FOCUS 30d, REDIRECT 60d, FEEDBACK 90d
+```
+
+### 2. **Build Command Enhancement** (build.md)
+
+After Step 4 (Load Colony Context), add Step 4.1:
+
+```markdown
+### Step 4.1: Display Active Pheromones
+
+Run using the Bash tool:
+```bash
+bash .aether/aether-utils.sh pheromone-display
+```
+
+This displays the formatted pheromone table to the user so they can see what guidance is active.
+```
+
+### 3. **Status Command Enhancement** (status.md)
+
+Add pheromone summary to `/ant:status` output:
+
+```markdown
+### Pheromones Active
+
+🎯 FOCUS: 2 signals
+🚫 REDIRECT: 1 signal
+💬 FEEDBACK: 1 signal
+
+Run /ant:pheromones for full details
+```
+
+### 4. **New Pheromones Command** (pheromones.md)
+
+A dedicated command for viewing/managing pheromones:
+
+```markdown
+---
+name: ant:pheromones
+description: "🎯🐜🚫🐜💬 View and manage active pheromone signals"
+---
+
+Usage:
+  /ant:pheromones          # Display all active signals
+  /ant:pheromones focus    # Show only FOCUS signals
+  /ant:pheromones redirect # Show only REDIRECT signals
+  /ant:pheromones feedback # Show only FEEDBACK signals
+  /ant:pheromones clear    # Clear all expired signals
+  /ant:pheromones expire <id> # Expire a specific signal
+```
+
+---
+
+## Implementation Plan
+
+### Phase 1: pheromone-display Function (aether-utils.sh)
+
+**Location:** After `pheromone-count` (~line 6058)
+
+```bash
+pheromone-display)
+  # Display active pheromones in formatted table
+  # Usage: pheromone-display [type]
+  #   type: Optional filter (focus/redirect/feedback)
+  # Returns: Formatted table string
+
+  pd_file="$DATA_DIR/pheromones.json"
+  pd_type="${1:-all}"
+  pd_now=$(date +%s)
+
+  if [[ ! -f "$pd_file" ]]; then
+    echo "No pheromones file found. Run /ant:init to initialize colony."
+    exit 0
+  fi
+
+  # Build display using same decay logic as pheromone-read
+  # ... (implementation details)
+```
+
+**Output format:**
+- Header with box drawing
+- Grouped by type (FOCUS, REDIRECT, FEEDBACK)
+- Each signal shows: effective strength %, content, age
+- Footer with totals and decay info
+
+### Phase 2: Update build.md
+
+Add Step 4.1 after colony-prime call to display pheromones visibly.
+
+### Phase 3: Update status.md
+
+Add pheromone summary section after memory health display.
+
+### Phase 4: Create pheromones.md Command
+
+New slash command for dedicated pheromone viewing and management.
+
+---
+
+## Display Locations
+
+| Where | What | When |
+|-------|------|------|
+| `/ant:build` | Full table | Before spawning workers |
+| `/ant:status` | Summary counts | In colony overview |
+| `/ant:council` | After injection | Show what was added |
+| `/ant:pheromones` | Full table + management | On demand |
+| `/ant:continue` | Summary | After phase completion |
+
+---
+
+## Visual Design
+
+### Full Table (for /ant:build, /ant:pheromones)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   A C T I V E   P H E R O M O N E S
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 FOCUS (Pay attention here)
+   1. [85%] "security"
+      └── injected 2d ago, expires in 28d
+   2. [72%] "performance optimization"
+      └── injected 5d ago, expires in 25d
+
+🚫 REDIRECT (Hard constraints - DO NOT do this)
+   1. [90%] "use ORM"
+      └── injected 1d ago, expires in 59d
+   2. [68%] "jQuery"
+      └── injected 7d ago, expires in 53d
+
+💬 FEEDBACK (Guidance to consider)
+   1. [65%] "prefer composition over inheritance"
+      └── injected 3d ago, expires in 87d
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+5 signals active | Decay rates: FOCUS 30d, REDIRECT 60d, FEEDBACK 90d
+```
+
+### Summary (for /ant:status)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ PHEROMONES                                               │
+├─────────────────────────────────────────────────────────┤
+│ 🎯 FOCUS: 2    🚫 REDIRECT: 1    💬 FEEDBACK: 1         │
+│                                                          │
+│ Strongest: "use ORM" [90%]                              │
+│ Newest: "security" [85%] - 2d ago                       │
+│                                                          │
+│ Run /ant:pheromones for details                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Injection Confirmation (for /ant:council, /ant:focus, etc.)
+
+```
+✓ Pheromone injected:
+  🎯 FOCUS: "security"
+  Strength: 0.8 | Expires: 30d
+
+Active signals: 5
+```
+
+---
+
+## Files to Create/Modify
+
+| File | Action | Purpose |
+|------|--------|---------|
+| `.aether/aether-utils.sh` | Modify | Add `pheromone-display` function |
+| `.claude/commands/ant/build.md` | Modify | Add Step 4.1 - display pheromones |
+| `.claude/commands/ant/status.md` | Modify | Add pheromone summary section |
+| `.claude/commands/ant/pheromones.md` | Create | New command for viewing/managing |
+| `.opencode/commands/ant/pheromones.md` | Create | OpenCode version |
+
+---
+
+## Testing
+
+1. Run `/ant:focus "test signal"` and verify it appears in display
+2. Run `/ant:redirect "avoid this"` and verify it appears in display
+3. Run `/ant:build 1` and verify pheromone table shows before workers spawn
+4. Run `/ant:status` and verify pheromone summary appears
+5. Test decay: Create signal, wait, verify strength decreases
+
+---
+
+## Success Criteria
+
+- [x] `/ant:build` displays full pheromone table before spawning workers
+- [x] `/ant:status` shows pheromone counts and strongest/newest
+- [x] `/ant:pheromones` command exists for dedicated viewing
+- [x] `/ant:council` displays what was injected after session (already existed)
+- [x] All signal types (FOCUS/REDIRECT/FEEDBACK) visible
+- [x] Decay strength shown as percentage
+- [x] Age and expiry shown per signal