mnemon-dev · Grivn · May 20, 2026 · May 19, 2026 · May 20, 2026 · May 20, 2026
diff --git a/Makefile b/Makefile
@@ -10,7 +10,7 @@ ifeq ($(GOBIN),)
   GOBIN     := $(shell go env GOPATH)/bin
 endif
 
-.PHONY: deps build install uninstall test unit vet harness-validate codex-app-eval codex-app-eval-suite codex-memory-deep-eval codex-skill-deep-eval codex-eval-loop-smoke docker-build docker-run compose-up compose-down compose-dev release-snapshot clean help
+.PHONY: deps build install uninstall test unit vet harness-validate codex-app-eval codex-app-eval-suite codex-memory-deep-eval codex-skill-deep-eval codex-eval-smoke docker-build docker-run compose-up compose-down compose-dev release-snapshot clean help
 
 .DEFAULT_GOAL := help
 
@@ -45,8 +45,8 @@ unit: ## Run Go unit tests
 vet: ## Run go vet static analysis
 	go vet ./...
 
-harness-validate: ## Validate harness module manifests and declared asset paths
-	bash scripts/validate_harness_modules.sh
+harness-validate: ## Validate harness loop manifests and declared asset paths
+	bash scripts/validate_harness_loops.sh
 
 codex-app-eval: ## Run real Codex app-server harness smoke eval
 	python3 scripts/codex_app_server_eval.py
@@ -60,8 +60,8 @@ codex-memory-deep-eval: ## Run deep real Codex app-server memory regression suit
 codex-skill-deep-eval: ## Run deep real Codex app-server skill regression suite
 	python3 scripts/codex_app_server_eval.py --suite --suite-name skill-deep
 
-codex-eval-loop-smoke: ## Run real Codex app-server eval-loop projection smoke check
-	python3 scripts/codex_app_server_eval.py --module eval-loop
+codex-eval-smoke: ## Run real Codex app-server eval projection smoke check
+	python3 scripts/codex_app_server_eval.py --loop eval
 
 # ── Containers / Deployment ──────────────────────────────────────────
 

diff --git a/README.md b/README.md
@@ -229,7 +229,7 @@ Different agents/processes can use different stores via the `MNEMON_STORE` envir
 
 **How do I customize the behavior?**
 Edit the generated guideline (`~/.mnemon/prompt/guide.md` in current setup
-flows) or use the installable [memory loop GUIDE](harness/modules/memory-loop/GUIDE.md)
+flows) or use the installable [memory loop GUIDE](harness/loops/memory/GUIDE.md)
 as the source. The skill file should stay focused on command syntax.
 
 **What is sub-agent delegation?**
@@ -270,8 +270,8 @@ See [Development and Deployment](docs/DEPLOYMENT.md) for Docker, Compose, Ollama
 ## Documentation
 
 - [Modular Self-Evolution Harness](docs/harness/README.md) — formal harness docs for modular agent, memory loop, and skill loop design
-- [Memory Loop Harness](harness/modules/memory-loop/README.md) — installable memory loop assets
-- [Skill Loop Harness](harness/modules/skill-loop/README.md) — installable skill loop assets
+- [Memory Loop Harness](harness/loops/memory/README.md) — installable memory loop assets
+- [Skill Loop Harness](harness/loops/skill/README.md) — installable skill loop assets
 - [Design & Architecture](docs/DESIGN.md) — current engine architecture, algorithms, integration design
 - [Usage & Reference](docs/USAGE.md) — CLI commands, embedding support, architecture overview
 - [Architecture Diagrams](docs/diagrams/) — system architecture, pipelines, lifecycle management

diff --git a/docs/harness/HOST_PROJECTION.md b/docs/harness/HOST_PROJECTION.md
@@ -2,11 +2,11 @@
 
 Chinese version: [HOST_PROJECTION.md](../zh/harness/HOST_PROJECTION.md)
 
-This document defines how a Mnemon loop module is projected into a concrete
+This document defines how a Mnemon loop template is projected into a concrete
 host runtime such as Claude Code, Codex, OpenClaw, or a future app-server eval
 host.
 
