AMPR-172 #501: Canonical PROPEL enforcement — six-phase CognitivePhase (#511)

I extended `CognitivePhase` to the canonical six-phase PROPEL cycle
(PERCEIVE / RECALL / OBSERVE / PLAN / EXECUTE / LEARN), added built-in
`PhaseSpark.Recall` and `PhaseSpark.Observe`, fixed every exhaustiveness
site the compiler surfaced (`SparkStack.phaseHeader`,
`AmperePhosphorBridge.effectForPhase`), removed the silent
`LEARN → PhosphorPhase.EVALUATE` paveover in the CLI bridge, expanded
the role-spark `.spark.md` fixtures to cover the new phases, rewrote
the PROPEL narrative across README/AGENTS/STYLE/docs, added a `PhaseSparkTest`
locking the acronym ordering plus a six-phase walk in
`AmperePhosphorBridgeTest`, and recorded the breaking change in a new
`CHANGELOG.md`.

Closes #501

Co-authored-by: Miley Chandonnet <miley@Mileys-Mac-mini.local>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

AGENTS.md

@@ -77,7 +77,7 @@ See [ampere-cli/README.md](ampere-cli/README.md) for full CLI documentation.
 
 ## Architecture at a Glance
 
-Ampere follows a layered architecture built on the **PROPEL** cognitive loop (Perceive, Recall, Optimize, Plan, Execute, Loop) and six core primitives (Tickets, Tasks, Plans, Meetings, Outcomes, Knowledge).
+Ampere follows a layered architecture built on the **PROPEL** cognitive loop (Perceive, Recall, Observe, Plan, Execute, Learn) and six core primitives (Tickets, Tasks, Plans, Meetings, Outcomes, Knowledge).
 
 | Layer | Location | Purpose |
 |-------|----------|---------|

CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to AMPERE are recorded here. Dates are in UTC.
+
+The project is pre-1.0; breaking changes are acceptable and explicitly called out.
+
+## [Unreleased]
+
+### Breaking
+
+- **PROPEL `CognitivePhase` enum is now canonically six members**
+  ([AMPR-172](https://linear.app/miley/issue/AMPR-172)).
+
+  `CognitivePhase` in
+  `link.socket.ampere.agents.domain.cognition.sparks.PhaseSpark.kt`
+  becomes the full PROPEL cycle in canonical order:
+
+  ```kotlin
+  enum class CognitivePhase {
+      PERCEIVE,
+      RECALL,
+      OBSERVE,
+      PLAN,
+      EXECUTE,
+      LEARN,
+  }
+  ```
+
+  Previously the enum carried only `PERCEIVE / PLAN / EXECUTE / LEARN`,
+  silently dropping `RECALL` and `OBSERVE`. The acronym is now load-bearing:
+  `enumValues<CognitivePhase>().toList()` yields the cycle in order.
+
+  **Migration for external consumers:**
+  - Any `when (phase: CognitivePhase)` site without an `else` branch will
+    fail to compile with an exhaustiveness error. Add explicit branches
+    for `RECALL` and `OBSERVE`.
+  - Code that iterated `CognitivePhase.entries` will now see six phases
+    instead of four. Test matrices that assumed four-phase coverage will
+    automatically extend; tests that hardcoded a four-element list need
+    updating.
+  - Declarative spark `.spark.md` frontmatter that previously enumerated
+    `"phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"]` continues to
+    parse, but the spark will not apply during `RECALL` or `OBSERVE`. If
+    full coverage is intended, update the list to all six phases.
+  - Serialized values are unchanged: existing `"PERCEIVE"` / `"PLAN"` /
+    `"EXECUTE"` / `"LEARN"` strings still deserialize. AMPERE does not
+    persist `CognitivePhase` across runs today, so no data migration is
+    required.
+
+- **CLI `AmperePhosphorBridge` removes the `LEARN → EVALUATE` paveover.**
+  The bridge now uses `PhosphorPhase.RECALL` for AMPERE's `RECALL`,
+  reuses the `PERCEIVE` height-pulse for `OBSERVE` (until Phosphor adds
+  an `OBSERVE` ramp of its own), and continues to map `LEARN` to
+  Phosphor's `EVALUATE` only as an interop bridge until Phosphor's enum
+  is renamed in a sibling ticket. The `LEARN → EVALUATE` mapping is now
+  documented as a known interop gap rather than a silent rename.
+
+### Added
+
+- `PhaseSpark.Recall` and `PhaseSpark.Observe` built-in sparks with
+  default `promptContribution` strings tuned for memory-recall and
+  state-monitoring behavior, respectively. `PhaseSpark.forPhase` covers
+  all six members.
+
+### Notes
+
+- Phosphor's own `CognitivePhase` enum (in
+  `link.socket.phosphor.signal.CognitivePhase`) still uses
+  `PERCEIVE / RECALL / PLAN / EXECUTE / EVALUATE / LOOP / NONE` and is
+  out of scope for this change. A sibling Phosphor ticket should add
+  `OBSERVE` and rename `EVALUATE → LEARN` to bring Phosphor onto the
+  canonical PROPEL acronym.
+
+## [0.6.0] — 2026-05
+
+Released; see `git log v0.6.0` for the commit history.

README.md

@@ -165,22 +165,22 @@ This allows you to steer the agent toward an informed decision in real-time, rat
 During each timestep of the environment simulation, each agent executes its own independent cognitive cycle:
 
 ```
-1. Perceive  ──▶  2. Recall  ──▶  3. Optimize
+1. Perceive  ──▶  2. Recall  ──▶  3. Observe
 
        ▲                               │
        │                               ▼
 
-    6. Loop  ◀──  5. Execute  ◀──  4. Plan
+    6. Learn  ◀──  5. Execute  ◀──  4. Plan
 ```
 
 | # | Phase          | Operation                           | Emitted Events                         |
 |---|----------------|-------------------------------------|----------------------------------------|
 | 1 | **(P)erceive** | Ingest signals from the environment | `SignalReceived`, `PerceptionFormed`   |
 | 2 | **(R)ecall**   | Query relevant memory and context   | `MemoryQueried`, `ContextAssembled`    |
-| 3 | **(O)ptimize** | Prioritize competing objectives     | `ObjectivesRanked`, `ConfidenceScored` |
+| 3 | **(O)bserve**  | Read current state and detect drift | `StateObserved`, `DriftDetected`       |
 | 4 | **(P)lan**     | Select and structure actions        | `PlanCreated`, `TasksDecomposed`       |
 | 5 | **(E)xecute**  | Carry out the plan                  | `ActionTaken`, `ResultObserved`        |
-| 6 | **(L)oop**     | Evaluate results, re-enter cycle    | `OutcomeEvaluated`, `CycleRestarted`   |
+| 6 | **(L)earn**    | Extract knowledge, re-enter cycle   | `OutcomeEvaluated`, `KnowledgeStored`  |
 
 Every phase transition is emitted as an event, ensuring every action inside an agent can be audited and traced.
 

STYLE.md

@@ -71,7 +71,7 @@ Ampere's naming fuses biological cognition with electrical systems. Neural signa
 |------|----------|-------------------|
 | **Spark** | Context modifier shaping cognitive specialization | Action potential triggering neural differentiation |
 | **Arc** | Defined orchestration pathway | Electrical arc -- current flowing along a defined path |
-| **PROPEL Loop** | Cognitive cycle (Perceive, Recall, Optimize, Plan, Execute, Loop) | Neural firing cycle -- stimulus, integration, response, feedback |
+| **PROPEL Loop** | Cognitive cycle (Perceive, Recall, Observe, Plan, Execute, Learn) | Neural firing cycle -- stimulus, integration, response, feedback |
 | **EventSerializerBus** | Central nervous system carrying signals | Axon bundle -- impulses traveling between brain regions |
 | **Memory Cell** | Persistent knowledge with provenance | Biological memory encoded in synaptic weights |
 | **Escalation** | Uncertainty surfacing to a human | Pain signal -- requesting external intervention |

ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/render/AmperePhosphorBridge.kt

@@ -45,12 +45,19 @@ class AmperePhosphorBridge(
 
     private fun effectForPhase(phase: AmperePhase?): EmitterEffect = when (phase) {
         AmperePhase.PERCEIVE -> EmitterEffect.HeightPulse()
+        AmperePhase.RECALL -> EmitterEffect.ColorWash(
+            colorRamp = CognitiveColorRamp.forPhase(PhosphorPhase.RECALL)
+        )
+        // OBSERVE is sensing/state-monitoring — share the PERCEIVE visual until Phosphor adds OBSERVE.
+        AmperePhase.OBSERVE -> EmitterEffect.HeightPulse()
         AmperePhase.PLAN -> EmitterEffect.ColorWash(
             colorRamp = CognitiveColorRamp.forPhase(PhosphorPhase.PLAN)
         )
         AmperePhase.EXECUTE -> EmitterEffect.SparkBurst(
             palette = AsciiLuminancePalette.EXECUTE
         )
+        // Phosphor's enum still uses EVALUATE for the reflection phase that AMPERE calls LEARN.
+        // Follow-up: file a Phosphor ticket to rename PhosphorPhase.EVALUATE -> LEARN.
         AmperePhase.LEARN -> EmitterEffect.ColorWash(
             colorRamp = CognitiveColorRamp.forPhase(PhosphorPhase.EVALUATE)
         )

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/cli/render/AmperePhosphorBridgeTest.kt

@@ -47,6 +47,30 @@ class AmperePhosphorBridgeTest {
         )
     }
 
+    @Test
+    fun `each PROPEL phase produces an emitter without crashing`() {
+        // The phase enum became six-member in AMPR-172. Walking the enum verifies
+        // that no `when (phase)` site in the bridge falls through silently and that
+        // every phase yields exactly one emitter instance per call.
+        CognitivePhase.entries.forEach { phase ->
+            val emitterManager = EmitterManager()
+            val bridge = AmperePhosphorBridge(emitterManager)
+            val telemetry = ProviderCallTelemetrySummary(
+                eventId = "evt-$phase",
+                agentId = "agent-$phase",
+                cognitivePhase = phase,
+                latencyMs = 100,
+                estimatedCost = null,
+                totalTokens = null,
+                success = true,
+            )
+
+            bridge.onProviderCallCompleted(telemetry, Vector3.ZERO)
+
+            assertEquals(1, emitterManager.activeCount, "phase=$phase should emit once")
+        }
+    }
+
     @Test
     fun `provider telemetry without cost still emits latency metadata`() {
         val emitterManager = EmitterManager()

ampere-core/src/commonMain/composeResources/files/sparks/code-agent.spark.md

@@ -4,7 +4,7 @@
   "id": "code-agent",
   "name": "Code Agent",
   "whenToUse": "tasks that write, read, modify, or commit code in a workspace, including code generation, refactoring, file edits, and surrounding git operations (branching, committing, pushing, opening PRs)",
-  "phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"],
+  "phases": ["PERCEIVE", "RECALL", "OBSERVE", "PLAN", "EXECUTE", "LEARN"],
   "tags": ["code", "implementation"],
   "agentRole": "Code Writer"
 }

ampere-core/src/commonMain/composeResources/files/sparks/product-agent.spark.md

@@ -4,7 +4,7 @@
   "id": "product-agent",
   "name": "Product Agent",
   "whenToUse": "tasks that break features into actionable backlog items, triage workloads, prioritise tickets, surface blocked work, and learn from past decomposition outcomes",
-  "phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"],
+  "phases": ["PERCEIVE", "RECALL", "OBSERVE", "PLAN", "EXECUTE", "LEARN"],
   "tags": ["product", "planning", "backlog", "decomposition"],
   "agentRole": "Product Manager"
 }

