aether-colony 5.2.1 → 5.3.1

package/.aether/utils/queen.sh

@@ -1391,8 +1391,7 @@ _colony_depth() {
             local new_depth="${2:-}"
             case "$new_depth" in
                 light|standard|deep|full)
-                    local tmp="${DATA_DIR}/COLONY_STATE.json.tmp.$$"
-                    jq --arg d "$new_depth" '.colony_depth = $d' "$DATA_DIR/COLONY_STATE.json" > "$tmp" && mv "$tmp" "$DATA_DIR/COLONY_STATE.json"
+                    NEW_DEPTH="$new_depth" _state_mutate '.colony_depth = env.NEW_DEPTH'
                     json_ok "$(jq -n --arg depth "$new_depth" '{depth: $depth, updated: true}')"
                     ;;
                 *)
@@ -1476,8 +1475,7 @@ _queen_write_charter() {
         local current_name
         current_name=$(jq -r '.colony_name // empty' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null) || true
         if [[ -z "$current_name" && -n "$cw_colony_name" ]]; then
-            local tmp_state="${DATA_DIR}/COLONY_STATE.json.tmp.$$"
-            jq --arg cn "$cw_colony_name" '.colony_name = $cn' "$DATA_DIR/COLONY_STATE.json" > "$tmp_state" && mv "$tmp_state" "$DATA_DIR/COLONY_STATE.json"
+            CW_COLONY_NAME="$cw_colony_name" _state_mutate '.colony_name = env.CW_COLONY_NAME'
         fi
     fi
 

package/.aether/utils/state-api.sh

@@ -96,11 +96,32 @@ _state_write() {
 
 _state_mutate() {
     # Read-modify-write COLONY_STATE.json with a jq expression
-    # Usage: state-mutate '<jq_expression>'
+    # Usage: state-mutate [--arg NAME VALUE] [--argjson NAME VALUE] '<jq_expression>'
+    # Supports jq --arg, --argjson, --slurpfile, --rawfile flags (forwarded to jq)
     # Acquires lock, creates backup, applies jq, validates, writes atomically
     # Returns: json_ok with mutated:true, or json_err on failure
 
-    sm_expr="${1:-}"
+    # Parse jq flags (--arg, --argjson, --slurpfile, --rawfile) from arguments
+    # The jq expression is always the last argument (after all flags)
+    local sm_jq_flags=()
+    local sm_expr=""
+    local i=0
+    local args=("$@")
+
+    while [[ $i -lt ${#args[@]} ]]; do
+        case "${args[$i]}" in
+            --arg|--argjson|--slurpfile|--rawfile)
+                # Flag requires a name and value — consume next two args
+                sm_jq_flags+=("${args[$i]}" "${args[$((i+1))]}" "${args[$((i+2))]}")
+                i=$((i + 3))
+                ;;
+            *)
+                # Last argument is the jq expression
+                sm_expr="${args[$i]}"
+                i=$((i + 1))
+                ;;
+        esac
+    done
 
     if [[ -z "$sm_expr" ]]; then
         json_err "$E_VALIDATION_FAILED" "state-mutate requires a jq expression argument"
@@ -122,8 +143,8 @@ _state_mutate() {
         fi
     fi
 
-    # Apply jq expression to current state
-    sm_updated=$(jq "$sm_expr" "$sm_state_file" 2>/dev/null) || {
+    # Apply jq expression to current state (with forwarded flags)
+    sm_updated=$(jq ${sm_jq_flags[@]+"${sm_jq_flags[@]}"} "$sm_expr" "$sm_state_file" 2>/dev/null) || {
         release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
         json_err "$E_JSON_INVALID" "jq expression failed: $sm_expr"
     }

package/.aether/utils/swarm.sh

@@ -32,7 +32,7 @@ _autofix_checkpoint() {
         label="${1:-autofix-$(date +%s)}"
         stash_name="aether-checkpoint: $label"
         # Only stash Aether-managed directories, never touch user files
-        if git stash push -m "$stash_name" -- $target_dirs >/dev/null 2>&1; then  # SUPPRESS:OK -- existence-test: stash operation may fail
+        if git stash push -m "$stash_name" -- $target_dirs ":(exclude).aether/data/" >/dev/null 2>&1; then  # SUPPRESS:OK -- existence-test: stash operation may fail
           json_ok "$(jq -n --arg ref "$stash_name" '{type: "stash", ref: $ref}')"
         else
           # Stash failed (possibly due to conflicts), record commit hash

package/.aether/utils/worktree.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# Worktree utility functions -- extracted from aether-utils.sh
+# Provides: _worktree_create, _worktree_cleanup
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write, acquire_lock,
+# release_lock, DATA_DIR, COLONY_DATA_DIR, SCRIPT_DIR, AETHER_ROOT, error
+# constants) is available.
+
+# Default worktree location relative to AETHER_ROOT
+WORKTREE_BASE_DIR="${AETHER_ROOT}/.aether/worktrees"
+
+# _worktree_create
+# Creates a git worktree for an agent working on a specific task.
+#
+# Usage: _worktree_create --branch <branch-name> [--base <base-branch>] [--task-id <task-id>]
+# Returns JSON: {ok:true, result:{path, branch, base, worktree_dir, task_id}}
+_worktree_create() {
+    local branch=""
+    local base=""
+    local task_id=""
+
+    # Parse arguments
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --branch) branch="${2:-}"; shift 2 ;;
+            --base)   base="${2:-}";   shift 2 ;;
+            --task-id) task_id="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    # Validate required arguments
+    if [[ -z "$branch" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Usage: worktree-create --branch <branch-name> [--base <base-branch>] [--task-id <task-id>]"
+    fi
+
+    # Sanitize branch name: reject obviously dangerous patterns
+    if [[ "$branch" == *..* ]] || [[ "$branch" == */* ]] || [[ "$branch" == *\\* ]]; then
+        json_err "$E_VALIDATION_FAILED" "Branch name must not contain '..', '/', or backslashes"
+    fi
+
+    # Default base to current branch
+    if [[ -z "$base" ]]; then
+        base=$(git -C "$AETHER_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    fi
+
+    local worktree_dir="$WORKTREE_BASE_DIR/$branch"
+
+    # Check if worktree already exists
+    if [[ -d "$worktree_dir" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Worktree already exists for branch '$branch' at $worktree_dir"
+    fi
+
+    # Check if branch already exists as a git branch (would indicate duplicate)
+    if git -C "$AETHER_ROOT" show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null; then
+        json_err "$E_VALIDATION_FAILED" "Branch '$branch' already exists"
+    fi
+
+    # Ensure base branch exists
+    if ! git -C "$AETHER_ROOT" show-ref --verify --quiet "refs/heads/$base" 2>/dev/null; then
+        json_err "$E_GIT_ERROR" "Base branch '$base' does not exist"
+    fi
+
+    # Ensure parent directory exists
+    mkdir -p "$WORKTREE_BASE_DIR"
+
+    # Create the worktree (git worktree add creates the branch automatically)
+    if ! git -C "$AETHER_ROOT" worktree add "$worktree_dir" -b "$branch" "$base" >/dev/null 2>&1; then
+        json_err "$E_GIT_ERROR" "Failed to create worktree for branch '$branch'"
+    fi
+
+    # Copy .aether/data/ structure to the new worktree so the agent has colony context
+    # Per state-contract-design.md, branch-local state lives in .aether/data/ (gitignored)
+    # and each worktree gets its own independent copy for colony context isolation.
+    if [[ -d "$AETHER_ROOT/.aether/data" ]]; then
+        mkdir -p "$worktree_dir/.aether/data"
+        cp -r "$AETHER_ROOT/.aether/data/." "$worktree_dir/.aether/data/" 2>/dev/null || true  # SUPPRESS:OK -- copy: data dir may be empty
+    fi
+
+    # Copy exchange scripts so xml-utils.sh can source pheromone-xml.sh etc.
+    if [[ -d "$AETHER_ROOT/.aether/exchange" ]]; then
+        mkdir -p "$worktree_dir/.aether/exchange"
+        cp -r "$AETHER_ROOT/.aether/exchange/." "$worktree_dir/.aether/exchange/" 2>/dev/null || true
+    fi
+
+    # Inject main's pheromone signals into the worktree (per D-01)
+    # Non-blocking: if injection fails, worktree still works without injected signals
+    if [[ -f "$worktree_dir/.aether/data/pheromones.json" ]]; then
+      local main_head
+      main_head=$(git -C "$AETHER_ROOT" rev-parse HEAD 2>/dev/null || echo "unknown")
+      (
+        cd "$worktree_dir" 2>/dev/null && \
+        DATA_DIR="$worktree_dir/.aether/data" \
+        COLONY_DATA_DIR="$worktree_dir/.aether/data" \
+        bash "$AETHER_ROOT/.aether/aether-utils.sh" \
+          pheromone-snapshot-inject --from-branch "$base" --from-commit "$main_head" \
+        >/dev/null 2>&1 || true
+      )
+    fi
+
+    # Build result JSON
+    local result
+    result=$(jq -n \
+        --arg path "$worktree_dir" \
+        --arg branch "$branch" \
+        --arg base "$base" \
+        --arg worktree_dir "$worktree_dir" \
+        --arg task_id "${task_id:-null}" \
+        '{
+            path: $path,
+            branch: $branch,
+            base: $base,
+            worktree_dir: $worktree_dir,
+            task_id: (if $task_id == "null" then null else $task_id end)
+        }')
+
+    json_ok "$result"
+}
+
+# _worktree_cleanup
+# Removes a git worktree and cleans up tracking.
+#
+# Usage: _worktree_cleanup --branch <branch-name> [--force]
+# Returns JSON: {ok:true, result:{removed, branch, path}}
+_worktree_cleanup() {
+    local branch=""
+    local force=false
+
+    # Parse arguments
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --branch) branch="${2:-}"; shift 2 ;;
+            --force)  force=true; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    # Validate required arguments
+    if [[ -z "$branch" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Usage: worktree-cleanup --branch <branch-name> [--force]"
+    fi
+
+    # Sanitize branch name
+    if [[ "$branch" == *..* ]] || [[ "$branch" == */* ]] || [[ "$branch" == *\\* ]]; then
+        json_err "$E_VALIDATION_FAILED" "Branch name must not contain '..', '/', or backslashes"
+    fi
+
+    local worktree_dir="$WORKTREE_BASE_DIR/$branch"
+
+    # Check if worktree exists
+    if [[ ! -d "$worktree_dir" ]]; then
+        json_err "$E_RESOURCE_NOT_FOUND" "No worktree found for branch '$branch'"
+    fi
+
+    # Check for uncommitted changes (unless --force)
+    # Exclude .aether/ files since they are branch-local state copies, not user changes
+    if [[ "$force" == "false" ]]; then
+        local dirty_count
+        dirty_count=$(git -C "$worktree_dir" status --porcelain 2>/dev/null \
+            | grep -v '\.aether/' \
+            | wc -l \
+            | tr -d ' ') || dirty_count=0
+
+        if [[ "$dirty_count" -gt 0 ]]; then
+            json_err "$E_VALIDATION_FAILED" "Worktree '$branch' has $dirty_count uncommitted changes. Use --force to remove anyway."
+        fi
+    fi
+
+    # Remove the worktree using git worktree remove
+    if ! git -C "$AETHER_ROOT" worktree remove "$worktree_dir" --force 2>/dev/null; then
+        # Fallback: manual cleanup if git worktree remove fails
+        rm -rf "$worktree_dir" 2>/dev/null || true
+        # Also prune stale worktree entries
+        git -C "$AETHER_ROOT" worktree prune 2>/dev/null || true
+    fi
+
+    # Attempt to delete the branch (best-effort -- may fail if branch is checked out elsewhere)
+    git -C "$AETHER_ROOT" branch -D "$branch" >/dev/null 2>&1 || true
+
+    # Build result JSON
+    local result
+    result=$(jq -n \
+        --arg branch "$branch" \
+        --arg path "$worktree_dir" \
+        '{removed: true, branch: $branch, path: $path}')
+
+    json_ok "$result"
+}

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.3.0] - 2026-03-31
+
+Aether v2.7 — PR Workflow + Stability. Six phases (39-44) adding multi-branch safety, clash detection, and release hardening.
+
+### Added
+- **Pheromone propagation** — Signals flow across git branches via `pheromone-snapshot-inject` and `pheromone-merge-back`; worktree creation auto-copies active pheromones
+- **Midden collection** — Failure records from merged branches collected into main via `midden-collect` with idempotent dedup; cross-PR pattern detection via `midden-cross-pr-analysis`; revert-aware tagging via `midden-handle-revert`
+- **Clash detection** — PreToolUse hook (`clash-pre-tool-use.js`) blocks edits to files modified in other active worktrees; `.aether/data/` files allowlisted (branch-local state)
+- **Worktree utilities** — `_worktree_create` auto-copies colony context (COLONY_STATE.json, pheromones.json) and runs pheromone-snapshot-inject
+- **Merge driver** — `.gitattributes` merge driver resolves package-lock.json conflicts by keeping "ours" via `merge-driver-lockfile.sh`
+- **Midden wiring** — `midden-collect` and `midden-cross-pr-analysis` wired into `/ant:continue` playbooks (non-blocking, follows pheromone merge-back pattern)
+- **Interactive installer** — `npx aether-colony` now shows a 3-option menu (Full setup / Global only / Repo only) with environment detection and context-sensitive defaults; supports `--global`, `--repo`, `--yes` flags for scripting
+- **`aether setup` command** — CLI equivalent of `/ant:lay-eggs` for setting up Aether in a repo without Claude Code open
+
+### Changed
+- **Package validation** — `validate-package.sh` expanded from 15 to 38+ required file entries (100% coverage of packaged utils)
+- **NPX installer** — Replaced `npx-install.js` with interactive `npx-entry.js`; old installer kept as deprecation redirect
+- **Package cleanliness** — 8 dev-only files excluded from npm tarball (scripts/, design docs, example schemas)
+- **CLAUDE.md** — Full accuracy audit: version bumped to v2.7.0, all counts verified (5,500 lines, 35 utils, 45 commands, 509 tests)
+- **README.md** — Architecture counts updated (35 utils, 45 commands, ~5,500 lines)
+- **YAML commands** — 6 stale command files regenerated from YAML sources (init, plan, seal for Claude and OpenCode)
+
+### Fixed
+- **Clash detection dispatcher** — `clash-detect.sh` and `worktree.sh` wired into `aether-utils.sh` dispatcher (source lines, dispatch cases, help JSON)
+- **Init command** — Clash detection hook verification and read-only worktree list integrated into `/ant:init` Step 7.6
+
 ## [2.1.0] - 2026-03-24
 
 Six phases of production hardening (Phases 9-14) targeting reliability, maintainability, and developer experience.