-The loop module standard defines the canonical package shape. Host projection
+The loop standard defines the canonical package shape. Host projection
 defines how that package becomes visible and executable inside a host runtime.
 
 ## Principle
@@ -16,9 +16,9 @@ projections that can be regenerated.
 
 ```text
 .mnemon/
-  canonical state, loop modules, reports, proposals, audit
+  canonical state, loop templates, reports, proposals, audit
       |
-      | projected by setup/<host>
+      | projected by harness/hosts/<host> through harness/ops
       v
 .claude/ or .codex/
   host-readable skills, hooks, config, and pointers back to .mnemon
@@ -31,17 +31,22 @@ The projection adapter should not create an independent copy of truth. It should
 render enough host-native files for the host to discover and use the loop while
 keeping durable state under `.mnemon`.
 
+Projection and observation are separate surfaces. Projection lets the host see
+Mnemon's Intent. Observation lets Mnemon see enough Reality to write status,
+collect evidence, and run future reconcile actions.
+
 ## Responsibilities
 
 A host projection adapter owns these responsibilities:
 
 | Responsibility | Description |
 | --- | --- |
-| Path resolution | Resolve project root, host config directory, canonical `.mnemon`, active store, and loop module path. |
+| Path resolution | Resolve project root, host config directory, canonical `.mnemon`, active store, and loop template path. |
 | Asset projection | Render or copy host-readable GUIDE, hooks, protocol skills, and subagents. |
 | Hook registration | Register host lifecycle hooks when the host supports them. |
 | Environment injection | Make `MNEMON_DATA_DIR`, `MNEMON_STORE`, `MNEMON_HARNESS_DIR`, and loop-specific env visible to hooks and skills. |
 | Manifest writing | Record what was projected and where under `.mnemon/hosts/<host>/manifest.json`. |
+| Status writing | Record the installed loop control model under `.mnemon/harness/<loop>/status.json`. |
 | Validation | Detect missing assets, stale projections, incompatible host capabilities, and path conflicts. |
 | Uninstall | Remove host projection files while preserving canonical `.mnemon` state by default. |
 
@@ -51,7 +56,7 @@ A host projection adapter should not:
 
 - Reimplement Mnemon memory storage or retrieval.
 - Move canonical state into `.claude`, `.codex`, or another host directory.
-- Hide host-specific behavior inside loop module root files.
+- Hide host-specific behavior inside loop template root files.
 - Mutate user-owned host config outside declared projection sections.
 - Delete memory, reports, proposals, or audit records unless the user explicitly
   requests destructive cleanup.
@@ -65,8 +70,10 @@ The target canonical layout is:
 ├── data/
 │   └── <store>/mnemon.db
 ├── harness/
-│   ├── memory-loop/
-│   └── skill-loop/
+│   ├── memory/
+│   │   └── status.json
+│   └── skill/
+│       └── status.json
 ├── reports/
 ├── proposals/
 ├── audit/
@@ -166,21 +173,28 @@ Recommended shape:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "host": "codex",
-  "installed_at": "2026-05-14T00:00:00Z",
+  "updated_at": "2026-05-20T00:00:00Z",
   "project_root": "/path/to/project",
   "mnemon_dir": "/path/to/project/.mnemon",
   "store": "default",
   "loops": {
-    "memory-loop": {
-      "module_path": ".mnemon/harness/memory-loop",
-      "module_version": "0.1.0",
-      "projection_path": ".codex",
-      "projected_assets": {
-        "skills": [".codex/skills/memory_get.md"],
-        "hooks": [".codex/hooks/prime.sh"],
-        "subagents": []
+    "memory": {
+      "loop_path": ".mnemon/harness/memory",
+      "loop_version": "0.1.0",
+      "state_path": ".mnemon/harness/memory",
+      "intent_policy": ".mnemon/harness/memory/GUIDE.md",
+      "status_path": ".mnemon/harness/memory/status.json",
+      "projection": {
+        "path": ".codex",
+        "surfaces": ["GUIDE.md", "hooks", "memory_get", "memory_set", "runtime env"]
+      },
+      "reality": {
+        "surfaces": ["hook output", "MEMORY.md length", "recall results", "write outcomes"]
+      },
+      "reconcile": {
+        "actions": ["read", "write", "compact", "consolidate", "no-op"]
       },
       "lifecycle_mapping": {
         "prime": "session-init",
@@ -193,23 +207,28 @@ Recommended shape:
 }
 ```
 