ampere-core/src/commonMain/composeResources/files/sparks/project-agent.spark.md

@@ -4,7 +4,7 @@
   "id": "project-agent",
   "name": "Project Agent",
   "whenToUse": "tasks that decompose a goal into a structured work breakdown, create or batch-update issues in an external tracker, assign tasks to agents, monitor epic progress, and escalate decisions that exceed an agent's authority",
-  "phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"],
+  "phases": ["PERCEIVE", "RECALL", "OBSERVE", "PLAN", "EXECUTE", "LEARN"],
   "tags": ["project", "coordination", "decomposition", "escalation"],
   "agentRole": "Project Manager"
 }

ampere-core/src/commonMain/composeResources/files/sparks/project-ampere.spark.md

@@ -20,7 +20,7 @@ AMPERE enables the creation of collaborative AI agent teams that can:
 - Coordinate through meetings and tickets
 
 ## Key Components
-- **Agents**: Autonomous entities with cognitive cycles (PERCEIVE → PLAN → EXECUTE → LEARN)
+- **Agents**: Autonomous entities with cognitive cycles (PERCEIVE → RECALL → OBSERVE → PLAN → EXECUTE → LEARN)
 - **Events**: Typed messages for agent communication (MessagePosted, TicketAssigned, etc.)
 - **Sparks**: Cognitive differentiation layers that specialize agent behavior
 - **Memory**: Knowledge persistence and recall for experiential learning