docs: align lifecycle docs with primitive chain audit

README.md

@@ -89,27 +89,17 @@ Then type `/quickstart` in your agent chat.
 
 ## How It Works
 
-AgentOps is built around five commands. They are not just prompts. They create tracked state, validation artifacts, and reusable knowledge.
+AgentOps is built around a phased lifecycle, not a bag of prompts. The current runtime shape is:
 
-| Step | Command | What Happens | Calls Internally |
+| Phase | Primary skills | What gets locked in |
-|------|---------|--------------|------------------|
+|------|----------------|---------------------|
-| 1 | `/research` | Explore the codebase and load prior repo knowledge | — |
+| Discovery | `/brainstorm` -> `/research` -> `/plan` -> `/pre-mortem` | repo context, scoped work, known risks, execution packet |
-| 2 | `/plan` | Break work into tracked issues with dependency waves | `/beads` |
+| Implementation | `/crank` -> `/swarm` -> `/implement` | closed issues, validated wave outputs, ratchet checkpoints |
-| 3 | `/pre-mortem` | Challenge the plan before code exists | `/council` |
+| Validation + learning | `/validation` -> `/vibe` -> `/post-mortem` -> `/retro` -> `/forge` | findings, learnings, next work, stronger prevention artifacts |
-| 4 | `/crank` | Execute unblocked work in waves with validation and commits | `/implement`, `/vibe` |
-| 5 | `/post-mortem` | Validate what shipped and extract reusable learnings | `/vibe`, `/retro` |
 
-`/rpi` chains all five. `/evolve` loops `/rpi` overnight with fitness-gated regression checks.
+`/rpi` orchestrates those three phases end to end. `/evolve` keeps running `/rpi` against `GOALS.md` so the worst fitness gap gets addressed next.
 
-### What those commands actually add
+Within each phase, agents iterate quickly in bounded loops. Across phases, the repo acts as durable memory through `.agents/`, finding registries, contracts, handoffs, and commits. That is the operational difference: the output is not just code. It is code + state + memory + gates.
-
-- `/research` keeps the agent from starting cold
-- `/plan` turns work into a graph instead of a chat todo list
-- `/pre-mortem` catches failure modes before implementation
-- `/crank` makes multi-step work executable in dependency order
-- `/post-mortem` turns one finished task into better future context
-
-This is why AgentOps feels different in practice: the output is not just code. It is code + state + memory + gates.
 
 | Pattern | Chain | When |
 |---------|-------|------|
@@ -122,13 +112,15 @@ This is why AgentOps feels different in practice: the output is not just code. I
 | **Knowledge query** | `/knowledge` → `/research` (if gaps) | Understanding before building |
 | **Standalone review** | `/council validate <target>` | Ad-hoc multi-judge review |
 
-### The three systems underneath it
+### Primitive chains underneath it
 
-- **Execution system**: `/plan`, beads, worktrees, `/crank`, `/evolve`
+- **Mission and fitness**: `GOALS.md`, `ao goals`, `/evolve`
-- **Validation system**: `/pre-mortem`, `/vibe`, `/council`
+- **Discovery chain**: `/brainstorm` -> `ao search` / `ao lookup` -> `/research` -> `/plan` -> `/pre-mortem`
-- **Memory system**: `.agents/`, `ao lookup`, `ao forge`, `/retro`, `/knowledge`
+- **Execution chain**: `/crank` -> `/swarm` -> `/implement` -> `/vibe` -> ratchet checkpoints
+- **Compiled prevention chain**: findings registry -> planning rules / pre-mortem checks / constraints -> later planning and validation
+- **Continuity chain**: session hooks + phased manifests + `/handoff` + `/recover`
 
-That is the real architecture. Not just a skill pack. A local operating layer around the agent.
+That is the real architecture: a local operating layer around the agent, not just a prompt pack. See [Primitive Chains](docs/architecture/primitive-chains.md) for the audited map.
 
 ### Why the memory matters
 

cli/cmd/ao/demo.go

