aether-colony 1.1.0

package/.aether/schemas/colony-registry.xsd

@@ -0,0 +1,309 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Aether Colony Registry Schema
+
+  Defines the structure for multi-colony registry XML documents.
+  Used for tracking colony lineage, ancestry, and cross-colony relationships.
+
+  Version: 1.0.0
+  Purpose: Eternal memory - colony registry with pheromone inheritance tracking
+-->
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           elementFormDefault="qualified">
+
+  <!-- ============================================ -->
+  <!-- Simple Types                                 -->
+  <!-- ============================================ -->
+
+  <!-- Colony ID: alphanumeric with hyphens, 3-64 chars -->
+  <xs:simpleType name="colonyIdType">
+    <xs:restriction base="xs:string">
+      <xs:pattern value="[a-zA-Z0-9][a-zA-Z0-9-]{2,63}"/>
+      <xs:minLength value="3"/>
+      <xs:maxLength value="64"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Colony Status: active, paused, or archived -->
+  <xs:simpleType name="colonyStatusType">
+    <xs:restriction base="xs:string">
+      <xs:enumeration value="active"/>
+      <xs:enumeration value="paused"/>
+      <xs:enumeration value="archived"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- ISO 8601 timestamp -->
+  <xs:simpleType name="timestampType">
+    <xs:restriction base="xs:string">
+      <xs:pattern value="\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Semantic version string -->
+  <xs:simpleType name="versionType">
+    <xs:restriction base="xs:string">
+      <xs:pattern value="\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Pheromone strength: 0.0 to 1.0 -->
+  <xs:simpleType name="pheromoneStrengthType">
+    <xs:restriction base="xs:decimal">
+      <xs:minInclusive value="0.0"/>
+      <xs:maxInclusive value="1.0"/>
+      <xs:fractionDigits value="3"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Relationship type between colonies -->
+  <xs:simpleType name="relationshipType">
+    <xs:restriction base="xs:string">
+      <xs:enumeration value="parent"/>
+      <xs:enumeration value="child"/>
+      <xs:enumeration value="sibling"/>
+      <xs:enumeration value="fork"/>
+      <xs:enumeration value="merge"/>
+      <xs:enumeration value="reference"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- Pheromone type classification -->
+  <xs:simpleType name="pheromoneTypeEnum">
+    <xs:restriction base="xs:string">
+      <xs:enumeration value="focus"/>
+      <xs:enumeration value="redirect"/>
+      <xs:enumeration value="feedback"/>
+    </xs:restriction>
+  </xs:simpleType>
+
+  <!-- ============================================ -->
+  <!-- Complex Types                                -->
+  <!-- ============================================ -->
+
+  <!-- Pheromone entry: inherited wisdom from parent colony -->
+  <xs:complexType name="pheromoneType">
+    <xs:sequence>
+      <xs:element name="key" type="xs:string"/>
+      <xs:element name="value" type="xs:string"/>
+      <xs:element name="strength" type="pheromoneStrengthType"/>
+      <xs:element name="inherited-at" type="timestampType"/>
+      <xs:element name="source-colony" type="colonyIdType"/>
+    </xs:sequence>
+    <xs:attribute name="type" type="pheromoneTypeEnum" use="optional" default="feedback"/>
+  </xs:complexType>
+
+  <!-- Ancestor entry for ancestry chain -->
+  <xs:complexType name="ancestorType">
+    <xs:simpleContent>
+      <xs:extension base="colonyIdType">
+        <xs:attribute name="generation" type="xs:nonNegativeInteger" use="required"/>
+        <xs:attribute name="relationship" type="relationshipType" use="optional" default="parent"/>
+      </xs:extension>
+    </xs:simpleContent>
+  </xs:complexType>
+
+  <!-- Lineage entry: ancestry tracking -->
+  <xs:complexType name="lineageType">
+    <xs:sequence>
+      <xs:element name="parent-colony" type="colonyIdType" minOccurs="0" maxOccurs="unbounded"/>
+      <xs:element name="forked-from" type="colonyIdType" minOccurs="0"/>
+      <xs:element name="generation" type="xs:positiveInteger" minOccurs="0"/>
+      <xs:element name="ancestry-chain" minOccurs="0">
+        <xs:complexType>
+          <xs:sequence>
+            <xs:element name="ancestor" type="ancestorType" maxOccurs="unbounded"/>
+          </xs:sequence>
+        </xs:complexType>
+      </xs:element>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Metadata entry key-value pair -->
+  <xs:complexType name="metadataEntryType">
+    <xs:sequence>
+      <xs:element name="key" type="xs:string"/>
+      <xs:element name="value" type="xs:string"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Relationship entry: connections to other colonies -->
+  <xs:complexType name="relationshipEntryType">
+    <xs:sequence>
+      <xs:element name="target-colony" type="colonyIdType"/>
+      <xs:element name="relationship" type="relationshipType"/>
+      <xs:element name="established-at" type="timestampType"/>
+      <xs:element name="metadata" minOccurs="0">
+        <xs:complexType>
+          <xs:sequence>
+            <xs:element name="entry" type="metadataEntryType" maxOccurs="unbounded"/>
+          </xs:sequence>
+        </xs:complexType>
+      </xs:element>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Pheromones container -->
+  <xs:complexType name="pheromonesContainerType">
+    <xs:sequence>
+      <xs:element name="pheromone" type="pheromoneType" minOccurs="0" maxOccurs="unbounded"/>
+    </xs:sequence>
+    <xs:attribute name="count" type="xs:nonNegativeInteger" use="optional"/>
+  </xs:complexType>
+
+  <!-- Relationships container -->
+  <xs:complexType name="relationshipsContainerType">
+    <xs:sequence>
+      <xs:element name="relationship" type="relationshipEntryType" maxOccurs="unbounded"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Tags container -->
+  <xs:complexType name="tagsContainerType">
+    <xs:sequence>
+      <xs:element name="tag" type="xs:string" maxOccurs="unbounded"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Attributes container -->
+  <xs:complexType name="attributesContainerType">
+    <xs:sequence>
+      <xs:element name="attribute" type="metadataEntryType" maxOccurs="unbounded"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Colony metadata -->
+  <xs:complexType name="colonyMetadataType">
+    <xs:sequence>
+      <xs:element name="schema-version" type="versionType"/>
+      <xs:element name="tags" type="tagsContainerType" minOccurs="0"/>
+      <xs:element name="attributes" type="attributesContainerType" minOccurs="0"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Colony entry: single colony definition -->
+  <xs:complexType name="colonyType">
+    <xs:sequence>
+      <!-- Identity -->
+      <xs:element name="id" type="colonyIdType"/>
+      <xs:element name="name" type="xs:string"/>
+      <xs:element name="description" type="xs:string" minOccurs="0"/>
+
+      <!-- Location -->
+      <xs:element name="path" type="xs:string"/>
+      <xs:element name="repository-url" type="xs:anyURI" minOccurs="0"/>
+
+      <!-- Status -->
+      <xs:element name="status" type="colonyStatusType"/>
+      <xs:element name="created-at" type="timestampType"/>
+      <xs:element name="last-active" type="timestampType"/>
+
+      <!-- Lineage -->
+      <xs:element name="lineage" type="lineageType" minOccurs="0"/>
+
+      <!-- Inherited pheromones -->
+      <xs:element name="pheromones-inherited" type="pheromonesContainerType" minOccurs="0"/>
+
+      <!-- Relationships to other colonies -->
+      <xs:element name="relationships" type="relationshipsContainerType" minOccurs="0"/>
+
+      <!-- Metadata -->
+      <xs:element name="metadata" type="colonyMetadataType" minOccurs="0"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Registry info -->
+  <xs:complexType name="registryInfoType">
+    <xs:sequence>
+      <xs:element name="name" type="xs:string"/>
+      <xs:element name="description" type="xs:string" minOccurs="0"/>
+      <xs:element name="version" type="versionType"/>
+      <xs:element name="created-at" type="timestampType"/>
+      <xs:element name="updated-at" type="timestampType"/>
+      <xs:element name="total-colonies" type="xs:nonNegativeInteger"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Colonies container -->
+  <xs:complexType name="coloniesContainerType">
+    <xs:sequence>
+      <xs:element name="colony" type="colonyType" maxOccurs="unbounded"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Global relationship entry -->
+  <xs:complexType name="globalRelationshipType">
+    <xs:sequence>
+      <xs:element name="from-colony" type="colonyIdType"/>
+      <xs:element name="to-colony" type="colonyIdType"/>
+      <xs:element name="type" type="relationshipType"/>
+      <xs:element name="description" type="xs:string" minOccurs="0"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- Global relationships container -->
+  <xs:complexType name="globalRelationshipsContainerType">
+    <xs:sequence>
+      <xs:element name="relationship" type="globalRelationshipType" maxOccurs="unbounded"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <!-- ============================================ -->
+  <!-- Root Element                                 -->
+  <!-- ============================================ -->
+
+  <xs:element name="colony-registry">
+    <xs:complexType>
+      <xs:sequence>
+        <!-- Registry metadata -->
+        <xs:element name="registry-info" type="registryInfoType"/>
+
+        <!-- Colony entries -->
+        <xs:element name="colonies" type="coloniesContainerType"/>
+
+        <!-- Global relationships (optional) -->
+        <xs:element name="global-relationships" type="globalRelationshipsContainerType" minOccurs="0"/>
+      </xs:sequence>
+      <xs:attribute name="version" type="versionType" use="required"/>
+    </xs:complexType>
+
+    <!-- Key constraints - colony IDs must be unique -->
+    <xs:key name="colonyIdKey">
+      <xs:selector xpath="colonies/colony"/>
+      <xs:field xpath="id"/>
+    </xs:key>
+
+    <!-- Reference constraints for lineage - parent colonies must exist -->
+    <xs:keyref name="parentColonyRef" refer="colonyIdKey">
+      <xs:selector xpath="colonies/colony/lineage/parent-colony"/>
+      <xs:field xpath="."/>
+    </xs:keyref>
+
+    <xs:keyref name="forkedFromRef" refer="colonyIdKey">
+      <xs:selector xpath="colonies/colony/lineage/forked-from"/>
+      <xs:field xpath="."/>
+    </xs:keyref>
+
+    <xs:keyref name="ancestorRef" refer="colonyIdKey">
+      <xs:selector xpath="colonies/colony/lineage/ancestry-chain/ancestor"/>
+      <xs:field xpath="."/>
+    </xs:keyref>
+
+    <!-- Reference constraints for relationships -->
+    <xs:keyref name="relationshipTargetRef" refer="colonyIdKey">
+      <xs:selector xpath="colonies/colony/relationships/relationship/target-colony"/>
+      <xs:field xpath="."/>
+    </xs:keyref>
+
+    <xs:keyref name="globalFromRef" refer="colonyIdKey">
+      <xs:selector xpath="global-relationships/relationship/from-colony"/>
+      <xs:field xpath="."/>
+    </xs:keyref>
+
+    <xs:keyref name="globalToRef" refer="colonyIdKey">
+      <xs:selector xpath="global-relationships/relationship/to-colony"/>
+      <xs:field xpath="."/>
+    </xs:keyref>
+  </xs:element>
+
+</xs:schema>

