aether-colony 3.1.17 → 5.0.0

package/.aether/utils/xml-convert.sh

@@ -0,0 +1,273 @@
+#!/bin/bash
+# XML Conversion Utilities
+# Bidirectional JSON/XML conversion and document merging
+#
+# Usage: source .aether/utils/xml-convert.sh
+#        xml-to-json <xml_file> [--pretty]
+#        json-to-xml <json_file> [root_element]
+#        xml-merge <output_file> <main_xml_file>
+#        xml-convert-detect-format <file>
+
+set -euo pipefail
+
+# Source xml-core.sh for JSON helpers and tool detection
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/xml-core.sh"
+
+# Additional tool detection for conversion
+XML2JSON_AVAILABLE=false
+if command -v xml2json >/dev/null 2>&1; then
+    XML2JSON_AVAILABLE=true
+fi
+
+# ============================================================================
+# Format Detection
+# ============================================================================
+
+# xml-convert-detect-format: Detect if file is XML or JSON
+# Usage: xml-convert-detect-format <file>
+# Returns: {"ok":true,"result":{"format":"xml|json|unknown","confidence":"high|medium|low"}}
+xml-convert-detect-format() {
+    local file="${1:-}"
+
+    [[ -z "$file" ]] && { xml_json_err "MISSING_ARG" "Missing file argument"; return 1; }
+    [[ -f "$file" ]] || { xml_json_err "FILE_NOT_FOUND" "File not found: $file"; return 1; }
+
+    # Read first 1KB for analysis
+    local header
+    header=$(head -c 1024 "$file" 2>/dev/null || head -c 1024 < "$file")
+
+    # Check for XML signatures
+    if echo "$header" | grep -qE '^\s*<\?xml\s+version'; then
+        xml_json_ok '{"format":"xml","confidence":"high","signature":"xml_declaration"}'
+        return 0
+    fi
+
+    if echo "$header" | grep -qE '^\s*<[a-zA-Z_][a-zA-Z0-9_]*[\s>]'; then
+        xml_json_ok '{"format":"xml","confidence":"medium","signature":"root_element"}'
+        return 0
+    fi
+
+    # Check for JSON signatures
+    if echo "$header" | grep -qE '^\s*(\{|\[)'; then
+        # Verify it's valid JSON
+        if jq empty "$file" 2>/dev/null; then
+            xml_json_ok '{"format":"json","confidence":"high","signature":"valid_json"}'
+            return 0
+        else
+            xml_json_ok '{"format":"json","confidence":"low","signature":"json_like","note":"Invalid JSON syntax"}'
+            return 0
+        fi
+    fi
+
+    xml_json_ok '{"format":"unknown","confidence":"low","signature":"none"}'
+}
+
+# ============================================================================
+# XML to JSON Conversion
+# ============================================================================
+
+# xml-to-json: Convert XML to JSON format
+# Usage: xml-to-json <xml_file> [--pretty]
+# Returns: {"ok":true,"result":{"json":"...","format":"object"}}
+xml-to-json() {
+    local xml_file="${1:-}"
+    local pretty=false
+
+    # Parse optional arguments
+    shift || true
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --pretty) pretty=true; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    # Check well-formedness first
+    local well_formed_result
+    well_formed_result=$(xml-well-formed "$xml_file" 2>/dev/null)
+    if ! echo "$well_formed_result" | jq -e '.result.well_formed' >/dev/null 2>&1; then
+        xml_json_err "PARSE_ERROR" "XML is not well-formed"
+        return 1
+    fi
+
+    # Try xml2json if available (npm package)
+    if [[ "$XML2JSON_AVAILABLE" == "true" ]]; then
+        local json_output
+        if json_output=$(xml2json "$xml_file" 2>/dev/null); then
+            if [[ "$pretty" == "true" ]]; then
+                json_output=$(echo "$json_output" | jq '.')
+            fi
+            local escaped_json
+            escaped_json=$(echo "$json_output" | jq -Rs '.')
+            xml_json_ok "{\"format\":\"object\",\"json\":$escaped_json}"
+            return 0
+        fi
+    fi
+
+    # Fallback: Use xsltproc with built-in XSLT
+    if [[ "$XSLTPROC_AVAILABLE" == "true" ]]; then
+        local xslt_script
+        xslt_script=$(cat << 'XSLT'
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="text"/>
+<xsl:template match="/">
+<xsl:text>{"root":</xsl:text>
+<xsl:apply-templates select="*"/>
+<xsl:text>}</xsl:text>
+</xsl:template>
+<xsl:template match="*">
+<xsl:text>{"</xsl:text>
+<xsl:value-of select="name()"/>
+<xsl:text>":</xsl:text>
+<xsl:choose>
+<xsl:when test="count(*) > 0">
+<xsl:text>[</xsl:text>
+<xsl:apply-templates select="*"/>
+<xsl:text>]</xsl:text>
+</xsl:when>
+<xsl:otherwise>
+<xsl:text>"</xsl:text>
+<xsl:value-of select="."/>
+<xsl:text>"</xsl:text>
+</xsl:otherwise>
+</xsl:choose>
+<xsl:text>}</xsl:text>
+<xsl:if test="position() != last()">,</xsl:if>
+</xsl:template>
+</xsl:stylesheet>
+XSLT
+)
+        local json_result
+        json_result=$(echo "$xslt_script" | xsltproc - "$xml_file" 2>/dev/null) || {
+            xml_json_err "CONVERSION_ERROR" "XSLT conversion failed"
+            return 1
+        }
+        xml_json_ok "{\"format\":\"object\",\"json\":$(echo "$json_result" | jq -Rs '.')}"
+        return 0
+    fi
+
+    # Last resort: Use xmlstarlet if available
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        local json_result
+        json_result=$(xmlstarlet sel -t -m "/" -o '{"root":{' -m "*" -v "name()" -o ':"' -v "." -o '"' -b -o '}}' "$xml_file" 2>/dev/null) || {
+            xml_json_err "CONVERSION_ERROR" "xmlstarlet conversion failed"
+            return 1
+        }
+        xml_json_ok "{\"format\":\"object\",\"json\":$(echo "$json_result" | jq -Rs '.')}"
+        return 0
+    fi
+
+    xml_json_err "TOOL_NOT_AVAILABLE" "No XML to JSON conversion tool available. Install xml2json, xsltproc, or xmlstarlet."
+    return 1
+}
+
+# ============================================================================
+# JSON to XML Conversion
+# ============================================================================
+
+# json-to-xml: Convert JSON to XML
+# Usage: json-to-xml <json_file> [root_element]
+# Returns: {"ok":true,"result":{"xml":"<root>...</root>"}}
+json-to-xml() {
+    local json_file="${1:-}"
+    local root_element="${2:-root}"
+
+    [[ -z "$json_file" ]] && { xml_json_err "MISSING_ARG" "Missing JSON file argument"; return 1; }
+    [[ -f "$json_file" ]] || { xml_json_err "FILE_NOT_FOUND" "JSON file not found: $json_file"; return 1; }
+
+    # Validate JSON first
+    if ! jq empty "$json_file" 2>/dev/null; then
+        xml_json_err "PARSE_ERROR" "Invalid JSON file: $json_file"
+        return 1
+    fi
+
+    # Build XML using jq to generate structure
+    local xml_output
+    xml_output=$(jq -r --arg root "$root_element" '
+        def to_xml:
+            if type == "object" then
+                to_entries | map(
+                    "<\(.key)>\(.value | to_xml)</\(.key)>"
+                ) | join("")
+            elif type == "array" then
+                map("<item>\(. | to_xml)</item>") | join("")
+            elif type == "string" then
+                .
+            elif type == "number" then
+                tostring
+            elif type == "boolean" then
+                tostring
+            elif type == "null" then
+                ""
+            else
+                tostring
+            end;
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<\($root)>\n" + (to_xml) + "\n</\($root)>"
+    ' "$json_file" 2>/dev/null) || {
+        xml_json_err "CONVERSION_ERROR" "JSON to XML conversion failed"
+        return 1
+    }
+
+    # Escape the XML for JSON output
+    local escaped_xml
+    escaped_xml=$(echo "$xml_output" | jq -Rs '.')
+    xml_json_ok "{\"xml\":$escaped_xml}"
+}
+
+# ============================================================================
+# XML Document Merging
+# ============================================================================
+
+# xml-merge: XInclude document merging
+# Usage: xml-merge <output_file> <main_xml_file>
+# Returns: {"ok":true,"result":{"merged":true,"output":"<path>","sources_resolved":N}}
+xml-merge() {
+    local output_file="${1:-}"
+    local main_xml="${2:-}"
+
+    [[ -z "$output_file" ]] && { xml_json_err "MISSING_ARG" "Missing output file argument"; return 1; }
+    [[ -z "$main_xml" ]] && { xml_json_err "MISSING_ARG" "Missing main XML file argument"; return 1; }
+    [[ -f "$main_xml" ]] || { xml_json_err "FILE_NOT_FOUND" "Main XML file not found: $main_xml"; return 1; }
+
+    # Check well-formedness of main file
+    local well_formed_result
+    well_formed_result=$(xml-well-formed "$main_xml" 2>/dev/null)
+    if ! echo "$well_formed_result" | jq -e '.result.well_formed' >/dev/null 2>&1; then
+        xml_json_err "PARSE_ERROR" "Main XML file is not well-formed"
+        return 1
+    fi
+
+    # Use xmllint for XInclude processing with security flags
+    if [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        local merged
+        merged=$(xmllint --nonet --noent --xinclude "$main_xml" 2>/dev/null) || {
+            xml_json_err "MERGE_ERROR" "XInclude merge failed"
+            return 1
+        }
+
+        # Write output
+        echo "$merged" > "$output_file"
+
+        # Count resolved includes (approximate)
+        local resolved_count
+        resolved_count=$(echo "$merged" | grep -c '<xi:include' 2>/dev/null || echo "0")
+
+        local escaped_output
+        escaped_output=$(echo "$output_file" | jq -Rs '.[:-1]')
+        xml_json_ok "{\"merged\":true,\"output\":$escaped_output,\"sources_resolved\":$resolved_count}"
+        return 0
+    fi
+
+    # Without xmllint, we cannot safely process XInclude
+    xml_json_err "TOOL_NOT_AVAILABLE" "xmllint required for XInclude merging. Install libxml2 utilities."
+    return 1
+}
+
+# Export functions
+export -f xml-convert-detect-format xml-to-json json-to-xml xml-merge
+export XML2JSON_AVAILABLE

package/.aether/utils/xml-query.sh

@@ -0,0 +1,201 @@
+#!/bin/bash
+# XML Query Utilities
+# XPath queries with xmlstarlet and xmllint fallback
+#
+# Usage: source .aether/utils/xml-query.sh
+#        xml-query <xml_file> <xpath_expression>
+#        xml-query-attr <xml_file> <xpath_expression>
+#        xml-query-text <xml_file> <element_name>
+#        xml-query-count <xml_file> <xpath_expression>
+
+set -euo pipefail
+
+# Source xml-core.sh for JSON helpers and tool detection
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/xml-core.sh"
+
+# ============================================================================
+# XPath Query Functions
+# ============================================================================
+
+# xml-query: Execute XPath query against XML file
+# Usage: xml-query <xml_file> <xpath_expression>
+# Returns: {"ok":true,"result":{"matches":["value1","value2",...]}}
+xml-query() {
+    local xml_file="${1:-}"
+    local xpath="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$xpath" ]] && { xml_json_err "MISSING_ARG" "Missing XPath expression"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local results=""
+
+    # Prefer xmlstarlet for full XPath support
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        results=$(xmlstarlet sel -t -v "$xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        # Remove trailing pipe
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint has limited XPath but works for basic queries
+        # Note: xmllint --xpath returns the text content of matched nodes
+        results=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | \
+                  sed 's/<[^>]*>//g' | tr '\n' '|' | sed 's/|$//')
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available (install xmlstarlet or libxml2)"
+        return 1
+    fi
+
+    # Build JSON array from pipe-separated results
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra matches <<< "$results"
+        for match in "${matches[@]}"; do
+            # Trim whitespace and escape for JSON
+            match=$(echo "$match" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            match=$(echo "$match" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$match\""
+            else
+                json_array="$json_array,\"$match\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "{\"matches\":$json_array}"
+    else
+        xml_json_ok '{"matches":[]}'
+    fi
+}
+
+# xml-query-attr: Extract attribute values using XPath
+# Usage: xml-query-attr <xml_file> <element_xpath> <attribute_name>
+# Returns: {"ok":true,"result":{"attribute":"name","values":["val1","val2"]}}
+xml-query-attr() {
+    local xml_file="${1:-}"
+    local element_xpath="${2:-}"
+    local attr_name="${3:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$element_xpath" ]] && { xml_json_err "MISSING_ARG" "Missing element XPath"; return 1; }
+    [[ -z "$attr_name" ]] && { xml_json_err "MISSING_ARG" "Missing attribute name"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local full_xpath="${element_xpath}/@${attr_name}"
+    local results=""
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        results=$(xmlstarlet sel -t -v "$full_xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint can extract attributes with //@attrname syntax
+        results=$(xmllint --nonet --noent --xpath "$full_xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    # Build JSON array
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra values <<< "$results"
+        for val in "${values[@]}"; do
+            val=$(echo "$val" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$val\""
+            else
+                json_array="$json_array,\"$val\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "{\"attribute\":\"$attr_name\",\"values\":$json_array}"
+    else
+        xml_json_ok "{\"attribute\":\"$attr_name\",\"values\":[]}"
+    fi
+}
+
+# xml-query-text: Extract text content of elements
+# Usage: xml-query-text <xml_file> <element_name>
+# Returns: {"ok":true,"result":{"element":"name","text":["text1","text2"]}}
+xml-query-text() {
+    local xml_file="${1:-}"
+    local element_name="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$element_name" ]] && { xml_json_err "MISSING_ARG" "Missing element name"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local xpath="//$element_name"
+    local results=""
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        # Use -m to match nodes and extract text
+        results=$(xmlstarlet sel -t -m "$xpath" -v "." -n "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint --xpath returns text content directly for simple paths
+        results=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | \
+                  sed 's/<[^>]*>//g' | tr '\n' '|' | sed 's/|$//')
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra texts <<< "$results"
+        for text in "${texts[@]}"; do
+            text=$(echo "$text" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            text=$(echo "$text" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$text\""
+            else
+                json_array="$json_array,\"$text\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "{\"element\":\"$element_name\",\"text\":$json_array}"
+    else
+        xml_json_ok "{\"element\":\"$element_name\",\"text\":[]}"
+    fi
+}
+
+# xml-query-count: Count nodes matching XPath expression
+# Usage: xml-query-count <xml_file> <xpath_expression>
+# Returns: {"ok":true,"result":{"count":5}}
+xml-query-count() {
+    local xml_file="${1:-}"
+    local xpath="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$xpath" ]] && { xml_json_err "MISSING_ARG" "Missing XPath expression"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local count=0
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        # Use count() XPath function
+        local count_result
+        count_result=$(xmlstarlet sel -t -v "count($xpath)" "$xml_file" 2>/dev/null)
+        count="${count_result:-0}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # Count matching lines (approximate for simple cases)
+        local matches
+        matches=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | grep -c '<' || true)
+        count="${matches:-0}"
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    xml_json_ok "{\"count\":$count}"
+}
+
+# Export functions
+export -f xml-query xml-query-attr xml-query-text xml-query-count

package/.aether/utils/xml-utils.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# XML Utilities Loader
+# Sources all XML modules for backward compatibility
+#
+# IMPORTANT: This file is now a loader only. New code should source
+# individual modules directly from .aether/utils/ or .aether/exchange/
+#
+# Usage: source .aether/utils/xml-utils.sh
+#
+# Modules loaded:
+#   - xml-core.sh      : Core operations (validate, format, escape)
+#   - xml-query.sh     : XPath queries
+#   - xml-convert.sh   : JSON/XML conversion
+#   - xml-compose.sh   : XInclude composition
+#   - pheromone-xml.sh : Pheromone exchange
+#   - wisdom-xml.sh    : Queen wisdom exchange
+#   - registry-xml.sh  : Colony registry exchange
+#
+# Deprecated functions (maintained for compatibility):
+#   - pheromone-to-xml()  -> Use xml-pheromone-export()
+#   - pheromone-from-xml() -> Use xml-pheromone-import()
+#   - queen-wisdom-to-xml() -> Use xml-wisdom-export()
+#   - queen-wisdom-from-xml() -> Use xml-wisdom-import()
+
+set -euo pipefail
+
+# Determine script directory for relative sourcing
+# Handle case when sourced interactively (BASH_SOURCE[0] may be empty)
+if [[ -n "${BASH_SOURCE[0]:-}" ]]; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+else
+    # Fallback: derive from the sourced script's location
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+fi
+EXCHANGE_DIR="$(cd "$SCRIPT_DIR/../exchange" && pwd)"
+
+# ============================================================================
+# Load Core Modules
+# ============================================================================
+
+# Core utilities (required by other modules)
+source "$SCRIPT_DIR/xml-core.sh"
+
+# Query functions
+source "$SCRIPT_DIR/xml-query.sh"
+
+# Conversion functions
+source "$SCRIPT_DIR/xml-convert.sh"
+
+# Composition functions
+source "$SCRIPT_DIR/xml-compose.sh"
+
+# ============================================================================
+# Load Exchange Modules
+# ============================================================================
+
+# Pheromone exchange (export/import)
+source "$EXCHANGE_DIR/pheromone-xml.sh"
+
+# Queen wisdom exchange
+source "$EXCHANGE_DIR/wisdom-xml.sh"
+
+# Colony registry exchange
+source "$EXCHANGE_DIR/registry-xml.sh"
+
+# ============================================================================
+# Backward Compatibility Aliases
+# ============================================================================
+
+# Map old function names to new ones for compatibility
+pheromone-to-xml() { xml-pheromone-export "$@"; }
+pheromone-from-xml() { xml-pheromone-import "$@"; }
+queen-wisdom-to-xml() { xml-wisdom-export "$@"; }
+queen-wisdom-from-xml() { xml-wisdom-import "$@"; }
+registry-to-xml() { xml-registry-export "$@"; }
+registry-from-xml() { xml-registry-import "$@"; }
+
+# Export compatibility aliases
+export -f pheromone-to-xml pheromone-from-xml
+export -f queen-wisdom-to-xml queen-wisdom-from-xml
+export -f registry-to-xml registry-from-xml
+
+# ============================================================================
+# Module Information
+# ============================================================================
+
+# xml-utils-info: Display module information
+# Usage: xml-utils-info
+xml-utils-info() {
+    xml_json_ok '{
+        "modules": [
+            "xml-core.sh",
+            "xml-query.sh",
+            "xml-convert.sh",
+            "xml-compose.sh",
+            "pheromone-xml.sh",
+            "wisdom-xml.sh",
+            "registry-xml.sh"
+        ],
+        "note": "This loader provides backward compatibility. New code should source individual modules.",
+        "tools": {
+            "xmllint": '"$XMLLINT_AVAILABLE"',
+            "xmlstarlet": '"$XMLSTARLET_AVAILABLE"',
+            "xsltproc": '"$XSLTPROC_AVAILABLE"'
+        }
+    }'
+}
+
+export -f xml-utils-info
+

package/{runtime → .aether}/workers.md

@@ -136,7 +136,7 @@ Before reporting ANY task as complete:
 - Run relevant tests yourself
 - Confirm success criteria with evidence
 
-See `.aether/verification.md` for full discipline reference.
+See `.aether/docs/disciplines/verification.md` for full discipline reference.
 
 ### Verification Loop Discipline
 
@@ -163,7 +163,7 @@ Diff:      [X files changed]
 Overall: [READY/NOT READY]
 ```
 
-See `.aether/verification-loop.md` for full discipline reference.
+See `.aether/docs/disciplines/verification-loop.md` for full discipline reference.
 
 ### Debugging Discipline
 
@@ -187,7 +187,7 @@ When you encounter ANY bug, test failure, or unexpected behavior:
 - "Just try changing X"
 - "I don't fully understand but this might work"
 
-See `.aether/debugging.md` for full discipline reference.
+See `.aether/docs/disciplines/debugging.md` for full discipline reference.
 
 ### TDD Discipline
 
@@ -210,7 +210,7 @@ When implementing ANY new code:
 
 **Coverage target:** 80%+ for new code.
 
-See `.aether/tdd.md` for full discipline reference.
+See `.aether/docs/disciplines/tdd.md` for full discipline reference.
 
 ### Learning Discipline
 
@@ -228,7 +228,7 @@ The colony learns from every phase. Observe patterns for future improvement.
 
 **Report patterns observed** in your output for colony learning.
 
-See `.aether/learning.md` for full discipline reference.
+See `.aether/docs/disciplines/learning.md` for full discipline reference.
 
 ### Coding Standards Discipline
 
@@ -252,7 +252,7 @@ Quick checklist before completing code:
 - **Error handling** - Try/catch with meaningful messages
 - **Async** - Parallelize with Promise.all where possible
 
-See `.aether/coding-standards.md` for full discipline reference.
+See `.aether/docs/disciplines/coding-standards.md` for full discipline reference.
 
 ### Activity Log
 
@@ -387,14 +387,9 @@ All spawns are logged to `.aether/data/spawn-tree.txt` and visible in `/ant:watc
 
 ### Visual Identity
 
-| Role | Emoji |
-|------|-------|
-| Builder | 🔨🐜 |
-| Watcher | 👁️🐜 |
-| Scout | 🔍🐜 |
-| Colonizer | 🗺️🐜 |
-| Architect | 🏛️🐜 |
-| Route-Setter | 📋🐜 |
+Workers display as `{caste_emoji} {worker_name}` (e.g., `🔨🐜 Hammer-42`).
+
+For complete caste emoji reference, see `.aether/docs/caste-system.md`.
 
 Use your emoji in output headers: `{emoji} {Role} Ant -- {status}`
 
@@ -448,7 +443,7 @@ All passing: ✓
 
 **When Encountering Errors:**
 
-Follow systematic debugging (see `.aether/debugging.md`):
+Follow systematic debugging (see `.aether/docs/disciplines/debugging.md`):
 
 1. **STOP** - Do not attempt quick fixes
 2. **Read error completely** - Stack trace, line numbers, error codes
@@ -562,7 +557,7 @@ Findings:
 
 **When Tests Fail:**
 
-Follow systematic debugging (see `.aether/debugging.md`):
+Follow systematic debugging (see `.aether/docs/disciplines/debugging.md`):
 
 1. **Read the failure completely** - Full error, stack trace
 2. **Reproduce** - Run the specific failing test
@@ -626,7 +621,9 @@ Recommendation: {specific fix or investigation needed}
 
 ---
 
-## Architect
+## Architect (Merged into Keeper)
+
+> **Note:** As of Phase 25, Architect capabilities are absorbed by the Keeper agent as "Architecture Mode". Workers named with Architect patterns still resolve to the 🏛️🐜 caste emoji. See `.opencode/agents/aether-keeper.md` for the merged definition.
 
 🏛️ **Purpose:** Synthesize knowledge, extract patterns, and coordinate documentation. The colony's wisdom -- when the colony learns, you organize and preserve that knowledge.