@@ -177,7 +177,7 @@ func interactiveDemo() error {
 
 This demo will:
   ✓ Create a sample .agents/ structure
-  ✓ Show the RPI workflow (Research → Plan → Implement)
+  ✓ Show the phased RPI workflow (Discovery → Implementation → Validation)
   ✓ Demonstrate the knowledge flywheel
   ✓ Explain quality gates
 

cli/cmd/ao/ratchet.go

@@ -9,7 +9,7 @@ import (
 var ratchetCmd = &cobra.Command{
 	Use:   "ratchet",
 	Short: "Brownian Ratchet workflow tracking",
-	Long: `Track progress through the RPI (Research-Plan-Implement) workflow.
+	Long: `Track progress through the phased RPI workflow.
 
 The Brownian Ratchet ensures progress can't be lost:
   Chaos × Filter → Ratchet = Progress

cli/cmd/ao/rpi.go

@@ -7,13 +7,14 @@ import (
 var rpiCmd = &cobra.Command{
 	Use:   "rpi",
 	Short: "RPI lifecycle automation",
-	Long: `Commands for automating the RPI (Research-Plan-Implement) lifecycle.
+	Long: `Commands for automating the RPI lifecycle.
 
 Commands:
   loop       Run continuous RPI cycles from next-work queue
 
 The RPI loop reads .agents/rpi/next-work.jsonl for harvested work items
-and spawns fresh Claude sessions for each cycle (Ralph Wiggum pattern).`,
+and spawns fresh Claude sessions for each cycle using the phased
+Discovery -> Implementation -> Validation workflow (Ralph Wiggum pattern).`,
 }
 
 func init() {

cli/docs/COMMANDS.md

@@ -876,7 +876,7 @@ ao handoff [summary] [flags]
 
 ### `ao ratchet`
 
-Track progress through the RPI (Research-Plan-Implement) workflow.
+Track progress through the phased RPI workflow.
 
 ```
 ao ratchet [command]
@@ -1034,7 +1034,7 @@ ao ratchet migrate-artifacts [path] [flags]
 
 ### `ao rpi`
 
-Commands for automating the RPI (Research-Plan-Implement) lifecycle.
+Commands for automating the RPI lifecycle.
 
 ```
 ao rpi [command]

docs/ARCHITECTURE.md

@@ -183,7 +183,7 @@ The learning model. Automated extraction → quality gates → tiered storage
 ### The RPI Workflow
 
 ```
-Research → Plan → Implement → Validate
+Discovery → Implementation → Validation
     ↑                            │
     └──── Knowledge Flywheel ────┘
 ```
@@ -192,10 +192,9 @@ Each phase is a context boundary. The output of one phase is compressed and scop
 
 | Phase | Skills | Output |
 |-------|--------|--------|
-| **Research** | `/research`, `/knowledge` | `.agents/research/` |
+| **Discovery** | `/brainstorm`, `/research`, `/plan`, `/pre-mortem` | research artifacts, execution packet, scoped risks |
-| **Plan** | `/pre-mortem`, `/plan` | Beads issues |
+| **Implementation** | `/crank`, `/swarm`, `/implement` | code, tests, ratchet checkpoints |
-| **Implement** | `/implement`, `/crank` | Code, tests |
+| **Validation** | `/validation`, `/vibe`, `/post-mortem` (primary: council + extraction + backlog + activation + retirement), `/retro` (quick-capture) | learnings, findings, next-work queue |
-| **Validate** | `/vibe`, `/post-mortem` (primary: council + extraction + backlog + activation + retirement), `/retro` (quick-capture) | `.agents/learnings/`, `.agents/patterns/` |
 
 Every `/post-mortem` feeds back into the next `/rpi` cycle:
 
@@ -398,17 +397,17 @@ For full workflow orchestration, skills integrate with the ao CLI:
 
 | Skill | ao Command |
 |-------|------------|
-| `/research` | `ao forge search` |
+| `/research` | `ao lookup`, `ao search`, `ao rpi phased` |
-| `/retro` | `ao forge index` |
+| `/retro` | `ao forge markdown`, `ao session close` |
-| `/post-mortem` | `ao ratchet record` |
+| `/post-mortem` | `ao forge`, `ao flywheel close-loop`, `ao constraint activate` |
-| `/implement` | `ao ratchet claim/record` |
+| `/implement` | `ao context assemble`, `ao lookup`, `ao ratchet record` |
-| `/crank` | `ao ratchet verify` |
+| `/crank` | `ao rpi phased`, `ao ratchet`, `ao flywheel status` |
 
 ---
 
 ## Session Hooks
 
-Three hooks form the knowledge flywheel's mechanical backbone:
+The runtime manifest currently declares seven hook event sections. Three lifecycle anchors form the compounding backbone, while the others enforce guardrails at prompt, tool, and task boundaries.
 
 ### SessionStart — sessions compound instead of reset
 

docs/GLOSSARY.md

@@ -116,12 +116,12 @@ The first phase of the RPI lifecycle. Deep codebase exploration using Explore ag
 A skill (`/retro`) that extracts learnings from completed work — decisions made, patterns discovered, and failures encountered — and feeds them into the knowledge flywheel. Learnings are scored for specificity, actionability, and novelty. [Full documentation](../skills/retro/SKILL.md)
 
 ### RPI (Research-Plan-Implement)
-The full lifecycle workflow: Research the codebase, Plan by decomposing the goal into issues, then Implement via pre-mortem, crank, vibe, and post-mortem. The `/rpi` skill runs all phases end to end; `ao rpi phased` runs each phase in its own fresh context window. [Full documentation](ARCHITECTURE.md#the-rpi-workflow)
+The historical name for AgentOps' full lifecycle workflow. In current runtime terms, `/rpi` orchestrates **Discovery -> Implementation -> Validation** while `ao rpi phased` enforces fresh context windows between those phases. The older acronym persists in product language and command names, but validation and loop closure are now first-class parts of the executable lifecycle. [Full documentation](ARCHITECTURE.md#the-rpi-workflow)
 
 ## S
 
 ### Skill
-A self-contained capability defined by a `SKILL.md` file with YAML frontmatter. Skills are the primary unit of functionality in AgentOps — each one has triggers, instructions, and optional reference docs loaded just-in-time. AgentOps ships 51 skills (41 user-facing, 10 internal). [Full documentation](SKILLS.md)
+A self-contained capability defined by a `SKILL.md` file with YAML frontmatter. Skills are the primary unit of functionality in AgentOps — each one has triggers, instructions, and optional reference docs loaded just-in-time. AgentOps currently ships 54 source skills (45 user-facing, 9 internal). [Full documentation](SKILLS.md)
 
 ### Swarm
 A skill (`/swarm`) that spawns parallel worker agents with fresh context. Each wave gets a new team; the lead validates and commits. Workers never commit directly. [Full documentation](../skills/swarm/SKILL.md)

docs/INDEX.md

@@ -17,6 +17,7 @@
 - [How It Works](how-it-works.md) — Brownian Ratchet, Ralph Wiggum Pattern, agent backends, hooks, context windowing
 - [Architecture](ARCHITECTURE.md) — System design and component overview
 - [Architecture Folder Index](architecture/README.md) — Architecture subdocs overview
+- [Primitive Chains](architecture/primitive-chains.md) — Audited primitive set, lifecycle chains, and terminology drift ledger
 - [AO-Olympus Ownership Matrix](architecture/ao-olympus-ownership-matrix.md) — Responsibility split for skills, runtime, and bridge contracts
 - [PDC Framework](architecture/pdc-framework.md) — Prevent, Detect, Correct quality control approach
 - [FAAFO Alignment](architecture/faafo-alignment.md) — FAAFO promise framework for vibe coding value

docs/SKILLS.md

@@ -113,7 +113,8 @@ Full RPI lifecycle orchestrator. Discovery → Implementation → Validation in
 
 ```bash
 /rpi "Add user authentication"
-/rpi --auto --max-cycles=1    # fully autonomous single cycle
+/rpi --fast-path "fix typo in README"
+/rpi --from=implementation ag-1234
 ```
 
 **Phases:** Discovery (research + plan + pre-mortem) → Implementation (crank) → Validation (vibe + post-mortem)
@@ -126,7 +127,7 @@ Autonomous multi-issue execution. Runs until epic is CLOSED.
 /crank <epic-id>
 ```
 
-**Modes:** Crew (sequential) or Mayor (parallel via polecats)
+**Execution model:** Wave-based orchestration via `/swarm` with runtime-native workers.
 
 ### /vibe
 
@@ -473,8 +474,8 @@ Skills integrate with the ao CLI for orchestration:
 
 | Skill | ao CLI Command |
 |-------|----------------|
-| `/research` | `ao forge search` |
+| `/research` | `ao lookup`, `ao search`, `ao rpi phased` |
-| `/retro` | `ao forge index` |
+| `/retro` | `ao forge markdown`, `ao session close` |
-| `/post-mortem` | `ao ratchet record` |
+| `/post-mortem` | `ao forge`, `ao flywheel close-loop`, `ao constraint activate` |
-| `/implement` | `ao ratchet claim/record` |
+| `/implement` | `ao context assemble`, `ao lookup`, `ao ratchet record` |
-| `/crank` | `ao ratchet verify` |
+| `/crank` | `ao rpi phased`, `ao ratchet`, `ao flywheel status` |

docs/agentops-brief.md

@@ -6,27 +6,27 @@
 
 ## What It Is
 
-A standard operating procedure system for AI coding tools.
+A repo-native operating layer for stateless coding agents.
 
-AgentOps gives every AI session a structured briefing before work begins, enforces a consistent workflow from research through validation, requires independent review before anything is committed, and writes a debrief at the end that feeds the next session's briefing.
+AgentOps gives every session a mission, a phased workflow, quality gates, and a durable memory substrate on disk. Work begins with repo context instead of a blank prompt, passes through explicit plan and code judgment, and ends by feeding findings, learnings, and next work back into the environment.
 
-The institutional knowledge stops walking out the door.
+The institutional knowledge stops walking out the door because the repo keeps it.
 
 ---
 
-## Four Components
+## Four Load-Bearing Layers
 
-### Skills — The SOPs
+### Skills — The Orchestration Layer
-Structured, numbered checklists the AI follows for every task type: exploring a codebase, breaking work into tracked tasks, reviewing code before it ships, running a postmortem. ~40 workflows covering the full cycle. The AI does not improvise — it follows the procedure.
+Structured workflows for discovery, execution, validation, recovery, and release. Skills route work into the right primitive chain instead of leaving the agent to improvise the lifecycle.
 
 ### Hooks — The Enforcement Layer
-Shell scripts that fire automatically at lifecycle events: session start, session end, after every tool call, before every commit. They inject the briefing, harvest the debrief, and enforce quality gates that cannot be bypassed by an inattentive AI.
+Runtime hooks fire at session start/end, prompt submission, tool boundaries, stop, and task completion. They keep guidance, validation, and loop closure active even when the operator does not remember every step.
 
-### `ao` CLI — The Memory System
+### `ao` CLI — The Retrieval and Ratchet Layer
-A command-line tool that manages knowledge across sessions. At session end it extracts learnings (one to three sentences each). At session start it injects the most relevant, freshest ones into the briefing. Learnings that keep proving useful are promoted; stale ones decay automatically. Sessions compound.
+The CLI handles retrieval, ratchet checkpoints, flywheel closure, goals, curation, and phased execution support. It is the mechanical bridge between plain files, workflows, and enforceable progress.
 
-### `.agents/` — The Knowledge Base
+### `.agents/` — The Stigmergic Memory Layer
-Plain files on disk. Learnings, patterns, research outputs, review verdicts, release notes. Each learning carries a utility score, a confidence level, a maturity rating, and a decay timestamp. Nothing proprietary — audit every file with a text editor.
+Plain files on disk: research, brainstorms, findings, learnings, handoffs, ratchet traces, next-work queues. No single session has to remember the plan. The environment carries it forward.
 
 ---
 
@@ -34,18 +34,18 @@ Plain files on disk. Learnings, patterns, research outputs, review verdicts, rel
 
 ```
 Session starts
-  → Prior knowledge injected into briefing automatically
+  -> Startup hooks retrieve lightweight context and continuity hints
-  → AI follows structured SOP for the task
+  -> Discovery scopes the work and pressure-tests the plan
 
-AI works
+Implementation runs
-  → Automated gates enforce quality on every tool call
+  -> Fresh workers execute in bounded waves
-  → Independent reviewers validate before anything ships
+  -> Validation gates challenge the output before closure
 
 Session ends
-  → Learnings extracted and scored
+  -> Learnings, findings, and next work are harvested
-  → Knowledge base updated
+  -> Flywheel closure updates what the next session will see
 
-Next session starts smarter than this one did.
+Next session starts with a richer environment than this one did.
 ```
 
 ---
@@ -70,15 +70,22 @@ With AgentOps:     [2 hrs] → [10 min] → [2 min] → instant  =  ~2.2 hours t
                     learn     recall     refine    mastered
 ```
 
-By session 100, the AI already knows every bug fixed in this codebase, every architectural decision and the reasoning behind it, and every approach that failed.
+By session 100, the repo already carries prior failures, design choices, planning rules, and validated patterns that new sessions can load before they repeat old mistakes.
 
 ---
 
-## DevOps Parallel
+## Development Model
 
-DevOps applied one insight to infrastructure: reliability comes from feedback loops, not from better operators. Postmortems, runbooks, shift-left testing, continuous validation — each revolution of the loop made the next incident cheaper to handle.
+The most accurate current framing is:
 
-AgentOps applies the same insight one layer up. Not better AI models. Better feedback loops around the models you already have.
+```text
+12-Factor AgentOps -> operating conditions
+Stigmergic Spiral -> macro lifecycle for stateless builders
+Brownian Ratchet -> chaos filtered into locked progress
+Knowledge Flywheel -> durable learning and loop closure
+```
+
+The claim is not "better models." The claim is "better repo mechanics around the models you already have."
 
 ---
 
@@ -94,38 +101,22 @@ AgentOps applies the same insight one layer up. Not better AI models. Better fee
 ┌──────────────────────────────────────────────────────────────────┐
 │                    AgentOps at a Glance                          │
 ├───────────────────┬──────────────────────┬───────────────────────┤
-│    49  Skills     │  121 CLI Commands    │    14 Hooks           │
+│    54 Skills      │   52 CLI Commands    │   7 Hook Events       │
-│  (workflows)      │  (ao binary)         │  (auto-enforcement)   │
+│  (45 + 9 split)   │  (audited surfaces)  │  (runtime manifest)   │
 └───────────────────┴──────────────────────┴───────────────────────┘
 ```
 
-### The Pipeline — Skills Calling Skills
+### The Pipeline — Primitive Chains in Motion
 
-`/rpi` chains the full workflow. Each node is a skill. Arrows show calls.
+`/rpi` orchestrates the macro lifecycle. Each phase expands into its own skill chain.
 
 ```
-                         ┌─────────────┐
+GOALS.md
-                         │   /evolve   │  ← loops /rpi overnight
+  -> /evolve
-                         └──────┬──────┘    fitness-gated
+      -> /rpi
-                                │
+          -> Discovery: /brainstorm -> /research -> /plan -> /pre-mortem
-                                ▼
+          -> Implementation: /crank -> /swarm -> /implement
-┌───────────────────────────────────────────────────────────────────┐
+          -> Validation: /validation -> /vibe -> /post-mortem -> /retro -> /forge
-│                             /rpi                                  │
-│                    (full pipeline orchestrator)                   │
-└──┬──────────┬───────────┬─────────────┬──────────┬───────────────┘
-   │          │           │             │          │
-   ▼          ▼           ▼             ▼          ▼
-/research   /plan    /pre-mortem     /crank    /post-mortem
-                          │             │          │
-                     calls /council     │          ├── calls /council
-                                        │          └── calls /retro
-                                        │
-                               spawns N parallel
-                                        │
-                                   /implement  × N
-                                        │
-                                     /vibe  ── calls /council
-                                            ── calls /complexity
 ```
 
 ### Judgment Layer — Everything Flows Through Council
@@ -144,17 +135,17 @@ AgentOps applies the same insight one layer up. Not better AI models. Better fee
     before building)         before shipping)   learnings)
 ```
 
-### Knowledge Handoff — Skills Calling the CLI
+### Knowledge Handoff — Skills and CLI Working Together
 
 ```
-   SKILL                   ao CLI COMMAND              RESULT
+   SURFACE                 CLI / FILE PRIMITIVE          RESULT
-   ─────                   ──────────────              ──────
+   ───────                 ────────────────────          ──────
-/research          →    ao lookup                  Prior knowledge loaded
+/research          ->    ao lookup + ao search      Prior repo context loaded
-/retro             →    ao forge transcript        Learnings extracted
+/plan              ->    findings registry          Reusable risks loaded pre-decomposition
-/retro             →    ao pool promote            Learnings validated
+/post-mortem       ->    ao forge + ao session      Learnings harvested and session closed
-/evolve            →    ao goals measure           Fitness checked
+/vibe              ->    ao ratchet record          Validation checkpoint persisted
-/rpi               →    ao ratchet record          Progress checkpointed
+/evolve            ->    ao goals measure           Worst fitness gap selected
-/implement         →    ao ratchet check           Gate verified
+/recover           ->    handoff artifacts          Interrupted work resumed from disk
 ```
 
 ### Hooks — Automatic Enforcement
@@ -165,32 +156,24 @@ TRIGGER                   HOOK                        WHAT IT DOES
 Session starts         session-start.sh            Inject prior knowledge
 Session ends           session-end-maintenance.sh  Harvest learnings
 Agent stops            ao-flywheel-close.sh        Close learning loop
-Every tool call        go-complexity-precommit.sh  Block over-complex code
+Prompt submit         prompt-nudge.sh             Remind missing intent / ratchet state
-Pre-commit             skill-lint-gate.sh          Reject malformed SOPs
+Pre tool use          pre-mortem-gate.sh          Require review before risky work
-Pre-commit             dangerous-git-guard.sh      Block force-pushes to main
+Post tool use         go-complexity-precommit.sh  Block over-complex edits
-Pre-commit             pre-mortem-gate.sh          Require review for large changes
+Task complete         task-validation-gate.sh     Execute compiled validation constraints
-Worker stop            subagent-stop.sh            Clean up parallel agent state
 ```
 
 ### CLI Command Groups
 
 ```
-KNOWLEDGE FLYWHEEL          VALIDATION GATES         SESSION / LIFECYCLE
+RETRIEVAL / CURATION        VALIDATION / RATCHETS    WORKFLOW / FITNESS
-──────────────────          ────────────────         ───────────────────
+────────────────────        ─────────────────────    ──────────────────
-ao forge                    ao gate pending          ao session close
+ao lookup                   ao ratchet status        ao rpi phased
-ao pool ingest              ao gate approve          ao rpi status
+ao search                   ao ratchet record        ao rpi status
-ao pool promote             ao gate reject           ao hooks list
+ao forge                    ao ratchet check         ao goals measure
-ao lookup                   ao ratchet status        ao config
+ao curate                   ao constraint activate   ao goals steer
-ao lookup                   ao ratchet record
+ao maturity                 ao constraint review     ao flywheel status
-ao search                   ao ratchet check         METRICS / HEALTH
+ao dedup                    ao session close         ao hooks list
-ao dedup                                             ────────────────
+ao contradict               ao temper validate       ao status
-ao curate                   GOALS / FITNESS          ao metrics health
+ao notebook                                          ao doctor
-                            ───────────────          ao metrics flywheel
-MEMORY TOOLS                ao goals measure         ao metrics report
-────────────                ao goals steer           ao flywheel status
-ao mind                     ao goals add             ao maturity
-ao notebook                 ao goals prune           ao doctor
-ao memory                   ao goals history
-ao trace                    ao goals drift
 ao extract
 ```

docs/architecture/README.md

@@ -1,9 +1,9 @@
 # Architecture Docs
 
 - [AO-Olympus Ownership Matrix](./ao-olympus-ownership-matrix.md)
+- [Primitive Chains](./primitive-chains.md)
 - [PDC Framework](./pdc-framework.md)
 - [FAAFO Alignment](./faafo-alignment.md)
 - [Failure Patterns](./failure-patterns.md)
 
 Back: [Docs Index](../INDEX.md)
-

docs/architecture/primitive-chains.md

@@ -0,0 +1,157 @@
+# Primitive Chains
+
+> AgentOps is not a flat skill catalog. It is a set of compiled primitive chains that turn disposable agent sessions into a ratcheting development system.
+
+## Why This Doc Exists
+
+The product story has drifted between "Research-Plan-Implement," "five commands," "shift-left validation," and "knowledge flywheel." All of those describe part of the system, but the executable shape is now clearer:
+
+- `12-Factor AgentOps` provides the operating conditions
+- the `Stigmergic Spiral` describes the macro lifecycle for stateless builders
+- the `Brownian Ratchet` explains how noisy parallel work still becomes forward progress
+- the skills, hooks, `ao` commands, and `.agents/` artifacts are the concrete primitives that implement that model
+
+This document maps the live primitives to the chains they form.
+
+## Primitive Matrix
+
+| Layer | Primitive | Primary Surfaces | What It Contributes |
+|------|-----------|------------------|---------------------|
+| Mission / fitness | explicit goals | `GOALS.md`, `GOALS.yaml`, `ao goals`, `/evolve` | Mission-type orders, measurable fit, next-gap selection |
+| Discovery | understand before acting | `/brainstorm`, `/research`, `ao search`, `ao lookup`, `.agents/research/` | Observe, orient, and scope using repo-native context |
+| Risk / prevention | confront what can fail | `/plan`, `/pre-mortem`, findings registry, planning rules, pre-mortem checks | Risk-first scoping and reusable failure prevention |
+| Execution | fresh-context implementation | `/crank`, `/swarm`, `/implement`, worktrees, beads waves | Parallel OODA loops with bounded scope and retries |
+| Validation | judgment before closure | `/vibe`, `/validation`, `/council`, task-validation gate | Detect defects and regressions before accepting completion |
+| Learning | extract and reinforce | `/post-mortem`, `/retro`, `/forge`, `ao flywheel`, `ao maturity` | Convert completed work into reusable knowledge |
+| Ratchet / provenance | lock progress | `ao ratchet`, commits, `.agents/ao/chain.jsonl` | Ensure accepted work becomes the new baseline |
+| Continuity | survive context loss | `/handoff`, `/recover`, phased manifests, session hooks, `.agents/rpi/` | Disk-backed continuity when sessions compact or die |
+
+## Chain 1: Macro Lifecycle
+
+This is the executable replacement for the older "five commands" story.
+
+```text
+Discovery -> Implementation -> Validation
+    |             |                 |
+    v             v                 v
+scope/risk    validated build   learn + next work
+```
+
+| Phase | Primary Skills | Durable Outputs |
+|------|----------------|-----------------|
+| Discovery | `/brainstorm` -> `/research` -> `/plan` -> `/pre-mortem` | research artifacts, beads graph, execution packet, known risks |
+| Implementation | `/crank` -> `/swarm` -> `/implement` | closed issues, code, tests, ratchet checkpoints |
+| Validation | `/validation` -> `/vibe` -> `/post-mortem` -> `/retro` -> `/forge` | findings, learnings, promoted constraints, next-work queue |
+
+`/rpi` is the orchestrator that routes across those phases. The historical acronym remains, but the current runtime shape is phased.
+
+## Chain 2: Discovery
+
+```text
+Mission -> brainstorm -> search / lookup -> research -> plan -> pre-mortem
+```
+
+What happens:
+
+1. `GOALS.md` or the user goal defines the mission, not the exact procedure.
+2. `/brainstorm` separates the problem from the implementation habit.
+3. `ao search` and `ao lookup` pull prior repo knowledge and nearby precedents.
+4. `/research` synthesizes the current state into `.agents/research/*.md`.
+5. `/plan` decomposes the work, loading prior findings and planning rules before it does.
+6. `/pre-mortem` pressure-tests the plan and can promote reusable findings back into prevention surfaces.
+
+This chain is the "scope + risk" half of the Stigmergic Spiral.
+
+## Chain 3: Implementation
+
+```text
+execution packet -> crank -> wave selection -> swarm -> implement -> verify -> ratchet
+```
+
+What happens:
+
+1. `/crank` reads the epic or execution packet.
+2. Ready work is selected in waves from beads or TaskList.
+3. `/swarm` spawns fresh workers using the runtime-native backend.
+4. `/implement` executes one issue with bounded context and local validation.
+5. The lead verifies the wave, records ratchet state, and retries `PARTIAL` or `BLOCKED` work.
+6. The loop stops only at `<promise>DONE</promise>`, `<promise>BLOCKED</promise>`, or hard limits.
+
+This chain is the micro-tempo engine. The worker set is disposable. The accepted output is not.
+
+## Chain 4: Validation and Learning
+
+```text
+vibe -> post-mortem -> retro -> forge -> flywheel close-loop
+```
+
+What happens:
+
+1. `/vibe` validates the produced system against code quality, architecture, security, and intent.
+2. `/post-mortem` captures what changed, what failed, and what should become reusable.
+3. `/retro` provides quick-capture learning when full wrap-up is unnecessary.
+4. `/forge` turns transcripts or markdown artifacts into structured knowledge.
+5. `ao flywheel close-loop` records session closure so the next run starts with better retrieval.
+
+This is where the repo becomes more capable than it was before the session started.
+
+## Chain 5: Compiled Prevention
+
+```text
+finding -> registry -> compiler outputs -> planning / validation / task-complete gates
+```
+
+| Step | Surface | Effect |
+|------|---------|--------|
+| Capture | `.agents/findings/registry.jsonl` | Normalized reusable findings ledger |
+| Compile | `.agents/pre-mortem-checks/`, `.agents/planning-rules/`, `.agents/constraints/index.json` | Findings become advisory or enforceable artifacts |
+| Reuse | `/plan`, `/pre-mortem`, `/vibe`, `task-validation-gate.sh` | Future work starts with prior failures already loaded |
+
+This is the contract ratchet: surprises are expected once, then compiled into the environment.
+
+## Chain 6: Continuity and Recovery
+
+```text
+session start -> phased handoff -> handoff / recover -> session end -> next session
+```
+
+| Continuity Surface | Role |
+|--------------------|------|
+| `hooks/session-start.sh` | Injects lightweight repo context and points at durable artifacts |
+| `ao rpi phased` + phase manifests | Keeps each phase context-bounded and disk-backed |
+| `/handoff` | Leaves a structured continuation packet for the next operator |
+| `/recover` | Rehydrates in-progress work after compaction or interruption |
+| `hooks/session-end-maintenance.sh` | Extracts and curates end-of-session knowledge |
+| `hooks/ao-flywheel-close.sh` | Closes the loop at stop time |
+
+This is the stigmergic memory layer. No agent has to remember yesterday if the environment was updated correctly.
+
+## Terminology Drift Ledger
+
+| Term | Historical Meaning | Current Executable Meaning |
+|------|--------------------|----------------------------|
+| `RPI` | Research -> Plan -> Implement | Historical product name for the full lifecycle; the runtime now executes `Discovery -> Implementation -> Validation` |
+| `five commands` | `/research`, `/plan`, `/pre-mortem`, `/crank`, `/post-mortem` | Useful legacy teaching aid, but incomplete because it omits `/brainstorm`, `/validation`, `/vibe`, `/retro`, `/forge`, and continuity surfaces |
+| `knowledge injection` | startup context loading | Now broader: `lookup`, `search`, notebooks, handoffs, findings, and phase manifests assemble context together |
+| `three hooks` | session start/end/stop | The runtime currently declares 7 hook event sections, with three lifecycle anchors plus prompt/tool/task guardrails |
+| `Research-Plan-Implement` | product slogan | Still appears in names and legacy docs, but phased execution and validation are first-class now |
+| `orchestrators never fork` | architectural rule of thumb | Desired direction, but some live skill contracts still declare `context.window: fork`; trust `SKILL.md` until the contracts are fully harmonized |
+
+## Audit Snapshot
+
+The current repo state behind this document:
+
+- `54` source skills in `skills/`
+- `45` user-facing and `9` internal skills
+- `52` CLI commands and `7` runtime hook event sections recorded in the current CLI/skills map
+- prevention is partly `ao`-mediated and partly file-native through the finding registry and compiled constraints
+
+For the current command-to-skill matrix, see [CLI ↔ Skills/Hooks Map](../cli-skills-map.md).
+
+## See Also
+
+- [How It Works](../how-it-works.md)
+- [Knowledge Flywheel](../knowledge-flywheel.md)
+- [Context Lifecycle Contract](../context-lifecycle.md)
+- [Brownian Ratchet](../brownian-ratchet.md)
+- [CLI ↔ Skills/Hooks Map](../cli-skills-map.md)

docs/brownian-ratchet.md

@@ -152,25 +152,23 @@ The loop continues until all work is reaped or escalated.
 
 ---
 
-## Applied to RPI Workflow
+## Applied to the Phased RPI Workflow
 
-The entire RPI (Research → Plan → Implement) workflow is a series of ratchets:
+The historical RPI name now runs as a phased lifecycle:
 
 ```
-RESEARCH ──┬──► SYNTHESIS ──┬──► PLAN ──┬──► IMPLEMENT ──┬──► VALIDATE
+DISCOVERY ──┬──► IMPLEMENTATION ──┬──► VALIDATION
-           │                │           │                │
+            │                     │
-           └── chaos        └── ratchet └── chaos        └── ratchet
+            └── chaos + filter    └── ratchet + learning
-               (explore)       (locked)    (polecats)       (merged)
 ```
 
 | Phase | Chaos | Filter | Ratchet |
 |-------|-------|--------|---------|
-| **Research** | Multiple exploration paths | Human synthesis decision | Artifact in `.agents/research/` |
+| **Discovery** | Multiple exploration paths and framing options | Research synthesis + pre-mortem review | Execution packet, scoped risks, and tracked issues |
-| **Plan** | Multiple plan attempts | Pre-mortem simulation | Epic locked with dependencies |
+| **Implementation** | Parallel fresh-context workers | Wave verification, tests, and `/vibe` | Accepted code plus ratchet checkpoints |
-| **Implement** | Parallel polecats | CI + tests + /vibe | Code merged to main |
+| **Validation** | Multi-aspect review and learning extraction | Council, findings registry, and flywheel closure | Knowledge stored, next work harvested, stronger prevention artifacts |
-| **Validate** | Multi-aspect checks | Quality gates | Knowledge stored |
 
-Each phase locks its output before the next phase begins. You can't un-research, un-plan, or un-merge.
+Each phase locks its output before the next phase begins. You cannot un-discover, un-verify, or un-learn without writing a new artifact that supersedes the old one.
 
 ---
 
@@ -186,7 +184,7 @@ Every skill has a role in the pattern:
 | `/crank` | Full FIRE loop | Autonomous execution until complete |
 | `/vibe` | THE filter | Quality gate that blocks bad code |
 | `/implement` | Micro-ratchet | Single issue: open → closed (atomic) |
-| `/formulate` | Captured pattern | Ratcheted solution for reuse |
+| `/swarm` | Parallel chaos engine | Fresh worker set per wave |
 | `/post-mortem` | Knowledge ratchet | Learnings locked, never go backward |
 
 ---

docs/how-it-works.md

@@ -23,6 +23,17 @@ Spawn parallel agents (chaos), validate with multi-model council (filter), merge
 
 See also: [Brownian Ratchet (deep dive)](brownian-ratchet.md)
 
+## The Stigmergic Spiral in Runtime Terms
+
+The repo now expresses the Stigmergic Spiral as executable mechanics:
+
+- **Spiral macro-cycle:** `Discovery -> Implementation -> Validation`
+- **OODA micro-cycles:** each wave repeatedly observes state, orients with repo artifacts, decides a bounded move, and acts
+- **Stigmergic memory:** `.agents/`, finding registries, contracts, handoffs, and commits carry state forward
+- **Degraded operation:** fresh workers, disk-backed recovery, and hook-enforced checkpoints assume context loss and tool drift are normal
+
+The important shift is where intelligence lives. Agent sessions are disposable. The environment compounds.
+
 ## Ralph Wiggum Pattern — Fresh Context Every Wave
 
 *Named after Ralph Wiggum's "I'm helping!" -- each worker starts fresh with no memory of previous workers, ensuring complete isolation between waves.*
@@ -40,14 +51,14 @@ Operational contract reference: `skills/shared/references/ralph-loop-contract.md
 
 ## Two-Tier Execution Model
 
-Skills follow a strict rule: **the orchestrator never forks; the workers it spawns always fork.**
+The target model is: **keep orchestration visible in the main session, and let spawned workers carry the isolated context.** Most current meta-skills follow that shape, but a few SKILL contracts still declare `context.window: fork` while the runtime behavior has shifted toward visible orchestration. When docs and contracts disagree, treat the live `SKILL.md` as authoritative.
 
 | Tier | Skills | Behavior |
 |------|--------|----------|
 | **NO-FORK** (orchestrators) | evolve, rpi, crank, vibe, post-mortem, pre-mortem | Stay in main session — operator sees progress and can intervene |
 | **FORK** (worker spawners) | council, codex-team | Fork into subagents — results merge back via filesystem |
 
-This was learned through production experience: orchestrators that forked (`context: fork` in SKILL.md) became invisible — the operator couldn't see cycle-by-cycle evolve progress, phase transitions in rpi, or wave reports from crank. The fix: remove `context: fork` from orchestrators, keep it only on worker spawners.
+This was learned through production experience: orchestration that disappears into a fork becomes hard to supervise. The long-term direction is to keep macro progress visible and isolate only the worker layer, but the repo still contains a small amount of contract drift that has not been fully normalized.
 
 `/swarm` is a special case — it's an orchestrator (no fork) that spawns runtime workers via `TeamCreate`/`spawn_agent`. The workers are runtime sub-agents, not SKILL.md skills.
 
@@ -81,15 +92,24 @@ Skills auto-select the best available backend:
 
 ## Hooks — The Workflow Enforces Itself
 
-3 active runtime hooks (from `hooks/hooks.json`). All have a kill switch: `AGENTOPS_HOOKS_DISABLED=1`.
+The active runtime manifest currently declares **7 hook event sections** in `hooks/hooks.json`. All have a kill switch: `AGENTOPS_HOOKS_DISABLED=1`.
 
-| Hook | Trigger | What it does |
+### Lifecycle anchors
-|------|---------|-------------|
-| Session start | Session start | Knowledge injection and startup maintenance |
-| Session end maintenance | Session end | Knowledge extraction, maturity, and cleanup |
-| Flywheel close | Stop | Closes the feedback loop via `ao flywheel close-loop` |
 
-Additional guardrail hook scripts remain available in `hooks/`, but they are not part of the active runtime manifest unless explicitly re-enabled.
+| Hook surface | Trigger | What it does |
+|--------------|---------|--------------|
+| Session start | `SessionStart` | Startup maintenance, lightweight retrieval, and continuity hints |
+| Session end maintenance | `SessionEnd` | Transcript mining, maturity management, and cleanup |
+| Flywheel close | `Stop` | Closes the feedback loop via `ao flywheel close-loop` |
+
+### Guardrails and continuity surfaces
+
+| Hook surface | Trigger | What it does |
+|--------------|---------|--------------|
+| Prompt guidance | `UserPromptSubmit` | Nudges missing intent and ratchet status before work drifts |
+| Pre-tool gates | `PreToolUse` | Enforces pre-mortem, commit, and worker safety checks before risky actions |
+| Post-tool checks | `PostToolUse` | Runs complexity, vet, and loop-drift checks after edits or commands |
+| Task completion gate | `TaskCompleted` | Executes compiled constraints and validation checks before accepting task completion |
 
 All hooks use `lib/hook-helpers.sh` for structured error recovery — failures include suggested next actions and auto-handoff context.
 

docs/knowledge-flywheel.md

@@ -1,64 +1,66 @@
 # The Knowledge Flywheel
 
-> **"Every session makes the next one smarter."**
+> Agents are stateless. The repo learns.
 
 ## The Problem
 
-AI assistants forget everything between sessions. Your team solves the same problems over and over.
+Coding agents forget everything between sessions. Notes alone do not fix that. If a solved problem is not extracted, curated, retrieved, and reused, the repo keeps paying for the same lesson.
 
 ## The Solution
 
-Olympus mines your Claude transcripts and extracts reusable knowledge:
+AgentOps turns session output into durable environment state:
-- Decisions and their rationale
+
-- Solutions that worked
+- research and design artifacts in `.agents/`
-- Patterns worth repeating
+- learnings and patterns extracted from completed work
-- Mistakes to avoid
+- reusable findings captured in a normalized registry
+- next-work queues and ratchet checkpoints for continuity
+- curation signals that keep retrieval focused on what is still useful
 
 ## The Flywheel
 
-```
+```text
-Mine transcripts → Extract knowledge → Index for recall → Apply to new work → Learn more
+Do work -> extract signal -> curate -> retrieve -> apply -> reinforce
-                                                                    ↓
+    ^                                                      |
-                                                         Compounds over time
+    |______________________________________________________|
 ```
 
-## Architecture
+The loop is not just memory. It is memory plus validation plus loop closure.
 
-```
+## Lifecycle
-┌───────────────────────────────────────────────────────────┐
+
-│                      THE FLYWHEEL                          │
+| Stage | Surfaces | What happens |
-│                                                            │
+|------|----------|--------------|
-│  .agents/patterns/  ──▶  Next /research reads              │
+| Capture | `/research`, `/post-mortem`, `/retro`, `/forge` | Current work is written down as research, learnings, or findings |
-│  .agents/learnings/ ──▶  Smart Connections indexes         │
+| Curate | `ao maturity`, `ao dedup`, `ao contradict`, constraint review | Stale or conflicting artifacts lose weight; useful ones stay retrievable |
-│  .agents/learnings/ ──▶  Knowledge compounds               │
+| Retrieve | `ao lookup`, `ao search`, startup hooks, phased handoffs | The next task starts with repo-native context instead of a blank window |
-│                                                            │
+| Apply | `/plan`, `/pre-mortem`, `/implement`, `/vibe` | Prior lessons shape current choices and validation |
-└───────────────────────────────────────────────────────────┘
+| Reinforce | citations, repeated use, promotion into constraints | Frequently useful knowledge hardens into planning rules or gates |
-                              │
-                              ▼
-                         NEXT CHAIN
-```
 
 ## Knowledge Stores
 
 | Store | Content | Updated By |
-|-------|---------|------------|
+|------|---------|------------|
-| `.agents/learnings/` | Lessons learned | `/forge`, `/post-mortem` |
+| `.agents/research/` | Scoped understanding and repo investigations | `/research` |
-| `.agents/patterns/` | Reusable patterns | `/forge`, `/retro` |
+| `.agents/brainstorm/` | Problem framing and option exploration | `/brainstorm` |
-| `.agents/learnings/` | Retrospectives | `/retro`, `/post-mortem` |
+| `.agents/learnings/` | Reusable lessons and retrospective signal | `/retro`, `/post-mortem`, `/forge` |
-| `.agents/ao/` | Session index, provenance | `ao forge` |
+| `.agents/findings/registry.jsonl` | Reusable findings before they become rules or constraints | `/pre-mortem`, `/vibe`, `/post-mortem` |
+| `.agents/rpi/next-work.jsonl` | Harvested next steps | `/post-mortem`, `/evolve` |
+| `.agents/ao/` | Ratchet trail, provenance, session metadata | `ao ratchet`, `ao forge`, `ao flywheel` |
 
 ## The Compounding Effect
 
-| Timeline | Claude Knows |
+| Without the flywheel | With the flywheel |
-|----------|--------------|
+|----------------------|-------------------|
-| Day 1 | Nothing - fresh start |
+| The same integration bug is rediscovered in a new session | The prior failure is retrieved before planning or validation |
-| Week 1 | Your coding patterns |
+| Handoffs rely on chat memory | Handoffs and phased state live on disk |
-| Month 1 | Your codebase |
+| Notes accumulate without pressure | Useful findings get promoted into rules, checks, or constraints |
-| Month 3 | Your organization |
+| Stale knowledge pollutes retrieval | Curation, contradiction checks, and maturity controls keep the corpus usable |
+
+The practical result is simple: each completed cycle can leave behind a more capable environment than the one it started in.
 
 ## See Also
 
-- [Brownian Ratchet Philosophy](brownian-ratchet.md)
+- [Context Lifecycle Contract](context-lifecycle.md)
-- `/forge` - Extract knowledge from transcripts
+- [How It Works](how-it-works.md)
-- `ao lookup` - Retrieve knowledge on demand
+- [Primitive Chains](architecture/primitive-chains.md)
-- `.agents/AGENTS.md` - Knowledge store navigation
+- [Brownian Ratchet](brownian-ratchet.md)

docs/positioning/devops-for-vibe-coding.md

@@ -20,15 +20,15 @@
 
 ## Elevator Pitch (30 seconds)
 
-> 12-Factor AgentOps is DevOps for vibe-coding. Instead of waiting for CI to catch problems with AI-generated code, we shift validation left—into the workflow itself. Pre-mortem before you implement. Vibe check before you commit. The same operational discipline that made infrastructure reliable, applied to coding agents.
+> 12-Factor AgentOps is DevOps for coding agents. It shifts validation left, but it also does the two things most tooling still misses: durable repo memory and loop closure. Pre-mortem before you implement. Vibe check before you commit. Findings and learnings written back into the environment so the next session starts smarter.
 
 ### One-Liner (10 seconds)
 
-> Shift-left validation for coding agents—catch it before you ship it.
+> The missing DevOps layer for coding agents: validation, memory, and loop closure.
 
 ### Tweet-Length (280 chars)
 
-> DevOps gave us reliable infrastructure. 12-Factor AgentOps gives us reliable coding agents. Validation built in, not bolted on. Pre-mortem before build. Vibe check before commit. Knowledge that compounds.
+> DevOps gave us reliable infrastructure. 12-Factor AgentOps gives us reliable coding agents. Validation built in, not bolted on. Durable memory on disk. Findings that compile into better future work.
 
 ---
 
@@ -46,7 +46,7 @@ Write code → Ship → CI catches problems → Fix → Repeat
 /pre-mortem → Implement → /vibe → Commit → Knowledge compounds
 ```
 
-The validation loop happens BEFORE code ships, not after. This is the core insight.
+The validation loop happens before code ships, not after. But validation alone is not the whole story. The larger system also extracts what was learned, compiles repeat failures into preventive artifacts, and feeds better context into the next cycle.
 
 ### 2. Coding Agent Specific
 
@@ -77,11 +77,11 @@ We apply proven operational discipline to a new domain:
 
 ### 4. Single-Session Excellence
 
-AgentOps optimizes the single coding session—where most value is created or destroyed:
+AgentOps optimizes the single coding session while refusing to waste what it learned:
 
 - Context management (40% rule)
 - Validation gates within the session
-- Knowledge extraction and injection
+- Knowledge extraction, retrieval, and compiled prevention
 - Human-AI collaboration patterns
 
 For multi-session orchestration, see Olympus (Temporal-based workflows).
@@ -90,11 +90,11 @@ For multi-session orchestration, see Olympus (Temporal-based workflows).
 
 The Knowledge Flywheel:
 ```
-Session → Forge (extract learnings) → Pool (validate) → Inject (apply)
+Session -> extract -> curate -> retrieve -> apply -> reinforce
-    ↑____________________________________________________________|
+    ^__________________________________________________________|
 ```
 
-Every session makes the next one better. This is the moat.
+Every session makes the next one better because the environment changes, not because the agent remembers. This is the moat.
 
 ---
 
@@ -102,7 +102,7 @@ Every session makes the next one better. This is the moat.
 
 - **DevOps principles applied to coding agents** — The same operational discipline that made infrastructure reliable
 - **Validation-first workflow** — Shift-left, not shift-blame
-- **Knowledge flywheel that compounds** — Learnings persist and improve future sessions
+- **Knowledge flywheel that compounds** — Learnings persist, get curated, and harden into future prevention
 - **Single-session orchestration** — Excellence where it matters most
 - **Framework, not SDK** — Patterns and practices, not lock-in
 
@@ -173,7 +173,7 @@ Single-Session          │   Agent SDKs
 
 ### When Asked "What is 12-Factor AgentOps?"
 
-> It's DevOps for vibe-coding. We apply the same operational principles that made infrastructure reliable—shift-left testing, post-mortems, continuous validation—to coding agents. Instead of shipping AI-generated code and hoping CI catches problems, you validate before you commit.
+> It's DevOps for coding agents. We apply the same operational principles that made infrastructure reliable, then add the missing memory and loop-closure layers agents need because they forget everything between sessions. Instead of shipping AI-generated code and hoping CI catches problems, you validate before commit and write the learning back into the repo.
 
 ### When Asked "How is it different from X?"
 
@@ -186,7 +186,7 @@ Single-Session          │   Agent SDKs
 
 ### When Asked "Why should I care?"
 
-> Because AI-generated code still needs validation. The 80% that works is valuable. The 20% that doesn't can be catastrophic. DevOps taught us to shift validation left. AgentOps applies that to coding agents.
+> Because AI-generated code still needs validation, and validation alone still leaves you paying for the same lesson twice. AgentOps shifts validation left, captures what failed, and turns useful findings into better future context and gates.
 
 ---
 

docs/reference.md

@@ -269,7 +269,7 @@ ao search "query"         # Semantic search across learnings
 ao flywheel status        # Knowledge growth rate, escape velocity
 ao metrics report         # Flywheel health dashboard
 ao forge transcript       # Extract learnings from session transcripts
-ao ratchet status         # RPI progress gates (Research → Plan → Implement → Validate)
+ao ratchet status         # RPI progress gates (Discovery → Implementation → Validation)
 ao pool list              # Show knowledge by quality tier
 ```
 
@@ -291,7 +291,7 @@ ao pool list              # Show knowledge by quality tier
 | `/research` | Deep codebase exploration |
 | `/plan` | Break goal into tracked issues |
 | `/release` | Pre-flight, changelog, version bumps, tag |
-| `/ratchet` | Progress gates that lock (Research → Plan → Implement → Validate) |
+| `/ratchet` | Progress gates that lock (Discovery → Implementation → Validation) |
 | `/beads` | Git-native issue tracking |
 
 ### Additional

docs/workflows/complete-cycle.md

@@ -1,6 +1,6 @@
 ---
 name: complete-cycle
-description: Full Research → Plan → Implement → Validate → Learn workflow
+description: Full Discovery → Implementation → Validation → Learn workflow
 estimated_time: 2-4 hours (or multi-session)
 phases: 5
 ---
@@ -22,11 +22,11 @@ phases: 5
 ## Workflow Phases
 
 ```
-Phase 1: Research (20-30% context)
+Phase 1: Discovery (20-30% context)
    ↓
-Phase 2: Plan (20-30% context)
+Phase 2: Scope + risk (20-30% context)
    ↓
-Phase 3: Implement (20-40% context)
+Phase 3: Implementation (20-40% context)
    ↓
 Phase 4: Validate (5-10% context)
    ↓

docs/workflows/session-lifecycle.md

@@ -362,17 +362,18 @@ cp .claude/templates/feature-list.json .
 
 ## Integration with RPI Workflow
 
-For complex features, use the Research → Plan → Implement flow:
+For complex features, use the phased RPI flow:
 
 ```
 ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  RESEARCH   │ ──▶ │    PLAN     │ ──▶ │  IMPLEMENT  │
+│ DISCOVERY   │ ──▶ │ IMPLEMENT   │ ──▶ │ VALIDATION  │
-│  /research  │     │   /plan     │     │  /implement │
+│ /research   │     │  /crank     │     │    /vibe    │
-│  (explore)  │     │  (specify)  │     │  (execute)  │
+│ /plan       │     │ /implement  │     │ /post-mortem│
+│ /pre-mortem │     │  (execute)  │     │  (learn)    │
 └─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
-  research.md         plan.md            code changes
+research + plan      validated code      learnings + next work
     bundle              bundle              + commit
 ```