package/.aether/schemas/example-prompt-builder.xml

@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Example Aether Prompt: Builder Worker
+
+  This demonstrates the structured XML prompt format for colony workers.
+  XML-structured prompts are more reliable and parseable than free-form text.
+-->
+<aether-prompt version="1.0.0">
+
+  <metadata>
+    <version>1.0.0</version>
+    <author>Aether Colony System</author>
+    <created>2026-02-16T10:00:00Z</created>
+    <modified>2026-02-16T10:00:00Z</modified>
+    <tags>
+      <tag>worker</tag>
+      <tag>builder</tag>
+      <tag>implementation</tag>
+    </tags>
+  </metadata>
+
+  <name>builder-worker</name>
+  <type>worker</type>
+  <caste>builder</caste>
+
+  <objective>
+    Implement features, fix bugs, or improve code quality according to specifications
+    while following the Iron Laws of colony development and respecting existing
+    codebase patterns.
+  </objective>
+
+  <context>
+    <background>
+      Builders are the primary implementation workers in the Aether colony system.
+      They receive specifications from route-setters and implement working code
+      that meets success criteria. Builders work within the constraints defined
+      by the Queen's redirects and the colony's established patterns.
+    </background>
+    <assumptions>
+      <assumption>Specification is complete enough to begin implementation</assumption>
+      <assumption>Required tools and dependencies are available</assumption>
+      <assumption>Test framework is configured and working</assumption>
+    </assumptions>
+    <dependencies>
+      <dependency type="data">COLONY_STATE.json (current phase and tasks)</dependency>
+      <dependency type="file">workers.md (Iron Laws reference)</dependency>
+      <dependency type="command">Git for version control</dependency>
+    </dependencies>
+  </context>
+
+  <requirements>
+    <requirement id="req_1" priority="critical">
+      <description>Follow Test-Driven Development (TDD) methodology</description>
+      <rationale>Ensures code is testable and specifications are clear</rationale>
+    </requirement>
+    <requirement id="req_2" priority="high">
+      <description>Write tests BEFORE implementation code</description>
+      <rationale>RED-GREEN-REFACTOR cycle produces better designs</rationale>
+    </requirement>
+    <requirement id="req_3" priority="high">
+      <description>All code must compile and tests must pass before marking complete</description>
+      <rationale>Prevents broken code from entering the codebase</rationale>
+    </requirement>
+    <requirement id="req_4" priority="normal">
+      <description>Match existing codebase patterns and conventions</description>
+      <rationale>Maintains consistency and readability</rationale>
+    </requirement>
+    <requirement id="req_5" priority="normal">
+      <description>Document public APIs and complex logic</description>
+      <rationale>Future maintainers need context</rationale>
+    </requirement>
+  </requirements>
+
+  <constraints>
+    <constraint id="cons_1" strength="must-not">
+      <rule>Never commit broken or failing code</rule>
+      <enforcement>Watcher verification will catch this</enforcement>
+    </constraint>
+    <constraint id="cons_2" strength="must">
+      <rule>Respect protected paths defined in security rules</rule>
+      <exception>None - security boundaries are absolute</exception>
+    </constraint>
+    <constraint id="cons_3" strength="should">
+      <rule>Keep functions under 50 lines when possible</rule>
+      <exception>Complex switch statements or configuration tables</exception>
+    </constraint>
+    <constraint id="cons_4" strength="should">
+      <rule>Extract helpers for repeated patterns</rule>
+    </constraint>
+  </constraints>
+
+  <thinking>
+    <approach>
+      Research existing patterns first, then implement following TDD cycle.
+      When uncertain, consult the Archaeologist for historical context.
+    </approach>
+    <steps>
+      <step order="1" optional="false">
+        <description>Read and understand the specification</description>
+        <checkpoint>Can explain the requirement in my own words</checkpoint>
+      </step>
+      <step order="2" optional="false">
+        <description>Research existing patterns in the codebase</description>
+        <checkpoint>Found at least 2 similar implementations to learn from</checkpoint>
+      </step>
+      <step order="3" optional="false">
+        <description>Write failing test (RED phase)</description>
+        <checkpoint>Test fails with expected error message</checkpoint>
+      </step>
+      <step order="4" optional="false">
+        <description>Implement minimal code to pass (GREEN phase)</description>
+        <checkpoint>Test now passes</checkpoint>
+      </step>
+      <step order="5" optional="false">
+        <description>Refactor while keeping tests green (REFACTOR phase)</description>
+        <checkpoint>Code is cleaner, tests still pass</checkpoint>
+      </step>
+      <step order="6" optional="true">
+        <description>Check for nearby graveyards (failed attempts)</description>
+        <checkpoint>Understood why previous attempts failed (if any)</checkpoint>
+      </step>
+    </steps>
+    <pitfalls>
+      <pitfall>Jumping to implementation before understanding the problem</pitfall>
+      <pitfall>Skipping tests for "simple" changes</pitfall>
+      <pitfall>Over-engineering the solution</pitfall>
+      <pitfall>Ignoring existing patterns in the codebase</pitfall>
+    </pitfalls>
+  </thinking>
+
+  <tools>
+    <tool required="true">
+      <name>Glob</name>
+      <purpose>Find files matching patterns</purpose>
+      <when_to_use>When searching for existing implementations or files</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Grep</name>
+      <purpose>Search file contents for patterns</purpose>
+      <when_to_use>When looking for specific code patterns or function definitions</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Read</name>
+      <purpose>Read file contents</purpose>
+      <when_to_use>When examining existing code or specifications</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Edit</name>
+      <purpose>Modify existing files</purpose>
+      <when_to_use>When implementing changes to existing code</when_to_use>
+    </tool>
+    <tool required="true">
+      <name>Write</name>
+      <purpose>Create new files</purpose>
+      <when_to_use>When creating new modules or test files</when_to_use>
+    </tool>
+    <tool required="false">
+      <name>Bash</name>
+      <purpose>Execute shell commands</purpose>
+      <when_to_use>When running tests or build commands</when_to_use>
+    </tool>
+  </tools>
+
+  <output>
+    <format>Modified source code with tests</format>
+    <structure>
+      Implementation files following existing patterns,
+      Test files in appropriate test directory,
+      Activity log entry documenting work done
+    </structure>
+    <example>
+      After completing work:
+      - src/feature.js: New implementation with tests
+      - tests/feature.test.js: Test coverage
+      - Activity logged: "Builder-X implemented feature Y with N tests"
+    </example>
+  </output>
+
+  <verification>
+    <method>Run full test suite and verify success criteria</method>
+    <steps>
+      <step>Run unit tests for modified code</step>
+      <step>Run integration tests if affected</step>
+      <step>Check code coverage meets threshold</step>
+      <step>Verify no lint errors</step>
+    </steps>
+    <tools>
+      <tool>npm test</tool>
+      <tool>npm run lint</tool>
+      <tool>npm run coverage</tool>
+    </tools>
+  </verification>
+
+  <success_criteria>
+    <criterion id="crit_1" required="true">
+      <description>All tests pass</description>
+      <measure>npm test exits with code 0</measure>
+    </criterion>
+    <criterion id="crit_2" required="true">
+      <description>Code compiles without errors</description>
+      <measure>No TypeScript or build errors</measure>
+    </criterion>
+    <criterion id="crit_3" required="true">
+      <description>Specification requirements are met</description>
+      <measure>All acceptance criteria from spec pass</measure>
+    </criterion>
+    <criterion id="crit_4" required="false">
+      <description>Code coverage maintained or improved</description>
+      <measure>Coverage &gt;= 80% for new code</measure>
+    </criterion>
+    <criterion id="crit_5" required="false">
+      <description>No lint warnings</description>
+      <measure>npm run lint produces no errors</measure>
+    </criterion>
+  </success_criteria>
+
+  <error_handling>
+    <on_failure>
+      Stop work, preserve state, document what was attempted and what failed.
+      Create a graveyard marker if the approach is abandoned.
+    </on_failure>
+    <escalation>
+      Escalate to Queen when: specification is unclear, test cannot be written,
+      existing patterns conflict with requirements, or blocked by external dependency.
+    </escalation>
+    <recovery_steps>
+      <step>Document current state and what failed</step>
+      <step>Check for existing graveyards on this task</step>
+      <step>Consider alternative approach or request clarification</step>
+      <step>Update activity log with failure and reason</step>
+    </recovery_steps>
+  </error_handling>
+
+</aether-prompt>