feat(harness): AI-native lifecycle architecture — governed agent collaboration

.gitignore

@@ -1,6 +1,8 @@
 # Binary
 /mnemon
 /mnemon-harness
+/mnemon-hub
+/mnemond
 /bin/
 
 # Local dogfood / capability test sandboxes (per-test subdirs)

Makefile

@@ -10,7 +10,7 @@ ifeq ($(GOBIN),)
   GOBIN     := $(shell go env GOPATH)/bin
 endif
 
-.PHONY: deps build install uninstall test unit vet harness-validate harness-docs-check eval-router-check 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
+.PHONY: deps build harness-build install uninstall test unit vet harness-validate harness-docs-check eval-router-check 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
 
@@ -22,6 +22,11 @@ deps: ## Download Go dependencies
 build: ## Build the mnemon binary
 	go build -ldflags "$(LDFLAGS)" -o $(BINARY) .
 
+harness-build: ## Build the harness binaries (mnemon-harness local plane + mnemon-hub remote hub + mnemond local governance daemon)
+	go build -ldflags "$(LDFLAGS)" -o mnemon-harness ./harness/cmd/mnemon-harness
+	go build -ldflags "$(LDFLAGS)" -o mnemon-hub ./harness/cmd/mnemon-hub
+	go build -ldflags "$(LDFLAGS)" -o mnemond ./harness/cmd/mnemond
+
 # ── Install / Uninstall ─────────────────────────────────────────────
 
 install: build ## Build and install mnemon to $GOBIN

README.md

@@ -261,7 +261,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/loops/memory/GUIDE.md)
+flows) or use the installable [memory loop GUIDE](harness/internal/assets/loops/memory/GUIDE.md)
 as the source. The skill file should stay focused on command syntax.
 
 **What is sub-agent delegation?**
@@ -302,8 +302,8 @@ See [Development and Deployment](docs/DEPLOYMENT.md) for Docker, Compose, Ollama
 ## Documentation
 
 - [Mnemon Harness Beta](harness/README.md) — experimental host-agent lifecycle state