-The manifest is the bridge between setup, status, uninstall, and eval tooling.
+The manifest is the bridge between ops, status, uninstall, eval tooling, and
+future reconcile tooling. Each installed loop also writes `status.json` in its
+canonical state directory so loop-local state can be inspected without reading
+host-specific configuration.
 
 ## Setup Contract
 
 All host adapters should support the same high-level operations:
 
 ```text
 install
-  validate loop module manifests
+  validate loop manifests
   resolve canonical .mnemon
   install canonical loop assets if needed
   render host projection
   register hooks/config
   write host manifest
+  write loop status
 
 status
   read host manifest
+  read loop status
   validate projected files exist
   validate registered hooks/config
   report stale or missing projections
@@ -233,7 +252,7 @@ behavior. It should use the same projection contract as real hosts:
 eval orchestrator
     |
     | create isolated workspace and .mnemon
-    | run setup/<host>/install
+    | run harness/ops/install.sh
     | start host app server
     v
 host app server
@@ -250,7 +269,7 @@ Eval should test host behavior under harness influence, not only Mnemon CLI
 CRUD. Useful assertions include:
 
 - The app server uses the isolated `.mnemon`.
-- The expected loop module versions are installed.
+- The expected loop template versions are installed.
 - Lifecycle events are invoked through the declared mapping.
 - Recall decisions affect later task behavior.
 - Writeback decisions create durable memory only when justified.
@@ -259,10 +278,9 @@ CRUD. Useful assertions include:
 ## Quality Rules
 
 - Projection files should be small and generated from canonical assets.
-- Host-specific behavior belongs in `setup/<host>/` or generated adapter files.
+- Host-specific behavior belongs in `harness/hosts/<host>/` or generated adapter files.
 - Setup should be repeatable and idempotent where practical.
 - Uninstall should be conservative and preserve canonical state.
 - Manifest paths should be relative when possible and absolute when required for
   runtime execution.
 - Public projection behavior must be documented in both English and Chinese.
-
diff --git a/docs/harness/LIFECYCLE_CONTROL_PLANE.md b/docs/harness/LIFECYCLE_CONTROL_PLANE.md
@@ -0,0 +1,158 @@
+# Lifecycle Control Plane
+
+Chinese version: [LIFECYCLE_CONTROL_PLANE.md](../zh/harness/LIFECYCLE_CONTROL_PLANE.md)
+
+This document defines the lightweight control model behind Mnemon Harness. The
+visual site version is available at [Lifecycle Control Plane](../site/lifecycle-control-plane/index.html).
+
+Mnemon does not need a heavy distributed control system. It needs a consistent
+model for making agent lifecycle capabilities durable, observable, portable, and
+governable.
+
+## Minimal Definition
+
+Mnemon keeps `State`, declares `Intent`, observes `Reality`, and uses
+`Reconcile` to pull Reality back toward Intent. The result is written back into
+State.
+
+```text
+State -> Intent -> Reality -> Reconcile -> State
+```
+
+This is the stable kernel. Concrete files, skills, hooks, host adapters, evals,
+and proposals enter the kernel through profiles.
+
+## Core Model
+
+| Concept | Meaning |
+| --- | --- |
+| State | Durable truth owned by Mnemon, such as memory, skills, reports, proposals, audit, and status under `.mnemon`. |
+| Intent | The lifecycle shape Mnemon wants the system to present. |
+| Reality | The current real state of the host, project, tools, evals, and runtime. |
+| Reconcile | The alignment mechanism that compares Intent with Reality and writes outcomes back into State. |
+
+Execution surfaces are not part of the core model. They belong to the execution
+layer: they are how Mnemon reaches host reality.
+
+## Entity Profiles
+
+Entities are not the model itself. Each entity declares a profile inside the
+model.
+
+| Profile | Meaning | Examples |
+| --- | --- | --- |
+| Template | Reusable definition, not necessarily reconciled. | `Loop` |
+| Controlled | Needs ongoing alignment of Intent and Reality. | `LoopBinding`, `EvalRun`, future `Goal` |
+| Surface | Expresses or reaches host capability. | `HostCapability`, `Projection` |
+| Evidence | Observed fact from Reality, not a declarative object. | `Observation`, runtime status |
+| Governance | Review, risk, and audit boundary. | `Proposal`, `Review`, `Audit` |
+
+Only controlled entities need the full `spec/status/reconcile` shape. Other
+profiles participate in reconcile differently.
+
+## Current Entities
+
+| Entity | Profile | Role |
+| --- | --- | --- |
+| `Loop` | Template | Reusable lifecycle capability package such as memory, skill, or eval. |
+| `Binding` | Controlled | Binds one `Loop` to one host; suitable as the first full controlled object sample. |
+| `HostCapability` | Surface | Describes static or dynamic capabilities a host can expose. |
+| `Projection` | Surface | Lets the HostAgent see Mnemon's Intent. |
+| `Observation` | Evidence | Lets Mnemon see the HostAgent's Reality. |
+| `Proposal` / `Review` / `Audit` | Governance | Stores proposals, decisions, and immutable records when Reconcile cannot safely complete automatically. |
+
+## Execution Surfaces
+
+Execution surfaces explain how Mnemon reaches the host without mixing that
+mechanism into the core model.
+
+### Projection
+
+Projection is the static direction: render Intent into a host-readable view.
+
+Examples:
+
+- `.codex/skills`
+- `.claude/hooks`
+- host config
+- generated docs
+- manifests
+
+Projection lets the HostAgent see Mnemon's Intent.
+
+### Observation
+
+Observation is the dynamic direction: turn Reality into status, evidence, or
+proposal input.
+
+Examples:
+
+- Codex appserver
+- session APIs
+- eval endpoints
+- tool status
+- runtime errors
+
+Observation lets Mnemon see HostAgent Reality.
+
+## What Memory-loop Proved
+
+Mnemon's method is to take capabilities that are often built as heavy external
+systems and reintroduce them into the host lifecycle through hooks, skills,
+daemon work, canonical state, and reconcile.
+
+`memory` validated this pattern for memory:
+
+```text
+external memory service
+  -> hook + skill + .mnemon state
+  -> prime / remind / nudge / compact lifecycle
+  -> lifecycle-native memory capability
+```
+
+The lifecycle control plane generalizes the same pattern for self-improving
+loops:
+
+```text
+standalone self-improvement loop
+  -> hook + skill + daemon + HostCapability
+  -> projection / observation / reconcile
+  -> governable project evolution
+```
+
+## Relation To Autoresearch
+
+Autoresearch is a useful reference because it demonstrates a constrained
+self-improving loop:
+
+```text
+edit -> run -> evaluate -> keep/discard -> repeat
+```
+
+Mnemon does not clone an experiment platform. Mnemon borrows the discipline of
+self-improving loops and makes them lifecycle-native, host-portable, and
+governable.
+
+In Mnemon, the decision space expands beyond keep or discard:
+
+- repair
+- validate
+- propose
+- review
+- audit
+- no-op
+
+## Evolution Levels
+
+Mnemon should grow through lightweight capability levels:
+
+| Level | Shape |
+| --- | --- |
+| Profiles | Every entity declares a profile before becoming a full resource object. |
+| Projection | Project Intent into the HostAgent. |
+| Observation | Observe Reality through appserver, eval, tool status, and runtime evidence. |
+| Governance | Let AI produce patches, reports, and proposals while review gates control risk. |
+
+The goal is not to copy a large control system. The goal is a small, consistent
+lifecycle model that can scale from memory to self-evolving agentic
+projects.