-- [Memory Loop Harness](harness/loops/memory/README.md) — installable memory loop assets
-- [Skill Loop Harness](harness/loops/skill/README.md) — installable skill loop assets
+- [Memory Loop Harness](harness/internal/assets/loops/memory/README.md) — installable memory loop assets
+- [Skill Loop Harness](harness/internal/assets/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
 - [Memory Import Guide](docs/IMPORT.md) — schema and LLM prompt for importing historical chats

docs/harness/QUICKSTART.md

@@ -0,0 +1,111 @@
+# mnemon-harness — Quickstart
+
+Two paths, each from nothing to something running and governed. Commands below
+are the real CLI; substitute your own host (`codex`, `claude-code`) and ports.
+
+> Status: experimental. This shows the governed-event loop working end to end;
+> it does not claim production readiness.
+
+---
+
+## Path A — operator: from install to your first governed decision
+
+Goal: stand up Local Mnemon, observe one candidate, and see it admitted as a
+governed decision on the Control Tower.
+
+```sh
+# 1. install the integration for your host + a memory loop
+mnemon-harness setup --host codex --loop memory \
+  --principal codex@project --control-url http://127.0.0.1:8801
+
+# 2. start Local Mnemon (the local governance daemon)
+mnemon-harness local run &
+
+# 3. observe a candidate — Local Mnemon admits it through its rules (ticked=true)
+mnemon-harness control observe \
+  --addr http://127.0.0.1:8801 --principal codex@project \
+  --token-file .mnemon/harness/channel/credentials/codex-project.token \
+  --type memory.write_candidate.observed --external-id q1 \
+  --payload '{"content":"my first governed memory","source":"user","confidence":"high"}'
+# -> observed seq=1 dup=false ticked=true
+
+# 4. stop the daemon, then read the Control Tower (it needs exclusive store access)
+#    (kill the `local run` above, then:)
+mnemon-harness tower --dump
+```
+
+The Tower prints the four pages. The decision appears on **LEDGER**, attributed
+to its proposer:
+
+```
+# LEDGER
+  dec_… by codex@project -> memory
+```
+
+That is the whole point: a candidate became a **governed, attributed decision**
+— not a silent write.
+
+---
+
+## Path B — capability author: from an empty directory to your own kind governing
+
+Goal: declare a new event kind as a loop package and watch it govern, with no
+code — a capability is **data that SELECTS from a closed catalog** of validators
+and renderers, never new behavior.
+
+Start from a working install (Path A, or `setup --host codex --loop memory …`).
+
+```sh
+# 1. drop a loop package: .mnemon/loops/<name>/capability.json
+mkdir -p .mnemon/loops/note
+cat > .mnemon/loops/note/capability.json <<'JSON'
+{
+  "schema_version": 1,
+  "name": "note",
+  "observed_type": "note.write_candidate.observed",
+  "proposed_type": "note.write.proposed",
+  "resource_kind": "note",
+  "items_field": "items",
+  "fields": [
+    { "name": "text", "validators": [ {"id": "required", "params": {"missing_style": "empty"}}, {"id": "safety:unsafe"} ] }
+  ],
+  "render": { "content": { "member": "bullet-list", "params": {"title": "# Notes", "field": "text"} } }
+}
+JSON
+
+# 2. enable it. A package with host assets (a loop.json) is wired by
+#    `setup --loop <name>`. A governance-only kind like this (no host assets)
+#    is enabled by adding it to config.loops + the binding scope:
+#      .mnemon/harness/local/config.json     -> "loops": [..., "note"]
+#      .mnemon/harness/channel/bindings.json -> the binding gains
+#          allowed_observed_types: "note.write_candidate.observed"
+#          subscription_scope:     {"kind":"note","id":"project"}
+
+# 3. run + observe your new kind — it governs through the SAME path as the built-ins
+mnemon-harness local run &
+mnemon-harness control observe \
+  --addr http://127.0.0.1:8803 --principal codex@project \
+  --token-file .mnemon/harness/channel/credentials/codex-project.token \
+  --type note.write_candidate.observed --external-id n1 \
+  --payload '{"text":"governed by a kind I declared"}'
+# -> observed seq=1 dup=false ticked=true
+```
+
+Your `note` kind admits, renders, and (if you connect a Remote Workspace) syncs
+— with no per-kind code. The full schema (validators, render members, risk
+tiers, sync strategies) is in [`loop-package-v2.md`](loop-package-v2.md) and
+[`capability-spec-v2.md`](capability-spec-v2.md).
+
+---
+
+## What you just used
+
+| You ran | The protocol object |
+|---|---|
+| `control observe` | an Event admitted at the Channel boundary |
+| `ticked=true` | the kernel decided it (a Decision) |
+| `tower` LEDGER | the accepted Decision + its attribution |
+| `capability.json` | a governed, versioned event-model declaration |
+
+Next: connect a Remote Workspace (`sync`) to share one governed state across
+machines, or read [`USAGE.md`](USAGE.md) for the full command surface.

docs/harness/README.md

@@ -1,64 +1,40 @@
 # Mnemon Harness Public Beta
 
-`mnemon-harness` is an experimental beta layer for attaching host agents to
-project-local governed state. It is source-build only and intentionally separate
-from the stable `mnemon` CLI.
+`mnemon-harness` is an experimental beta for installing host-agent integration
+assets and connecting them to a local Mnemon service.
 
-It is not production-ready and has no compatibility guarantee. Commands, file
-layouts, schemas, projected surfaces, and behavior may change in breaking ways
-before a stable release.
+Stable Mnemon remains the memory CLI. The harness is source-build only, has no
+compatibility guarantee, and is currently scoped to memory and skill
+integration.
 
-Stable Mnemon remains a memory and recall tool. The harness adds lifecycle
-exchange, evidence, proposals, audit, coordination topology, and a review TUI
-around host agents such as Codex and Claude Code.
+## 1. Product Surface
 
-## 1. What It Is
+The user-facing command surface is intentionally small:
 
-Mnemon Harness is a governed agent-state substrate.
+- `setup`: install memory and skill Agent Integration assets.
+- `local`: run or inspect Local Mnemon.
+- `status`: show Agent Integration, Local Mnemon, and Remote Workspace state.
+- `sync`: connect Local Mnemon to a Remote Workspace.
 
-```text
-host agent
-  <-> Lifecycle Exchange
-      context out: .codex/.claude projection files
-      signal in:   .mnemon/events.jsonl
-  <-> governed project state
-      profile + goals + proposals + audit + coordination
-```
-
-The host directories are projection surfaces. Canonical state lives in the
-append-only event log and governed records under `.mnemon/`.
+Other implementation commands are internal and are not part of the beta product
+contract.
 
-## 2. Current Beta Surface
+## 2. Current Scope
 
-The public beta includes:
+The beta supports Codex and Claude Code projections for the memory and skill
+loops. Projected host directories such as `.codex/` and `.claude/` are generated
+surfaces. Local state lives under `.mnemon/harness/`.
 
-- lifecycle event append/status/daemon commands
-- Codex and Claude Code projection surfaces
-- projection envelope and readback verification
-- profile projection into host context
-- goal, eval, proposal, apply, and audit commands
-- coordination topology and governed coordination apply
-- TUI views for hosts, evidence, proposals, profile, coordination, and traces
-- Codex runner checks behind explicit user action and cost gates
-
-It does not promise production readiness, automatic apply, broad org/team scope
-composition, or a full multi-agent runtime.
+The current beta does not promise production readiness, automatic apply,
+multi-agent governance, broad organization scope, or a general evaluation
+runtime.
 
 ## 3. Separation From Stable Mnemon
 
 `mnemon-harness` is built from `./harness/cmd/mnemon-harness`.
 
-The stable `mnemon` binary does not import harness packages. It exposes only a
-small default-off event seam so a project can write events that the harness may
-later read.
-
-```sh
-MNEMON_HARNESS_EVENT_EMIT=1 mnemon remember "..." --cat note
-mnemon event emit custom.observed --payload '{"ok":true}'
-```
-
-Without the opt-in environment variable or explicit `mnemon event` command,
-stable Mnemon behavior is unchanged.
+Stable `mnemon` behavior is unchanged unless a user explicitly opts into harness
+event emission or runs `mnemon-harness` directly.
 
 ## 4. Try It
 
@@ -69,31 +45,18 @@ go build -o mnemon .
 go build -o mnemon-harness ./harness/cmd/mnemon-harness
 ```
 
-Run the no-model smoke path:
+Install memory and skill integration for a project:
 
 ```sh
-tmpdir="$(mktemp -d)"
-./mnemon-harness lifecycle --root "$tmpdir" init
-./mnemon-harness lifecycle --root "$tmpdir" event append --json '{
-  "schema_version": 1,
-  "id": "evt_harness_smoke_001",
-  "ts": "2026-05-31T00:00:00Z",
-  "type": "memory.hot_write_observed",
-  "loop": "memory",
-  "host": "codex",
-  "actor": "host-agent",
-  "source": "harness-smoke",
-  "correlation_id": "corr_harness_smoke",
-  "payload": {"reason": "smoke"}
-}'
-./mnemon-harness lifecycle --root "$tmpdir" status refresh
-./mnemon-harness ui --root "$tmpdir"
+./mnemon-harness setup --host codex --loop memory --loop skill --project-root .
+./mnemon-harness local run
+./mnemon-harness status
 ```
 
 See [USAGE.md](USAGE.md) for command examples.
 
 ## 5. Release Boundary
 
 This beta intentionally ships minimal public documentation. Internal planning,
-internal validation artifacts, generated site HTML, and detailed future plans are
-not part of this branch.
+experimental command surfaces, generated site HTML, and future governance
+experiments are not part of the product contract.